Chado CV

Collaboration diagram for Chado CV:

Functions
	chado_get_cv ($identifiers, $options=[])
	chado_get_cv_select_options ()
	chado_get_cvterm ($identifiers, $options=[])
	chado_get_cvterm_select_options ($cv_id, $rel_type=FALSE)
	tripal_update_cvtermpath_old ($cv_id, $job_id=NULL)
	chado_update_cvtermpath ($cv_id, $job=NULL)
	chado_insert_cv ($name, $definition)
	chado_insert_cvterm ($term, $options=[])
	chado_submit_obo_job ($obo)
	chado_insert_obo ($name, $path)
	chado_get_obo ($values)
	chado_autocomplete_cv ($string='')
	chado_autocomplete_cvterm ($cv_id, $string='')
	chado_associate_cvterm ($basetable, $record_id, $cvterm, $options=[])

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 = []
	)

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.

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 = []
	)

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.

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

(

)

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

Returns

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

chado_get_cvterm()

chado_get_cvterm	(		$identifiers,
			$options = []
	)

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.

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
	)

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.

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_get_obo()

chado_get_obo

(

$values

)

Retrieves an OBO record.

Parameters

$values

An associate array with the following allowed keys: obo_id, name.

Returns

An instance of an OBO record object.

chado_insert_cv()

chado_insert_cv	(		$name,
			$definition
	)

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.

Returns

An object populated with fields from the newly added database.

chado_insert_cvterm()

chado_insert_cvterm	(		$term,
			$options = []
	)

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.

Returns

A cvterm object

chado_insert_obo()

chado_insert_obo	(		$name,
			$path
	)

Add the OBO to the tripal_cv_obo table in the Drupal database.

If the OBO name already exists in the table then the path is updated.

Parameters

$name	The human readable name of this ontology.
$path	The file path or URL of the ontology.

Returns

Returns the ontology ID.

chado_submit_obo_job()

chado_submit_obo_job

(

$obo

)

TODO: deprecate this function

Avoid using this function as it will be deprecated in future releases.

This function allows other modules to programatically submit an ontology for loading into Chado.

This function will add a job to the Jobs subsystem for parsing the ontology. You can either pass a known OBO ID to the function or the URL or full path the the ontology file. If a URL or file name is passed then the $obo_name argument must also be provided. If this is the first time the ontology has been provided to Tripal then it will be added to the database and will be assigned a unique OBO ID.

Parameters

$obo_id	If the ontology is already loaded into the Tripal tables then use this argument to specify the unique ID for the ontology that will be loaded.
$obo_name	If the OBO has not been added before then use this argument to specify the human readable name of the ontology.
$obo_url	If the OBO to be loaded is located on a remote server then use this argument to provide the URL.
$obo_file	If the OBO is housed on the local file system of the server then use this argument to specify the full path.

Returns

returns the job_id of the submitted job or FALSE if the job was not added

chado_update_cvtermpath()

chado_update_cvtermpath	(		$cv_id,
			$job = NULL
	)

Replacement for the fill_cvtermpath() stored procedure in Chado.

Fills the cvtermpath table of Chado with relationships between every node in the ontology graph and all of it's descendents. This was previously performed using the fill_cvtermpath() stored procedure of Chado but that function cannot handle loops in the ontology graphs and results in stack depth errors in PostgreSQL.

Parameters

$cv_id	The controlled vocabulary ID from the cv table of Chado (i.e. cv.cv_id).
$job	An instance of a TripalJob.

tripal_update_cvtermpath_old()

tripal_update_cvtermpath_old	(		$cv_id,
			$job_id = NULL
	)

Updates the cvtermpath table of Chado for the specified CV.

Parameters

$cv_id	The chado cv_id.
$job_id	This function is intended to be used with the Tripal Jobs API. When this function is called as a job the $job_id is automatically passed to this function.

Returns

TRUE on success FALSE on failure.