Chado CV

Functions
	chado_get_cv ($identifiers, $options=[], $schema_name=NULL)
	chado_get_cv_select_options ($schema_name=NULL)
	chado_get_cvterm ($identifiers, $options=[], $schema_name=NULL)
	chado_get_cvterm_select_options ($cv_id, $rel_type=FALSE, $schema_name=NULL)
	chado_insert_cv ($name, $definition, $options=[], $schema_name=NULL)
	chado_insert_cvterm ($term, $options=[], $schema_name=NULL)
	chado_autocomplete_cv ($string='')
	chado_autocomplete_cvterm ($cv_id, $string='')
	chado_associate_cvterm ($basetable, $record_id, $cvterm, $options, $schema_name)

Detailed Description

Provides API functions specifically for managing controlled vocabulary records in Chado. Please note that Tripal v3 provides a generic set of API functions for working with controlled vocabularies (CVs). This allows for CVs to be stored using any back-end. By default CV's continue to be housed in Chado. Therefore, if you are working directly with controlled vocabulary records inside of a Chado-aware module then these functions can be used.

Function Documentation

chado_associate_cvterm()

chado_associate_cvterm	(		$basetable,
			$record_id,
			$cvterm,
			$options,
			$schema_name
	)

Add a record to a cvterm linking table (ie: feature_cvterm).

Parameters

$basetable	The base table to which the cvterm should be linked/associated. Thus to associate a cvterm to a feature the basetable=feature and cvterm_id is added to the feature_cvterm table.
$record_id	The primary key of the basetable to associate the cvterm with. This should be in integer.
$cvterm	An associative array describing the cvterm. Valid keys include: name: the name for the cvterm, cv_name: the name of the cv the cvterm belongs to. cv_id: the primary key of the cv the cvterm belongs to.
$options	An associative array of options. Valid keys include: insert_cvterm: Insert the cvterm if it doesn't already exist. FALSE is the default.
$schema_name	The name of the chado schema the record resides in.

chado_autocomplete_cv()

chado_autocomplete_cv

(

$string = ''

)

This function is intended to be used in autocomplete forms.

This function searches for a matching controlled vobulary name.

Parameters

$string

The string to search for.

Returns

A json array of terms that begin with the provided string.

chado_autocomplete_cvterm()

chado_autocomplete_cvterm	(		$cv_id,
			$string = ''
	)

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

Parameters

$cv_id	The CV 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_cv()

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

Retrieves a chado controlled vocabulary variable

Parameters

$identifier	An array with the key stating what the identifier is. Supported keys (only on of the following unique keys is required): cv_id: the chado cv.cv_id primary key. name: the chado cv.name field (assume unique).
$options	An array of options. Supported keys include: Any keys supported by chado_generate_var(). See that function definition fot additional details.
$schema_name	The name of the chado schema the records reside in.

NOTE: the $identifier parameter can really be any array similar to $values passed into chado_select_record(). It should fully specify the cv 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, FALSE will be returned.

chado_get_cv_select_options()

chado_get_cv_select_options

(

$schema_name = NULL

)

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

Parameters

$schema_name

The name of the chado schema the records reside in.

Returns

An array(cv_id => name) for each cv in the chado cv table.

chado_get_cvterm()

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

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.
$schema_name	The name of the chado schema the records reside in.

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.

Returns

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.

chado_get_cvterm_select_options()

chado_get_cvterm_select_options	(		$cv_id,
			$rel_type = FALSE,
			$schema_name = NULL
	)

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

Parameters

$cv_id	The chado cv_id; only cvterms with the supplied cv_id will be returnedl.
$rel_type	Set to TRUE if the terms returned should only be relationship types in the vocabulary. This is useful for creating drop-downs of terms used for relationship linker tables.
$schema_name	The name of the chado schema the records reside in.

Returns

An associative array with the cvterm_id's as keys. The first element in the array has a key of '0' and a value of 'Select a Type'.

chado_insert_cv()

chado_insert_cv	(		$name,
			$definition,
			$options = [],
			$schema_name = NULL
	)

Adds a controlled vocabulary to the CV table of Chado.

Parameters

$name	The name of the controlled vocabulary. These are typically all lower case with no special characters other than an undrescore (for spaces).
$comment	A description or definition of the vocabulary.
$options	No options currently supported. For consistency.
$schema_name	The name of the chado schema the records reside in.

Returns

An object populated with fields from the newly added database.

chado_insert_cvterm()

chado_insert_cvterm	(		$term,
			$options = [],
			$schema_name = NULL
	)

Add's a controlled vocabulary term to Chado.

This function will add a cvterm record (and a dbxref record if appropriate values are provided). If the parent vocabulary does not exist then that also is added to the cv table. If the cvterm is a relationship term then the 'is_relationship' value should be set. All terms must also have a corresponding database. This is specified in the term's ID just before the colon (e.g. GO:003824). If the database does not exist in the DB table then it will be added automatically. The accession (the value just after the colon in the term's ID) will be added to the dbxref table. If the CVterm already exists and $update is set (default) then the cvterm is updated. If the CVTerm already exists and $update is not set, then no changes are made and the CVTerm object is returned.

Parameters

$term	An associative array with the following keys: id: the term accession. must be of the form <DB>:<ACCESSION>, where <DB> is the name of the database to which the cvterm belongs and the <ACCESSION> is the term's accession number in the database. name: the name of the term. usually meant to be human-readable. is_obsolete: is present and set to 1 if the term is defunct. definition: the definition of the term. cv_name: The CV name to which the term belongs. If this arugment is null or not provided then the function tries to find a record in the CV table with the same name provided in the $term[namespace]. If this field is provided then it overrides what the value in $term[namespace]. is_relationship: If this term is a relationship term then this value should be 1. db_name: In some cases the database name will not be part of the $term['id'] and it needs to be explicitly set. Use this argument only if the database name cannot be specififed in the term ID (e.g. <DB>:<ACCESSION>).
$options	An associative array with the following keys: update_existing: By default this is TRUE. If the term exists it is automatically updated.
$schema_name	The name of the chado schema the records reside in.

Returns

A cvterm object