MorphyLib
Phylogenetic data reconstruction library accommodating inapplicable data
mpl.h File Reference

Defines the Morphy Phylogenetic Library API: a library for phylogenetic computation accommodating morphological character hierarchies. More...

#include <stdbool.h>
#include "morphydefs.h"
#include "mplerror.h"

Go to the source code of this file.

Functions

Morphy mpl_new_Morphy (void)
 Creates a new instance of a Morphy object. More...
 
int mpl_delete_Morphy (Morphy m)
 Destroys an instance of a Morphy object. More...
 
int mpl_init_Morphy (const int ntax, const int nchar, Morphy m)
 Sets up the dimensions of the dataset. More...
 
int mpl_get_numtaxa (Morphy m)
 Retrieve the number of taxa (rows) in the dataset. More...
 
int mpl_get_num_charac (Morphy m)
 Retrieve the number of taxa (rows) in the dataset. More...
 
int mpl_set_num_internal_nodes (const int nnodes, Morphy m)
 Sets the number of internal nodes in the dataset. More...
 
int mpl_get_num_internal_nodes (Morphy m)
 Gets the number of internal nodal reconstruction sets being used by MorphyLib. More...
 
int mpl_attach_symbols (const char *symbols, Morphy m)
 Attach a caller-specified list of symbols. More...
 
char * mpl_get_symbols (const Morphy m)
 Retrieves the current list of symbols. More...
 
int mpl_attach_rawdata (const char *rawmatrix, Morphy m)
 Attach raw character state data (i.e. tip data). More...
 
int mpl_delete_rawdata (Morphy m)
 Deletes the caller-input data. More...
 
int mpl_set_gap_symbol (const char gapsymb, Morphy m)
 
int mpl_set_missing_symbol (const char missymb, Morphy m)
 
int mpl_apply_tipdata (Morphy m)
 Commits parameters prior to nodal set calculations. More...
 
int mpl_incl_charac (const int charID, Morphy m)
 
int mpl_excl_charac (const int charID, Morphy m)
 
int mpl_set_charac_weight (const int charID, Mflt weight)
 
int mpl_set_parsim_t (const int charID, const MPLchtype chtype, Morphy m)
 Sets a character's parsimony function type. More...
 
int mpl_set_gaphandl (const gap_t gaptype, Morphy m)
 Tells MorphyLib how to treat the gap symbol. More...
 
int mpl_query_gaphandl (Morphy m)
 Returns the type of gap handling method currently in effect. More...
 
int mpl_first_down_recon (const int node_id, const int left_id, const int right_id, Morphy m)
 Reconstructs the first (downpass) nodal reconstructions. More...
 
int mpl_first_up_recon (const int node_id, const int left_id, const int right_id, const int anc_id, Morphy m)
 Reconstructs the second (uppass) nodal reconstructions. More...
 
int mpl_second_down_recon (const int node_id, const int left_id, const int right_id, Morphy m)
 Performs the second nodal reconstructions for characters with inapplicability. More...
 
int mpl_second_up_recon (const int node_id, const int left_id, const int right_id, const int anc_id, Morphy m)
 Finalises the ancestral state reconstructions for characters with inapplicable values. More...
 
int mpl_update_tip (const int tip_id, const int anc_id, Morphy m)
 Initial update of tip values following uppass reconstruction. More...
 
int mpl_finalize_tip (const int tip_id, const int anc_id, Morphy m)
 Finalizes ambiguous or missing values in the tips. More...
 
int mpl_update_lower_root (const int l_root_id, const int root_id, Morphy m)
 Updates the nodal sets for a lower ('dummy') root node. More...
 
int mpl_get_insertcost (const int srcID, const int tgt1ID, const int tgt2ID, bool max, int cutoff, Morphy m)
 
int mpl_get_packed_states (const int nodeID, const int character, int passnum, Morphy m)
 
char * mpl_get_stateset (const int nodeID, const int character, int passnum, Morphy m)
 

Detailed Description

Defines the Morphy Phylogenetic Library API: a library for phylogenetic computation accommodating morphological character hierarchies.

Copyright (C) 2017 Martin D. Brazeau

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

