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 'organism'. If the type is 'organism' then this tree represents a taxonomic tree. The default, if not specified, is the term 'polypeptide'. 'name_re': If the leaf type is NOT 'taxonomy', then the value of this field can be a regular expression to pull out the name of the feature from the node label in the intput 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.

Related topics

File

tripal_chado/api/modules/tripal_chado.phylotree.api.inc, line 827

Provides API functions specificially for managing phylogenetic and taxonomic tree records in Chado.

Code

function chado_phylogeny_import_tree_file($file_name, $format, $options = array(), $job_id = NULL) {

  // Set some option details.
  if (!array_key_exists('leaf_type', $options)) {
    $options['leaf_type'] = 'polypeptide';
  }
  if (!array_key_exists('match', $options)) {
    $options['match'] = 'name';
  }
  if (!array_key_exists('name_re', $options)) {
    $options['name_re'] = '^(.*)$';
  }
  $options['name_re'] = trim($options['name_re']);

  // If a phylotree ID is not passed in then make sure we have the other
  // required fields for creating a tree.
  if (!array_key_exists('phylotree_id', $options)) {
    if (!array_key_exists('name', $options)) {
      tripal_report_error('tripal_phylogeny', TRIPAL_ERROR, 
      'The phylotree_id is required for importing the tree.');
      return FALSE;
    }
  }

  // Get the phylotree record.
  $values = array('phylotree_id' => $options['phylotree_id']);
  $phylotree = chado_generate_var('phylotree', $values);

  if (!$phylotree) {
    tripal_report_error('tripal_phylogeny', TRIPAL_ERROR, 
    'Could not find the phylotree using the ID provided: %phylotree_id.', 
    array('%phylotree_id' => $options['phylotree_id']));
    return FALSE;
  }

  $transaction = db_transaction();
  print "\nNOTE: Loading of this tree file is performed using a database transaction. \n" .
    "If the load fails or is terminated prematurely then the entire set of \n" .
    "insertions/updates is rolled back and will not be found in the database\n\n";
  try {

    // Parse the file according to the format indicated.
    if ($format == 'newick') {
      // Parse the tree into the expected nested node format.
      module_load_include('inc', 'tripal_chado', 'includes/loaders/tripal_chado.phylotree_newick');
      $tree = tripal_phylogeny_parse_newick_file($file_name);

      // Assign the right and left indecies to the tree ndoes.
      chado_assign_phylogeny_tree_indices($tree);
    }
    // Iterate through the tree nodes and add them to Chado in accordance
    // with the details in the $options array.
    chado_phylogeny_import_tree($tree, $phylotree, $options);
  }
  catch (Exception $e) {
    $transaction->rollback();
    watchdog_exception('tripal_phylogeny', $e);
  }
}