Functions | |
| chado_validate_phylotree ($val_type, &$options, &$errors, &$warnings) | |
| chado_insert_phylotree (&$options, &$errors, &$warnings) | |
| chado_update_phylotree ($phylotree_id, &$options) | |
| chado_delete_phylotree ($phylotree_id) | |
| chado_assign_phylogeny_tree_indices (&$tree, &$index=1) | |
| chado_phylogeny_import_tree (&$tree, $phylotree, $options, $vocab=[], $parent=NULL) | |
| chado_phylogeny_lookup_organism_by_name ($name) | |
| chado_phylogeny_get_node_types_vocab ($options) | |
| chado_phylogeny_import_tree_file ($file_name, $format, $options=[], $job_id=NULL) | |
Detailed Description
Provides API functions specifically for managing phylogenetic and taxonomic tree records in Chado. The API consists of functions for creation, retrieval, update and deltion (CRUD) for phylogenetic tree records as well as importing of trees in the newick file format.
Function Documentation
◆ chado_assign_phylogeny_tree_indices()
| chado_assign_phylogeny_tree_indices | ( | & | $tree, |
| & | $index = 1 |
||
| ) |
Iterates through the tree and sets the left and right indices.
- Parameters
-
$tree The tree array. $index This parameters is not used when the function is first called. It is used for recursive calls.
◆ chado_delete_phylotree()
| chado_delete_phylotree | ( | $phylotree_id | ) |
Deletes a phylotree record from Chado.
- Parameters
-
$phylotree_id
- Returns
- TRUE on success, FALSE on failure.
◆ chado_insert_phylotree()
| chado_insert_phylotree | ( | & | $options, |
| & | $errors, | ||
| & | $warnings | ||
| ) |
Inserts a phylotree record into Chado.
This function validates the options passed prior to insertion of the record, and if validation passes then any values in the options array that needed validation lookups (such as the dbxref, analysis, leaf_type, etc) will have their approriate primary key values added to the options array.
- Parameters
-
$options An array of key value pairs with the following keys required: 'name': The name of the tree. This will be displayed to users. 'description: A description about the tree 'analysis_id: The ID of the analysis to which this phylotree should be associated. 'analysis': If the analysis_id key is not used then the analysis name may be provided to identify the analysis to which the tree should be associated. 'leaf_type': A sequence ontology term or the word 'taxonomy'. If the type is 'taxonomy' then this tree represents a taxonomic tree. The default, if not specified, is the term 'polypeptide'. 'tree_file': The path of the file containing the phylogenetic tree to import or a Drupal managed_file numeric ID. 'format': The file format. Currently only 'newick' is supported.
Optional keys: 'dbxref': A database cross-reference of the form DB:ACCESSION. Where DB is the database name, which is already present in Chado, and ACCESSION is the unique identifier for this tree in the remote database. 'name_re': The value of this field can be a regular expression to pull out the name of the feature or organism from the node label in the input tree. If no value is provided the entire label is used. 'match': Set to 'uniquename' if the leaf nodes should be matched with the feature uniquename. 'load_later': If set, the tree will be loaded via a separate Tripal jobs call. Otherwise, the tree will be loaded immediately. 'no_load': If set the tree file will not be loaded. 'job': The Tripal job object, if present.
- Parameters
-
$errors An empty array where validation error messages will be set. The keys of the array will be name of the field from the options array and the value is the error message. $warnings An empty array where validation warning messagges will be set. The warnings should not stop an insert or an update but should be provided to the user as information by a drupal_set_message() if appropriate. The keys of the array will be name of the field from the options array and the value is the error message.
- Returns
- TRUE for success and FALSE for failure.
◆ chado_phylogeny_get_node_types_vocab()
| chado_phylogeny_get_node_types_vocab | ( | $options | ) |
Get the vocabulary terms used to describe nodes in the tree.
- Returns
- Array of vocab info or FALSE on failure.
◆ chado_phylogeny_import_tree()
| chado_phylogeny_import_tree | ( | & | $tree, |
| $phylotree, | |||
| $options, | |||
$vocab = [], |
|||
$parent = NULL |
|||
| ) |
Iterates through the tree array and creates phylonodes in Chado.
The function iterates through the tree in a top-down approach adding parent internal nodes prior to leaf nodes. Each node of the tree should have the following fields:
-name: The name (or label) for this node. -depth: The depth of the node in the tree. -is_root: Set to 1 if this node is a root node. -is_leaf: Set to 1 if this node is a leaf node. -is_internal: Set to 1 if this node is an internal node. -left_index: The index of the node to the left in the tree. -right_index: The index of the node to the right in the tree. -branch_set: An array containing a list of nodes of that are children of the node. -parent: The name of the parent node. -organism_id: The organism_id for associating the node with an organism. -properties: An array of key/value pairs where the key is the cvterm_id and the value is the property value. These properties will be associated with the phylonode.
Prior to importing the tree the indices can be set by using the chado_assign_phylogeny_tree_indices() function.
- Parameters
-
$tree The tree array. $phylotree . The phylotree object (from Chado). $options The options provide some direction for how the tree is imported. The following keys can be used: -leaf_type: Set to the leaf type name. If this is a non-taxonomic tree that is associated with features, then this should be the Sequence Ontology term for the feature (e.g. polypeptide). If this is a taxonomic tree then set to 'taxonomy'. -match: Set to either 'name' or 'uniquename'. This is used for matching the feature name or uniquename with the node name. This is not needed for taxonomic trees. -match_re: Set to a regular that can be used for matching the node name with the feature name if the node name is not identical to the feature name. $vocab Optional. An array containing a set of key/value pairs that maps node types to CV terms. The keys must be 'root', 'internal' or 'leaf'. If no vocab is provded then the terms provided by the tripal_phylogeny CV will be used. $parent This argument is not needed when the funtion is first called. This function is recursive and this argument is used on recursive calls.
◆ chado_phylogeny_import_tree_file()
| chado_phylogeny_import_tree_file | ( | $file_name, | |
| $format, | |||
$options = [], |
|||
$job_id = NULL |
|||
| ) |
Imports a tree file.
This function is used as a wrapper for loading a phylogenetic tree using any number of file loaders.
- Parameters
-
$file_name The name of the file containing the phylogenetic tree to import. $format The format of the file. Currently only the 'newick' file format is supported. $options Options if the phylotree record already exists: 'phylotree_id': The imported nodes will be associated with this tree. 'leaf_type': A sequence ontology term or the word 'taxonomy'. If the type is 'taxonomy' then this tree represents a taxonomic tree. The default, if not specified, is the term 'polypeptide'. 'name_re': The value of this field can be a regular expression to pull out the name of the feature or organism from the node label in the input tree. If no value is provided the entire label is used. 'match': Set to 'uniquename' if the leaf nodes should be matched with the feature uniquename.
◆ chado_phylogeny_lookup_organism_by_name()
| chado_phylogeny_lookup_organism_by_name | ( | $name | ) |
Lookup an organism_id given an organism name (genus species)
- Parameters
-
$name The organism name. Infraspecific type abbreviation is allowed.
- Returns
- organism_id from chado.organism table on success, or FALSE on failure.
◆ chado_update_phylotree()
| chado_update_phylotree | ( | $phylotree_id, | |
| & | $options | ||
| ) |
Updates a phylotree record into Chado.
This function validates the options passed prior to update of the record and if validation passes then any values in the options array that needed validation lookups (such as the dbxref, analysis, leaf_type, etc) will have their approriate primary key values added to the options array. A Drupal File object will be added to the options array for the tree file if one is provided.
- Parameters
-
$phylotree_id The ID of the phylotree to update. $options An array of key value pairs with the following optional keys: 'name': The name of the tree. This will be displayed to users. 'description: A description about the tree 'analysis_id: The ID of the analysis to which this phylotree should be associated. 'analysis': If the analysis_id key is not used then the analysis name may be provided to identify the analysis to which the tree should be associated. 'leaf_type': A sequence ontology term or the word 'taxonomy'. If the type is 'taxonomy' then this tree represents a taxonomic tree. The default, if not specified, is the term 'polypeptide'. 'tree_file': The path of the file containing the phylogenetic tree to import or a Drupal managed_file numeric ID. 'format': The file format. Currently only 'newick' is supported 'dbxref': A database cross-reference of the form DB:ACCESSION. Where DB is the database name, which is already present in Chado, and ACCESSION is the unique identifier for this tree in the remote database. 'name_re': The value of this field can be a regular expression to pull out the name of the feature or organism from the node label in the input tree. If no value is provided the entire label is used. 'match': Set to 'uniquename' if the leaf nodes should be matched with the feature uniquename. 'load_later': If set, the tree will be loaded via a separate Tripal jobs call. Otherwise, the tree will be loaded immediately.
◆ chado_validate_phylotree()
| chado_validate_phylotree | ( | $val_type, | |
| & | $options, | ||
| & | $errors, | ||
| & | $warnings | ||
| ) |
Validates an $options array for insert or update of a phylotree record.
If validation passes then any values that needed validation lookups (such as the dbxref, analysis, leaf_type, etc) will have their approriate primary_keys added to the $options array, and missing default values will also be added.
- Parameters
-
$val_type The type of validation. Can be either 'insert' or 'update'. $options An array of key/value pairs containing any of the valid keys for either the chado_insert_phylotree() or chado_update_phylotree() functions. $errors An empty array where validation error messages will be set. The keys of the array will be the name of the field from the options array and the value is the error message. $warnings An empty array where validation warning messagges will be set. The warnings should not stop an insert or an update but should be provided to the user as information by a drupal_set_message() if appropriate. The keys of the array will be the name of the field from the options array and the value is the error message.
- Returns
- If validation fails then FALSE is returned. Any options that do not pass validation checks will be added in the $errors array with the key being the option and the value being the error message. If validation is successful then TRUE is returned.
