tripal_cv.api.inc 20 KB

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