tripal_cv.api.inc 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513
  1. <?php
  2. /**
  3. * @defgroup tripal_cv_api CV Module API
  4. * @ingroup tripal_api
  5. * @ingroup tripal_cv
  6. * This module provides a set of functions to simplify working with
  7. * controlled vocabularies. Most of the API functions deal with retrieving
  8. * terms or their parent vocabularies.
  9. *
  10. * However, the API also supports
  11. * generation of trees for browsing a vocabulary as well as generation of
  12. * pie graphs for display of hierarchical counts of terms. Version 0.3b of
  13. * Tripal provides a feature browser and a feature summary chart uses
  14. * the API functions provided here. But in general charts and trees can be
  15. * created for any controlled vocabulary.
  16. *
  17. */
  18. /**
  19. * Purpose: To retrieve a chado controlled vocabulary object
  20. *
  21. * @param $select_values
  22. * An array meant to uniquely select a given controlled vocabulary
  23. *
  24. * @return
  25. * Chado controlled vocabulary object
  26. *
  27. * The controlled vocabulary is selected using tripal_core_chado select and as such the
  28. * $select_values array parameter meant to uniquely identify the controlled vocab to be
  29. * returned follows the same form as when using tripal_core_chado_select directly.
  30. *
  31. * Example Usage:
  32. * @code
  33. $select_values = array(
  34. 'name' => 'feature_property'
  35. );
  36. $cv_object = tripal_cv_get_cv($select_values);
  37. * @endcode
  38. * The above code selects the feature_property cv and returns the following object:
  39. * @code
  40. $cv_object = stdClass Object (
  41. [cv_id] => 13
  42. [name] => feature_property
  43. [definition] =>
  44. );
  45. * @endcode
  46. *
  47. * @ingroup tripal_cv_api
  48. */
  49. function tripal_cv_get_cv ($select_values) {
  50. $columns = array(
  51. 'cv_id',
  52. 'name',
  53. 'definition',
  54. );
  55. $results = tripal_core_chado_select('cv', $columns, $select_values);
  56. if (sizeof($results) == 1) {
  57. return $results[0];
  58. } elseif (empty($results)) {
  59. watchdog('tripal_cv',
  60. 'tripal_cv_get_cv: No cv matches criteria values:%values',
  61. array('%values' => print_r($select_values, TRUE)),
  62. WATCHDOG_WARNING
  63. );
  64. return FALSE;
  65. } else {
  66. watchdog('tripal_cv',
  67. 'tripal_cv_get_cv: 2+ cvs match criteria values:%values',
  68. array('%values' => print_r($select_values, TRUE)),
  69. WATCHDOG_WARNING
  70. );
  71. }
  72. }
  73. // Purpose: To retrieve a chado cv object
  74. // @param $where_options
  75. // @code
  76. // array(
  77. // <column_name> => array(
  78. // 'type' => <type of column: INT/STRING>,
  79. // 'value' => <the vlaue you want to filter on>,
  80. // 'exact' => <if TRUE use =; if FALSE use ~>,
  81. // )
  82. // )
  83. // @endcode
  84. //
  85. // @return
  86. // Chado cv object with all fields from the chado cv table
  87. //
  88. // @ingroup tripal_cv_api
  89. //
  90. //function tripal_cv_get_cv ($where_options)
  91. /**
  92. * Retrieve a cv given the cv name
  93. *
  94. * @param $name
  95. * The name of the cv to be returned
  96. * @return
  97. * The cv object for the specified CV name
  98. *
  99. * @ingroup tripal_cv_api
  100. */
  101. function tripal_cv_get_cv_by_name ($name) {
  102. $previous_db = tripal_db_set_active('chado');
  103. $r = db_fetch_object(db_query("SELECT * FROM cv WHERE name = '%s'",$name));
  104. tripal_db_set_active($previous_db);
  105. return $r;
  106. }
  107. /**
  108. * Retrieve the cv object for the specified CV id
  109. *
  110. * NOTE: This function is deprecated.
  111. * @see tripal_core_chado_generate_vars
  112. *
  113. * @param $cv_id
  114. * The unique identifier for the cv retrieve
  115. *
  116. * @return
  117. * An object describing the cv
  118. *
  119. * @ingroup tripal_cv_api
  120. */
  121. function tripal_cv_get_cv_by_id ($cv_id) {
  122. $previous_db = tripal_db_set_active('chado');
  123. $r = db_fetch_object(db_query("SELECT * FROM cv WHERE cv_id = %d",$cv_id));
  124. tripal_db_set_active($previous_db);
  125. return $r;
  126. }
  127. /**
  128. * Create an options array to be used in a form element which provides a list of all chado cvs
  129. *
  130. * @return
  131. * An array(cv_id => name) for each cv in the chado cv table
  132. *
  133. * @ingroup tripal_cv_api
  134. */
  135. function tripal_cv_get_cv_options() {
  136. $previous_db = tripal_db_set_active('chado');
  137. $result = db_query(
  138. "SELECT cv_id, name FROM cv"
  139. );
  140. tripal_db_set_active($previous_db);
  141. $options = array();
  142. while ( $r = db_fetch_object($result) ) {
  143. $options[$r->cv_id] = $r->name;
  144. }
  145. return $options;
  146. }
  147. /**
  148. * Retrieve a chado cvterm object with a given name
  149. *
  150. * @param $name
  151. * the cvterm.name
  152. * @param $cv_id
  153. * the cv_id of the term you are looking for
  154. * @param $cv_name
  155. * the name of the CV
  156. *
  157. * @return
  158. * cvterm object
  159. *
  160. * @ingroup tripal_cv_api
  161. */
  162. function tripal_cv_get_cvterm_by_name ($name, $cv_id=0,$cv_name='tripal') {
  163. if ($cv_id) {
  164. $values = array(
  165. 'name' => $name,
  166. 'cv_id' => $cv_id,
  167. );
  168. $r = tripal_core_chado_select('cvterm',array('*'),$values);
  169. }
  170. elseif($cv_name){
  171. $values = array(
  172. 'name' => $name,
  173. 'cv_id' => array(
  174. 'name' => $cv_name,
  175. ),
  176. );
  177. $r = tripal_core_chado_select('cvterm',array('*'),$values);
  178. }
  179. else {
  180. $values = array(
  181. 'name' => $name,
  182. );
  183. $r = tripal_core_chado_select('cvterm',array('*'),$values);
  184. }
  185. if(!$r){
  186. return FALSE;
  187. }
  188. if(count($r) > 0){
  189. return FALSE;
  190. }
  191. return $r[0];
  192. }
  193. /**
  194. * Create an options array to be used in a form element
  195. * which provides a list of all chado cvterms
  196. *
  197. * @param $cv_id
  198. * The chado cv_id;
  199. * only cvterms with the supplied cv_id will be returned
  200. * @return
  201. * An array(cvterm_id => name)
  202. * for each cvterm in the chado cvterm table where cv_id=that supplied
  203. *
  204. * @ingroup tripal_cv_api
  205. */
  206. function tripal_cv_get_cvterm_options($cv_id = 0) {
  207. $previous_db = tripal_db_set_active('chado');
  208. if ($cv_id > 0) {
  209. $result = db_query(
  210. "SELECT cvterm_id, name FROM cvterm WHERE cv_id=%d", $cv_id
  211. );
  212. } else {
  213. $result = db_query(
  214. "SELECT cvterm_id, name FROM cvterm"
  215. );
  216. }
  217. tripal_db_set_active($previous_db);
  218. $options = array();
  219. while ( $r = db_fetch_object($result) ) {
  220. $options[$r->cvterm_id] = $r->name;
  221. }
  222. return $options;
  223. }
  224. /**
  225. * Implements hook_chado_cvterm_schema()
  226. * Purpose: To add descriptions and foreign keys to default table description
  227. * Note: This array will be merged with the array from all other implementations
  228. *
  229. * @return
  230. * Array describing the cvterm table
  231. *
  232. * @ingroup tripal_schema_api
  233. */
  234. function tripal_cv_chado_cvterm_schema() {
  235. $description = array();
  236. $description['foreign keys']['cv'] = array(
  237. 'table' => 'cv',
  238. 'columns' => array(
  239. 'cv_id' => 'cv_id',
  240. ),
  241. );
  242. $description['foreign keys']['dbxref'] = array(
  243. 'table' => 'dbxref',
  244. 'columns' => array(
  245. 'dbxref_id' => 'dbxref_id',
  246. ),
  247. );
  248. return $description;
  249. }
  250. /**
  251. * Adds a controlled vocabular to the CV table of Chado.
  252. *
  253. * @param $name
  254. * The name of the controlled vocabulary. These are typically all lower case
  255. * with no special characters other than an undrescore (for spaces).
  256. * @param $comment
  257. * A description or definition of the vocabulary.
  258. *
  259. * @return
  260. * An object populated with fields from the newly added database.
  261. *
  262. * @ingroup tripal_cv_api
  263. */
  264. function tripal_cv_add_cv($name,$comment){
  265. // see if the CV (default-namespace) exists already in the database
  266. $vocab = $name;
  267. $remark = $comment;
  268. $cv_sql = "SELECT * FROM {cv} WHERE name = '%s'";
  269. $cv = db_fetch_object(db_query($cv_sql,$vocab));
  270. // if the CV exists then update it, otherwise insert
  271. if(!$cv){
  272. $sql = "INSERT INTO {cv} (name,definition) VALUES ('%s','%s')";
  273. if(!db_query($sql,$vocab,$remark)){
  274. watchdog('tripal_cv', "Failed to create the CV record",NULL,WATCHDOG_WARNING);
  275. return 0;
  276. }
  277. $cv = db_fetch_object(db_query($cv_sql,$vocab));
  278. } else {
  279. $sql = "UPDATE {cv} SET definition = '%s' WHERE name ='%s'";
  280. if(!db_query($sql,$remark,$vocab)){
  281. watchdog('tripal_cv', "Failed to update the CV record",NULL,WATCHDOG_WARNING);
  282. return 0;
  283. }
  284. $cv = db_fetch_object(db_query($cv_sql,$vocab));
  285. }
  286. return $cv;
  287. }
  288. /**
  289. * Add's a CV term to the cvterm table. If the parent CV does not exist then
  290. * that too is added to the CV table. If the cvterm is a relationship term
  291. * then the $is_relationship argument should be set. The function will try
  292. * to first find the relationship in the relationship ontology for updating and
  293. * if it can't be found will add the relationship to the __global CV. All terms
  294. * must also have a corresponding database. This is specified in the term's
  295. * ID just before the colon (e.g. GO:003824). If the database does not exist
  296. * in the DB table then it will be added automatically. The accession (the
  297. * value just after the colon in the term's ID) will be added to the dbxref
  298. * table. If the CVterm already exists and $update is set (default) then the
  299. * cvterm is updated. If the CVTerm already exists and $update is not set, then
  300. * no changes are made and the CVTerm object is returned.
  301. *
  302. * @param $term
  303. * An associative array with the following keys: 'id', 'name' and 'namespace',
  304. * 'is_obsolete', and 'def'. Where 'id' is the term accession, 'name' is the
  305. * term name, 'namespace' is the CV name for the term, 'def' is the term
  306. * definition and 'is_obsolete' is present and set to 1 if the term is defunct.
  307. * The 'id' must be of the form <DB>:<ACCESSION>, where <DB> is the name of
  308. * the database to which the cvterm belongs and the <ACCESSION> is the
  309. * term's accession number in the database.
  310. * @param $defaultcv
  311. * Optional. The CV name to which the term
  312. * belongs. If this arugment is null or not provided then the function tries
  313. * to find a record in the CV table with the same name provided in the
  314. * $term[namespace]. If this field is provided then it overrides what the
  315. * value in $term[namespace]
  316. * @param $is_relationship
  317. * If this term is a relationship term then this value should be 1.
  318. * @param $update
  319. * By default this is set to 1. If the term exists it is automatically updated.
  320. * @param $dbname
  321. * In some cases the database name will not be part of the $term['id'] and it
  322. * needs to be explicitly set. Use this argument only if the database name
  323. * cannot be specififed in the term ID (e.g. <DB>:<ACCESSION>).
  324. *
  325. * @return
  326. * A CVTerm object
  327. *
  328. * @ingroup tripal_cv_api
  329. */
  330. function tripal_cv_add_cvterm($term,$defaultcv='',$is_relationship = 0,$update = 1,$dbname=NULL){
  331. // get the term properties
  332. $id = $term['id'];
  333. $name = $term['name'];
  334. $cvname = $term['namespace'];
  335. $definition = preg_replace('/^\"(.*)\"/','\1',$term['def']);
  336. $is_obsolete = 0;
  337. if(isset($term['is_obsolete']) and strcmp($term['is_obsolete'],'true')==0){
  338. $is_obsolete = 1;
  339. }
  340. if(!$name and !$id){
  341. watchdog('tripal_cv', "Cannot find cvterm without 'id' or 'name'",NULL,WATCHDOG_WARNING);
  342. return 0;
  343. }
  344. if(!$id){
  345. $id = $name;
  346. }
  347. if(!$name){
  348. $name = $id;
  349. }
  350. if(!$cvname){
  351. $cvname = $defaultcv;
  352. }
  353. // make sure the CV name exists
  354. $cv = tripal_cv_add_cv($cvname,'');
  355. if(!$cv){
  356. watchdog('tripal_cv', "Cannot find namespace '$cvname' when adding/updating $id",NULL,WATCHDOG_WARNING);
  357. return 0;
  358. }
  359. // this SQL statement will be used a lot to find a cvterm so just set it
  360. // here for easy reference below. Because CV terms can change their names
  361. // but accessions don't change, the following SQL finds cvterms based on
  362. // their accession rather than the name
  363. $cvtermsql = "SELECT CVT.name, CVT.cvterm_id, DB.name as dbname, DB.db_id
  364. FROM {cvterm} CVT
  365. INNER JOIN {dbxref} DBX on CVT.dbxref_id = DBX.dbxref_id
  366. INNER JOIN {db} DB on DBX.db_id = DB.db_id
  367. INNER JOIN {cv} CV on CV.cv_id = CVT.cv_id
  368. WHERE DBX.accession = '%s' and DB.name = '%s'";
  369. // get the accession and the database from the cvterm
  370. if($dbname){
  371. $accession = $id;
  372. }
  373. elseif(preg_match('/^.+?:.*$/',$id)){
  374. $accession = preg_replace('/^.+?:(.*)$/','\1',$id);
  375. $dbname = preg_replace('/^(.+?):.*$/','\1',$id);
  376. }
  377. if($is_relationship and !$dbname){
  378. $accession = $id;
  379. // because this is a relationship cvterm first check to see if it
  380. // exists in the relationship ontology. If it does then return the cvterm.
  381. // If not then set the dbname to _global and we'll add it or find it there
  382. $cvterm = db_fetch_object(db_query($cvtermsql,$accession,'OBO_REL'));
  383. if($cvterm){
  384. return $cvterm;
  385. } else {
  386. // next check if this term is in the _global ontology. If it is then
  387. // return it no matter what the original CV
  388. $dbname = '_global';
  389. $cvterm = db_fetch_object(db_query($cvtermsql,$accesion,$dbname));
  390. if($cvterm){
  391. return $cvterm;
  392. }
  393. }
  394. }
  395. if(!$is_relationship and !$dbname){
  396. watchdog('tripal_cv', "A database identifier is missing from the term: $id",NULL,WATCHDOG_WARNING);
  397. return 0;
  398. }
  399. // add the database. The function will just return the DB object if the
  400. // database already exists.
  401. $db = tripal_db_add_db($dbname);
  402. if(!$db){
  403. watchdog('tripal_cv', "Cannot find database '$dbname' in Chado.",NULL,WATCHDOG_WARNING);
  404. return 0;
  405. }
  406. // if the cvterm doesn't exist then add it otherwise just update it
  407. $cvterm = db_fetch_object(db_query($cvtermsql,$accession,$dbname));
  408. if(!$cvterm){
  409. // check to see if the dbxref exists if not, add it
  410. $dbxref = tripal_db_add_dbxref($db->db_id,$accession);
  411. if(!$dbxref){
  412. watchdog('tripal_cv', "Failed to find or insert the dbxref record for cvterm, $name (id: $accession), for database $dbname",NULL,WATCHDOG_WARNING);
  413. return 0;
  414. }
  415. // check to see if the dbxref already has an entry in the cvterm table
  416. $sql = "SELECT * FROM {cvterm} WHERE dbxref_id = %d";
  417. $check = db_fetch_object(db_query($sql,$dbxref->dbxref_id));
  418. if(!$check){
  419. // now add the cvterm
  420. $sql = "
  421. INSERT INTO {cvterm} (cv_id, name, definition, dbxref_id,
  422. is_obsolete, is_relationshiptype)
  423. VALUES (%d,'%s','%s',%d,%d,%d)
  424. ";
  425. if(!db_query($sql,$cv->cv_id,$name,$definition,
  426. $dbxref->dbxref_id,$is_obsolete,$is_relationship)){
  427. if(!$is_relationship){
  428. watchdog('tripal_cv', "Failed to insert the term: $name ($dbname)",NULL,WATCHDOG_WARNING);
  429. return 0;
  430. } else {
  431. watchdog('tripal_cv', "Failed to insert the relationship term: $name (cv: " . $cvname . " db: $dbname)",NULL,WATCHDOG_WARNING);
  432. return 0;
  433. }
  434. }
  435. }
  436. // if the dbxref already exists check to make sure it exists for the correct databaes name
  437. // if it does then we're good and we don't need to do anything
  438. elseif($check and strcmp($check->name,$name)==0){
  439. // this entry already exists. We're good, so do nothing
  440. }
  441. // if the dbxref exists but does not map to the same database name
  442. elseif($check and strcmp($check->name,$name)!=0){
  443. 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);
  444. return 0;
  445. }
  446. $cvterm = db_fetch_object(db_query($cvtermsql,$name,$dbname));
  447. if(!$is_relationship){
  448. print "Added CV term: $name ($dbname)\n";
  449. } else {
  450. print "Added relationship CV term: $name ($dbname)\n";
  451. }
  452. }
  453. elseif($update) { // update the cvterm
  454. $sql = "
  455. UPDATE {cvterm} SET name='%s', definition='%s',
  456. is_obsolete = %d, is_relationshiptype = %d
  457. WHERE cvterm_id = %d
  458. ";
  459. if(!db_query($sql,$term['name'],$definition,
  460. $is_obsolete,$is_relationship,$cvterm->cvterm_id)){
  461. watchdog('tripal_cv', "Failed to update the term: $name",NULL,WATCHDOG_WARNING);
  462. return 0;
  463. }
  464. $cvterm = db_fetch_object(db_query($cvtermsql,$name,$dbname));
  465. if(!$is_relationship){
  466. print "Updated CV term: $name ($dbname)\n";
  467. } else {
  468. print "Updated relationship CV term: $name ($dbname)\n";
  469. }
  470. }
  471. // return the cvterm
  472. return $cvterm;
  473. }