This header includes all the externally exported definitions and function prototypes. A calling program creates an instance of a Morphy object and interacts with its elements through the functions described in this interface. The Morphy object contains no tree objects, but requires a pre-specified list of indices (integers) corresponding to the node indices in the calling program. Morphy will not keep track of the relationships between the nodes, and it is up to the caller to keep track of these. Each character must* be assigned a type, and Morphy will make no default assumptions. Once one or more characters are assigned a function type (which creates internal partitions), and a postorder list of nodes is known, then the library functions can be called to reconstruct state sets and deliver length estimates for each node.

Morphy will provide functions for local reoptimisation, partial reoptimisation and optimisation of subtrees.

Function Documentation

◆ mpl_apply_tipdata()

int mpl_apply_tipdata ( Morphy  m)

Commits parameters prior to nodal set calculations.

Once the caller is satisfied with the setup of types, weights, and partitioning, this function must be called, thereby committing the parameters until any changes are made. If no character types have been assigned, the function will fail with an error code.

Parameters
mAn instance of the Morphy object.
Returns
A Morphy error code.

◆ mpl_attach_rawdata()

int mpl_attach_rawdata ( const char *  rawmatrix,
Morphy  m 
)

Attach raw character state data (i.e. tip data).

Attaches a raw data character state matrix in the form of a C-style (i.e. NULL-terminated string). This can be the matrix block extracted from a Nexus file or an xread table format. The matrix should contain no terminal or tip labels.

Parameters
rawmatrixC-style string corresponding to the tip data.
mAn instance of the Morphy object.
Returns
Morphy error code.

◆ mpl_attach_symbols()

int mpl_attach_symbols ( const char *  symbols,
Morphy  m 
)

Attach a caller-specified list of symbols.

Allows the caller to specify a list of symbols in the data matrix, otherwise, the symbols list used by Morphy will be extracted from the matrix. The symbols list must match the symbols provided in the matrix. When Morphy extracts symbols from the matrix, their ordering is alphanumeric, according to their ASCII codes (i.e. "+0123...ABCD...abcd..."). Loading a user-specified symbols list will override this ordering. Symbols loaded in either the list or the matrix must be valid Morphy character state symbols as defined in the statedata.h header file.

Parameters
symbolsA C-style (i.e. NULL-terminated) string of valid state symbols.
mAn instance of the Morphy object.
Returns
Morphy error code.

◆ mpl_delete_Morphy()

int mpl_delete_Morphy ( Morphy  m)

Destroys an instance of a Morphy object.

Destroys an instance of the Morphy object, calling all destructors for internal object completely returning the memory to the system.

Parameters
mA Morphy object to be destroyed.
Returns
A Morphy error code.

◆ mpl_delete_rawdata()

int mpl_delete_rawdata ( Morphy  m)

Deletes the caller-input data.

Deletes all of the user-input data and restores all parameters to their original values, except for the dimensions of the matrix.

Parameters
mAn instance of the Morphy object.
Returns
Morphy error code.

◆ mpl_finalize_tip()

int mpl_finalize_tip ( const int  tip_id,
const int  anc_id,
Morphy  m 
)

Finalizes ambiguous or missing values in the tips.

Ambiguous terminal state sets need to be resolved after the uppass based on descendant state values in order for local reoptimisation procedures to be accurate and for inapplicable step counting to proceed accurately. This function calls updaters for the records of states active on the subtrees, thereby allowing local reoptimization functions to accurately predict length increases when a subtree is added near a tip.

Because this function needs to be fairly high-performance, it does not do much checking for parameter validity, thus unsafe usage of this function might not be caught. It is up to calling functions to ensure that the appropriate parameters have been set before use.

Parameters
tip_idThe index of the tip being updated.
anc_idThe index of the tip's immediate ancestor.
mAn instance of the Morphy object.
Returns
A null value (for now).

◆ mpl_first_down_recon()

int mpl_first_down_recon ( const int  node_id,
const int  left_id,
const int  right_id,
Morphy  m 
)

Reconstructs the first (downpass) nodal reconstructions.

Reconstructs the preliminary nodal set for all characters for a particular node. This function is called over a postorder sequence of internal nodes where left and right descendants are known.

