MorphyLib
Phylogenetic data reconstruction library accommodating inapplicable data
|
Defines the Morphy Phylogenetic Library API: a library for phylogenetic computation accommodating morphological character hierarchies. More...
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) |
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.
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.
m | An instance of the Morphy object. |
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.
rawmatrix | C-style string corresponding to the tip data. |
m | An instance of the Morphy object. |
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.
symbols | A C-style (i.e. NULL-terminated) string of valid state symbols. |
m | An instance of the Morphy object. |
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.
m | A Morphy object to be destroyed. |
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.
m | An instance of the Morphy object. |
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.
tip_id | The index of the tip being updated. |
anc_id | The index of the tip's immediate ancestor. |
m | An instance of the Morphy object. |
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.
node_id | The index of the node being reconstructed. |
left_id | The index of the left descendant. |
right_id | The index of the right descendant. |
m | An instance of the Morphy object. |
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.
node_id | The index of the node being reconstructed. |
left_id | The index of the left descendant. |
right_id | The index of the right descendant. |
anc_id | The index of the immediate ancestor of the node. |
m | An instance of the Morphy object. |
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.
m | An instance of the Morphy object. |
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.
m | An instance of the Morphy object. |
int mpl_get_numtaxa | ( | Morphy | m | ) |
Retrieve the number of taxa (rows) in the dataset.
Retrieves the number of taxa (rows) in the dataset.
m | An instance of the Morphy object. |
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).
m | An instance of the Morphy object. |
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.
ntax | The number of taxa (or tips/terminals). |
nchar | The number of characters (i.e. transformation series) in the data set. |
m | An instance of the Morphy object. |
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.
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.
m | An instance of the Morphy object. |
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.
node_id | The index of the node being reconstructed. |
left_id | The index of the left descendant. |
right_id | The index of the right descendant. |
m | An instance of the Morphy object. |
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.
node_id | The index of the node being reconstructed. |
left_id | The index of the left descendant. |
right_id | The index of the right descendant. |
anc_id | The index of the immediate ancestor of the node. |
m | An instance of the Morphy object. |
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.
gaptype | The type of gap treatment to be applied (documented in morphydefs.h). |
m | An instance of the Morphy object. |
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.
nnodes | The desired number of internal nodes. |
m | An instance of the Morphy object |
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.
charID | The index of the character (transformation series) as defined in the input matrix. |
chtype | The parsimony function type as defined in morphydefs.h |
m | An instance of the Morphy object. |
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.
l_root_id | The index of the lower root. |
root_id | The index of the upper root node. |
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.
tip_id | The index of the tip being updated. |
anc_id | The index of the tip's immediate ancestor. |
m | An instance of the Morphy object. |