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

$basetable	The 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_id	The primary key of the basetable to associate the dbxref with. This should be in integer.
$dbxref	An 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.
$options	An associative array of options. Valid keys include: insert_dbxref: Insert the dbxref if it doesn't already exist. TRUE is the default.
$schema_name	The 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_id	The DB ID in which to search for the term.
$string	The 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);

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

$identifier	An 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).
$options	An array of options. Supported keys include: Any keys supported by chado_generate_var(). See that function definition for additional details.
$schema_name	The 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);

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

$identifier	An 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.
$options	An array of options. Supported keys include: Any keys supported by chado_generate_var(). See that function definition for additional details.
$schema_name	The 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

$dbxref	A dbxref object as created by the chado_generate_var() function.
$options	None supported yet. Here for consistency.
$schema_name	The 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

$values	An 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.
$options	Optional. 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_name	Optional. 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

$values	An 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.
$options	Currently no options are supported. This is here for consistency throughout the API.
$schema_name	The 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.