tripal_chado.organism.api.inc 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385
  1. <?php
  2. /**
  3. * @file
  4. * Provides API functions specifically for managing feature
  5. * records in Chado.
  6. */
  7. /**
  8. * @defgroup tripal_organism_api Chado Organism
  9. * @ingroup tripal_chado_api
  10. * @{
  11. * Provides API functions specifically for managing organism
  12. * records in Chado.
  13. * @}
  14. */
  15. /**
  16. * Retrieves a chado organism variable.
  17. *
  18. * @param $identifier
  19. * An array with the key stating what the identifier is. Supported keys (only
  20. * one of the following unique keys is required):
  21. * - organism_id: the chado organism.organism_id primary key.
  22. * - genus & species: the chado organism.genus field & organism.species
  23. * field. There are also some specially handled keys. They are:
  24. * - property: An array/object describing the property to select records
  25. * for.
  26. * It should at least have either a type_name (if unique across cvs) or
  27. * type_id. Other supported keys include: cv_id/cv_name (of the type),
  28. * value and rank.
  29. * @param $options
  30. * An array of options. Supported keys include:
  31. * - Any keys supported by chado_generate_var(). See that function
  32. * definition for additional details.
  33. *
  34. * NOTE: the $identifier parameter can really be any array similar to $values
  35. * passed into chado_select_record(). It should fully specify the organism
  36. * record to be returned.
  37. *
  38. * @return
  39. * If unique values were passed in as an identifier then an object describing
  40. * the organism will be returned (will be a chado variable from
  41. * chado_generate_var()). Otherwise, NULL will be returned.
  42. *
  43. * @ingroup tripal_organism_api
  44. */
  45. function chado_get_organism($identifiers, $options = []) {
  46. // Set Defaults.
  47. if (!isset($options['include_fk'])) {
  48. // Tells chado_generate_var to not follow any foreign keys.
  49. $options['include_fk'] = [];
  50. }
  51. // Error Checking of parameters.
  52. if (!is_array($identifiers)) {
  53. tripal_report_error(
  54. 'tripal_organism_api',
  55. TRIPAL_ERROR,
  56. "chado_get_organism: The identifier passed in is expected to be an array with the key
  57. matching a column name in the organism table (ie: organism_id or name). You passed in %identifier.",
  58. [
  59. '%identifier' => print_r($identifiers, TRUE),
  60. ]
  61. );
  62. }
  63. elseif (empty($identifiers)) {
  64. tripal_report_error(
  65. 'tripal_organism_api',
  66. TRIPAL_ERROR,
  67. "chado_get_organism: You did not pass in anything to identify the organism you want. The identifier
  68. is expected to be an array with the key matching a column name in the organism table
  69. (ie: organism_id or name). You passed in %identifier.",
  70. [
  71. '%identifier' => print_r($identifiers, TRUE),
  72. ]
  73. );
  74. }
  75. // If one of the identifiers is property then use chado_get_record_with_property().
  76. if (isset($identifiers['property'])) {
  77. $property = $identifiers['property'];
  78. unset($identifiers['property']);
  79. $organism = chado_get_record_with_property(
  80. ['table' => 'organism', 'base_records' => $identifiers],
  81. ['type_name' => $property],
  82. $options
  83. );
  84. }
  85. // Else we have a simple case and we can just use chado_generate_var to get
  86. // the organism.
  87. else {
  88. // Try to get the organism
  89. $organism = chado_generate_var(
  90. 'organism',
  91. $identifiers,
  92. $options
  93. );
  94. }
  95. // Ensure the organism is singular. If it's an array then it is not singular.
  96. if (is_array($organism)) {
  97. tripal_report_error(
  98. 'tripal_organism_api',
  99. TRIPAL_ERROR,
  100. "chado_get_organism: The identifiers you passed in were not unique. You passed in %identifier.",
  101. [
  102. '%identifier' => print_r($identifiers, TRUE),
  103. ]
  104. );
  105. }
  106. // Report an error if $organism is FALSE since then chado_generate_var has
  107. // failed.
  108. elseif ($organism === FALSE) {
  109. tripal_report_error(
  110. 'tripal_organism_api',
  111. TRIPAL_ERROR,
  112. "chado_get_organism: chado_generate_var() failed to return an organism based on the identifiers
  113. you passed in. You should check that your identifiers are correct, as well as, look
  114. for a chado_generate_var error for additional clues. You passed in %identifier.",
  115. [
  116. '%identifier' => print_r($identifiers, TRUE),
  117. ]
  118. );
  119. }
  120. // Else, as far we know, everything is fine so give them their organism :)
  121. else {
  122. return $organism;
  123. }
  124. }
  125. /**
  126. * Returns the full scientific name of an organism.
  127. *
  128. * @param $organism
  129. * An organism object.
  130. *
  131. * @return
  132. * The full scientific name of the organism.
  133. *
  134. * @ingroup tripal_organism_api
  135. */
  136. function chado_get_organism_scientific_name($organism) {
  137. $name = $organism->genus . ' ' . $organism->species;
  138. // For Chado v1.3 we have a type_id and infraspecific name.
  139. if (property_exists($organism, 'type_id')) {
  140. $rank = '';
  141. // For organism objects created using chado_generate_var.
  142. if (is_object($organism->type_id)) {
  143. if ($organism->type_id) {
  144. $rank = $organism->type_id->name;
  145. }
  146. }
  147. else {
  148. $rank_term = chado_get_cvterm(['cvterm_id' => $organism->type_id]);
  149. if ($rank_term) {
  150. $rank = $rank_term->name;
  151. }
  152. }
  153. if ($rank) {
  154. $rank = chado_abbreviate_infraspecific_rank($rank);
  155. // rank will now be an empty string if it had been the "no_rank" cv term
  156. if ($rank) {
  157. $name .= ' ' . $rank;
  158. }
  159. }
  160. if ($organism->infraspecific_name) {
  161. $name .= ' ' . $organism->infraspecific_name;
  162. }
  163. }
  164. return $name;
  165. }
  166. /**
  167. * Returns a list of organisms that are currently synced with Drupal to use in
  168. * select lists.
  169. *
  170. * @param $syncd_only
  171. * Whether or not to return all chado organisms or just those sync'd with
  172. * drupal. Defaults to TRUE (only sync'd organisms).
  173. *
  174. * @return
  175. * An array of organisms sync'd with Drupal where each value is the organism
  176. * scientific name and the keys are organism_id's.
  177. *
  178. * @ingroup tripal_organism_api
  179. */
  180. function chado_get_organism_select_options($syncd_only = TRUE) {
  181. $org_list = [];
  182. $org_list[] = 'Select an organism';
  183. if ($syncd_only) {
  184. $sql = "
  185. SELECT *
  186. FROM [chado_organism] CO
  187. INNER JOIN {organism} O ON O.organism_id = CO.organism_id
  188. ORDER BY O.genus, O.species
  189. ";
  190. // if present in this site's version of chado, include infraspecific nomenclature in sorting
  191. if (chado_column_exists('organism', 'infraspecific_name')) {
  192. $sql .= ", REPLACE ((SELECT name FROM {cvterm} CVT WHERE CVT.cvterm_id = O.type_id
  193. AND CVT.cv_id = (SELECT cv_id FROM {cv} WHERE name='taxonomic_rank')), 'no_rank', ''),
  194. O.infraspecific_name";
  195. }
  196. $orgs = chado_query($sql);
  197. // Iterate through the organisms and build an array of those that are synced.
  198. foreach ($orgs as $org) {
  199. $org_list[$org->organism_id] = chado_get_organism_scientific_name($org);
  200. }
  201. }
  202. else {
  203. // use this SQL statement for getting the organisms
  204. $csql = "SELECT * FROM {organism} ORDER BY genus, species";
  205. // if present in this site's version of chado, include infraspecific nomenclature in sorting
  206. if (chado_column_exists('organism', 'infraspecific_name')) {
  207. $csql .= ", REPLACE ((SELECT name FROM {cvterm} CVT WHERE CVT.cvterm_id = type_id" .
  208. " AND CVT.cv_id = (SELECT cv_id FROM {cv} WHERE name='taxonomic_rank')), 'no_rank', '')," .
  209. " infraspecific_name";
  210. }
  211. $orgs = chado_query($csql);
  212. // Iterate through the organisms and build an array of those that are synced.
  213. foreach ($orgs as $org) {
  214. $org_list[$org->organism_id] = chado_get_organism_scientific_name($org);
  215. }
  216. }
  217. return $org_list;
  218. }
  219. /**
  220. * Return the path for the organism image.
  221. *
  222. * @param $organism
  223. * An organism table record.
  224. *
  225. * @return
  226. * If the type parameter is 'url' (the default) then the fully qualified
  227. * url to the image is returend. If no image is present then NULL is returned.
  228. *
  229. * @ingroup tripal_organism_api
  230. */
  231. function chado_get_organism_image_url($organism) {
  232. $url = '';
  233. if (!is_object($organism)) {
  234. return NULL;
  235. }
  236. // Get the organism's node.
  237. $nid = chado_get_nid_from_id('organism', $organism->organism_id);
  238. // Look in the file_usage table of Drupal for the image file. This
  239. // is the current way for handling uploaded images. It allows the file to
  240. // keep its proper name and extension.
  241. $fid = db_select('file_usage', 'fu')
  242. ->fields('fu', ['fid'])
  243. ->condition('module', 'tripal_organism')
  244. ->condition('type', 'organism_image')
  245. ->condition('id', $nid)
  246. ->execute()
  247. ->fetchField();
  248. if ($fid) {
  249. $file = file_load($fid);
  250. return file_create_url($file->uri);
  251. }
  252. // First look for an image with the genus/species name. This is old-style
  253. // tripal and we keep it for backwards compatibility.
  254. $base_path = realpath('.');
  255. $image_dir = tripal_get_files_dir('tripal_organism') . "/images";
  256. $image_name = $organism->genus . "_" . $organism->species . ".jpg";
  257. $image_path = "$base_path/$image_dir/$image_name";
  258. if (file_exists($image_path)) {
  259. $url = file_create_url("$image_dir/$image_name");
  260. return $url;
  261. }
  262. // If we don't find the file using the genus and species then look for the
  263. // image with the node ID in the name. This method was used for Tripal 1.1
  264. // and 2.x-alpha version.
  265. $image_name = $nid . ".jpg";
  266. $image_path = "$base_path/$image_dir/$image_name";
  267. if (file_exists($image_path)) {
  268. $url = file_create_url("$image_dir/$image_name");
  269. return $url;
  270. }
  271. return NULL;
  272. }
  273. /**
  274. * This function is intended to be used in autocomplete forms
  275. * for searching for organisms that begin with the provided string.
  276. *
  277. * @param $text
  278. * The string to search for.
  279. *
  280. * @return
  281. * A json array of terms that begin with the provided string.
  282. *
  283. * @ingroup tripal_organism_api
  284. */
  285. function chado_autocomplete_organism($text) {
  286. $matches = [];
  287. $genus = $text;
  288. $species = '';
  289. if (preg_match('/^(.*?)\s+(.*)$/', $text, $matches)) {
  290. $genus = $matches[1];
  291. $species = $matches[2];
  292. }
  293. $sql = "SELECT * FROM {organism} WHERE lower(genus) like lower(:genus) ";
  294. $args = [];
  295. $args[':genus'] = $genus . '%';
  296. if ($species) {
  297. $sql .= "AND lower(species) like lower(:species) ";
  298. $args[':species'] = $species . '%';
  299. }
  300. $sql .= "ORDER BY genus, species";
  301. // if present in this site's version of chado, include infraspecific nomenclature in sorting
  302. if (chado_column_exists('organism', 'infraspecific_name')) {
  303. $sql .= ", REPLACE ((SELECT name FROM {cvterm} CVT WHERE CVT.cvterm_id = type_id" .
  304. " AND CVT.cv_id = (SELECT cv_id FROM {cv} WHERE name='taxonomic_rank')), 'no_rank', '')," .
  305. " infraspecific_name";
  306. }
  307. $sql .= " LIMIT 25 OFFSET 0";
  308. $results = chado_query($sql, $args);
  309. $items = [['args' => [$sql => $args]]];
  310. foreach ($results as $organism) {
  311. $name = chado_get_organism_scientific_name($organism);
  312. $items["$name [id: $organism->organism_id]"] = $name;
  313. }
  314. drupal_json_output($items);
  315. }
  316. /**
  317. * A handy function to abbreviate the infraspecific rank.
  318. *
  319. * @param $rank
  320. * The rank below species.
  321. *
  322. * @return
  323. * The proper abbreviation for the rank.
  324. *
  325. * @ingroup tripal_organism_api
  326. */
  327. function chado_abbreviate_infraspecific_rank($rank) {
  328. $abb = '';
  329. switch ($rank) {
  330. case 'no_rank':
  331. $abb = '';
  332. break;
  333. case 'subspecies':
  334. $abb = 'subsp.';
  335. break;
  336. case 'varietas':
  337. $abb = 'var.';
  338. break;
  339. case 'variety':
  340. $abb = 'var.';
  341. break;
  342. case 'subvarietas':
  343. $abb = 'subvar.';
  344. break;
  345. case 'subvariety':
  346. $abb = 'subvar.';
  347. break;
  348. case 'forma':
  349. $abb = 'f.';
  350. break;
  351. case 'subforma':
  352. $abb = 'subf.';
  353. break;
  354. default:
  355. $abb = $rank;
  356. }
  357. return $abb;
  358. }