tripal_cv.api.inc 37 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096
  1. <?php
  2. /**
  3. * @file
  4. * This module provides a set of functions to simplify working with
  5. * controlled vocabularies.
  6. */
  7. /**
  8. * @defgroup tripal_cv_api Controlled Vocabulary API
  9. * @ingroup tripal_api
  10. * This module provides a set of functions to simplify working with
  11. * controlled vocabularies. Most of the API functions deal with retrieving
  12. * terms or their parent vocabularies.
  13. *
  14. * However, the API also supports
  15. * generation of trees for browsing a vocabulary as well as generation of
  16. * pie graphs for display of hierarchical counts of terms. Version 0.3b of
  17. * Tripal provides a feature browser and a feature summary chart uses
  18. * the API functions provided here. But in general charts and trees can be
  19. * created for any controlled vocabulary.
  20. *
  21. */
  22. /**
  23. * Retrieves a chado controlled vocabulary variable
  24. *
  25. * @param $identifier
  26. * An array with the key stating what the identifier is. Supported keys (only on of the
  27. * following unique keys is required):
  28. * - cv_id: the chado cv.cv_id primary key
  29. * - name: the chado cv.name field (assume unique)
  30. * @param $options
  31. * An array of options. Supported keys include:
  32. * - Any keys supported by chado_generate_var(). See that function definition for
  33. * additional details.
  34. *
  35. * NOTE: the $identifier parameter can really be any array similar to $values passed into
  36. * chado_select_record(). It should fully specify the cv record to be returned.
  37. *
  38. * @return
  39. * If unique values were passed in as an identifier then an object describing the cv
  40. * will be returned (will be a chado variable from chado_generate_var()). Otherwise,
  41. * FALSE will be returned.
  42. *
  43. * @ingroup tripal_cv_api
  44. */
  45. function tripal_get_cv($identifiers, $options = array()) {
  46. // Set Defaults
  47. if (!isset($options['include_fk'])) {
  48. // Tells chado_generate_var not to follow any foreign keys
  49. $options['include_fk'] = array();
  50. }
  51. // Error Checking of parameters
  52. if (!is_array($identifiers)) {
  53. tripal_report_error(
  54. 'tripal_cv_api',
  55. TRIPAL_ERROR,
  56. "tripal_get_cv: The identifier passed in is expected to be an array with the key
  57. matching a column name in the cv table (ie: cv_id or name). You passed in %identifier.",
  58. array(
  59. '%identifier'=> print_r($identifiers, TRUE)
  60. )
  61. );
  62. }
  63. elseif (empty($identifiers)) {
  64. tripal_report_error(
  65. 'tripal_cv_api',
  66. TRIPAL_ERROR,
  67. "tripal_get_cv: You did not pass in anything to identify the cv you want. The identifier
  68. is expected to be an array with the key matching a column name in the cv table
  69. (ie: cv_id or name). You passed in %identifier.",
  70. array(
  71. '%identifier'=> print_r($identifiers, TRUE)
  72. )
  73. );
  74. }
  75. // Try to get the cv
  76. $cv = chado_generate_var(
  77. 'cv',
  78. $identifiers,
  79. $options
  80. );
  81. // Ensure the cv is singular. If it's an array then it is not singular
  82. if (is_array($cv)) {
  83. tripal_report_error(
  84. 'tripal_cv_api',
  85. TRIPAL_ERROR,
  86. "tripal_get_cv: The identifiers you passed in were not unique. You passed in %identifier.",
  87. array(
  88. '%identifier'=> print_r($identifiers, TRUE)
  89. )
  90. );
  91. }
  92. // Report an error if $cv is FALSE since then chado_generate_var has failed
  93. elseif ($cv === FALSE) {
  94. tripal_report_error(
  95. 'tripal_cv_api',
  96. TRIPAL_ERROR,
  97. "tripal_get_cv: chado_generate_var() failed to return a cv based on the identifiers
  98. you passed in. You should check that your identifiers are correct, as well as, look
  99. for a chado_generate_var error for additional clues. You passed in %identifier.",
  100. array(
  101. '%identifier'=> print_r($identifiers, TRUE)
  102. )
  103. );
  104. }
  105. // Else, as far we know, everything is fine so give them their cv :)
  106. else {
  107. return $cv;
  108. }
  109. }
  110. /**
  111. * Create an options array to be used in a form element which provides a
  112. * list of all chado cvs
  113. *
  114. * @return
  115. * An array(cv_id => name) for each cv in the chado cv table
  116. *
  117. * @ingroup tripal_cv_api
  118. */
  119. function tripal_get_cv_select_options() {
  120. $results = chado_select_record('cv', array('cv_id', 'name'), array(), array('order_by' => array('name' => 'ASC')));
  121. $options = array();
  122. foreach ($results as $r) {
  123. $options[$r->cv_id] = $r->name;
  124. }
  125. return $options;
  126. }
  127. /**
  128. * Retrieves a chado controlled vocabulary term variable
  129. *
  130. * @param $identifier
  131. * An array with the key stating what the identifier is. Supported keys (only one of the
  132. * following unique keys are required):
  133. * - cvterm_id: the chado cv.cvterm_id primary key
  134. * - name: the chado cvterm.name field (assume unique)
  135. * There are also some specially handled keys. They are:
  136. * - cv_id: an integer indicating the cv_id or an array with 'name' => the name of the cv.
  137. * - synonym: an array with 'name' => the name of the synonym of the cvterm you want
  138. * returned; 'cv_id' => the cv_id of the synonym; 'cv_name' => the name of the cv
  139. * of the synonym
  140. * - property: An array/object describing the property to select records for. It
  141. * should at least have either a type_name (if unique across cvs) or type_id. Other
  142. * supported keys include: cv_id/cv_name (of the type), value and rank
  143. * @param $options
  144. * An array of options. Supported keys include:
  145. * - Any keys supported by chado_generate_var(). See that function definition for
  146. * additional details.
  147. *
  148. * NOTE: the $identifier parameter can really be any array similar to $values passed into
  149. * chado_select_record(). It should fully specify the cvterm record to be returned.
  150. *
  151. * @return
  152. * If unique values were passed in as an identifier then an object describing the cvterm
  153. * will be returned (will be a chado variable from chado_generate_var()). Otherwise,
  154. * FALSE will be returned.
  155. *
  156. * @ingroup tripal_cv_api
  157. */
  158. function tripal_get_cvterm($identifiers, $options = array()) {
  159. // Set Defaults
  160. if (!isset($options['include_fk'])) {
  161. // Tells chado_generate_var to only get the cv
  162. $options['include_fk'] = array('cv_id' => TRUE);
  163. }
  164. // Error Checking of parameters
  165. if (!is_array($identifiers)) {
  166. tripal_report_error('tripal_cv_api', TRIPAL_ERROR,
  167. "tripal_get_cvterm: The identifier passed in is expected to be an array with the key
  168. matching a column name in the cvterm table (ie: cvterm_id or name). You passed in %identifier.",
  169. array('%identifier'=> print_r($identifiers, TRUE))
  170. );
  171. }
  172. elseif (empty($identifiers)) {
  173. tripal_report_error('tripal_cv_api', TRIPAL_ERROR,
  174. "tripal_get_cvterm: You did not pass in anything to identify the cvterm you want. The identifier
  175. is expected to be an array with the key matching a column name in the cvterm table
  176. (ie: cvterm_id or name). You passed in %identifier.",
  177. array('%identifier'=> print_r($identifiers, TRUE))
  178. );
  179. }
  180. // If synonym was passed in, then process this first before calling chado_generate_var()
  181. if (isset($identifiers['synonym'])) {
  182. $synonym = $identifiers['synonym']['name'];
  183. $values = array('synonym' => $synonym);
  184. if (isset($identifiers['synonym']['cv_id'])) {
  185. $values['cvterm_id'] = array('cv_id' => $identifiers['synonym']['cv_id']);
  186. }
  187. if (isset($identifiers['synonym']['cv_name'])) {
  188. $values['cvterm_id'] = array('cv_id' => array('name' => $identifiers['synonym']['cv_name']));
  189. }
  190. $options = array(
  191. 'case_insensitive_columns' => array('name')
  192. );
  193. $result = chado_select_record('cvtermsynonym', array('cvterm_id'), $values, $options);
  194. // if the synonym doens't exist or more than one record is returned then return false
  195. if (count($result) == 0) {
  196. return FALSE;
  197. }
  198. if (count($result) > 1) {
  199. return FALSE;
  200. }
  201. $identifiers = array('cvterm_id' => $result[0]->cvterm_id);
  202. }
  203. // If one of the identifiers is property then use chado_get_record_with_property()
  204. if (isset($identifiers['property'])) {
  205. $property = $identifiers['property'];
  206. unset($identifiers['property']);
  207. $cvterm = chado_get_record_with_property('cvterm', $property, $identifiers, $options);
  208. }
  209. // Else we have a simple case and we can just use chado_generate_var to get the cvterm
  210. else {
  211. // Try to get the cvterm
  212. $cvterm = chado_generate_var('cvterm', $identifiers, $options);
  213. }
  214. // Ensure the cvterm is singular. If it's an array then it is not singular
  215. if (is_array($cvterm)) {
  216. tripal_report_error(
  217. 'tripal_cv_api',
  218. TRIPAL_ERROR,
  219. "tripal_get_cvterm: The identifiers you passed in were not unique. You passed in %identifier.",
  220. array(
  221. '%identifier'=> print_r($identifiers, TRUE)
  222. )
  223. );
  224. }
  225. // Report an error if $cvterm is FALSE since then chado_generate_var has failed
  226. elseif ($cvterm === FALSE) {
  227. tripal_report_error(
  228. 'tripal_cv_api',
  229. TRIPAL_ERROR,
  230. "tripal_get_cvterm: chado_generate_var() failed to return a cvterm based on the identifiers
  231. you passed in. You should check that your identifiers are correct, as well as, look
  232. for a chado_generate_var error for additional clues. You passed in %identifier.",
  233. array(
  234. '%identifier'=> print_r($identifiers, TRUE)
  235. )
  236. );
  237. }
  238. // Else, as far we know, everything is fine so give them their cvterm :)
  239. else {
  240. return $cvterm;
  241. }
  242. }
  243. /**
  244. * Create an options array to be used in a form element
  245. * which provides a list of all chado cvterms
  246. *
  247. * @param $cv_id
  248. * The chado cv_id;
  249. * only cvterms with the supplied cv_id will be returned
  250. * @return
  251. * An array(cvterm_id => name)
  252. * for each cvterm in the chado cvterm table where cv_id=that supplied
  253. *
  254. * @ingroup tripal_cv_api
  255. */
  256. function tripal_get_cvterm_select_options($cv_id = 0) {
  257. if ($cv_id > 0) {
  258. $results = chado_select_record('cvterm', array('cvterm_id', 'name'), array('cv_id' => $cv_id));
  259. }
  260. else {
  261. $results = chado_select_record('cvterm', array('cvterm_id', 'name'), array());
  262. }
  263. $options = array();
  264. foreach ($results as $r) {
  265. $options[$r->cvterm_id] = $r->name;
  266. }
  267. return $options;
  268. }
  269. /**
  270. * Updates the cvtermpath table of Chado for the specified CV.
  271. *
  272. * @param $cv_id
  273. * The chado cv_id;
  274. * @param $job_id
  275. * This function is intended to be used with the Tripal Jobs API.
  276. * When this function is called as a job the $job_id is automatically
  277. * passed to this function.
  278. * @return
  279. * TRUE on success FALSE on failure
  280. *
  281. * @ingroup tripal_cv_api
  282. */
  283. function tripal_update_cvtermpath($cvid, $job_id = NULL) {
  284. // TODO: need better error checking in this function
  285. // first get the controlled vocabulary name:
  286. $sql = "SELECT * FROM {cv} WHERE cv_id = :cv_id";
  287. $cv = chado_query($sql, array(':cv_id' => $cvid))->fetchObject();
  288. print "\nUpdating cvtermpath for $cv->name...\n";
  289. $previous = chado_set_active('chado');
  290. try {
  291. $sql = "SELECT * FROM fill_cvtermpath(:name)";
  292. db_query($sql, array(':name' => $cv->name));
  293. chado_set_active($previous);
  294. }
  295. catch (Exception $e) {
  296. chado_set_active($previous);
  297. $error = $e->getMessage();
  298. tripal_report_error('tripal_cv', TRIPAL_ERROR, "Could not fill cvtermpath table: @error", array('@error' => $error));
  299. return FALSE;
  300. }
  301. return TRUE;
  302. }
  303. /**
  304. * Adds a controlled vocabular to the CV table of Chado.
  305. *
  306. * @param $name
  307. * The name of the controlled vocabulary. These are typically all lower case
  308. * with no special characters other than an undrescore (for spaces).
  309. * @param $comment
  310. * A description or definition of the vocabulary.
  311. *
  312. * @return
  313. * An object populated with fields from the newly added database.
  314. *
  315. * @ingroup tripal_cv_api
  316. */
  317. function tripal_insert_cv($name, $definition) {
  318. // insert/update values
  319. $ins_values = array(
  320. 'name' => $name,
  321. 'definition' => $definition
  322. );
  323. // see if the CV (default-namespace) exists already in the database
  324. $sel_values = array('name' => $name);
  325. $sel_options = array('statement_name' => 'sel_cv_na');
  326. $results = chado_select_record('cv', array('*'), $sel_values, $sel_options);
  327. // if it does not exists then add it
  328. if (count($results) == 0) {
  329. $ins_options = array('statement_name' => 'ins_cv_nade');
  330. $success = chado_insert_record('cv', $ins_values, $ins_options);
  331. if (!$success) {
  332. tripal_report_error('tripal_cv', TRIPAL_WARNING, "Failed to create the CV record", NULL);
  333. return FALSE;
  334. }
  335. $results = chado_select_record('cv', array('*'), $sel_values, $sel_options);
  336. }
  337. // if it already exists then do an update
  338. else {
  339. $upd_options = array('statement_name' => 'upd_cv_nade');
  340. $success = chado_update_record('cv', $sel_values, $ins_values, $upd_options);
  341. if (!$success) {
  342. tripal_report_error('tripal_cv', TRIPAL_WARNING, "Failed to update the CV record", NULL);
  343. return FALSE;
  344. }
  345. $results = chado_select_record('cv', array('*'), $sel_values, $sel_options);
  346. }
  347. // return the cv object
  348. return $results[0];
  349. }
  350. /**
  351. * Add's a controlled vocabulary term to the cvterm table.
  352. *
  353. * If the parent CV does not exist then
  354. * that too is added to the CV table. If the cvterm is a relationship term
  355. * then the $is_relationship argument should be set. The function will try
  356. * to first find the relationship in the relationship ontology for updating and
  357. * if it can't be found will add the relationship to the __global CV. All terms
  358. * must also have a corresponding database. This is specified in the term's
  359. * ID just before the colon (e.g. GO:003824). If the database does not exist
  360. * in the DB table then it will be added automatically. The accession (the
  361. * value just after the colon in the term's ID) will be added to the dbxref
  362. * table. If the CVterm already exists and $update is set (default) then the
  363. * cvterm is updated. If the CVTerm already exists and $update is not set, then
  364. * no changes are made and the CVTerm object is returned.
  365. *
  366. * @param $term
  367. * An associative array with the following keys:
  368. * - id: the term accession. must be of the form <DB>:<ACCESSION>, where <DB> is the
  369. * name of the database to which the cvterm belongs and the <ACCESSION> is the
  370. * term's accession number in the database.
  371. * - name: the name of the term. usually meant to be human-readable.
  372. * - namespace: the CV name for the term. DEPRECATED. Please use cv_name instead.
  373. * - is_obsolete: is present and set to 1 if the term is defunct
  374. * - definition: the definition of the term
  375. * - cv_name: The CV name to which the term belongs. If this arugment is null or not
  376. * provided then the function tries to find a record in the CV table with the same
  377. * name provided in the $term[namespace]. If this field is provided then it
  378. * overrides what the value in $term[namespace]
  379. * - is_relationship: If this term is a relationship term then this value should be 1.
  380. * _ db_name: In some cases the database name will not be part of the $term['id'] and it
  381. * needs to be explicitly set. Use this argument only if the database name
  382. * cannot be specififed in the term ID (e.g. <DB>:<ACCESSION>).
  383. * @param $options
  384. * - update_existing: By default this is TRUE. If the term exists it is automatically updated.
  385. *
  386. * @return
  387. * A CVTerm object
  388. *
  389. * @ingroup tripal_cv_api
  390. */
  391. function tripal_insert_cvterm($term, $options = array()) {
  392. // Set Defaults
  393. if (isset($term['cv_name'])) {
  394. $defaultcv = $term['cv_name'];
  395. }
  396. else {
  397. $defaultcv = '_global';
  398. }
  399. if (isset($term['is_relationship'])) {
  400. $is_relationship = $term['is_relationship'];
  401. }
  402. else {
  403. $is_relationship = 0;
  404. }
  405. if (isset($term['db_name'])) {
  406. $dbname = $term['db_name'];
  407. }
  408. else {
  409. $dbname = 'internal';
  410. }
  411. if (isset($options['update_existing'])) {
  412. $update = $options['update_existing'];
  413. }
  414. else {
  415. $update = 1;
  416. }
  417. // get the term properties
  418. $id = (isset($term['id'])) ? $term['id'] : '';
  419. $name = '';
  420. $cvname = '';
  421. $definition = '';
  422. $is_obsolete = 0;
  423. $accession = '';
  424. if (array_key_exists('name', $term)) {
  425. $name = $term['name'];
  426. }
  427. else {
  428. $name = $id;
  429. }
  430. if (array_key_exists('namespace', $term)) {
  431. $cvname = $term['namespace'];
  432. }
  433. else {
  434. $cvname = $defaultcv;
  435. }
  436. if (array_key_exists('definition', $term)) {
  437. $definition = preg_replace('/^\"(.*)\"/', '\1', $term['definition']);
  438. }
  439. else {
  440. $definition = '';
  441. }
  442. if (array_key_exists('is_obsolete', $term)) {
  443. $is_obsolete = $term['is_obsolete'];
  444. if (strcmp($is_obsolete, 'true') == 0) {
  445. $is_obsolete = 1;
  446. }
  447. }
  448. if (!$name and !$id) {
  449. tripal_report_error('tripal_cv', TRIPAL_WARNING, "Cannot find cvterm without 'id' or 'name'", NULL);
  450. return 0;
  451. }
  452. if (!$id) {
  453. $id = $name;
  454. }
  455. // get the accession and the database from the cvterm id
  456. if ($dbname) {
  457. $accession = $id;
  458. }
  459. if (preg_match('/^.+?:.*$/', $id)) {
  460. $accession = preg_replace('/^.+?:(.*)$/', '\1', $id);
  461. $dbname = preg_replace('/^(.+?):.*$/', '\1', $id);
  462. }
  463. // check that we have a database name, give a different message if it's a relationship
  464. if ($is_relationship and !$dbname) {
  465. tripal_report_error('tripal_cv', TRIPAL_WARNING, "A database name is not provided for this relationship term: $id", NULL);
  466. return 0;
  467. }
  468. if (!$is_relationship and !$dbname) {
  469. tripal_report_error('tripal_cv', TRIPAL_WARNING, "A database identifier is missing from the term: $id", NULL);
  470. return 0;
  471. }
  472. // make sure the CV name exists
  473. $cv = tripal_cv_get_cv_by_name($cvname);
  474. if (!$cv) {
  475. $cv = tripal_cv_add_cv($cvname, '');
  476. }
  477. if (!$cv) {
  478. tripal_report_error('tripal_cv', TRIPAL_WARNING, "Cannot find namespace '$cvname' when adding/updating $id", NULL);
  479. return 0;
  480. }
  481. // this SQL statement will be used a lot to find a cvterm so just set it
  482. // here for easy reference below. Because CV terms can change their names
  483. // but accessions don't change, the following SQL finds cvterms based on
  484. // their accession rather than the name
  485. $cvtermsql = "
  486. SELECT CVT.name, CVT.cvterm_id, CV.cv_id, CV.name as cvname,
  487. DB.name as dbname, DB.db_id, DBX.accession
  488. FROM {cvterm} CVT
  489. INNER JOIN {dbxref} DBX on CVT.dbxref_id = DBX.dbxref_id
  490. INNER JOIN {db} DB on DBX.db_id = DB.db_id
  491. INNER JOIN {cv} CV on CV.cv_id = CVT.cv_id
  492. WHERE DBX.accession = :accession and DB.name = :name
  493. ";
  494. // add the database. The function will just return the DB object if the
  495. // database already exists.
  496. $db = tripal_get_db(array('name' => $dbname));
  497. if (!$db) {
  498. $db = tripal_db_add_db($dbname);
  499. }
  500. if (!$db) {
  501. tripal_report_error('tripal_cv', TRIPAL_WARNING, "Cannot find database '$dbname' in Chado.", NULL);
  502. return 0;
  503. }
  504. // the cvterm table has two unique dependencies. We need to check both.
  505. // first check the (name, cv_id, is_obsolete) constraint
  506. $values = array(
  507. 'name' => $name,
  508. 'is_obsolete' => $is_obsolete,
  509. 'cv_id' => array(
  510. 'name' => $cvname,
  511. ),
  512. );
  513. $options = array('statement_name' => 'sel_cvterm_c1');
  514. $result = chado_select_record('cvterm', array('*'), $values, $options);
  515. // if the constraint is met then let's check it to see if
  516. // the database name matches the one we have been provided
  517. if (count($result) == 1) {
  518. $cvterm = $result[0];
  519. // get the dbxref record
  520. $values = array('dbxref_id' => $cvterm->dbxref_id);
  521. $options = array('statement_name' => 'sel_dbxref_id');
  522. $result = chado_select_record('dbxref', array('*'), $values, $options);
  523. $dbxref = $result[0];
  524. // get the db
  525. $values = array('db_id' => $dbxref->db_id);
  526. $options = array('statement_name' => 'sel_db_id');
  527. $result = chado_select_record('db', array('*'), $values, $options);
  528. $db_check = $result[0];
  529. // the database name for this existing term does not match that of the
  530. // one provided to this function. The CV name matches otherwise we
  531. // wouldn't have made it this far. So, let's swap the database for
  532. // this term
  533. if ($db_check->name != $db->name) {
  534. // look to see if the correct dbxref record already exists for this database
  535. $values = array(
  536. 'db_id' => $db->db_id,
  537. 'accession' => $accession,
  538. );
  539. $options = array('statement_name' => 'sel_dbxref_idac');
  540. $result = chado_select_record('dbxref', array('*'), $values, $options);
  541. // if we already have a good dbxref then we want to update our cvterm
  542. // to use this dbxref
  543. if (count($result) > 0) {
  544. $dbxref = $result[0];
  545. $match = array('cvterm_id' => $cvterm->cvterm_id);
  546. $values = array('dbxref_id' => $dbxref->dbxref_id);
  547. $options = array('statement_name' => 'upd_cvterm_db');
  548. $success = chado_update_record('cvterm', $match, $values, $options);
  549. if (!$success) {
  550. tripal_report_error('tripal_cv', TRIPAL_WARNING, "Failed to correct the dbxref id for the cvterm " .
  551. "'$name' (id: $accession), for database $dbname", NULL);
  552. return 0;
  553. }
  554. }
  555. // if we don't have the record then we want to delete our cvterm and let the code
  556. // below recreate it with the correct info
  557. else {
  558. $match = array('cvterm_id' => $cvterm->cvterm_id);
  559. $options = array('statement_name' => 'del_cvterm_cv');
  560. chado_delete_record('cvterm', $match, $options);
  561. }
  562. }
  563. // check that the accession matches. Sometimes an OBO can define the same term
  564. // multiple times but with different accessions. If this is the case we
  565. // can't do an insert or it will violate the constraint in the cvterm table.
  566. // so we'll need to add the record to the cvterm_dbxref table instead
  567. if ($dbxref->accession != $accession) {
  568. // get/add the dbxref fort his term
  569. $dbxref_new = tripal_db_add_dbxref($db->db_id, $accession);
  570. if (!$dbxref_new) {
  571. tripal_report_error('tripal_cv', TRIPAL_WARNING, "Failed to find or insert the dbxref record for cvterm, " .
  572. "$name (id: $accession), for database $dbname", NULL);
  573. return 0;
  574. }
  575. // check to see if the cvterm_dbxref record already exists
  576. $values = array(
  577. 'cvterm_id' => $cvterm->cvterm_id,
  578. 'dbxref_id' => $dbxref_new->dbxref_id,
  579. 'is_for_definition' => 1,
  580. );
  581. $options = array('statement_name' => 'sel_cvtermdbxref_cvdbis');
  582. $result = chado_select_record('cvterm_dbxref', array('*'), $values, $options);
  583. // if the cvterm_dbxref record does not exists then add it
  584. if (count($result)==0) {
  585. $options = array(
  586. 'statement_name' => 'ins_cvtermdbxref_cvdbis',
  587. 'return_record' => FALSE,
  588. );
  589. $success = chado_insert_record('cvterm_dbxref', $values, $options);
  590. if (!$success) {
  591. tripal_report_error('tripal_cv', TRIPAL_WARNING, "Failed to find or insert the cvterm_dbxref record for a " .
  592. "duplicated cvterm: $name (id: $accession), for database $dbname", NULL);
  593. return 0;
  594. }
  595. }
  596. // get the original cvterm with the same name and return that.
  597. $result = chado_query($cvtermsql, array(':accession' => $dbxref->accession, ':name' => $dbname));
  598. $cvterm = $result->fetchObject();
  599. return $cvterm;
  600. }
  601. // continue on, we've fixed the record if the db_id did not match,
  602. // we can now perform and updated if we need to.
  603. }
  604. // get the CVterm record
  605. $result = chado_query($cvtermsql, array(':accession' => $accession, ':name' => $dbname));
  606. $cvterm = $result->fetchObject();
  607. if (!$cvterm) {
  608. // check to see if the dbxref exists if not, add it
  609. $dbxref = tripal_db_add_dbxref($db->db_id, $accession);
  610. if (!$dbxref) {
  611. tripal_report_error('tripal_cv', TRIPAL_WARNING, "Failed to find or insert the dbxref record for cvterm, " .
  612. "$name (id: $accession), for database $dbname", NULL);
  613. return 0;
  614. }
  615. // check to see if the dbxref already has an entry in the cvterm table
  616. // this is the second constraint in the cvterm table
  617. $values = array('dbxref_id' => $dbxref->dbxref_id);
  618. $options = array('statement_name' => 'sel_cvterm_db');
  619. $check = chado_select_record('cvterm', array('cvterm_id'), $values, $options);
  620. if (count($check) == 0) {
  621. // now add the cvterm
  622. $ins_values = array(
  623. 'cv_id' => $cv->cv_id,
  624. 'name' => $name,
  625. 'definition' => $definition,
  626. 'dbxref_id' => $dbxref->dbxref_id,
  627. 'is_obsolete' => $is_obsolete,
  628. 'is_relationshiptype' => $is_relationship,
  629. );
  630. $ins_options = array('statement_name' => 'ins_cvterm_all');
  631. $success = chado_insert_record('cvterm', $ins_values, $ins_options);
  632. if (!$success) {
  633. if (!$is_relationship) {
  634. tripal_report_error('tripal_cv', TRIPAL_WARNING, "Failed to insert the term: $name ($dbname)", NULL);
  635. return 0;
  636. }
  637. else {
  638. tripal_report_error('tripal_cv', TRIPAL_WARNING, "Failed to insert the relationship term: $name (cv: " . $cvname . " db: $dbname)", NULL);
  639. return 0;
  640. }
  641. }
  642. }
  643. // this dbxref already exists in the cvterm table
  644. else {
  645. tripal_report_error('tripal_cv', TRIPAL_WARNING, "The dbxref already exists for another cvterm record: $name (cv: " . $cvname . " db: $dbname)", NULL);
  646. return 0;
  647. }
  648. $result = chado_query($cvtermsql, array(':accession' => $accession, ':name' => $dbname));
  649. $cvterm = $result->fetchObject();
  650. }
  651. // upate the cvterm
  652. elseif ($update) {
  653. $match = array('cvterm_id' => $cvterm->cvterm_id);
  654. $upd_values = array(
  655. 'name' => $name,
  656. 'definition' => $definition,
  657. 'is_obsolete' => $is_obsolete,
  658. 'is_relationshiptype' => $is_relationship,
  659. );
  660. $upd_options = array('statement_name' => 'upd_cvterm_nadeisis');
  661. $success = chado_update_record('cvterm', $match, $upd_values, $upd_options);
  662. if (!$success) {
  663. tripal_report_error('tripal_cv', TRIPAL_WARNING, "Failed to update the term: $name", NULL);
  664. return 0;
  665. }
  666. $result = chado_query($cvtermsql, array(':accession' => $accession, ':name' => $dbname));
  667. $cvterm = $result->fetchObject();
  668. }
  669. else {
  670. // do nothing, we have the cvterm but we don't want to update
  671. }
  672. // return the cvterm
  673. return $cvterm;
  674. }
  675. /**
  676. * This function allows other modules to programatically
  677. * submit an ontology for loading into Chado.
  678. *
  679. * This function will add a job to the Jobs subsystem for parsing the ontology.
  680. * You can either pass a known OBO ID to the function or the URL
  681. * or full path the the ontology file. If a URL or file name is
  682. * passed then the $obo_name argument must also be provided. If
  683. * this is the first time the ontology has been provided to Tripal
  684. * then it will be added to the database and will be assigned a
  685. * unique OBO ID.
  686. *
  687. * @param $obo_id
  688. * If the ontology is already loaded into the Tripal tables then
  689. * use this argument to specify the unique ID for the ontology
  690. * that will be loaded
  691. * @param $obo_name
  692. * If the OBO has not been added before then use this argument
  693. * to specify the human readable name of the ontology.
  694. * @param $obo_url
  695. * If the OBO to be loaded is located on a remote server then
  696. * use this argument to provide the URL.
  697. * @param $obo_file
  698. * If the OBO is housed on the local file system of the server then
  699. * use this argument to specify the full path.
  700. *
  701. * @return
  702. * returns the job_id of the submitted job or FALSE if the job was not added
  703. *
  704. * @ingroup tripal_cv_api
  705. */
  706. function tripal_submit_obo_job($obo) {
  707. global $user;
  708. // Set Defaults
  709. $obo['obo_id'] = (isset($obo['obo_id'])) ? $obo['obo_id'] : NULL;
  710. $obo['name'] = (isset($obo['name'])) ? $obo['name'] : NULL;
  711. $obo['url'] = (isset($obo['url'])) ? $obo['url'] : NULL;
  712. $obo['file'] = (isset($obo['file'])) ? $obo['file'] : NULL;
  713. if ($obo['obo_id']) {
  714. $sql = "SELECT * FROM {tripal_cv_obo} WHERE obo_id = :obo_id";
  715. $result = db_query($sql, array(':obo_id' => $obo['obo_id']))->fetchObject();
  716. $args = array($result->obo_id);
  717. return tripal_add_job("Load OBO " . $result->name, 'tripal_cv',
  718. "tripal_cv_load_obo_v1_2_id", $args, $user->uid);
  719. }
  720. else {
  721. if ($obo['url']) {
  722. $args = array($obo['name'], $obo['url']);
  723. return tripal_add_job("Load OBO $obo_name", 'tripal_cv',
  724. "tripal_cv_load_obo_v1_2_url", $args, $user->uid);
  725. }
  726. elseif ($obo['file']) {
  727. $args = array($obo['name'], $obo['file']);
  728. return tripal_add_job("Load OBO $obo_name", 'tripal_cv',
  729. "tripal_cv_load_obo_v1_2_file", $args, $user->uid);
  730. }
  731. }
  732. return FALSE;
  733. }
  734. /**
  735. * Add the obo to the tripal_cv_obo table in the Drupal database
  736. *
  737. * @param $name
  738. * The human readable name of this ontology
  739. * @param $path
  740. * The file path or URL of the ontology
  741. *
  742. * @return
  743. * Returns the ontology ID
  744. *
  745. * @ingroup tripal_cv_api
  746. */
  747. function tripal_insert_obo($name, $path) {
  748. $record = new stdClass;
  749. $record->name = $name;
  750. $record->path = $path;
  751. drupal_write_record('tripal_cv_obo', $record);
  752. return $record->obo_id;
  753. }
  754. /**
  755. * This function is intended to be used in autocomplete forms
  756. * for searching for CV terms that begin with the provided string
  757. *
  758. * @param $cv_id
  759. * The CV ID in which to search for the term
  760. * @param $string
  761. * The string to search for
  762. *
  763. * @return
  764. * A json array of terms that begin with the provided string
  765. *
  766. * @ingroup tripal_cv_api
  767. */
  768. function tripal_autocomplete_cvterm($cv_id, $string = '') {
  769. $sql = "
  770. SELECT cvterm_id, name
  771. FROM {cvterm}
  772. WHERE cv_id = :cv_id and lower(name) like lower(:name)
  773. ORDER by name
  774. LIMIT 25 OFFSET 0
  775. ";
  776. $results = chado_query($sql, array(':cv_id' => $cv_id, ':name' => $string . '%'));
  777. $items = array();
  778. foreach ($results as $term) {
  779. $items[$term->name] = $term->name;
  780. }
  781. drupal_json_output($items);
  782. }
  783. /**
  784. * Add a record to a cvterm linking table (ie: feature_cvterm)
  785. *
  786. * @param $basetable
  787. * The base table to which the cvterm should be linked/associated. Thus to associate a
  788. * cvterm to a feature the basetable=feature and cvterm_id is added to the feature_cvterm table.
  789. * @param $record_id
  790. * The primary key of the basetable to associate the cvterm with. This should be in integer.
  791. * @param $cvterm
  792. * An associative array describing the cvterm. Valid keys include: 'name' => the
  793. * name for the cvterm, 'cv_name' => the name of the cv the cvterm belongs to;
  794. * 'cv_id' => the primary key of the cv the cvterm belongs to.
  795. * @param $options
  796. * An associative array of options. Valid keys include:
  797. * - insert_cvterm: Insert the cvterm if it doesn't already exist. FALSE is the default
  798. *
  799. * @ingroup tripal_db_api
  800. */
  801. function tripal_associate_cvterm($basetable, $record_id, $cvterm) {
  802. $linking_table = $basetable . '_cvterm';
  803. $foreignkey_name = $basetable . '_id';
  804. // Default Values
  805. $options['insert_cvterm'] = (isset($options['insert_cvterm'])) ? $options['insert_cvterm'] : FALSE;
  806. // If the cvterm_id is set then we know it already exists
  807. // Otherwise, select to check
  808. if (!isset($cvterm['cvterm_id'])) {
  809. $values = array(
  810. 'name' => $cvterm['name'],
  811. );
  812. if (isset($cvterm['cv_id'])) {
  813. $values['cv_id'] = $cvterm['cv_id'];
  814. } elseif (isset($cvterm['cv_name'])) {
  815. $values['cv_id'] = array(
  816. 'name' => $cvterm['cv_name']
  817. );
  818. }
  819. else {
  820. tripal_report_error(
  821. 'tripal_cv_api',
  822. TRIPAL_WARNING,
  823. "tripal_associate_cvterm: The cvterm needs to have either the cv_name or cv_id
  824. supplied. You were trying to associate a cvterm with the %base %record_id
  825. and supplied the cvterm values: %cvterm.",
  826. array('%base' => $basetable, '%record_id' => $record_id, '%cvterm' => print_r($cvterm,TRUE))
  827. );
  828. return FALSE;
  829. }
  830. $select = chado_select_record('cvterm',array('*'), $values);
  831. if ($select) {
  832. $cvterm['cvterm_id'] = $select[0]->cvterm_id;
  833. }
  834. elseif ($options['insert_cvterm']) {
  835. // Insert the cvterm
  836. $insert = tripal_insert_cvterm($values);
  837. if (isset($insert->cvterm_id)) {
  838. $cvterm['cvterm_id'] = $insert->cvterm_id;
  839. }
  840. else {
  841. tripal_report_error(
  842. 'tripal_cv_api',
  843. TRIPAL_WARNING,
  844. "tripal_associate_cvterm: Unable to insert the cvterm using the cvterm values: %cvterm.",
  845. array('%cvterm' => print_r($cvterm,TRUE))
  846. );
  847. return FALSE;
  848. }
  849. }
  850. else {
  851. tripal_report_error(
  852. 'tripal_api',
  853. TRIPAL_WARNING,
  854. "tripal_associate_cvterm: The cvterm doesn't already exist. You supplied the cvterm values: %cvterm.",
  855. array('%cvterm' => print_r($cvterm,TRUE))
  856. );
  857. return FALSE;
  858. }
  859. }
  860. // Now add the link between the record & cvterm
  861. if ($cvterm['cvterm_id'] > 0) {
  862. $values = array(
  863. 'cvterm_id' => $cvterm['cvterm_id'],
  864. $foreignkey_name => $record_id,
  865. 'pub_id' => 1,
  866. );
  867. $result = chado_select_record($linking_table, array('*'), $values);
  868. // if it doesn't already exist then add it
  869. if (!$result) {
  870. $success = chado_insert_record($linking_table, $values);
  871. if (!$success) {
  872. tripal_report_error(
  873. 'tripal_api',
  874. TRIPAL_WARNING,
  875. "Failed to insert the %base record %term",
  876. array('%base' => $linking_table, '%term' => $cvterm['name'])
  877. );
  878. return FALSE;
  879. }
  880. $result = chado_select_record($linking_table, array('*'), $values);
  881. }
  882. if (isset($result[0])) {
  883. return $result[0];
  884. }
  885. else {
  886. return FALSE;
  887. }
  888. }
  889. return FALSE;
  890. }
  891. /**
  892. * This function sets the default vocabulary for a given table and field.
  893. *
  894. * @param $table
  895. * The name of the table that contains a field with a foreign key
  896. * relationship to the cvterm table
  897. * @param $field
  898. * The table field name that has the foreign key relationship to the
  899. * cvterm table for which the default vocabulary will be set
  900. * @param $cv_name
  901. * The name of the vocabulary
  902. *
  903. * @return
  904. * TRUE if set, FALSE if an error occured
  905. */
  906. function tripal_set_default_cv($table, $field, $cv_name) {
  907. // make sure the cv_id is valid
  908. $cv = tripal_get_cv(array('name' => $cv_name));
  909. if ($cv) {
  910. // first delete any entries for this table and field
  911. $num_deleted = db_delete('tripal_cv_defaults')
  912. ->condition('table_name', $table)
  913. ->condition('field_name', $field)
  914. ->execute();
  915. // now add the default value
  916. $cv_default_id = db_insert('tripal_cv_defaults')
  917. ->fields(array(
  918. 'table_name' => $table,
  919. 'field_name' => $field,
  920. 'cv_id' => $cv->cv_id,
  921. ))
  922. ->execute();
  923. if (!$cv_default_id) {
  924. tripal_report_error('tripal_cv', TRIPAL_WARNING,
  925. "Cannot set default vocabulary for %table.%field. Check the error logs.",
  926. array('%table' => $table, '%field' => $field));
  927. return FALSE;
  928. }
  929. }
  930. else {
  931. tripal_report_error('tripal_cv', TRIPAL_WARNING,
  932. "Cannot set default vocabulary for %table.%field. The vocabulary name, '%cvname', doesn't exist.",
  933. array('%table' => $table, '%field' => $field, '%cvname' => $cv_name));
  934. return FALSE;
  935. }
  936. }
  937. /**
  938. * Retreives the default vocabulary for a given table and field
  939. * @param $table
  940. * The name of the table that contains a field with a foreign key
  941. * relationship to the cvterm table
  942. * @param $field
  943. * The table field name that has the foreign key relationship to the
  944. * cvterm table for which the default vocabulary will be set
  945. *
  946. * @return
  947. * The cv array of the default vocabulary or an empty array if not
  948. * available.
  949. */
  950. function tripal_get_default_cv($table, $field) {
  951. $sql = "
  952. SELECT cv_id
  953. FROM {tripal_cv_defaults}
  954. WHERE table_name = :table and field_name = :field
  955. ";
  956. $cv_id = db_query($sql, array(':table' => $table, ':field' => $field))->fetchField();
  957. return tripal_get_cv(array('cv_id' => $cv_id));
  958. }
  959. /**
  960. * Create an options array to be used in a form element
  961. * which provides a list of all chado cvterms. Unlike the
  962. * tripal_get_cvterm_select_option, this function retreives the cvterms using
  963. * the default vocabulary set for a given table and field. It will also
  964. * notify the administrative user if a default vocabulary is missing for the
  965. * field and if the vocabulary is empty.
  966. *
  967. * @param $table
  968. * The name of the table that contains the field with a foreign key
  969. * relationship to the cvterm table
  970. * @param $field
  971. * The table field name that has the foreign key relationship to the
  972. * cvterm table for which the default vocabulary will be set
  973. * @param $field_desc
  974. * A human readable descriptive name for the field
  975. *
  976. * @return
  977. * An array(cvterm_id => name)
  978. * for each cvterm in the chado cvterm table where cv_id=that supplied
  979. */
  980. function tripal_get_cvterm_default_select_options($table, $field, $field_desc) {
  981. $default_cv = tripal_get_default_cv($table, $field);
  982. $options = array();
  983. if ($default_cv) {
  984. $options = tripal_get_cvterm_select_options($default_cv->cv_id);
  985. }
  986. else {
  987. tripal_set_message('There is not a default vocabulary set for ' . $field_desc . '. '.
  988. 'Please set one using the ' .
  989. l('vocabulary defaults configuration page',
  990. 'admin/tripal/chado/tripal_cv/defaults',
  991. array('attributes' => array('target' => '_blank'))) . '.',
  992. TRIPAL_WARNING);
  993. }
  994. if (count($options) == 0) {
  995. tripal_set_message('There are no ' . $field_desc . '. Please ' .
  996. l('add terms',
  997. 'admin/tripal/chado/tripal_cv/cv/' .$default_cv->cv_id. '/cvterm/add',
  998. array('attributes' => array('target' => '_blank'))) . ' to the ' .
  999. $default_cv->name .' vocabulary.',
  1000. TRIPAL_WARNING);
  1001. }
  1002. return $options;
  1003. }