tripal_cv.api.inc 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555
  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. * To retrieve a chado controlled vocabulary term object
  149. *
  150. * @param $select_values
  151. * An array meant to uniquely select a given controlled vocabulary term
  152. *
  153. * @return
  154. * Chado controlled vocabulary term object
  155. *
  156. * The controlled vocabulary term is selected using tripal_core_chado select and as such the
  157. * $select_values array parameter meant to uniquely identify the controlled vocab term to be
  158. * returned follows the same form as when using tripal_core_chado_select directly.
  159. *
  160. * Example Usage:
  161. * @code
  162. $select_values = array(
  163. 'name' => 'synonym',
  164. 'cv_id' => array(
  165. 'name' => 'feature_property'
  166. )
  167. );
  168. $cvterm_object = tripal_cv_get_cvterm($select_values);
  169. * @endcode
  170. * The above code selects the synonym cvterm from the feature_proeprty cv and returns
  171. * the following object:
  172. * @code
  173. $cvterm_object = stdClass Object (
  174. [cvterm_id] => 2099
  175. [name] => synonym
  176. [definition] => Historic community symbol, may have originally been symbol []
  177. [is_obsolete] => 0
  178. [is_relationshiptype] => 1
  179. [cv_cv_id] => 13
  180. [cv_name] => feature_property
  181. [cv_definition] =>
  182. [dbreference_dbxref_id] => 2581
  183. [dbreference_accession] => synonym
  184. [dbreference_description] =>
  185. [dbreference_version] =>
  186. [dbreference_db_db_id] => 49
  187. [dbreference_db_name] => SOFP
  188. [dbreference_db_description] =>
  189. [dbreference_db_urlprefix] =>
  190. [dbreference_db_url] =>
  191. );
  192. * @endcode
  193. *
  194. * @ingroup tripal_cv_api
  195. */
  196. function tripal_cv_get_cvterm ($select_values) {
  197. $columns = array(
  198. 'cvterm_id',
  199. 'cv_id',
  200. 'name',
  201. 'definition',
  202. 'dbxref_id',
  203. 'is_obsolete',
  204. 'is_relationshiptype'
  205. );
  206. $results = tripal_core_chado_select('cvterm', $columns, $select_values);
  207. if (sizeof($results) == 1) {
  208. // Add cv
  209. $cvterm = tripal_cv_add_cv_to_object(array('cv_id'=>$results[0]->cv_id),$results[0],array());
  210. unset($cvterm->cv_id);
  211. // Add dbxref
  212. $cvterm = tripal_db_add_dbxref_to_object(array('dbxref_id'=>$cvterm->dbxref_id),$cvterm,array());
  213. unset($cvterm->dbxref_id);
  214. return $cvterm;
  215. } elseif (empty($results)) {
  216. watchdog('tripal_cv',
  217. 'tripal_cv_get_cvterm: No cvterm matches criteria values:%values',
  218. array('%values' => print_r($select_values, TRUE)),
  219. WATCHDOG_WARNING
  220. );
  221. return FALSE;
  222. } else {
  223. watchdog('tripal_cv',
  224. 'tripal_cv_get_cvterm: 2+ cvterms match criteria values:%values',
  225. array('%values' => print_r($select_values, TRUE)),
  226. WATCHDOG_WARNING
  227. );
  228. }
  229. }
  230. /**
  231. * Retrieve a chado cvterm object with a given name
  232. *
  233. * @param $name
  234. * the cvterm.name
  235. * @param $cv_id
  236. * the cv_id of the term you are looking for
  237. *
  238. * @return
  239. * cvterm object
  240. *
  241. * @ingroup tripal_cv_api
  242. */
  243. function tripal_cv_get_cvterm_by_name ($name, $cv_id=0) {
  244. if (!empty($cv_id)) {
  245. $sql = "SELECT * FROM cvterm WHERE name='%s' AND cv_id=%d";
  246. $previous_db = tripal_db_set_active('chado');
  247. $r = db_fetch_object(db_query($sql, $name, $cv_id));
  248. tripal_db_set_active($previous_db);
  249. } else {
  250. $sql = "SELECT * FROM cvterm WHERE name='%s'";
  251. $previous_db = tripal_db_set_active('chado');
  252. $r = db_fetch_object(db_query($sql, $name));
  253. tripal_db_set_active($previous_db);
  254. }
  255. return $r;
  256. }
  257. /**
  258. * Create an options array to be used in a form element
  259. * which provides a list of all chado cvterms
  260. *
  261. * @param $cv_id
  262. * The chado cv_id;
  263. * only cvterms with the supplied cv_id will be returned
  264. * @return
  265. * An array(cvterm_id => name)
  266. * for each cvterm in the chado cvterm table where cv_id=that supplied
  267. *
  268. * @ingroup tripal_cv_api
  269. */
  270. function tripal_cv_get_cvterm_options($cv_id = 0) {
  271. $previous_db = tripal_db_set_active('chado');
  272. if ($cv_id > 0) {
  273. $result = db_query(
  274. "SELECT cvterm_id, name FROM cvterm WHERE cv_id=%d", $cv_id
  275. );
  276. } else {
  277. $result = db_query(
  278. "SELECT cvterm_id, name FROM cvterm"
  279. );
  280. }
  281. tripal_db_set_active($previous_db);
  282. $options = array();
  283. while ( $r = db_fetch_object($result) ) {
  284. $options[$r->cvterm_id] = $r->name;
  285. }
  286. return $options;
  287. }
  288. /**
  289. * Implements hook_chado_cvterm_schema()
  290. * Purpose: To add descriptions and foreign keys to default table description
  291. * Note: This array will be merged with the array from all other implementations
  292. *
  293. * @return
  294. * Array describing the cvterm table
  295. *
  296. * @ingroup tripal_schema_api
  297. */
  298. function tripal_cv_chado_cvterm_schema() {
  299. $description = array();
  300. $description['foreign keys']['cv'] = array(
  301. 'table' => 'cv',
  302. 'columns' => array(
  303. 'cv_id' => 'cv_id',
  304. ),
  305. );
  306. $description['foreign keys']['dbxref'] = array(
  307. 'table' => 'dbxref',
  308. 'columns' => array(
  309. 'dbxref_id' => 'dbxref_id',
  310. ),
  311. );
  312. return $description;
  313. }
  314. /**
  315. *
  316. * @ingroup tripal_cv_api
  317. */
  318. function tripal_cv_add_cv($name,$comment){
  319. // see if the CV (default-namespace) exists already in the database
  320. $vocab = $name;
  321. $remark = $comment;
  322. $cv_sql = "SELECT * FROM {cv} WHERE name = '%s'";
  323. $cv = db_fetch_object(db_query($cv_sql,$vocab));
  324. // if the CV exists then update it, otherwise insert
  325. if(!$cv){
  326. $sql = "INSERT INTO {cv} (name,definition) VALUES ('%s','%s')";
  327. if(!db_query($sql,$vocab,$remark)){
  328. watchdog('tripal_cv', "Failed to create the CV record",NULL,WATCHDOG_WARNING);
  329. return 0;
  330. }
  331. $cv = db_fetch_object(db_query($cv_sql,$vocab));
  332. } else {
  333. $sql = "UPDATE {cv} SET definition = '%s' WHERE name ='%s'";
  334. if(!db_query($sql,$remark,$vocab)){
  335. watchdog('tripal_cv', "Failed to update the CV record",NULL,WATCHDOG_WARNING);
  336. return 0;
  337. }
  338. $cv = db_fetch_object(db_query($cv_sql,$vocab));
  339. }
  340. return $cv;
  341. }
  342. /**
  343. * Add's a CV term to the cvterm table. If the parent CV does not exist then
  344. * that too is added to the CV table. If the cvterm is a relationship term
  345. * then the $is_relationship argument should be set. The function will try
  346. * to first find the relationship in the relationship ontology for updating and
  347. * if it can't be found will add the relationship to the __global CV. All terms
  348. * must also have a corresponding database. This is specified in the term's
  349. * ID just before the colon (e.g. GO:003824). If the database does not exist
  350. * in the DB table then it will be added automatically. The accession (the
  351. * value just after the colon in the term's ID) will be added to the dbxref
  352. * table. If the CVterm already exists and $update is set (default) then the
  353. * cvterm is updated. If the CVTerm already exists and $update is not set, then
  354. * no changes are made and the CVTerm object is returned.
  355. *
  356. * @param $term
  357. * An associative array with the following keys: 'id', 'name' and 'namespace',
  358. * 'is_obsolete', and 'def'. Where 'id' is the term accession, 'name' is the
  359. * term name, 'namespace' is the CV name for the term, 'def' is the term
  360. * definition and 'is_obsolete' is present and set to 1 if the term is defunct.
  361. * The 'id' must be of the form <DB>:<ACCESSION>, where <DB> is the name of
  362. * the database to which the cvterm belongs and the <ACCESSION> is the
  363. * term's accession number in the database.
  364. * @param $defaultcv
  365. * Optional. A CV object populated with the fields of the CV to which the term
  366. * belongs. If this arugment is null or not provided then the function tries
  367. * to find a record in the CV table with the same name provided in the
  368. * $term[namespace].
  369. * @param $is_relationship
  370. * If this term is a relationship term then this value should be 1.
  371. * @param $update
  372. * By default this is set to 1. If the term exists it is automatically updated.
  373. *
  374. * @return
  375. * A CVTerm object
  376. *
  377. * @ingroup tripal_cv_api
  378. */
  379. function tripal_cv_add_cvterm($term,$defaultcv,$is_relationship = 0,$update = 1){
  380. // get the term properties
  381. $id = $term['id'];
  382. $name = $term['name'];
  383. $cvname = $term['namespace'];
  384. $definition = preg_replace('/^\"(.*)\"/','\1',$term['def']);
  385. $is_obsolete = 0;
  386. if(isset($term['is_obsolete']) and strcmp($term['is_obsolete'],'true')==0){
  387. $is_obsolete = 1;
  388. }
  389. if(!$cvname){
  390. $cvname = $defaultcv->name;
  391. }
  392. // make sure the CV name exists
  393. $cv = tripal_cv_add_cv($cvname,'');
  394. if(!$cv){
  395. watchdog('tripal_cv', "Cannot find namespace '$cvname' when adding/updating $id",NULL,WATCHDOG_WARNING);
  396. return 0;
  397. }
  398. // this SQL statement will be used a lot to find a cvterm so just set it
  399. // here for easy reference below. Because CV terms can change their names
  400. // but accessions don't change, the following SQL finds cvterms based on
  401. // their accession rather than the name
  402. $cvtermsql = "SELECT CVT.name, CVT.cvterm_id, DB.name as dbname, DB.db_id
  403. FROM {cvterm} CVT
  404. INNER JOIN {dbxref} DBX on CVT.dbxref_id = DBX.dbxref_id
  405. INNER JOIN {db} DB on DBX.db_id = DB.db_id
  406. INNER JOIN {cv} CV on CV.cv_id = CVT.cv_id
  407. WHERE DBX.accession = '%s' and DB.name = '%s'";
  408. // get the accession and the database from the cvterm
  409. if(preg_match('/^.+?:.*$/',$id)){
  410. $accession = preg_replace('/^.+?:(.*)$/','\1',$id);
  411. $dbname = preg_replace('/^(.+?):.*$/','\1',$id);
  412. }
  413. if($is_relationship and !$dbname){
  414. $accession = $id;
  415. // because this is a relationship cvterm first check to see if it
  416. // exists in the relationship ontology. If it does then return the cvterm.
  417. // If not then set the dbname to _global and we'll add it or find it there
  418. $cvterm = db_fetch_object(db_query($cvtermsql,$accession,'OBO_REL'));
  419. if($cvterm){
  420. return $cvterm;
  421. } else {
  422. // next check if this term is in the _global ontology. If it is then
  423. // return it no matter what the original CV
  424. $dbname = '_global';
  425. $cvterm = db_fetch_object(db_query($cvtermsql,$accesion,$dbname));
  426. if($cvterm){
  427. return $cvterm;
  428. }
  429. }
  430. }
  431. if(!$is_relationship and !$dbname){
  432. watchdog('tripal_cv', "A database identifier is missing from the term: $id",NULL,WATCHDOG_WARNING);
  433. return 0;
  434. }
  435. // add the database. The function will just return the DB object if the
  436. // database already exists.
  437. $db = tripal_db_add_db($dbname);
  438. if(!$db){
  439. watchdog('tripal_cv', "Cannot find database '$dbname' in Chado.",NULL,WATCHDOG_WARNING);
  440. return 0;
  441. }
  442. // if the cvterm doesn't exist then add it otherwise just update it
  443. $cvterm = db_fetch_object(db_query($cvtermsql,$accession,$dbname));
  444. if(!$cvterm){
  445. // check to see if the dbxref exists if not, add it
  446. $dbxref = tripal_db_add_dbxref($db->db_id,$accession);
  447. if(!$dbxref){
  448. watchdog('tripal_cv', "Failed to find or insert the dbxref record for cvterm, $name (id: $accession), for database $dbname",NULL,WATCHDOG_WARNING);
  449. return 0;
  450. }
  451. // check to see if the dbxref already has an entry in the cvterm table
  452. $sql = "SELECT * FROM {cvterm} WHERE dbxref_id = %d";
  453. $check = db_fetch_object(db_query($sql,$dbxref->dbxref_id));
  454. if(!$check){
  455. // now add the cvterm
  456. $sql = "
  457. INSERT INTO {cvterm} (cv_id, name, definition, dbxref_id,
  458. is_obsolete, is_relationshiptype)
  459. VALUES (%d,'%s','%s',%d,%d,%d)
  460. ";
  461. if(!db_query($sql,$cv->cv_id,$name,$definition,
  462. $dbxref->dbxref_id,$is_obsolete,$is_relationship)){
  463. if(!$is_relationship){
  464. watchdog('tripal_cv', "Failed to insert the term: $name ($dbname)",NULL,WATCHDOG_WARNING);
  465. return 0;
  466. } else {
  467. watchdog('tripal_cv', "Failed to insert the relationship term: $name (cv: " . $cvname . " db: $dbname)",NULL,WATCHDOG_WARNING);
  468. return 0;
  469. }
  470. }
  471. }
  472. // if the dbxref already exists check to make sure it exists for the correct databaes name
  473. // if it does then we're good and we don't need to do anything
  474. elseif($check and strcmp($check->name,$name)==0){
  475. // this entry already exists. We're good, so do nothing
  476. }
  477. // if the dbxref exists but does not map to the same database name
  478. elseif($check and strcmp($check->name,$name)!=0){
  479. 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);
  480. return 0;
  481. }
  482. $cvterm = db_fetch_object(db_query($cvtermsql,$name,$dbname));
  483. if(!$is_relationship){
  484. print "Added CV term: $name ($dbname)\n";
  485. } else {
  486. print "Added relationship CV term: $name ($dbname)\n";
  487. }
  488. }
  489. elseif($update) { // update the cvterm
  490. $sql = "
  491. UPDATE {cvterm} SET name='%s', definition='%s',
  492. is_obsolete = %d, is_relationshiptype = %d
  493. WHERE cvterm_id = %d
  494. ";
  495. if(!db_query($sql,$term['name'],$definition,
  496. $is_obsolete,$is_relationship,$cvterm->cvterm_id)){
  497. watchdog('tripal_cv', "Failed to update the term: $name",NULL,WATCHDOG_WARNING);
  498. return 0;
  499. }
  500. $cvterm = db_fetch_object(db_query($cvtermsql,$name,$dbname));
  501. if(!$is_relationship){
  502. print "Updated CV term: $name ($dbname)\n";
  503. } else {
  504. print "Updated relationship CV term: $name ($dbname)\n";
  505. }
  506. }
  507. // return the cvterm
  508. return $cvterm;
  509. }