Because this function needs to be fairly high-performance, it does not do much checking for parameter validity, thus unsafe usage of this function might not be caught. It is up to calling functions to ensure that the appropriate parameters have been set before use.

Parameters
node_idThe index of the node being reconstructed.
left_idThe index of the left descendant.
right_idThe index of the right descendant.
mAn instance of the Morphy object.
Returns
The integral parsimony length (right now)

◆ mpl_first_up_recon()

int mpl_first_up_recon ( const int  node_id,
const int  left_id,
const int  right_id,
const int  anc_id,
Morphy  m 
)

Reconstructs the second (uppass) nodal reconstructions.

Reconstructs second-pass nodal sets. For normal (all-applicable) characters, this is the final pass. This function is called over a preorder sequence of nodes where left, right, and ancestral nodes are known.

Because this function needs to be fairly high-performance, it does not do much checking for parameter validity, thus unsafe usage of this function might not be caught. It is up to calling functions to ensure that the appropriate parameters have been set before use.

Parameters
node_idThe index of the node being reconstructed.
left_idThe index of the left descendant.
right_idThe index of the right descendant.
anc_idThe index of the immediate ancestor of the node.
mAn instance of the Morphy object.
Returns
A null value (for now).

◆ mpl_get_num_charac()

int mpl_get_num_charac ( Morphy  m)

Retrieve the number of taxa (rows) in the dataset.

Retrieves the number of taxa (rows) in the dataset.

Parameters
mAn instance of the Morphy object.
Returns
The number of taxa if success, otherwise an error code.

◆ mpl_get_num_internal_nodes()

int mpl_get_num_internal_nodes ( Morphy  m)

Gets the number of internal nodal reconstruction sets being used by MorphyLib.

Gets the number of internal nodal reconstruction sets being used by MorphyLib.

Parameters
mAn instance of the Morphy object.
Returns
The number of internal nodes.

◆ mpl_get_numtaxa()

int mpl_get_numtaxa ( Morphy  m)

Retrieve the number of taxa (rows) in the dataset.

Retrieves the number of taxa (rows) in the dataset.

Parameters
mAn instance of the Morphy object.
Returns
The number of taxa if success, otherwise an error code.

◆ mpl_get_symbols()

char* mpl_get_symbols ( const Morphy  m)

Retrieves the current list of symbols.

Returns a pointer to the string of character state symbols currently being used by Morphy (i.e. either the list of symbols extracted from the matrix, or the caller-specified values).

Parameters
mAn instance of the Morphy object.
Returns
A C-style (null-terminated) string of the character state symbols being used. NULL if failure.

◆ mpl_init_Morphy()

int mpl_init_Morphy ( const int  ntax,
const int  nchar,
Morphy  m 
)

Sets up the dimensions of the dataset.

Provides initial dimensions for the dataset, which will constrain any input matrix supplied to Morphy.

Parameters
ntaxThe number of taxa (or tips/terminals).
ncharThe number of characters (i.e. transformation series) in the data set.
mAn instance of the Morphy object.
Returns
Morphy error code.

◆ mpl_new_Morphy()

Morphy mpl_new_Morphy ( void  )

Creates a new instance of a Morphy object.

Creates a new empty Morphy object. All fields are unpopulated and uninitialised.

Returns
A void pointer to the Morphy instance. NULL if unsuccessful.

◆ mpl_query_gaphandl()

int mpl_query_gaphandl ( Morphy  m)

Returns the type of gap handling method currently in effect.

Returns the type of gap handling method currently in effect. The methods are defined in the morphydefs.h file.

Parameters
mAn instance of the Morphy object.
Returns
A Morphy error code.

◆ mpl_second_down_recon()

int mpl_second_down_recon ( const int  node_id,
const int  left_id,
const int  right_id,
Morphy  m 
)

Performs the second nodal reconstructions for characters with inapplicability.

Updates the nodal sets that had ambiguous unions with the inapplicable state and calculates steps involving applicable states after the update.

Because this function needs to be fairly high-performance, it does not do much checking for parameter validity, thus unsafe usage of this function might not be caught. It is up to calling functions to ensure that the appropriate parameters have been set before use.

