Buddy Parameters

Chado Buddy Input Values

Values are passed to a buddy function through an associative array. The keys for this array are the chado table name and the table column name separated by a period. For example, for the table db and column name, the key would be db.name. This method prevents ambiguity when a buddy handles more than one table, and different tables may have the same column name, such as db.name and cv.name.

Any or all input values can be also be passed in using a ChadoBuddyRecord, using the key buddy_record in the values array.

Chado Buddy Output Values

Depending on the function, most of the chado buddy functions will return one or more objects of the class ChadoBuddyRecord. An object of this class provides two functions to retrieve values:

  1. $chado_buddy_record->getValues() - this function returns an associative array in the same format as was used to pass input data.

  2. $chado_buddy_record->getValue($key, $options) - this function returns a single value from the record. By default, if the passed key does not exist, an exception is thrown. This strict mode can be disabled and a NULL will be returned instead. Enable this lenient mode with:

    $options = ['strict' => FALSE]

Note

For insert and update functions, the function will return a single object of the ChadoBuddyRecord class.

For query functions, the function will return an array of ChadoBuddyRecord records. This array will be empty if no records matched the input values, and can have one or more records if matches were found.

Chado Buddy Example #1

Here is a simple example to look up the db_id value of the local database record.

$buddy_service = \Drupal::service('tripal_chado.chado_buddy');
$dbxref_instance = $buddy_service->createInstance('chado_dbxref_buddy', []);

$chado_buddy_records = $dbxref_instance->getDb(['db.name' => 'local'], []);
$db_id = NULL;
if ($chado_buddy_records) {
  $db_id = $chado_buddy_records[0]->getValue('db.db_id');
  print "local db id=$db_id\n";
}

Chado Buddy Example #2

Here is a more advanced example of creating a new controlled vocabulary term, including a dbxref, and using that term to assign a property to a gene.

$buddy_service = \Drupal::service('tripal_chado.chado_buddy');
$cvterm_instance = $buddy_service->createInstance('chado_cvterm_buddy', []);
$property_instance = $buddy_service->createInstance('chado_property_buddy', []);

// Create the cvterm and dbxref records in chado, unless they already exist.
$values = [
  'db.name' => 'local',
  'cv.name' => 'local',
  'dbxref.accession' => 'X000002',
  'cvterm.name' => 'Example 2',
  'cvterm.definition' => 'A fake ontology term for example #2',
];
$chado_cvterm_record = $cvterm_instance->upsertCvterm($values, []);
// if for any reason insert failed, an exception is thrown, so
// you should catch exceptions as shown in example #3
$cvterm_id = $chado_cvterm_record->getValue('cvterm.cvterm_id');
print "Created or found cvterm with id=$cvterm_id\n";

// Create the property record in the featureprop table
$feature_id = 1; // For this example, assume a gene feature already exists with this id
// Here we demonstrate passing all the cvterm values using a ChadoBuddyRecord
$values = [
  'buddy_record' => $chado_cvterm_record,
  'featureprop.value' => 'Example value of 2 for the property',
];
$chado_property_record = $property_instance->upsertProperty('feature', $feature_id, $values, []);
$featureprop_id = $chado_property_record->getValue('featureprop.featureprop_id');
print "Added property with id=$featureprop_id\n";

Chado Buddy Example #3

This is the same as example #2, but we enable a mode where we can create the cvterm and dbxref automatically if it does not already exist, as long as we have all the values required to do so. In addition, we catch any exceptions that may occur so we can handle them appropriately, for example, the database or CV names we supplied might not exist.

$buddy_service = \Drupal::service('tripal_chado.chado_buddy');
$property_instance = $buddy_service->createInstance('chado_property_buddy', []);

$values = [
  'db.name' => 'local',
  'cv.name' => 'local',
  'dbxref.accession' => 'X000003',
  'cvterm.name' => 'Example 3',
  'cvterm.definition' => 'A fake ontology term for example #3',
  'featureprop.value' => 'Example value of 3 for the property',
];
// This option triggers the ability to create the term and dbxref automatically
$options = [
  'create_cvterm' => TRUE,
];
$feature_id = 1; // For this example, assume a gene feature already exists with this id
// Catch exceptions in case anything goes wrong
try {
  $chado_property_record = $property_instance->upsertProperty('feature', $feature_id, $values, $options);
}
catch (\Exception $e) {
  print $e->getMessage();
}
$featureprop_id = $chado_property_record->getValue('featureprop.featureprop_id');
print "Added property with id=$featureprop_id\n";