function tripal_get_organism

2.x tripal_organism.api.inc tripal_get_organism($identifiers, $options = array())

Retrieves a chado organism variable

Parameters

$identifier: An array with the key stating what the identifier is. Supported keys (only on of the following unique keys is required):

  • organism_id: the chado organism.organism_id primary key
  • genus & species: the chado organism.genus field & organism.species field

There are also some specially handled keys. They are:

  • 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 organism record to be returned.

Return value

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

Related topics

2 string references to 'tripal_get_organism'

File

tripal_organism/api/tripal_organism.api.inc, line 42
Provides an application programming interface (API) to manage organisms

Code

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

  // Set Defaults
  if (!isset($options['include_fk'])) {
    // Tells chado_generate_var not to follow any foreign keys
    $options['include_fk'] = array();
  }

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

  // If one of the identifiers is property then use chado_get_record_with_property()
  if (isset($identifiers['property'])) {
    $property = $identifiers['property'];
    unset($identifiers['property']);
    $organism = chado_get_record_with_property(
    array('table' => 'organism', 'base_records' => $identifiers), 
    array('type_name' => $property), 
    $options
    );
  }

  // Else we have a simple case and we can just use chado_generate_var to get the analysis
  else {

    // Try to get the organism
    $organism = chado_generate_var(
    'organism', 
    $identifiers, 
    $options
    );
  }

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

  // Report an error if $organism is FALSE since then chado_generate_var has failed
  elseif ($organism === FALSE) {
    tripal_report_error(
    'tripal_organism_api', 
    TRIPAL_ERROR, 
    "tripal_get_organism: chado_generate_var() failed to return a organism 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 organism :)
  else {
    return $organism;
  }
}