Parameters
node_idThe index of the node being reconstructed.
left_idThe index of the left descendant.
right_idThe index of the right descendant.
mAn instance of the Morphy object.
Returns
The integral parsimony length (right now)

◆ mpl_second_up_recon()

int mpl_second_up_recon ( const int  node_id,
const int  left_id,
const int  right_id,
const int  anc_id,
Morphy  m 
)

Finalises the ancestral state reconstructions for characters with inapplicable values.

Finalises the nodal sets for any characters that may have involved the inapplicable token and counts excess regions of applicability at nodes having at least two descendant subtrees that possess any applicable characters.

Because this function needs to be fairly high-performance, it does not do much checking for parameter validity, thus unsafe usage of this function might not be caught. It is up to calling functions to ensure that the appropriate parameters have been set before use.

Parameters
node_idThe index of the node being reconstructed.
left_idThe index of the left descendant.
right_idThe index of the right descendant.
anc_idThe index of the immediate ancestor of the node.
mAn instance of the Morphy object.
Returns
The integral parsimony length (for now)

◆ mpl_set_gaphandl()

int mpl_set_gaphandl ( const gap_t  gaptype,
Morphy  m 
)

Tells MorphyLib how to treat the gap symbol.

The caller can specify the type of gap handling to use before the tipdata are applied. The options are documented in the morphydefs.h header file but include at least GAP_INAPPLIC, GAP_MISSING, and GAP_NEWSTATE to specify inapplicable, missing, or new state values respectively. These values are applied to all characters for which they are appropriate.

Parameters
gaptypeThe type of gap treatment to be applied (documented in morphydefs.h).
mAn instance of the Morphy object.
Returns
A Morphy error code.

◆ mpl_set_num_internal_nodes()

int mpl_set_num_internal_nodes ( const int  nnodes,
Morphy  m 
)

Sets the number of internal nodes in the dataset.

This specifies the number of internal nodes over which reconstruction sets need to be made. It is up to the caller to ensure the correct number of nodes and the relationships between them.

Parameters
nnodesThe desired number of internal nodes.
mAn instance of the Morphy object
Returns
A Morphy error code.

◆ mpl_set_parsim_t()

int mpl_set_parsim_t ( const int  charID,
const MPLchtype  chtype,
Morphy  m 
)

Sets a character's parsimony function type.

Set the parsimony function type to one defined in the morphydefs.h header file. Setting the character to type NONE_T will also cause it to be excluded from any further calculations.

Parameters
charIDThe index of the character (transformation series) as defined in the input matrix.
chtypeThe parsimony function type as defined in morphydefs.h
mAn instance of the Morphy object.
Returns
A Morphy error code.

◆ mpl_update_lower_root()

int mpl_update_lower_root ( const int  l_root_id,
const int  root_id,
Morphy  m 
)

Updates the nodal sets for a lower ('dummy') root node.

If trees are rooted, then Morphy uppass functions require a lower or 'dummy' root in order to function properly. This function should be called to set the nodal state sets to the dummy root. The nodal set will be equal to the set of the root node, unless there is an ambiguous union of applicable and gap tokens when gaps are treated as in applicable. In which case, the set union is resolved in favour of any applicable tokens in the set.

Parameters
l_root_idThe index of the lower root.
root_idThe index of the upper root node.
Returns
A Morphy error code.

◆ mpl_update_tip()

int mpl_update_tip ( const int  tip_id,
const int  anc_id,
Morphy  m 
)

Initial update of tip values following uppass reconstruction.

Polymorphic terminal state sets need to be resolved after the uppass based on descendant state values in order for local reoptimisation procedures to be accurate and for inapplicable step counting to proceed accurately. This function calls updaters for the records of states active on the subtrees, thereby allowing the second downpass to accurately reconstruct subtree state activity. Missing values are left as-is in characters with inapplicability, otherwise, final ancestral state reconstructions may be inaccurate.

Because this function needs to be fairly high-performance, it does not do much checking for parameter validity, thus unsafe usage of this function might not be caught. It is up to calling functions to ensure that the appropriate parameters have been set before use.

Parameters
tip_idThe index of the tip being updated.
anc_idThe index of the tip's immediate ancestor.
mAn instance of the Morphy object.
Returns
A null value (for now).