tripal_db.api.inc

  1. 2.x tripal_db/api/tripal_db.api.inc
  2. 1.x tripal_db/api/tripal_db.api.inc

Provides an application programming interface (API) to manage references to external databases

File

tripal_db/api/tripal_db.api.inc
View source
  1. <?php
  2. /**
  3. * @file
  4. * Provides an application programming interface (API) to manage references to
  5. * external databases
  6. */
  7. /**
  8. * @defgroup tripal_db_api Database Reference API
  9. * @ingroup tripal_api
  10. * @{
  11. * Provides an application programming interface (API) to manage references to external databases
  12. * @}
  13. */
  14. /**
  15. * Retrieves a chado db variable
  16. *
  17. * Example Usage:
  18. * @code
  19. $select_values = array(
  20. 'name' => 'SOFP'
  21. );
  22. $db_object = tripal_get_db($select_values);
  23. * @endcode
  24. * The above code selects the SOFP db and returns the following object:
  25. * @code
  26. $db_object = stdClass Object (
  27. [db_id] => 49
  28. [name] => SOFP
  29. [description] =>
  30. [urlprefix] =>
  31. [url] =>
  32. );
  33. * @endcode
  34. *
  35. * @param $identifier
  36. * An array with the key stating what the identifier is. Supported keys (only on of the
  37. * following unique keys is required):
  38. * - db_id: the chado db.db_id primary key
  39. * - name: the chado db.name field (assume unique)
  40. * @param $options
  41. * An array of options. Supported keys include:
  42. * - Any keys supported by chado_generate_var(). See that function definition for
  43. * additional details.
  44. *
  45. * NOTE: the $identifier parameter can really be any array similar to $values passed into
  46. * chado_select_record(). It should fully specify the db record to be returned.
  47. *
  48. * @return
  49. * If unique values were passed in as an identifier then an object describing the cv
  50. * will be returned (will be a chado variable from chado_generate_var()). Otherwise,
  51. * an array of objects will be returned.
  52. *
  53. * @ingroup tripal_db_api
  54. */
  55. function tripal_get_db($identifiers, $options = array()) {
  56. // Set Defaults
  57. if (!isset($options['include_fk'])) {
  58. // Tells chado_generate_var not to follow any foreign keys
  59. $options['include_fk'] = array();
  60. }
  61. // Error Checking of parameters
  62. if (!is_array($identifiers)) {
  63. tripal_report_error(
  64. 'tripal_db_api',
  65. TRIPAL_ERROR,
  66. "tripal_get_db: The identifier passed in is expected to be an array with the key
  67. matching a column name in the db table (ie: db_id or name). You passed in %identifier.",
  68. array(
  69. '%identifier'=> print_r($identifiers, TRUE)
  70. )
  71. );
  72. }
  73. elseif (empty($identifiers)) {
  74. tripal_report_error(
  75. 'tripal_db_api',
  76. TRIPAL_ERROR,
  77. "tripal_get_db: You did not pass in anything to identify the db you want. The identifier
  78. is expected to be an array with the key matching a column name in the db table
  79. (ie: db_id or name). You passed in %identifier.",
  80. array(
  81. '%identifier'=> print_r($identifiers, TRUE)
  82. )
  83. );
  84. }
  85. // Try to get the db
  86. $db = chado_generate_var(
  87. 'db',
  88. $identifiers,
  89. $options
  90. );
  91. // Ensure the db is singular. If it's an array then it is not singular
  92. if (is_array($db)) {
  93. tripal_report_error(
  94. 'tripal_db_api',
  95. TRIPAL_ERROR,
  96. "tripal_get_db: The identifiers you passed in were not unique. You passed in %identifier.",
  97. array(
  98. '%identifier'=> print_r($identifiers, TRUE)
  99. )
  100. );
  101. }
  102. // Report an error if $db is FALSE since then chado_generate_var has failed
  103. elseif ($db === FALSE) {
  104. tripal_report_error(
  105. 'tripal_db_api',
  106. TRIPAL_ERROR,
  107. "tripal_get_db: chado_generate_var() failed to return a db based on the identifiers
  108. you passed in. You should check that your identifiers are correct, as well as, look
  109. for a chado_generate_var error for additional clues. You passed in %identifier.",
  110. array(
  111. '%identifier'=> print_r($identifiers, TRUE)
  112. )
  113. );
  114. }
  115. // Else, as far we know, everything is fine so give them their db :)
  116. else {
  117. return $db;
  118. }
  119. }
  120. /**
  121. * Create an options array to be used in a form element
  122. * which provides a list of all chado dbs
  123. *
  124. * @return
  125. * An array(db_id => name) for each db in the chado db table
  126. *
  127. * @ingroup tripal_db_api
  128. */
  129. function tripal_get_db_select_options() {
  130. $dbs = chado_query("SELECT db_id, name FROM {db} ORDER BY name");
  131. $options = array();
  132. $options[] = 'Select a Database';
  133. foreach ($dbs as $db) {
  134. $options[$db->db_id] = $db->name;
  135. }
  136. return $options;
  137. }
  138. /**
  139. * Retrieves a chado database reference variable
  140. *
  141. * Example Usage:
  142. * @code
  143. $identifiers = array(
  144. 'accession' => 'synonym',
  145. 'db_id' => array(
  146. 'name' => 'SOFP'
  147. )
  148. );
  149. $dbxref_object = tripal_get_dbxref($identifiers);
  150. * @endcode
  151. * The above code selects the synonym database reference and returns the following object:
  152. * @code
  153. $dbxref_object = stdClass Object (
  154. [dbxref_id] => 2581
  155. [accession] => synonym
  156. [description] =>
  157. [version] =>
  158. [db_db_id] => 49
  159. [db_name] => SOFP
  160. [db_description] =>
  161. [db_urlprefix] =>
  162. [db_url] =>
  163. );
  164. * @endcode
  165. *
  166. * @param $identifier
  167. * An array apropriate for use with the chado_generate_var for uniquely
  168. * identifying a dbxref record. Alternatively, there are also some specially
  169. * handled keys. They are:
  170. * - property: An array/object describing the property to select records for. It
  171. * should at least have either a type_name (if unique across cvs) or type_id. Other
  172. * supported keys include: cv_id/cv_name (of the type), value and rank
  173. * There are also some specially handled keys. They are:
  174. * - property: An array/object describing the property to select records for. It
  175. * should at least have either a type_name (if unique across cvs) or type_id. Other
  176. * supported keys include: cv_id/cv_name (of the type), value and rank
  177. * @param $options
  178. * An array of options. Supported keys include:
  179. * - Any keys supported by chado_generate_var(). See that function definition for
  180. * additional details.
  181. *
  182. * NOTE: the $identifier parameter can really be any array similar to $values passed into
  183. * chado_select_record(). It should fully specify the dbxref record to be returned.
  184. *
  185. * @return
  186. * If unique values were passed in as an identifier then an object describing the dbxref
  187. * will be returned (will be a chado variable from chado_generate_var()). Otherwise,
  188. * FALSE will be returned.
  189. *
  190. * @ingroup tripal_db_api
  191. */
  192. function tripal_get_dbxref($identifiers, $options = array()) {
  193. // Set Defaults
  194. if (!isset($options['include_fk'])) {
  195. // Tells chado_generate_var not only expand the db
  196. $options['include_fk'] = array('db_id' => TRUE);
  197. }
  198. // Error Checking of parameters
  199. if (!is_array($identifiers)) {
  200. tripal_report_error(
  201. 'tripal_db_api',
  202. TRIPAL_ERROR,
  203. "tripal_get_dbxref: The identifier passed in is expected to be an array with the key
  204. matching a column name in the dbxref table (ie: dbxref_id or name). You passed in %identifier.",
  205. array(
  206. '%identifier'=> print_r($identifiers, TRUE)
  207. )
  208. );
  209. }
  210. elseif (empty($identifiers)) {
  211. tripal_report_error(
  212. 'tripal_db_api',
  213. TRIPAL_ERROR,
  214. "tripal_get_dbxref: You did not pass in anything to identify the dbxref you want. The identifier
  215. is expected to be an array with the key matching a column name in the dbxref table
  216. (ie: dbxref_id or name). You passed in %identifier.",
  217. array(
  218. '%identifier'=> print_r($identifiers, TRUE)
  219. )
  220. );
  221. }
  222. // If one of the identifiers is property then use chado_get_record_with_property()
  223. if (isset($identifiers['property'])) {
  224. $property = $identifiers['property'];
  225. unset($identifiers['property']);
  226. $dbxref = chado_get_record_with_property(
  227. array('table' => 'dbxref', 'base_records' => $identifiers),
  228. array('type_name' => $property),
  229. $options
  230. );
  231. }
  232. // Else we have a simple case and we can just use chado_generate_var to get the analysis
  233. else {
  234. $dbxref = chado_generate_var('dbxref', $identifiers, $options);
  235. }
  236. // Ensure the dbxref is singular. If it's an array then it is not singular
  237. if (is_array($dbxref)) {
  238. tripal_report_error('tripal_db_api', TRIPAL_ERROR,
  239. "tripal_get_dbxref: The identifiers you passed in were not unique. You passed in %identifier.",
  240. array('%identifier'=> print_r($identifiers, TRUE))
  241. );
  242. }
  243. // Report an error if $dbxref is FALSE since then chado_generate_var has failed
  244. elseif ($dbxref === FALSE) {
  245. tripal_report_error(
  246. 'tripal_db_api',
  247. TRIPAL_ERROR,
  248. "tripal_get_dbxref: chado_generate_var() failed to return a dbxref based on the identifiers
  249. you passed in. You should check that your identifiers are correct, as well as, look
  250. for a chado_generate_var error for additional clues. You passed in %identifier.",
  251. array(
  252. '%identifier'=> print_r($identifiers, TRUE)
  253. )
  254. );
  255. }
  256. // Else, as far we know, everything is fine so give them their dbxref :)
  257. else {
  258. return $dbxref;
  259. }
  260. }
  261. /**
  262. * Adds a new database to the Chado DB table and returns the DB object.
  263. *
  264. * @param $values
  265. * An associative array of the values of the db (those to be inserted)
  266. * - name: The name of the database. This name is usually used as the prefix for
  267. * CV term accessions
  268. * - description: (Optional) A description of the database. By default no description is required.
  269. * - url: (Optional) The URL for the database
  270. * - urlprefix: (Optional) The URL that is to be used as a prefix when constructing a
  271. * link to a database term
  272. * @param $options
  273. * Optional. An associative array of options that can include:
  274. * - update_existing: Set this to '1' to force an update of the database if it
  275. * already exists. The default is to not update. If the database exists
  276. * then nothing is added.
  277. *
  278. * @return
  279. * An object populated with fields from the newly added database. If the
  280. * database already exists it returns the values in the current entry.
  281. *
  282. * @ingroup tripal_db_api
  283. */
  284. function tripal_insert_db($values, $options = array()) {
  285. // Default Values
  286. $dbname = $values['name'];
  287. $description = (isset($values['description'])) ? $values['description'] : '';
  288. $url = (isset($values['url'])) ? $values['url'] : '';
  289. $urlprefix = (isset($values['urlprefix'])) ? $values['urlprefix'] : '';
  290. $update = (isset($options['update_existing'])) ? $options['update_existing'] : TRUE;
  291. // build the values array for inserting/updating
  292. $ins_values = array(
  293. 'name' => $dbname,
  294. 'description' => $description,
  295. 'url' => $url,
  296. 'urlprefix' => $urlprefix
  297. );
  298. // get the database record if it already exists
  299. $sel_values = array('name' => $dbname);
  300. $sel_options = array('statement_name' => 'sel_db_na');
  301. $result = chado_select_record('db', array('*'), $sel_values, $sel_options);
  302. // if it does not exists then add it
  303. if (count($result) == 0) {
  304. $ins_options = array('statement_name' => 'ins_db_nadeurur');
  305. $success = chado_insert_record('db', $ins_values, $ins_options);
  306. if (!$success) {
  307. tripal_report_error('tripal_db', TRIPAL_WARNING, "Cannot create db '$dbname'.", NULL);
  308. return 0;
  309. }
  310. $result = chado_select_record('db', array('*'), $sel_values, $sel_options);
  311. }
  312. // if it exists and update is enabled the do the update
  313. elseif ($update) {
  314. $upd_options = array('statement_name' => 'upd_db_nadeurur');
  315. $success = chado_update_record('db', $sel_values, $ins_values, $upd_options);
  316. if (!$success) {
  317. tripal_report_error('tripal_db', TRIPAL_WARNING, "Cannot update db '$dbname'.", NULL);
  318. return 0;
  319. }
  320. $result = chado_select_record('db', array('*'), $sel_values, $sel_options);
  321. }
  322. // return the database object
  323. return $result[0];
  324. }
  325. /**
  326. * Add a database reference
  327. *
  328. * @param $values
  329. * An associative array of the values to be inserted including:
  330. * - db_id: the database_id of the database the reference is from
  331. * - accession: the accession
  332. * - version: (Optional) The version of the database reference
  333. * - description: (Optional) A description of the database reference
  334. *
  335. * @ingroup tripal_db_api
  336. */
  337. function tripal_insert_dbxref($values) {
  338. $db_id = $values['db_id'];
  339. $accession = $values['accession'];
  340. $version = (isset($values['version'])) ? $values['version'] : '';
  341. $description = (isset($values['description'])) ? $values['description'] : '';
  342. $ins_values = array(
  343. 'db_id' => $db_id,
  344. 'accession' => $accession,
  345. 'version' => $version,
  346. 'description' => $description
  347. );
  348. // check to see if the dbxref exists
  349. $sel_values = array(
  350. 'db_id' => $db_id,
  351. 'accession' => $accession,
  352. 'version' => $version
  353. );
  354. $result = chado_select_record('dbxref', array('*'), $sel_values);
  355. // if it doesn't already exist then add it
  356. if (!$result) {
  357. $success = chado_insert_record('dbxref', $ins_values);
  358. if (!$success) {
  359. tripal_report_error('tripal_cv', TRIPAL_WARNING, "Failed to insert the dbxref record $accession", NULL);
  360. return 0;
  361. }
  362. $result = chado_select_record('dbxref', array('*'), $sel_values);
  363. }
  364. if (isset($result[0])) {
  365. return $result[0];
  366. }
  367. else {
  368. return FALSE;
  369. }
  370. }
  371. /**
  372. * Add a record to a database reference linking table (ie: feature_dbxref)
  373. *
  374. * @param $basetable
  375. * The base table for which the dbxref should be associated. Thus to associate a dbxref
  376. * with a feature the basetable=feature and dbxref_id is added to the feature_dbxref table
  377. * @param $record_id
  378. * The primary key of the basetable to associate the dbxref with. This should be in integer.
  379. * @param $dbxref
  380. * An associative array describing the dbxref. Valid keys include: 'accession' => the
  381. * accession for the dbxref, 'db_name' => the name of the database the dbxref belongs to;
  382. * 'db_id' => the primary key of the database the dbxref belongs to.
  383. * @param $options
  384. * An associative array of options. Valid keys include:
  385. * - insert_dbxref: Insert the dbxref if it doesn't already exist. TRUE is the default
  386. *
  387. * @ingroup tripal_db_api
  388. */
  389. function tripal_associate_dbxref($basetable, $record_id, $dbxref, $options = array()) {
  390. $linking_table = $basetable . '_dbxref';
  391. $foreignkey_name = $basetable . '_id';
  392. // Default Values
  393. $options['insert_dbxref'] = (isset($options['insert_dbxref'])) ? $options['insert_dbxref'] : TRUE;
  394. // If the dbxref_id is set then we know it already exists
  395. // Otherwise, select to check
  396. if (!isset($dbxref['dbxref_id'])) {
  397. $values = array(
  398. 'accession' => $dbxref['accession'],
  399. );
  400. if (isset($dbxref['db_id'])) {
  401. $values['db_id'] = $dbxref['db_id'];
  402. } elseif (isset($dbxref['db_name'])) {
  403. $values['db_id'] = array(
  404. 'name' => $dbxref['db_name']
  405. );
  406. }
  407. else {
  408. tripal_report_error(
  409. 'tripal_db_api',
  410. TRIPAL_WARNING,
  411. "tripal_associate_dbxref: The dbxref needs to have either the db_name or db_id
  412. supplied. You were trying to associate a dbxref with the %base %record_id
  413. and supplied the dbxref values: %dbxref.",
  414. array('%base' => $basetable, '%record_id' => $record_id, '%dbxref' => print_r($dbxref,TRUE))
  415. );
  416. return FALSE;
  417. }
  418. $select = chado_select_record('dbxref',array('*'), $values);
  419. if ($select) {
  420. $dbxref['dbxref_id'] = $select[0]->dbxref_id;
  421. }
  422. elseif ($options['insert_dbxref']) {
  423. // Insert the dbxref
  424. $insert = tripal_insert_dbxref($values);
  425. if (isset($insert->dbxref_id)) {
  426. $dbxref['dbxref_id'] = $insert->dbxref_id;
  427. }
  428. else {
  429. tripal_report_error(
  430. 'tripal_db_api',
  431. TRIPAL_WARNING,
  432. "tripal_associate_dbxref: Unable to insert the dbxref using the dbxref values: %dbxref.",
  433. array('%dbxref' => print_r($dbxref,TRUE))
  434. );
  435. return FALSE;
  436. }
  437. }
  438. else {
  439. tripal_report_error(
  440. 'tripal_api',
  441. TRIPAL_WARNING,
  442. "tripal_associate_dbxref: The dbxref doesn't already exist. You supplied the dbxref values: %dbxref.",
  443. array('%dbxref' => print_r($dbxref,TRUE))
  444. );
  445. return FALSE;
  446. }
  447. }
  448. // Now add the link between the record & dbxref
  449. if ($dbxref['dbxref_id'] > 0) {
  450. $values = array(
  451. 'dbxref_id' => $dbxref['dbxref_id'],
  452. $foreignkey_name => $record_id
  453. );
  454. $result = chado_select_record($linking_table, array('*'), $values);
  455. // if it doesn't already exist then add it
  456. if (!$result) {
  457. $success = chado_insert_record($linking_table, $values);
  458. if (!$success) {
  459. tripal_report_error(
  460. 'tripal_api',
  461. TRIPAL_WARNING,
  462. "Failed to insert the %base record %accession",
  463. array('%base' => $linking_table, '%accession' => $dbxref['accession'])
  464. );
  465. return FALSE;
  466. }
  467. $result = chado_select_record($linking_table, array('*'), $values);
  468. }
  469. if (isset($result[0])) {
  470. return $result[0];
  471. }
  472. else {
  473. return FALSE;
  474. }
  475. }
  476. return FALSE;
  477. }