tripal_cv.api.inc 38 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105
  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; only cvterms with the supplied cv_id will be returned
  249. *
  250. * @return
  251. * An associative array with the cvterm_id's as keys. The first
  252. * element in the array has a key of '0' and a value of 'Select a Type'
  253. *
  254. * @ingroup tripal_cv_api
  255. */
  256. function tripal_get_cvterm_select_options($cv_id) {
  257. $columns = array('cvterm_id', 'name');
  258. $values = array('cv_id' => $cv_id);
  259. $s_options = array('order_by' => array('name' => 'ASC'));
  260. $cvterms = chado_select_record('cvterm', $columns, $values, $s_options);
  261. $options = array();
  262. $options[0] = 'Select a Type';
  263. foreach ($cvterms as $cvterm) {
  264. $options[$cvterm->cvterm_id] = $cvterm->name;
  265. }
  266. return $options;
  267. }
  268. /**
  269. * Updates the cvtermpath table of Chado for the specified CV.
  270. *
  271. * @param $cv_id
  272. * The chado cv_id;
  273. * @param $job_id
  274. * This function is intended to be used with the Tripal Jobs API.
  275. * When this function is called as a job the $job_id is automatically
  276. * passed to this function.
  277. * @return
  278. * TRUE on success FALSE on failure
  279. *
  280. * @ingroup tripal_cv_api
  281. */
  282. function tripal_update_cvtermpath($cv_id, $job_id = NULL) {
  283. // TODO: need better error checking in this function
  284. // first get the controlled vocabulary name:
  285. $sql = "SELECT * FROM {cv} WHERE cv_id = :cv_id";
  286. $cv = chado_query($sql, array(':cv_id' => $cv_id))->fetchObject();
  287. print "\nUpdating cvtermpath for $cv->name...\n";
  288. $previous = chado_set_active('chado');
  289. try {
  290. $sql = "SELECT * FROM fill_cvtermpath(:name)";
  291. db_query($sql, array(':name' => $cv->name));
  292. chado_set_active($previous);
  293. }
  294. catch (Exception $e) {
  295. chado_set_active($previous);
  296. $error = $e->getMessage();
  297. tripal_report_error('tripal_cv', TRIPAL_ERROR, "Could not fill cvtermpath table: @error", array('@error' => $error));
  298. return FALSE;
  299. }
  300. return TRUE;
  301. }
  302. /**
  303. * Adds a controlled vocabular to the CV table of Chado.
  304. *
  305. * @param $name
  306. * The name of the controlled vocabulary. These are typically all lower case
  307. * with no special characters other than an undrescore (for spaces).
  308. * @param $comment
  309. * A description or definition of the vocabulary.
  310. *
  311. * @return
  312. * An object populated with fields from the newly added database.
  313. *
  314. * @ingroup tripal_cv_api
  315. */
  316. function tripal_insert_cv($name, $definition) {
  317. // insert/update values
  318. $ins_values = array(
  319. 'name' => $name,
  320. 'definition' => $definition
  321. );
  322. // see if the CV (default-namespace) exists already in the database
  323. $sel_values = array('name' => $name);
  324. $sel_options = array('statement_name' => 'sel_cv_na');
  325. $results = chado_select_record('cv', array('*'), $sel_values, $sel_options);
  326. // if it does not exists then add it
  327. if (count($results) == 0) {
  328. $ins_options = array('statement_name' => 'ins_cv_nade');
  329. $success = chado_insert_record('cv', $ins_values, $ins_options);
  330. if (!$success) {
  331. tripal_report_error('tripal_cv', TRIPAL_WARNING, "Failed to create the CV record", NULL);
  332. return FALSE;
  333. }
  334. $results = chado_select_record('cv', array('*'), $sel_values, $sel_options);
  335. }
  336. // if it already exists then do an update
  337. else {
  338. $upd_options = array('statement_name' => 'upd_cv_nade');
  339. $success = chado_update_record('cv', $sel_values, $ins_values, $upd_options);
  340. if (!$success) {
  341. tripal_report_error('tripal_cv', TRIPAL_WARNING, "Failed to update the CV record", NULL);
  342. return FALSE;
  343. }
  344. $results = chado_select_record('cv', array('*'), $sel_values, $sel_options);
  345. }
  346. // return the cv object
  347. return $results[0];
  348. }
  349. /**
  350. * Add's a controlled vocabulary term to the cvterm table.
  351. *
  352. * If the parent CV does not exist then
  353. * that too is added to the CV table. If the cvterm is a relationship term
  354. * then the $is_relationship argument should be set. The function will try
  355. * to first find the relationship in the relationship ontology for updating and
  356. * if it can't be found will add the relationship to the __global CV. All terms
  357. * must also have a corresponding database. This is specified in the term's
  358. * ID just before the colon (e.g. GO:003824). If the database does not exist
  359. * in the DB table then it will be added automatically. The accession (the
  360. * value just after the colon in the term's ID) will be added to the dbxref
  361. * table. If the CVterm already exists and $update is set (default) then the
  362. * cvterm is updated. If the CVTerm already exists and $update is not set, then
  363. * no changes are made and the CVTerm object is returned.
  364. *
  365. * @param $term
  366. * An associative array with the following keys:
  367. * - id: the term accession. must be of the form <DB>:<ACCESSION>, where <DB> is the
  368. * name of the database to which the cvterm belongs and the <ACCESSION> is the
  369. * term's accession number in the database.
  370. * - name: the name of the term. usually meant to be human-readable.
  371. * - namespace: the CV name for the term. DEPRECATED. Please use cv_name instead.
  372. * - is_obsolete: is present and set to 1 if the term is defunct
  373. * - definition: the definition of the term
  374. * - cv_name: The CV name to which the term belongs. If this arugment is null or not
  375. * provided then the function tries to find a record in the CV table with the same
  376. * name provided in the $term[namespace]. If this field is provided then it
  377. * overrides what the value in $term[namespace]
  378. * - is_relationship: If this term is a relationship term then this value should be 1.
  379. * - db_name: In some cases the database name will not be part of the $term['id'] and it
  380. * needs to be explicitly set. Use this argument only if the database name
  381. * cannot be specififed in the term ID (e.g. <DB>:<ACCESSION>).
  382. * @param $options
  383. * An associative array with the following keys:
  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_get_cv(array('name' => $cvname));
  474. if (!$cv) {
  475. $cv = tripal_insert_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_insert_db(array('name' => $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_insert_dbxref(array(
  570. 'db_id' => $db->db_id,
  571. 'accession' => $accession
  572. ));
  573. if (!$dbxref_new) {
  574. tripal_report_error('tripal_cv', TRIPAL_WARNING, "Failed to find or insert the dbxref record for cvterm, " .
  575. "$name (id: $accession), for database $dbname", NULL);
  576. return 0;
  577. }
  578. // check to see if the cvterm_dbxref record already exists
  579. $values = array(
  580. 'cvterm_id' => $cvterm->cvterm_id,
  581. 'dbxref_id' => $dbxref_new->dbxref_id,
  582. 'is_for_definition' => 1,
  583. );
  584. $options = array('statement_name' => 'sel_cvtermdbxref_cvdbis');
  585. $result = chado_select_record('cvterm_dbxref', array('*'), $values, $options);
  586. // if the cvterm_dbxref record does not exists then add it
  587. if (count($result)==0) {
  588. $options = array(
  589. 'statement_name' => 'ins_cvtermdbxref_cvdbis',
  590. 'return_record' => FALSE,
  591. );
  592. $success = chado_insert_record('cvterm_dbxref', $values, $options);
  593. if (!$success) {
  594. tripal_report_error('tripal_cv', TRIPAL_WARNING, "Failed to find or insert the cvterm_dbxref record for a " .
  595. "duplicated cvterm: $name (id: $accession), for database $dbname", NULL);
  596. return 0;
  597. }
  598. }
  599. // get the original cvterm with the same name and return that.
  600. $result = chado_query($cvtermsql, array(':accession' => $dbxref->accession, ':name' => $dbname));
  601. $cvterm = $result->fetchObject();
  602. return $cvterm;
  603. }
  604. // continue on, we've fixed the record if the db_id did not match,
  605. // we can now perform and updated if we need to.
  606. }
  607. // get the CVterm record
  608. $result = chado_query($cvtermsql, array(':accession' => $accession, ':name' => $dbname));
  609. $cvterm = $result->fetchObject();
  610. if (!$cvterm) {
  611. // check to see if the dbxref exists if not, add it
  612. $dbxref = tripal_insert_dbxref(array(
  613. 'db_id' => $db->db_id,
  614. 'accession' => $accession
  615. ));
  616. if (!$dbxref) {
  617. tripal_report_error('tripal_cv', TRIPAL_WARNING, "Failed to find or insert the dbxref record for cvterm, " .
  618. "$name (id: $accession), for database $dbname", NULL);
  619. return 0;
  620. }
  621. // check to see if the dbxref already has an entry in the cvterm table
  622. // this is the second constraint in the cvterm table
  623. $values = array('dbxref_id' => $dbxref->dbxref_id);
  624. $options = array('statement_name' => 'sel_cvterm_db');
  625. $check = chado_select_record('cvterm', array('cvterm_id'), $values, $options);
  626. if (count($check) == 0) {
  627. // now add the cvterm
  628. $ins_values = array(
  629. 'cv_id' => $cv->cv_id,
  630. 'name' => $name,
  631. 'definition' => $definition,
  632. 'dbxref_id' => $dbxref->dbxref_id,
  633. 'is_obsolete' => $is_obsolete,
  634. 'is_relationshiptype' => $is_relationship,
  635. );
  636. $ins_options = array('statement_name' => 'ins_cvterm_all');
  637. $success = chado_insert_record('cvterm', $ins_values, $ins_options);
  638. if (!$success) {
  639. if (!$is_relationship) {
  640. tripal_report_error('tripal_cv', TRIPAL_WARNING, "Failed to insert the term: $name ($dbname)", NULL);
  641. return 0;
  642. }
  643. else {
  644. tripal_report_error('tripal_cv', TRIPAL_WARNING, "Failed to insert the relationship term: $name (cv: " . $cvname . " db: $dbname)", NULL);
  645. return 0;
  646. }
  647. }
  648. }
  649. // this dbxref already exists in the cvterm table
  650. else {
  651. tripal_report_error('tripal_cv', TRIPAL_WARNING, "The dbxref already exists for another cvterm record: $name (cv: " . $cvname . " db: $dbname)", NULL);
  652. return 0;
  653. }
  654. $result = chado_query($cvtermsql, array(':accession' => $accession, ':name' => $dbname));
  655. $cvterm = $result->fetchObject();
  656. }
  657. // upate the cvterm
  658. elseif ($update) {
  659. $match = array('cvterm_id' => $cvterm->cvterm_id);
  660. $upd_values = array(
  661. 'name' => $name,
  662. 'definition' => $definition,
  663. 'is_obsolete' => $is_obsolete,
  664. 'is_relationshiptype' => $is_relationship,
  665. );
  666. $upd_options = array('statement_name' => 'upd_cvterm_nadeisis');
  667. $success = chado_update_record('cvterm', $match, $upd_values, $upd_options);
  668. if (!$success) {
  669. tripal_report_error('tripal_cv', TRIPAL_WARNING, "Failed to update the term: $name", NULL);
  670. return 0;
  671. }
  672. $result = chado_query($cvtermsql, array(':accession' => $accession, ':name' => $dbname));
  673. $cvterm = $result->fetchObject();
  674. }
  675. else {
  676. // do nothing, we have the cvterm but we don't want to update
  677. }
  678. // return the cvterm
  679. return $cvterm;
  680. }
  681. /**
  682. * This function allows other modules to programatically
  683. * submit an ontology for loading into Chado.
  684. *
  685. * This function will add a job to the Jobs subsystem for parsing the ontology.
  686. * You can either pass a known OBO ID to the function or the URL
  687. * or full path the the ontology file. If a URL or file name is
  688. * passed then the $obo_name argument must also be provided. If
  689. * this is the first time the ontology has been provided to Tripal
  690. * then it will be added to the database and will be assigned a
  691. * unique OBO ID.
  692. *
  693. * @param $obo_id
  694. * If the ontology is already loaded into the Tripal tables then
  695. * use this argument to specify the unique ID for the ontology
  696. * that will be loaded
  697. * @param $obo_name
  698. * If the OBO has not been added before then use this argument
  699. * to specify the human readable name of the ontology.
  700. * @param $obo_url
  701. * If the OBO to be loaded is located on a remote server then
  702. * use this argument to provide the URL.
  703. * @param $obo_file
  704. * If the OBO is housed on the local file system of the server then
  705. * use this argument to specify the full path.
  706. *
  707. * @return
  708. * returns the job_id of the submitted job or FALSE if the job was not added
  709. *
  710. * @ingroup tripal_cv_api
  711. */
  712. function tripal_submit_obo_job($obo) {
  713. global $user;
  714. // Set Defaults
  715. $obo['obo_id'] = (isset($obo['obo_id'])) ? $obo['obo_id'] : NULL;
  716. $obo['name'] = (isset($obo['name'])) ? $obo['name'] : NULL;
  717. $obo['url'] = (isset($obo['url'])) ? $obo['url'] : NULL;
  718. $obo['file'] = (isset($obo['file'])) ? $obo['file'] : NULL;
  719. if ($obo['obo_id']) {
  720. $sql = "SELECT * FROM {tripal_cv_obo} WHERE obo_id = :obo_id";
  721. $result = db_query($sql, array(':obo_id' => $obo['obo_id']))->fetchObject();
  722. $args = array($result->obo_id);
  723. return tripal_add_job("Load OBO " . $result->name, 'tripal_cv',
  724. "tripal_cv_load_obo_v1_2_id", $args, $user->uid);
  725. }
  726. else {
  727. if ($obo['url']) {
  728. $args = array($obo['name'], $obo['url']);
  729. return tripal_add_job("Load OBO " . $obo['name'], 'tripal_cv',
  730. "tripal_cv_load_obo_v1_2_url", $args, $user->uid);
  731. }
  732. elseif ($obo['file']) {
  733. $args = array($obo['name'], $obo['file']);
  734. return tripal_add_job("Load OBO " . $obo['name'], 'tripal_cv',
  735. "tripal_cv_load_obo_v1_2_file", $args, $user->uid);
  736. }
  737. }
  738. return FALSE;
  739. }
  740. /**
  741. * Add the obo to the tripal_cv_obo table in the Drupal database
  742. *
  743. * @param $name
  744. * The human readable name of this ontology
  745. * @param $path
  746. * The file path or URL of the ontology
  747. *
  748. * @return
  749. * Returns the ontology ID
  750. *
  751. * @ingroup tripal_cv_api
  752. */
  753. function tripal_insert_obo($name, $path) {
  754. $record = new stdClass;
  755. $record->name = $name;
  756. $record->path = $path;
  757. drupal_write_record('tripal_cv_obo', $record);
  758. return $record->obo_id;
  759. }
  760. /**
  761. * This function is intended to be used in autocomplete forms
  762. * for searching for CV terms that begin with the provided string
  763. *
  764. * @param $cv_id
  765. * The CV ID in which to search for the term
  766. * @param $string
  767. * The string to search for
  768. *
  769. * @return
  770. * A json array of terms that begin with the provided string
  771. *
  772. * @ingroup tripal_cv_api
  773. */
  774. function tripal_autocomplete_cvterm($cv_id, $string = '') {
  775. $sql = "
  776. SELECT cvterm_id, name
  777. FROM {cvterm}
  778. WHERE cv_id = :cv_id and lower(name) like lower(:name)
  779. ORDER by name
  780. LIMIT 25 OFFSET 0
  781. ";
  782. $results = chado_query($sql, array(':cv_id' => $cv_id, ':name' => $string . '%'));
  783. $items = array();
  784. foreach ($results as $term) {
  785. $items[$term->name] = $term->name;
  786. }
  787. drupal_json_output($items);
  788. }
  789. /**
  790. * Add a record to a cvterm linking table (ie: feature_cvterm)
  791. *
  792. * @param $basetable
  793. * The base table to which the cvterm should be linked/associated. Thus to associate a
  794. * cvterm to a feature the basetable=feature and cvterm_id is added to the feature_cvterm table.
  795. * @param $record_id
  796. * The primary key of the basetable to associate the cvterm with. This should be in integer.
  797. * @param $cvterm
  798. * An associative array describing the cvterm. Valid keys include:
  799. * - name: the name for the cvterm,
  800. * - cv_name: the name of the cv the cvterm belongs to.
  801. * - cv_id: the primary key of the cv the cvterm belongs to.
  802. * @param $options
  803. * An associative array of options. Valid keys include:
  804. * - insert_cvterm: Insert the cvterm if it doesn't already exist. FALSE is the default
  805. *
  806. * @ingroup tripal_db_api
  807. */
  808. function tripal_associate_cvterm($basetable, $record_id, $cvterm, $options = array()) {
  809. $linking_table = $basetable . '_cvterm';
  810. $foreignkey_name = $basetable . '_id';
  811. // Default Values
  812. $options['insert_cvterm'] = (isset($options['insert_cvterm'])) ? $options['insert_cvterm'] : FALSE;
  813. // If the cvterm_id is not set then find the cvterm record using the name and cv_id
  814. if (!isset($cvterm['cvterm_id'])) {
  815. $values = array(
  816. 'name' => $cvterm['name'],
  817. );
  818. if (isset($cvterm['cv_id'])) {
  819. $values['cv_id'] = $cvterm['cv_id'];
  820. }
  821. elseif (isset($cvterm['cv_name'])) {
  822. $values['cv_id'] = array(
  823. 'name' => $cvterm['cv_name']
  824. );
  825. }
  826. else {
  827. tripal_report_error('tripal_cv_api', TRIPAL_WARNING,
  828. "tripal_associate_cvterm: The cvterm needs to have either the cv_name or cv_id
  829. supplied. You were trying to associate a cvterm with the %base %record_id
  830. and supplied the cvterm values: %cvterm.",
  831. array('%base' => $basetable, '%record_id' => $record_id, '%cvterm' => print_r($cvterm,TRUE))
  832. );
  833. return FALSE;
  834. }
  835. // Get the cvterm. If it doesn't exist then add it if the option
  836. // 'insert_cvterm' is set.
  837. $select = chado_select_record('cvterm', array('*'), $values);
  838. if ($select) {
  839. $cvterm['cvterm_id'] = $select[0]->cvterm_id;
  840. }
  841. elseif ($options['insert_cvterm']) {
  842. // Insert the cvterm
  843. $insert = tripal_insert_cvterm($values);
  844. if (isset($insert->cvterm_id)) {
  845. $cvterm['cvterm_id'] = $insert->cvterm_id;
  846. }
  847. else {
  848. tripal_report_error('tripal_cv_api', TRIPAL_WARNING,
  849. "tripal_associate_cvterm: Unable to insert the cvterm using the cvterm values: %cvterm.",
  850. array('%cvterm' => print_r($cvterm,TRUE))
  851. );
  852. return FALSE;
  853. }
  854. }
  855. else {
  856. tripal_report_error('tripal_api', TRIPAL_WARNING,
  857. "tripal_associate_cvterm: The cvterm doesn't already exist. You supplied the cvterm values: %cvterm.",
  858. array('%cvterm' => print_r($cvterm,TRUE))
  859. );
  860. return FALSE;
  861. }
  862. }
  863. // Now add the link between the record & cvterm
  864. if ($cvterm['cvterm_id'] > 0) {
  865. $values = array(
  866. 'cvterm_id' => $cvterm['cvterm_id'],
  867. $foreignkey_name => $record_id,
  868. 'pub_id' => 1,
  869. );
  870. // Check if the cvterm is already associated. If so, don't re-add it.
  871. $result = chado_select_record($linking_table, array('*'), $values);
  872. if (!$result) {
  873. $success = chado_insert_record($linking_table, $values);
  874. if (!$success) {
  875. tripal_report_error('tripal_api', TRIPAL_WARNING,
  876. "Failed to insert the %base record %term",
  877. array('%base' => $linking_table, '%term' => $cvterm['name'])
  878. );
  879. return FALSE;
  880. }
  881. $result = chado_select_record($linking_table, array('*'), $values);
  882. }
  883. if (isset($result[0])) {
  884. return $result[0];
  885. }
  886. else {
  887. return FALSE;
  888. }
  889. }
  890. return FALSE;
  891. }
  892. /**
  893. * This function sets the default vocabulary for a given table and field.
  894. *
  895. * @param $table
  896. * The name of the table that contains a field with a foreign key
  897. * relationship to the cvterm table
  898. * @param $field
  899. * The table field name that has the foreign key relationship to the
  900. * cvterm table for which the default vocabulary will be set
  901. * @param $cv_name
  902. * The name of the vocabulary
  903. *
  904. * @return
  905. * TRUE if set, FALSE if an error occured
  906. */
  907. function tripal_set_default_cv($table, $field, $cv_name, $cv_id = FALSE) {
  908. // Get the CV object
  909. if ($cv_id) {
  910. $cv = tripal_get_cv(array('cv_id' => $cv_id));
  911. }
  912. else {
  913. $cv = tripal_get_cv(array('name' => $cv_name));
  914. }
  915. if ($cv) {
  916. // first delete any entries for this table and field
  917. $num_deleted = db_delete('tripal_cv_defaults')
  918. ->condition('table_name', $table)
  919. ->condition('field_name', $field)
  920. ->execute();
  921. // now add the default value
  922. $cv_default_id = db_insert('tripal_cv_defaults')
  923. ->fields(array(
  924. 'table_name' => $table,
  925. 'field_name' => $field,
  926. 'cv_id' => $cv->cv_id,
  927. ))
  928. ->execute();
  929. if (!$cv_default_id) {
  930. tripal_report_error('tripal_cv', TRIPAL_WARNING,
  931. "Cannot set default vocabulary for %table.%field. Check the error logs.",
  932. array('%table' => $table, '%field' => $field));
  933. return FALSE;
  934. }
  935. }
  936. else {
  937. tripal_report_error('tripal_cv', TRIPAL_WARNING,
  938. "Cannot set default vocabulary for %table.%field. The vocabulary name, '%cvname', doesn't exist.",
  939. array('%table' => $table, '%field' => $field, '%cvname' => $cv_name));
  940. return FALSE;
  941. }
  942. }
  943. /**
  944. * Retreives the default vocabulary for a given table and field
  945. * @param $table
  946. * The name of the table that contains a field with a foreign key
  947. * relationship to the cvterm table
  948. * @param $field
  949. * The table field name that has the foreign key relationship to the
  950. * cvterm table for which the default vocabulary will be set
  951. *
  952. * @return
  953. * The cv object of the default vocabulary or an empty array if not
  954. * available.
  955. */
  956. function tripal_get_default_cv($table, $field) {
  957. $sql = "
  958. SELECT cv_id
  959. FROM {tripal_cv_defaults}
  960. WHERE table_name = :table and field_name = :field
  961. ";
  962. $cv_id = db_query($sql, array(':table' => $table, ':field' => $field))->fetchField();
  963. return tripal_get_cv(array('cv_id' => $cv_id));
  964. }
  965. /**
  966. * Create an options array to be used in a form element
  967. * which provides a list of all chado cvterms. Unlike the
  968. * tripal_get_cvterm_select_option, this function retreives the cvterms using
  969. * the default vocabulary set for a given table and field. It will also
  970. * notify the administrative user if a default vocabulary is missing for the
  971. * field and if the vocabulary is empty.
  972. *
  973. * @param $table
  974. * The name of the table that contains the field with a foreign key
  975. * relationship to the cvterm table
  976. * @param $field
  977. * The table field name that has the foreign key relationship to the
  978. * cvterm table for which the default vocabulary will be set
  979. * @param $field_desc
  980. * A human readable descriptive name for the field
  981. *
  982. * @return
  983. * An array(cvterm_id => name)
  984. * for each cvterm in the chado cvterm table where cv_id=that supplied
  985. */
  986. function tripal_get_cvterm_default_select_options($table, $field, $field_desc) {
  987. $default_cv = tripal_get_default_cv($table, $field);
  988. $options = array();
  989. if ($default_cv) {
  990. $options = tripal_get_cvterm_select_options($default_cv->cv_id);
  991. if (count($options) == 0) {
  992. tripal_set_message('There are no ' . $field_desc . '. Please ' .
  993. l('add terms',
  994. 'admin/tripal/chado/tripal_cv/cv/' .$default_cv->cv_id. '/cvterm/add',
  995. array('attributes' => array('target' => '_blank'))) . ' to the ' .
  996. $default_cv->name .' vocabulary.',
  997. TRIPAL_WARNING);
  998. }
  999. }
  1000. else {
  1001. tripal_set_message('There is not a default vocabulary set for ' . $field_desc . '. '.
  1002. 'Please set one using the ' .
  1003. l('vocabulary defaults configuration page',
  1004. 'admin/tripal/chado/tripal_cv/defaults',
  1005. array('attributes' => array('target' => '_blank'))) . '.',
  1006. TRIPAL_WARNING);
  1007. }
  1008. return $options;
  1009. }