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 'anlaysis_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 'organism'. If the type is 'organism' 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': 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. 'load_now': If set, the tree will be loaded immediately if a tree_file is provided. Otherwise, the tree will be loaded via a Tripal jobs call.

Related topics

File

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

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

Code

function chado_update_phylotree($phylotree_id, &$options) {
  global $user;

  // Validate the incoming options.
  $errors = array();
  $warnings = array();
  $success = chado_validate_phylotree('update', $options, $errors, $warnings);
  if (!$success) {
    foreach ($errors as $field => $message) {
      tripal_report_error('tripal_phylogeny', TRIPAL_ERROR, $message);
    }
    return FALSE;
  }

  // If we're here then all is good, so update the phylotree record.
  $match = array(
    'phylotree_id' => $phylotree_id,
  );
  if (array_key_exists('name', $options) and $options['name']) {
    $values['name'] = $options['name'];
  }
  if (array_key_exists('analysis_id', $options) and $options['analysis_id']) {
    $values['analysis_id'] = $options['analysis_id'];
  }
  if (array_key_exists('dbxref_id', $options) and $options['dbxref_id']) {
    $values['dbxref_id'] = $options['dbxref_id'];
  }
  if (array_key_exists('description', $options) and $options['description']) {
    $values['comment'] = $options['description'];
  }
  if (array_key_exists('type_id', $options) and $options['type_id']) {
    $values['type_id'] = $options['type_id'];
  }

  $phylotree = chado_update_record('phylotree', $match, $values, array('return_record' => TRUE));
  if (!$phylotree) {
    drupal_set_message(t('Unable to update phylotree.'), 'warning');
    tripal_report_error('tripal_phylogeny', TRIPAL_WARNING, 
    'Update phylotree: Unable to update phylotree where values: %values', 
    array('%values' => print_r($values, TRUE))
    );
  }

  // If we have a tree file, then import the tree.
  if (array_key_exists('tree_file', $options) and $options['tree_file']) {

    // Remove any existing nodes
    chado_delete_record('phylonode', array('phylotree_id' => $options['phylotree_id']));

    // Make sure if we already have a file that we remove the old one.
    $sql = "
      SELECT FM.fid
      FROM {file_managed} FM
        INNER JOIN {file_usage} FU on FM.fid = FU.fid
      WHERE FU.id = :id and FU.module = 'tripal_phylogeny'
    ";
    $fid = db_query($sql, array(':id' => $options['phylotree_id']))->fetchField();
    if ($fid) {
      $file = file_load($fid);
      file_delete($file, TRUE);
    }

    // If the tree_file is numeric then it is a Drupal managed file and
    // we want to make the file permanent and associated with the tree.
    if (is_numeric($options['tree_file'])) {
      $file = file_load($options['tree_file']);
      $file->status = FILE_STATUS_PERMANENT;
      $file = file_save($file);
      file_usage_add($file, 'tripal_phylogeny', 'newick', $options['phylotree_id']);

      // Add a job to parse the new node tree.
      $real_file_path = drupal_realpath($file->uri);
    }
    else {
      $real_file_path = $options['tree_file'];
    }

    // If caller has requested to load the file now then do so, otherwise
    // submit using a Tripal job.
    if (array_key_exists('load_now', $options) and $options['load_now']) {
      $args = array(
        'phylotree_id' => $options['phylotree_id'],
        'leaf_type' => $options['leaf_type'],
        'match' => $options['match'] ? 'uniquename' : 'name',
        'name_re' => $options['name_re'],
      );
      chado_phylogeny_import_tree_file($real_file_path, $options['format'], $args);
    }
    else {
      $args = array(
        $real_file_path,
        'newick',
        array(
          'phylotree_id' => $options['phylotree_id'],
          'leaf_type' => $options['leaf_type'],
          'match' => $options['match'] ? 'uniquename' : 'name',
          'name_re' => $options['name_re'],
        ),
      );
      if (tripal_add_job("Import Tree File: " . $file->filename, 'tripal_phylogeny', 
      'chado_phylogeny_import_tree_file', $args, $user->uid)) {
        drupal_set_message(t('The tree visualizations will appear once the tree is fully imported.'));
      }
    }
  }

  return TRUE;
}