Tripal
Functions
Chado DB

Functions

 chado_get_db ($identifiers, $options=[], $schema_name=NULL)
 
 chado_get_db_select_options ($schema_name=NULL)
 
 chado_get_dbxref ($identifiers, $options=[], $schema_name=NULL)
 
 chado_get_dbxref_url ($dbxref, $options=[], $schema_name=NULL)
 
 chado_insert_db ($values, $options=[], $schema_name=NULL)
 
 chado_insert_dbxref ($values, $options=[], $schema_name=NULL)
 
 chado_associate_dbxref ($basetable, $record_id, $dbxref, $options=[], $schema_name=NULL)
 
 chado_autocomplete_dbxref ($db_id, $string='')
 

Detailed Description

External databases can be used to indicate the source for a variety of data. The most common use is with controlled vocabularies (CV). Chado expects that every CV have an external database record, where the database name must be the short name of the CV. In other cases, records such as features, stocks, libraries, etc., can also be present in remote databases and these associations can be made through dbxref linker tables. The API functions provided here provide tools to easily work with external databases.

Function Documentation

◆ chado_associate_dbxref()

chado_associate_dbxref (   $basetable,
  $record_id,
  $dbxref,
  $options = [],
  $schema_name = NULL 
)

Add a record to a database reference linking table (ie: feature_dbxref).

Parameters
$basetableThe base table for which the dbxref should be associated. Thus to associate a dbxref with a feature the basetable=feature and dbxref_id is added to the feature_dbxref table.
$record_idThe primary key of the basetable to associate the dbxref with. This should be in integer.
$dbxrefAn associative array describing the dbxref. Valid keys include: 'accession' => the accession for the dbxref, 'db_name' => the name of the database the dbxref belongs to. 'db_id' => the primary key of the database the dbxref belongs to.
$optionsAn associative array of options. Valid keys include:
  • insert_dbxref: Insert the dbxref if it doesn't already exist. TRUE is the default.
$schema_nameThe name of the chado schema the records reside in.

◆ chado_autocomplete_dbxref()

chado_autocomplete_dbxref (   $db_id,
  $string = '' 
)

This function is intended to be used in autocomplete forms for searching for accession that begin with the provided string.

Todo:
currently doesn't support multiple chado schema.
Parameters
$db_idThe DB ID in which to search for the term.
$stringThe string to search for.
Returns
A json array of terms that begin with the provided string.

◆ chado_get_db()

chado_get_db (   $identifiers,
  $options = [],
  $schema_name = NULL 
)

Retrieves a chado db variable.

Example Usage:

$select_values = array(
'name' => 'SOFP'
);
$db_object = chado_get_db($select_values);
chado_get_db($identifiers, $options=[], $schema_name=NULL)
Definition: tripal_chado.db.api.php:68

The above code selects the SOFP db and returns the following object:

$db_object = stdClass Object (
[db_id] => 49
[name] => SOFP
[description] =>
[urlprefix] =>
[url] =>
);
Parameters
$identifierAn array with the key stating what the identifier is. Supported keys (only on of the following unique keys is required):
  • db_id: the chado db.db_id primary key.
  • name: the chado db.name field (assume unique).
$optionsAn array of options. Supported keys include:
$schema_nameThe name of the schema the database you want to select is in.

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

Returns
If unique values were passed in as an identifier then an object describing the cv will be returned (will be a chado variable from chado_generate_var()). Otherwise, an array of objects will be returned.

◆ chado_get_db_select_options()

chado_get_db_select_options (   $schema_name = NULL)

Create an options array to be used in a form element which provides a list of all chado dbs.

Returns
An array(db_id => name) for each db in the chado db table.

◆ chado_get_dbxref()

chado_get_dbxref (   $identifiers,
  $options = [],
  $schema_name = NULL 
)

Retrieves a chado database reference variable.

Example Usage:

$identifiers = array(
'accession' => 'synonym',
'db_id' => array(
'name' => 'SOFP'
)
);
$dbxref_object = chado_get_dbxref($identifiers);
chado_get_dbxref($identifiers, $options=[], $schema_name=NULL)
Definition: tripal_chado.db.api.php:236

The above code selects the synonym database reference and returns the following object:

$dbxref_object = stdClass Object (
[dbxref_id] => 2581
[accession] => synonym
[description] =>
[version] =>
[db_db_id] => 49
[db_name] => SOFP
[db_description] =>
[db_urlprefix] =>
[db_url] =>
);
Parameters
$identifierAn array apropriate for use with the chado_generate_var for uniquely identifying a dbxref record. Alternatively, 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.
$optionsAn array of options. Supported keys include:
$schema_nameThe schema the database reference you want to retrieve is in.

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

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

◆ chado_get_dbxref_url()

chado_get_dbxref_url (   $dbxref,
  $options = [],
  $schema_name = NULL 
)

Generates a URL for the controlled vocabulary term.

If the URL and URL prefix are provided for the database record of a cvterm then a URL can be created for the term. By default, the db.name and dbxref.accession are concatenated and appended to the end of the db.urlprefix. But Tripal supports the use of {db} and {accession} tokens when if present in the db.urlprefix string will be replaced with the db.name and dbxref.accession respectively.

Parameters
$dbxrefA dbxref object as created by the chado_generate_var() function.
$optionsNone supported yet. Here for consistency.
$schema_nameThe name of the schema the database reference is in.
Returns
A string containing the URL.

◆ chado_insert_db()

chado_insert_db (   $values,
  $options = [],
  $schema_name = NULL 
)

Adds a new database to the Chado DB table and returns the DB object.

Parameters
$valuesAn associative array of the values of the db (those to be inserted):
  • name: The name of the database. This name is usually used as the prefix for CV term accessions.
  • description: (Optional) A description of the database. By default no description is required.
  • url: (Optional) The URL for the database.
  • urlprefix: (Optional) The URL that is to be used as a prefix when constructing a link to a database term.
$optionsOptional. An associative array of options that can include:
  • update_existing: Set this to '1' to force an update of the database if it already exists. The default is to not update. If the database exists then nothing is added.
$schema_nameOptional. The name of the schema the database should be inserted into.
Returns
An object populated with fields from the newly added database. If the database already exists it returns the values in the current entry.

◆ chado_insert_dbxref()

chado_insert_dbxref (   $values,
  $options = [],
  $schema_name = NULL 
)

Add a database reference.

Parameters
$valuesAn associative array of the values to be inserted including:
  • db_id: the database_id of the database the reference is from.
  • accession: the accession.
  • version: (Optional) The version of the database reference.
  • description: (Optional) A description of the database reference.
$optionsCurrently no options are supported. This is here for consistency throughout the API.
$schema_nameThe name of the schema to insert the dbxref into.
Returns
The newly inserted dbxref as an object, similar to that returned by the chado_select_record() function.