123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513 |
- <?php
- /**
- * @defgroup tripal_cv_api CV Module API
- * @ingroup tripal_api
- * @ingroup tripal_cv
- * This module provides a set of functions to simplify working with
- * controlled vocabularies. Most of the API functions deal with retrieving
- * terms or their parent vocabularies.
- *
- * However, the API also supports
- * generation of trees for browsing a vocabulary as well as generation of
- * pie graphs for display of hierarchical counts of terms. Version 0.3b of
- * Tripal provides a feature browser and a feature summary chart uses
- * the API functions provided here. But in general charts and trees can be
- * created for any controlled vocabulary.
- *
- */
- /**
- * Purpose: To retrieve a chado controlled vocabulary object
- *
- * @param $select_values
- * An array meant to uniquely select a given controlled vocabulary
- *
- * @return
- * Chado controlled vocabulary object
- *
- * The controlled vocabulary is selected using tripal_core_chado select and as such the
- * $select_values array parameter meant to uniquely identify the controlled vocab to be
- * returned follows the same form as when using tripal_core_chado_select directly.
- *
- * Example Usage:
- * @code
- $select_values = array(
- 'name' => 'feature_property'
- );
- $cv_object = tripal_cv_get_cv($select_values);
- * @endcode
- * The above code selects the feature_property cv and returns the following object:
- * @code
- $cv_object = stdClass Object (
- [cv_id] => 13
- [name] => feature_property
- [definition] =>
- );
- * @endcode
- *
- * @ingroup tripal_cv_api
- */
- function tripal_cv_get_cv ($select_values) {
- $columns = array(
- 'cv_id',
- 'name',
- 'definition',
- );
- $results = tripal_core_chado_select('cv', $columns, $select_values);
- if (sizeof($results) == 1) {
- return $results[0];
- } elseif (empty($results)) {
- watchdog('tripal_cv',
- 'tripal_cv_get_cv: No cv matches criteria values:%values',
- array('%values' => print_r($select_values, TRUE)),
- WATCHDOG_WARNING
- );
- return FALSE;
- } else {
- watchdog('tripal_cv',
- 'tripal_cv_get_cv: 2+ cvs match criteria values:%values',
- array('%values' => print_r($select_values, TRUE)),
- WATCHDOG_WARNING
- );
- }
-
- }
- // Purpose: To retrieve a chado cv object
- // @param $where_options
- // @code
- // array(
- // <column_name> => array(
- // 'type' => <type of column: INT/STRING>,
- // 'value' => <the vlaue you want to filter on>,
- // 'exact' => <if TRUE use =; if FALSE use ~>,
- // )
- // )
- // @endcode
- //
- // @return
- // Chado cv object with all fields from the chado cv table
- //
- // @ingroup tripal_cv_api
- //
- //function tripal_cv_get_cv ($where_options)
- /**
- * Retrieve a cv given the cv name
- *
- * @param $name
- * The name of the cv to be returned
- * @return
- * The cv object for the specified CV name
- *
- * @ingroup tripal_cv_api
- */
- function tripal_cv_get_cv_by_name ($name) {
- $previous_db = tripal_db_set_active('chado');
- $r = db_fetch_object(db_query("SELECT * FROM cv WHERE name = '%s'",$name));
- tripal_db_set_active($previous_db);
- return $r;
- }
- /**
- * Retrieve the cv object for the specified CV id
- *
- * NOTE: This function is deprecated.
- * @see tripal_core_chado_generate_vars
- *
- * @param $cv_id
- * The unique identifier for the cv retrieve
- *
- * @return
- * An object describing the cv
- *
- * @ingroup tripal_cv_api
- */
- function tripal_cv_get_cv_by_id ($cv_id) {
- $previous_db = tripal_db_set_active('chado');
- $r = db_fetch_object(db_query("SELECT * FROM cv WHERE cv_id = %d",$cv_id));
- tripal_db_set_active($previous_db);
- return $r;
- }
- /**
- * Create an options array to be used in a form element which provides a list of all chado cvs
- *
- * @return
- * An array(cv_id => name) for each cv in the chado cv table
- *
- * @ingroup tripal_cv_api
- */
- function tripal_cv_get_cv_options() {
- $previous_db = tripal_db_set_active('chado');
- $result = db_query(
- "SELECT cv_id, name FROM cv"
- );
- tripal_db_set_active($previous_db);
- $options = array();
- while ( $r = db_fetch_object($result) ) {
- $options[$r->cv_id] = $r->name;
- }
- return $options;
- }
- /**
- * Retrieve a chado cvterm object with a given name
- *
- * @param $name
- * the cvterm.name
- * @param $cv_id
- * the cv_id of the term you are looking for
- * @param $cv_name
- * the name of the CV
- *
- * @return
- * cvterm object
- *
- * @ingroup tripal_cv_api
- */
- function tripal_cv_get_cvterm_by_name ($name, $cv_id=0,$cv_name='tripal') {
- if ($cv_id) {
- $values = array(
- 'name' => $name,
- 'cv_id' => $cv_id,
- );
- $r = tripal_core_chado_select('cvterm',array('*'),$values);
- }
- elseif($cv_name){
- $values = array(
- 'name' => $name,
- 'cv_id' => array(
- 'name' => $cv_name,
- ),
- );
- $r = tripal_core_chado_select('cvterm',array('*'),$values);
- }
- else {
- $values = array(
- 'name' => $name,
- );
- $r = tripal_core_chado_select('cvterm',array('*'),$values);
- }
-
- if(!$r){
- return FALSE;
- }
- if(count($r) > 0){
- return FALSE;
- }
- return $r[0];
- }
- /**
- * Create an options array to be used in a form element
- * which provides a list of all chado cvterms
- *
- * @param $cv_id
- * The chado cv_id;
- * only cvterms with the supplied cv_id will be returned
- * @return
- * An array(cvterm_id => name)
- * for each cvterm in the chado cvterm table where cv_id=that supplied
- *
- * @ingroup tripal_cv_api
- */
- function tripal_cv_get_cvterm_options($cv_id = 0) {
- $previous_db = tripal_db_set_active('chado');
- if ($cv_id > 0) {
- $result = db_query(
- "SELECT cvterm_id, name FROM cvterm WHERE cv_id=%d", $cv_id
- );
- } else {
- $result = db_query(
- "SELECT cvterm_id, name FROM cvterm"
- );
- }
- tripal_db_set_active($previous_db);
- $options = array();
- while ( $r = db_fetch_object($result) ) {
- $options[$r->cvterm_id] = $r->name;
- }
- return $options;
- }
- /**
- * Implements hook_chado_cvterm_schema()
- * Purpose: To add descriptions and foreign keys to default table description
- * Note: This array will be merged with the array from all other implementations
- *
- * @return
- * Array describing the cvterm table
- *
- * @ingroup tripal_schema_api
- */
- function tripal_cv_chado_cvterm_schema() {
- $description = array();
- $description['foreign keys']['cv'] = array(
- 'table' => 'cv',
- 'columns' => array(
- 'cv_id' => 'cv_id',
- ),
- );
-
- $description['foreign keys']['dbxref'] = array(
- 'table' => 'dbxref',
- 'columns' => array(
- 'dbxref_id' => 'dbxref_id',
- ),
- );
- return $description;
- }
- /**
- * Adds a controlled vocabular to the CV table of Chado.
- *
- * @param $name
- * The name of the controlled vocabulary. These are typically all lower case
- * with no special characters other than an undrescore (for spaces).
- * @param $comment
- * A description or definition of the vocabulary.
- *
- * @return
- * An object populated with fields from the newly added database.
- *
- * @ingroup tripal_cv_api
- */
- function tripal_cv_add_cv($name,$comment){
- // see if the CV (default-namespace) exists already in the database
- $vocab = $name;
- $remark = $comment;
- $cv_sql = "SELECT * FROM {cv} WHERE name = '%s'";
- $cv = db_fetch_object(db_query($cv_sql,$vocab));
- // if the CV exists then update it, otherwise insert
- if(!$cv){
- $sql = "INSERT INTO {cv} (name,definition) VALUES ('%s','%s')";
- if(!db_query($sql,$vocab,$remark)){
- watchdog('tripal_cv', "Failed to create the CV record",NULL,WATCHDOG_WARNING);
- return 0;
- }
- $cv = db_fetch_object(db_query($cv_sql,$vocab));
- } else {
- $sql = "UPDATE {cv} SET definition = '%s' WHERE name ='%s'";
- if(!db_query($sql,$remark,$vocab)){
- watchdog('tripal_cv', "Failed to update the CV record",NULL,WATCHDOG_WARNING);
- return 0;
- }
- $cv = db_fetch_object(db_query($cv_sql,$vocab));
- }
- return $cv;
- }
- /**
- * Add's a CV term to the cvterm table. If the parent CV does not exist then
- * that too is added to the CV table. If the cvterm is a relationship term
- * then the $is_relationship argument should be set. The function will try
- * to first find the relationship in the relationship ontology for updating and
- * if it can't be found will add the relationship to the __global CV. 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.
- *
- * @param $term
- * An associative array with the following keys: 'id', 'name' and 'namespace',
- * 'is_obsolete', and 'def'. Where 'id' is the term accession, 'name' is the
- * term name, 'namespace' is the CV name for the term, 'def' is the term
- * definition and 'is_obsolete' is present and set to 1 if the term is defunct.
- * The 'id' 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.
- * @param $defaultcv
- * Optional. 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]
- * @param $is_relationship
- * If this term is a relationship term then this value should be 1.
- * @param $update
- * By default this is set to 1. If the term exists it is automatically updated.
- * @param $dbname
- * 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>).
- *
- * @return
- * A CVTerm object
- *
- * @ingroup tripal_cv_api
- */
- function tripal_cv_add_cvterm($term,$defaultcv='',$is_relationship = 0,$update = 1,$dbname=NULL){
- // get the term properties
- $id = $term['id'];
- $name = $term['name'];
- $cvname = $term['namespace'];
- $definition = preg_replace('/^\"(.*)\"/','\1',$term['def']);
- $is_obsolete = 0;
- if(isset($term['is_obsolete']) and strcmp($term['is_obsolete'],'true')==0){
- $is_obsolete = 1;
- }
- if(!$name and !$id){
- watchdog('tripal_cv', "Cannot find cvterm without 'id' or 'name'",NULL,WATCHDOG_WARNING);
- return 0;
- }
- if(!$id){
- $id = $name;
- }
- if(!$name){
- $name = $id;
- }
- if(!$cvname){
- $cvname = $defaultcv;
- }
- // make sure the CV name exists
- $cv = tripal_cv_add_cv($cvname,'');
- if(!$cv){
- watchdog('tripal_cv', "Cannot find namespace '$cvname' when adding/updating $id",NULL,WATCHDOG_WARNING);
- return 0;
- }
- // this SQL statement will be used a lot to find a cvterm so just set it
- // here for easy reference below. Because CV terms can change their names
- // but accessions don't change, the following SQL finds cvterms based on
- // their accession rather than the name
- $cvtermsql = "SELECT CVT.name, CVT.cvterm_id, DB.name as dbname, DB.db_id
- FROM {cvterm} CVT
- INNER JOIN {dbxref} DBX on CVT.dbxref_id = DBX.dbxref_id
- INNER JOIN {db} DB on DBX.db_id = DB.db_id
- INNER JOIN {cv} CV on CV.cv_id = CVT.cv_id
- WHERE DBX.accession = '%s' and DB.name = '%s'";
- // get the accession and the database from the cvterm
- if($dbname){
- $accession = $id;
- }
- elseif(preg_match('/^.+?:.*$/',$id)){
- $accession = preg_replace('/^.+?:(.*)$/','\1',$id);
- $dbname = preg_replace('/^(.+?):.*$/','\1',$id);
- }
- if($is_relationship and !$dbname){
- $accession = $id;
- // because this is a relationship cvterm first check to see if it
- // exists in the relationship ontology. If it does then return the cvterm.
- // If not then set the dbname to _global and we'll add it or find it there
- $cvterm = db_fetch_object(db_query($cvtermsql,$accession,'OBO_REL'));
- if($cvterm){
- return $cvterm;
- } else {
- // next check if this term is in the _global ontology. If it is then
- // return it no matter what the original CV
- $dbname = '_global';
- $cvterm = db_fetch_object(db_query($cvtermsql,$accesion,$dbname));
- if($cvterm){
- return $cvterm;
- }
- }
- }
- if(!$is_relationship and !$dbname){
- watchdog('tripal_cv', "A database identifier is missing from the term: $id",NULL,WATCHDOG_WARNING);
- return 0;
- }
- // add the database. The function will just return the DB object if the
- // database already exists.
- $db = tripal_db_add_db($dbname);
- if(!$db){
- watchdog('tripal_cv', "Cannot find database '$dbname' in Chado.",NULL,WATCHDOG_WARNING);
- return 0;
- }
- // if the cvterm doesn't exist then add it otherwise just update it
- $cvterm = db_fetch_object(db_query($cvtermsql,$accession,$dbname));
- if(!$cvterm){
- // check to see if the dbxref exists if not, add it
- $dbxref = tripal_db_add_dbxref($db->db_id,$accession);
- if(!$dbxref){
- watchdog('tripal_cv', "Failed to find or insert the dbxref record for cvterm, $name (id: $accession), for database $dbname",NULL,WATCHDOG_WARNING);
- return 0;
- }
- // check to see if the dbxref already has an entry in the cvterm table
- $sql = "SELECT * FROM {cvterm} WHERE dbxref_id = %d";
- $check = db_fetch_object(db_query($sql,$dbxref->dbxref_id));
- if(!$check){
- // now add the cvterm
- $sql = "
- INSERT INTO {cvterm} (cv_id, name, definition, dbxref_id,
- is_obsolete, is_relationshiptype)
- VALUES (%d,'%s','%s',%d,%d,%d)
- ";
- if(!db_query($sql,$cv->cv_id,$name,$definition,
- $dbxref->dbxref_id,$is_obsolete,$is_relationship)){
- if(!$is_relationship){
- watchdog('tripal_cv', "Failed to insert the term: $name ($dbname)",NULL,WATCHDOG_WARNING);
- return 0;
- } else {
- watchdog('tripal_cv', "Failed to insert the relationship term: $name (cv: " . $cvname . " db: $dbname)",NULL,WATCHDOG_WARNING);
- return 0;
- }
- }
- }
- // if the dbxref already exists check to make sure it exists for the correct databaes name
- // if it does then we're good and we don't need to do anything
- elseif($check and strcmp($check->name,$name)==0){
- // this entry already exists. We're good, so do nothing
- }
- // if the dbxref exists but does not map to the same database name
- elseif($check and strcmp($check->name,$name)!=0){
- watchdog('tripal_cv', "The dbxref already exists in the cvterm table. DBXREF ID: $dbxref->dbxref_id, ACCESSION: $accession. DB: '".$dbxref->db_name ."'. term '$name'. The requested db was '$dbname'",NULL,WATCHDOG_WARNING);
- return 0;
- }
- $cvterm = db_fetch_object(db_query($cvtermsql,$name,$dbname));
- if(!$is_relationship){
- print "Added CV term: $name ($dbname)\n";
- } else {
- print "Added relationship CV term: $name ($dbname)\n";
- }
- }
- elseif($update) { // update the cvterm
- $sql = "
- UPDATE {cvterm} SET name='%s', definition='%s',
- is_obsolete = %d, is_relationshiptype = %d
- WHERE cvterm_id = %d
- ";
- if(!db_query($sql,$term['name'],$definition,
- $is_obsolete,$is_relationship,$cvterm->cvterm_id)){
- watchdog('tripal_cv', "Failed to update the term: $name",NULL,WATCHDOG_WARNING);
- return 0;
- }
- $cvterm = db_fetch_object(db_query($cvtermsql,$name,$dbname));
- if(!$is_relationship){
- print "Updated CV term: $name ($dbname)\n";
- } else {
- print "Updated relationship CV term: $name ($dbname)\n";
- }
- }
- // return the cvterm
- return $cvterm;
- }
|