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 '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' 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': 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. 'no_load': If set the tree file will not be loaded.

$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.

Return value

TRUE for success and FALSE for failure.

File

tripal_phylogeny/api/tripal_phylogeny.api.inc, line 271

Code

function tripal_insert_phylotree(&$options, &$errors, &$warnings) {
  global $user;

  $options['name_re'] = trim($options['name_re']);
  $options['leaf_type'] = trim($options['leaf_type']);
  $options['name'] = trim($options['name']);
  $options['format'] = trim($options['format']);
  $options['tree_file'] = trim($options['tree_file']);

  // Validate the incoming options.
  $success = tripal_validate_phylotree('insert', $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 add the phylotree record.
  $values = array(
    'analysis_id' => $options['analysis_id'],
    'name' => $options['name'],
    'dbxref_id' => $options['dbxref_id'],
    'comment' => $options['description'],
    'type_id' => $options['type_id'],
  );
  $phylotree = chado_insert_record('phylotree', $values);
  if (!$phylotree) {
    drupal_set_message(t('Unable to add phylotree.'), 'warning');
    tripal_report_error('tripal_phylogeny', TRIPAL_WARNING, 'Insert phylotree: Unable to create phylotree where values: %values', 
    array('%values' => print_r($values, TRUE)));
    return FALSE;
  }
  $phylotree_id = $phylotree['phylotree_id'];
  $options['phylotree_id'] = $phylotree_id;

  // 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 = NULL;
    $file = file_load($options['tree_file']);
    $file->status = FILE_STATUS_PERMANENT;
    $file = file_save($file);
    file_usage_add($file, 'tripal_phylogeny', $options['format'], $phylotree_id);
    $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('no_load', $options) or !$options['no_load']) {
    if (array_key_exists('load_now', $options) and $options['load_now']) {
      $args = array(
        'phylotree_id' => $phylotree_id,
        'leaf_type' => $options['leaf_type'],
        'match' => $options['match'] ? 'uniquename' : 'name',
        'name_re' => $options['name_re'],
      );
      tripal_phylogeny_import_tree_file($real_file_path, $options['format'], $args);
    }
    else {
      $args = array(
        $real_file_path,
        'newick',
        array(
          'phylotree_id' => $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', 
      'tripal_phylogeny_import_tree_file', $args, $user->uid)) {
        drupal_set_message(t('The tree visualizations will appear once the tree is fully imported.'));
      }
    }
  }

  return TRUE;
}