Retrieves a chado controlled vocabulary term variable.

Parameters

$identifier: An array apropriate for use with the chado_generate_var for uniquely identifying a cvterm record. Alternativley, there are also some specially handled keys. They are:

• id: an ID for the term of the for [dbname]:[accession], where [dbname] is the short name of the vocabulary and accession is the unique ID.
• cv_id: an integer indicating the cv_id or an array with 'name' => the name of the cv.
• synonym: an array with 'name' => the name of the synonym of the cvterm you want returned; 'cv_id' => the cv_id of the synonym; 'cv_name' => the name of the cv of the synonym.
• property: An array/object describing the property to select records for. It should at least have either a type_name (if unique across cvs) or type_id. Other supported keys include: cv_id/cv_name (of the type), value and rank.

$options: An array of options. Supported keys include:

• Any keys supported by chado_generate_var(). See that function definition for additional details.

NOTE: the $identifier parameter can really be any array similar to $values passed into chado_select_record(). It should fully specify the cvterm record to be returned.

Return value

If unique values were passed in as an identifier then an object describing the cvterm will be returned (will be a chado variable from chado_generate_var()). Otherwise, FALSE will be returned.

Related topics

File

tripal_chado/api/modules/tripal_chado.cv.api.inc, line 177

Provides API functions specificially for managing controlled vocabulary records in Chado.

Code

function chado_get_cvterm($identifiers, $options = array()) {

  // Set Defaults.
  if (!isset($options['include_fk'])) {
    // Tells chado_generate_var to only get the cv.
    $options['include_fk'] = array('cv_id' => TRUE);
  }

  // Error Checking of parameters.
  if (!is_array($identifiers)) {
    tripal_report_error('tripal_cv_api', TRIPAL_ERROR, 
    "chado_get_cvterm: The identifier passed in is expected to be an array with the key
        matching a column name in the cvterm table (ie: cvterm_id or name). You passed in %identifier.", 
    array('%identifier' => print_r($identifiers, TRUE))
    );
  }
  elseif (empty($identifiers)) {
    tripal_report_error('tripal_cv_api', TRIPAL_ERROR, 
    "chado_get_cvterm: You did not pass in anything to identify the cvterm you want. The identifier
        is expected to be an array with the key matching a column name in the cvterm table
        (ie: cvterm_id or name). You passed in %identifier.", 
    array('%identifier' => print_r($identifiers, TRUE))
    );
  }

  // If synonym was passed in, then process this first before calling 
  // chado_generate_var().
  if (isset($identifiers['synonym'])) {
    $synonym = $identifiers['synonym']['name'];

    $values = array('synonym' => $synonym);
    if (isset($identifiers['synonym']['cv_id'])) {
      $values['cvterm_id'] = array('cv_id' => $identifiers['synonym']['cv_id']);
    }
    if (isset($identifiers['synonym']['cv_name'])) {
      $values['cvterm_id'] = array('cv_id' => array('name' => $identifiers['synonym']['cv_name']));
    }
    $options = array(
      'case_insensitive_columns' => array('name')
    );
    $result = chado_select_record('cvtermsynonym', array('cvterm_id'), $values, $options);

    // if the synonym doens't exist or more than one record is returned then 
    // return false.
    if (count($result) == 0) {
      return FALSE;
    }
    if (count($result) > 1) {
      return FALSE;
    }

    $identifiers = array('cvterm_id' => $result[0]->cvterm_id);
  }

  // If one of the identifiers is property then use chado_get_record_with_property().
  if (isset($identifiers['property'])) {
    $property = $identifiers['property'];
    unset($identifiers['property']);
    $cvterm = chado_get_record_with_property(
    array('table' => 'cvterm', 'base_records' => $identifiers), 
    array('type_name' => $property), 
    $options
    );
  }
  if (isset($identifiers['id'])) {
    list($db_name, $accession) = preg_split('/:/', $identifiers['id']);
    $cvterm = chado_generate_var('cvterm', array(
      'dbxref_id' => array(
        'db_id' => array(
          'name' => $db_name,
        ),
        'accession' => $accession,
      )
    ));
  }

  // Else we have a simple case and we can just use chado_generate_var to get 
  // the cvterm.
  else {
    // Try to get the cvterm.
    $cvterm = chado_generate_var('cvterm', $identifiers, $options);
  }

  // Ensure the cvterm is singular. If it's an array then it is not singular.
  if (is_array($cvterm)) {
    tripal_report_error(
    'tripal_cv_api', 
    TRIPAL_ERROR, 
    "chado_get_cvterm: The identifiers you passed in were not unique. You passed in %identifier.", 
    array(
      '%identifier' => print_r($identifiers, TRUE)
    )
    );
  }

  // Report an error if $cvterm is FALSE since then chado_generate_var has 
  // failed.
  elseif ($cvterm === FALSE) {
    tripal_report_error(
    'tripal_cv_api', 
    TRIPAL_ERROR, 
    "chado_get_cvterm: chado_generate_var() failed to return a cvterm based on the identifiers
        you passed in. You should check that your identifiers are correct, as well as, look
        for a chado_generate_var error for additional clues. You passed in %identifier.", 
    array(
      '%identifier' => print_r($identifiers, TRUE)
    )
    );
  }

  // Else, as far we know, everything is fine so give them their cvterm :)
  else {
    return $cvterm;
  }

}