tripal_chado.phylotree.api.inc 34 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885
  1. <?php
  2. /**
  3. * @file
  4. * Provides API functions specificially for managing phylogenetic and taxonomic
  5. * tree records in Chado.
  6. */
  7. /**
  8. * @defgroup tripal_phylotree_api Chado Phylotree
  9. * @ingroup tripal_chado_api
  10. * @{
  11. * Provides API functions specificially for managing phylogenetic and taxonomic
  12. * tree records in Chado. The API consists of functions for creation,
  13. * retrieval, update and deltion (CRUD) for phylogenetic tree records as
  14. * well as importing of trees in the newick file format.
  15. * @}
  16. */
  17. /**
  18. * Validates an $options array for insert or update of a phylotree record.
  19. *
  20. * If validation passes then any values that needed validation lookups
  21. * (such as the dbxref, analysis, leaf_type, etc) will have their approriate
  22. * primary_keys added to the $options array, and missing default values
  23. * will also be added.
  24. *
  25. * @param $val_type
  26. * The type of validation. Can be either 'insert' or 'update'.
  27. * @param $options
  28. * An array of key/value pairs containing any of the valid keys for
  29. * either the chado_insert_phylotree() or chado_update_phylotree()
  30. * functions.
  31. * @param $errors
  32. * An empty array where validation error messages will be set. The keys
  33. * of the array will be name of the field from the options array and the
  34. * value is the error message.
  35. * @param $warnings
  36. * An empty array where validation warning messagges will be set. The
  37. * warnings should not stop an insert or an update but should be provided
  38. * to the user as information by a drupal_set_message() if appropriate. The
  39. * keys of the array will be name of the field from the options array and the
  40. * value is the error message.
  41. * @return
  42. * If validation failes then FALSE is returned. Any options that do not pass
  43. * validation checks will be added in the $errors array with the key being
  44. * the option and the value being the error message. If validation
  45. * is successful then TRUE is returned.
  46. *
  47. * @ingroup tripal_phylotree_api
  48. */
  49. function chado_validate_phylotree($val_type, &$options, &$errors, &$warnings) {
  50. if ($val_type != 'insert' and $val_type != 'update') {
  51. tripal_report_error('tripal_phylogeny', TRIPAL_ERROR, "The $val_type argument must be either 'update or 'insert'.");
  52. }
  53. // Set Defaults.
  54. if ($val_type == 'insert') {
  55. // Match by feature name.
  56. if (!array_key_exists('match', $options)) {
  57. $options['match'] = 'name';
  58. }
  59. // The regular expression is to match the entire node name.
  60. if (!array_key_exists('name_re', $options)) {
  61. $options['name_re'] = '^(.*)$';
  62. }
  63. // A dbxref is not required by Tripal but is required by the database
  64. // field in the phylotree table. Therefore, if the dbxref is not provided
  65. // we can set this to be the null database and null dbxref which
  66. // is represented as 'null:local:null'
  67. if (!array_key_exists('dbxref', $options)) {
  68. $options['dbxref'] = "null:local:null";
  69. }
  70. }
  71. // Make sure required values are set.
  72. if ($val_type == 'insert') {
  73. if (!array_key_exists('name', $options)) {
  74. $errors['name'] = t('Please provide the name of the tree.');
  75. return FALSE;
  76. }
  77. if (!array_key_exists('description', $options)) {
  78. $errors['description'] = t('Please provide a description for this tree.');
  79. return FALSE;
  80. }
  81. if (!array_key_exists('tree_file', $options)) {
  82. $errors['tree_file'] = t('Please provide either the full path to the tree_file or a Drupal managed file ID number.');
  83. return FALSE;
  84. }
  85. if (!array_key_exists('format', $options) or !$options['format']) {
  86. $errors['format'] = t('Please provide a file format for the tree file.');
  87. return FALSE;
  88. }
  89. // Make sure the file format is correct.
  90. if ($options['format'] != 'newick' and $options['format'] != 'taxonomy') {
  91. $errors['format'] = t('The file format is not supported. Currently only the "newick" file format is supported.');
  92. return FALSE;
  93. }
  94. }
  95. else {
  96. // Does the phylotree ID exist and is it valid.
  97. if (!array_key_exists('phylotree_id', $options)) {
  98. $errors['phylotree_id'] = t('Please provide the ID for the tree.');
  99. return FALSE;
  100. }
  101. $exists = chado_select_record('phylotree', array('phylotree_id'),
  102. array('phylotree_id' => $options['phylotree_id']), array('has_record' => 1));
  103. if (!$exists) {
  104. $errors['phylotree_id'] = t('The phylotree_id does not exist.');
  105. return FALSE;
  106. }
  107. }
  108. // Make sure the file exists if one is specified.
  109. if (array_key_exists('tree_file', $options) and $options['tree_file']) {
  110. // If this is a numeric Drupal file then all is good, no need to check.
  111. if (!is_numeric($options['tree_file'])) {
  112. if (!file_exists($options['tree_file'])) {
  113. $errors['tree_file'] = t('The file provided does not exists.');
  114. return FALSE;
  115. }
  116. }
  117. // Make sure the file format is correct.
  118. if (!array_key_exists('format', $options) or
  119. ($options['format'] != 'newick' and $options['format'] != 'taxonomy')) {
  120. $errors['format'] = t('Please provide a supported file format. Currently only the "newick" file format is supported.');
  121. return FALSE;
  122. }
  123. // If no leaf type is provided then use the polypeptide term.
  124. if (!array_key_exists('leaf_type', $options) or !$options['leaf_type']) {
  125. $options['leaf_type'] = 'polypeptide';
  126. }
  127. }
  128. // Make sure the analysis exists.
  129. $analysis = NULL;
  130. if (array_key_exists('analysis_id', $options) and $options['analysis_id']) {
  131. $analysis = chado_select_record('analysis', array('analysis_id'), array('analysis_id' => $options['analysis_id']));
  132. if (!$analysis) {
  133. $errors['analysis_id'] = t('The analysis name provided does not exist.');
  134. return FALSE;
  135. }
  136. $options['analysis_id'] = $analysis[0]->analysis_id;
  137. }
  138. if (array_key_exists('analysis', $options) and $options['analysis']) {
  139. $analysis = chado_select_record('analysis', array('analysis_id'), array('name' => $options['analysis']));
  140. if (!$analysis) {
  141. $errors['analysis'] = t('The analysis ID provided does not exist.');
  142. return FALSE;
  143. }
  144. $options['analysis_id'] = $analysis[0]->analysis_id;
  145. }
  146. // Make sure the leaf type exists.
  147. $type = NULL;
  148. if (array_key_exists('leaf_type', $options) and $options['leaf_type']) {
  149. if ($options['leaf_type'] == 'taxonomy') {
  150. $values = array(
  151. 'cv_id' => array(
  152. 'name' => 'EDAM'
  153. ),
  154. 'name' => 'Species tree'
  155. );
  156. $type = chado_select_record('cvterm', array('cvterm_id'), $values);
  157. }
  158. else {
  159. $values = array(
  160. 'cv_id' => array(
  161. 'name' => 'sequence'
  162. ),
  163. 'name' => $options['leaf_type']
  164. );
  165. $type = chado_select_record('cvterm', array('cvterm_id'), $values);
  166. if (!$type) {
  167. $errors['leaf_type'] = t('The leaf_type provided is not a valid Sequence Ontology term: %term.');
  168. return FALSE;
  169. }
  170. }
  171. $options['type_id'] = $type[0]->cvterm_id;
  172. }
  173. // A Dbxref is required by the phylotree module, but if the
  174. // tree was generated in-house and the site admin doens't want to
  175. // assign a local dbxref then we will set it to the null db
  176. // and the local:null dbxref.
  177. if (array_key_exists('dbxref', $options)) {
  178. if (!$options['dbxref']) {
  179. $options['dbxref'] = 'null:local:null';
  180. }
  181. $matches = array();
  182. preg_match('/^(.*?):(.*)$/', $options['dbxref'], $matches);
  183. $db_name = $matches[1];
  184. $accession = $matches[2];
  185. $values = array(
  186. 'accession' => $accession,
  187. 'db_id' => array(
  188. 'name' => $db_name
  189. ),
  190. );
  191. $dbxref = chado_generate_var('dbxref', $values);
  192. if (!$dbxref) {
  193. $errors['dbxref'] = t('The dbxref provided does not exist in the database: %dbxref.', array('%dbxref' => $dbxref));
  194. return FALSE;
  195. }
  196. $options['dbxref_id'] = $dbxref->dbxref_id;
  197. }
  198. // Make sure the tree name is unique.
  199. if (array_key_exists('name', $options) and $options['name']) {
  200. $sql = "
  201. SELECT *
  202. FROM {phylotree} P
  203. WHERE
  204. P.name = :name
  205. ";
  206. $args = array(':name' => $options['name']);
  207. if ($val_type == 'update') {
  208. $sql .= " AND NOT P.phylotree_id = :phylotree_id";
  209. $args[':phylotree_id'] = $options['phylotree_id'];
  210. }
  211. $result = chado_query($sql, $args)->fetchObject();
  212. if ($result) {
  213. $errors['name'] = t("The tree name is in use by another tree. Please provide a different unique name for this tree.");
  214. }
  215. }
  216. return TRUE;
  217. }
  218. /**
  219. * Inserts a phylotree record into Chado.
  220. *
  221. * This function validates the options passed prior to insertion of the record,
  222. * and if validation passes then any values in the options array that needed
  223. * validation lookups (such as the dbxref, analysis, leaf_type, etc) will have
  224. * their approriate primary key values added to the options array.
  225. *
  226. * @param $options
  227. * An array of key value pairs with the following keys required:
  228. * 'name': The name of the tree. This will be displayed to users.
  229. * 'description: A description about the tree
  230. * 'anlaysis_id: The ID of the analysis to which this phylotree should be
  231. * associated.
  232. * 'analysis': If the analysis_id key is not used then the analysis name
  233. * may be provided to identify the analysis to which the tree
  234. * should be associated.
  235. * 'leaf_type': A sequence ontology term or the word 'organism'. If the
  236. * type is 'organism' then this tree represents a
  237. * taxonomic tree. The default, if not specified, is the
  238. * term 'polypeptide'.
  239. * 'tree_file': The path of the file containing the phylogenetic tree to
  240. * import or a Drupal managed_file numeric ID.
  241. * 'format': The file format. Currently only 'newick is supported'.
  242. *
  243. * Optional keys:
  244. * 'dbxref': A database cross-reference of the form DB:ACCESSION.
  245. * Where DB is the database name, which is already present
  246. * in Chado, and ACCESSION is the unique identifier for
  247. * this tree in the remote database.
  248. * 'name_re': If the leaf type is NOT 'taxonomy', then the value of
  249. * this field can be a regular expression to pull out
  250. * the name of the feature from the node label in the
  251. * intput tree. If no value is provided the entire label is
  252. * used.
  253. * 'match': Set to 'uniquename' if the leaf nodes should be matched
  254. * with the feature uniquename.
  255. * 'load_now': If set, the tree will be loaded immediately if a tree_file
  256. * is provided. Otherwise, the tree will be loaded via
  257. * a Tripal jobs call.
  258. * 'no_load': If set the tree file will not be loaded.
  259. * @param $errors
  260. * An empty array where validation error messages will be set. The keys
  261. * of the array will be name of the field from the options array and the
  262. * value is the error message.
  263. * @param $warnings
  264. * An empty array where validation warning messagges will be set. The
  265. * warnings should not stop an insert or an update but should be provided
  266. * to the user as information by a drupal_set_message() if appropriate. The
  267. * keys of the array will be name of the field from the options array and the
  268. * value is the error message.
  269. * @return
  270. * TRUE for success and FALSE for failure.
  271. *
  272. * @ingroup tripal_phylotree_api
  273. */
  274. function chado_insert_phylotree(&$options, &$errors, &$warnings) {
  275. global $user;
  276. $options['name_re'] = trim($options['name_re']);
  277. $options['leaf_type'] = trim($options['leaf_type']);
  278. $options['name'] = trim($options['name']);
  279. $options['format'] = trim($options['format']);
  280. $options['tree_file'] = trim($options['tree_file']);
  281. // Validate the incoming options.
  282. $success = chado_validate_phylotree('insert', $options, $errors, $warnings);
  283. if (!$success) {
  284. foreach ($errors as $field => $message) {
  285. tripal_report_error('tripal_phylogeny', TRIPAL_ERROR, $message);
  286. }
  287. return FALSE;
  288. }
  289. // If we're here then all is good, so add the phylotree record.
  290. $values = array(
  291. 'analysis_id' => $options['analysis_id'],
  292. 'name' => $options['name'],
  293. 'dbxref_id' => $options['dbxref_id'],
  294. 'comment' => $options['description'],
  295. 'type_id' => $options['type_id'],
  296. );
  297. $phylotree = chado_insert_record('phylotree', $values);
  298. if (!$phylotree) {
  299. drupal_set_message(t('Unable to add phylotree.'), 'warning');
  300. tripal_report_error('tripal_phylogeny', TRIPAL_WARNING, 'Insert phylotree: Unable to create phylotree where values: %values',
  301. array('%values' => print_r($values, TRUE)));
  302. return FALSE;
  303. }
  304. $phylotree_id = $phylotree['phylotree_id'];
  305. $options['phylotree_id'] = $phylotree_id;
  306. // If the tree_file is numeric then it is a Drupal managed file and
  307. // we want to make the file permanent and associated with the tree.
  308. if (is_numeric($options['tree_file'])) {
  309. $file = NULL;
  310. $file = file_load($options['tree_file']);
  311. $file->status = FILE_STATUS_PERMANENT;
  312. $file = file_save($file);
  313. file_usage_add($file, 'tripal_phylogeny', $options['format'], $phylotree_id);
  314. $real_file_path = drupal_realpath($file->uri);
  315. }
  316. else {
  317. $real_file_path = $options['tree_file'];
  318. }
  319. // If caller has requested to load the file now then do so, otherwise
  320. // submit using a Tripal job.
  321. if (!array_key_exists('no_load', $options) or !$options['no_load']) {
  322. if (array_key_exists('load_now', $options) and $options['load_now']) {
  323. $args = array(
  324. 'phylotree_id' => $phylotree_id,
  325. 'leaf_type' => $options['leaf_type'],
  326. 'match' => $options['match'] ? 'uniquename' : 'name',
  327. 'name_re' => $options['name_re'],
  328. );
  329. chado_phylogeny_import_tree_file($real_file_path, $options['format'], $args);
  330. }
  331. else {
  332. $args = array(
  333. $real_file_path,
  334. 'newick',
  335. array(
  336. 'phylotree_id' => $phylotree_id,
  337. 'leaf_type' => $options['leaf_type'],
  338. 'match' => $options['match'] ? 'uniquename' : 'name',
  339. 'name_re' => $options['name_re'],
  340. ),
  341. );
  342. if (tripal_add_job("Import Tree File: " . $file->filename, 'tripal_phylogeny',
  343. 'chado_phylogeny_import_tree_file', $args, $user->uid)) {
  344. drupal_set_message(t('The tree visualizations will appear once the tree is fully imported.'));
  345. }
  346. }
  347. }
  348. return TRUE;
  349. }
  350. /**
  351. * Updates a phylotree record into Chado.
  352. *
  353. * This function validates the options passed prior to update of the record
  354. * and if validation passes then any values in the options array that needed
  355. * validation lookups (such as the dbxref, analysis, leaf_type, etc) will have
  356. * their approriate primary key values added to the options array. A Drupal
  357. * File object will be added to the options array for the tree file if one
  358. * is provided.
  359. *
  360. *
  361. * @param $phylotree_id
  362. * The ID of the phylotree to update.
  363. * @param $options
  364. * An array of key value pairs with the following optional keys:
  365. * 'name': The name of the tree. This will be displayed to users.
  366. * 'description: A description about the tree
  367. * 'anlaysis_id: The ID of the analysis to which this phylotree should be
  368. * associated.
  369. * 'analysis': If the analysis_id key is not used then the analysis name
  370. * may be provided to identify the analysis to which the tree
  371. * should be associated.
  372. * 'leaf_type': A sequence ontology term or the word 'organism'. If the
  373. * type is 'organism' then this tree represents a
  374. * taxonomic tree. The default, if not specified, is the
  375. * term 'polypeptide'.
  376. * 'tree_file': The path of the file containing the phylogenetic tree to
  377. * import or a Drupal managed_file numeric ID.
  378. * 'format': The file format. Currently only 'newick is supported'
  379. * 'dbxref': A database cross-reference of the form DB:ACCESSION.
  380. * Where DB is the database name, which is already present
  381. * in Chado, and ACCESSION is the unique identifier for
  382. * this tree in the remote database.
  383. * 'name_re': If the leaf type is NOT 'taxonomy', then the value of
  384. * this field can be a regular expression to pull out
  385. * the name of the feature from the node label in the
  386. * intput tree. If no value is provided the entire label is
  387. * used.
  388. * 'match': Set to 'uniquename' if the leaf nodes should be matched
  389. * with the feature uniquename.
  390. * 'load_now': If set, the tree will be loaded immediately if a tree_file
  391. * is provided. Otherwise, the tree will be loaded via
  392. * a Tripal jobs call.
  393. *
  394. * @ingroup tripal_phylotree_api
  395. */
  396. function chado_update_phylotree($phylotree_id, &$options) {
  397. global $user;
  398. // Validate the incoming options.
  399. $errors = array();
  400. $warnings = array();
  401. $success = chado_validate_phylotree('update', $options, $errors, $warnings);
  402. if (!$success) {
  403. foreach ($errors as $field => $message) {
  404. tripal_report_error('tripal_phylogeny', TRIPAL_ERROR, $message);
  405. }
  406. return FALSE;
  407. }
  408. // If we're here then all is good, so update the phylotree record.
  409. $match = array(
  410. 'phylotree_id' => $phylotree_id,
  411. );
  412. if (array_key_exists('name', $options) and $options['name']) {
  413. $values['name'] = $options['name'];
  414. }
  415. if (array_key_exists('analysis_id', $options) and $options['analysis_id']) {
  416. $values['analysis_id'] = $options['analysis_id'];
  417. }
  418. if (array_key_exists('dbxref_id', $options) and $options['dbxref_id']) {
  419. $values['dbxref_id'] = $options['dbxref_id'];
  420. }
  421. if (array_key_exists('description', $options) and $options['description']) {
  422. $values['comment'] = $options['description'];
  423. }
  424. if (array_key_exists('type_id', $options) and $options['type_id']) {
  425. $values['type_id'] = $options['type_id'];
  426. }
  427. $phylotree = chado_update_record('phylotree', $match, $values, array('return_record' => TRUE));
  428. if (!$phylotree) {
  429. drupal_set_message(t('Unable to update phylotree.'), 'warning');
  430. tripal_report_error('tripal_phylogeny', TRIPAL_WARNING,
  431. 'Update phylotree: Unable to update phylotree where values: %values',
  432. array('%values' => print_r($values, TRUE))
  433. );
  434. }
  435. // If we have a tree file, then import the tree.
  436. if (array_key_exists('tree_file', $options) and $options['tree_file']) {
  437. // Remove any existing nodes
  438. chado_delete_record('phylonode', array('phylotree_id' => $options['phylotree_id']));
  439. // Make sure if we already have a file that we remove the old one.
  440. $sql = "
  441. SELECT FM.fid
  442. FROM {file_managed} FM
  443. INNER JOIN {file_usage} FU on FM.fid = FU.fid
  444. WHERE FU.id = :id and FU.module = 'tripal_phylogeny'
  445. ";
  446. $fid = db_query($sql, array(':id' => $options['phylotree_id']))->fetchField();
  447. if ($fid) {
  448. $file = file_load($fid);
  449. file_delete($file, TRUE);
  450. }
  451. // If the tree_file is numeric then it is a Drupal managed file and
  452. // we want to make the file permanent and associated with the tree.
  453. if (is_numeric($options['tree_file'])) {
  454. $file = file_load($options['tree_file']);
  455. $file->status = FILE_STATUS_PERMANENT;
  456. $file = file_save($file);
  457. file_usage_add($file, 'tripal_phylogeny', 'newick', $options['phylotree_id']);
  458. // Add a job to parse the new node tree.
  459. $real_file_path = drupal_realpath($file->uri);
  460. }
  461. else {
  462. $real_file_path = $options['tree_file'];
  463. }
  464. // If caller has requested to load the file now then do so, otherwise
  465. // submit using a Tripal job.
  466. if (array_key_exists('load_now', $options) and $options['load_now']) {
  467. $args = array(
  468. 'phylotree_id' => $options['phylotree_id'],
  469. 'leaf_type' => $options['leaf_type'],
  470. 'match' => $options['match'] ? 'uniquename' : 'name',
  471. 'name_re' => $options['name_re'],
  472. );
  473. chado_phylogeny_import_tree_file($real_file_path, $options['format'], $args);
  474. }
  475. else {
  476. $args = array(
  477. $real_file_path,
  478. 'newick',
  479. array(
  480. 'phylotree_id' => $options['phylotree_id'],
  481. 'leaf_type' => $options['leaf_type'],
  482. 'match' => $options['match'] ? 'uniquename' : 'name',
  483. 'name_re' => $options['name_re'],
  484. ),
  485. );
  486. if (tripal_add_job("Import Tree File: " . $file->filename, 'tripal_phylogeny',
  487. 'chado_phylogeny_import_tree_file', $args, $user->uid)) {
  488. drupal_set_message(t('The tree visualizations will appear once the tree is fully imported.'));
  489. }
  490. }
  491. }
  492. return TRUE;
  493. }
  494. /**
  495. * Deletes a phylotree record from Chado.
  496. *
  497. * @param $phylotree_id
  498. *
  499. * @return
  500. * TRUE on success, FALSE on failure.
  501. *
  502. * @ingroup tripal_phylotree_api
  503. */
  504. function chado_delete_phylotree($phylotree_id) {
  505. // If we don't have a phylotree id for this node then this isn't a node of
  506. // type chado_phylotree or the entry in the chado_phylotree table was lost.
  507. if (!$phylotree_id) {
  508. tripal_report_error('tripal_phylogeny', TRIPAL_ERROR,
  509. 'Please provide a phylotree_id to delete a tree.');
  510. return FALSE;
  511. }
  512. // Remove the tree
  513. $values = array('phylotree_id' => $phylotree_id);
  514. return chado_delete_record('phylotree', $values);
  515. }
  516. /**
  517. * Iterates through the tree and sets the left and right indicies.
  518. *
  519. * @param $tree
  520. * The tree array.
  521. * @param $index
  522. * This parameters is not used when the function is first called. It
  523. * is used for recursive calls.
  524. *
  525. * @ingroup tripal_phylotree_api
  526. */
  527. function chado_assign_phylogeny_tree_indices(&$tree, &$index = 1) {
  528. // Assign a left and right index to each node. The child node must
  529. // have a right and left index less than that of it's parents. We
  530. // increment the index by 100 to give space for new nodes that might
  531. // be added later.
  532. if (array_key_exists('name', $tree)) {
  533. $tree['left_index'] = $index += 100;
  534. if (array_key_exists('is_leaf', $tree)) {
  535. $tree['right_index'] = $index += 100;
  536. }
  537. }
  538. if (array_key_exists('branch_set', $tree)) {
  539. foreach ($tree['branch_set'] as $key => $node) {
  540. chado_assign_phylogeny_tree_indices($tree['branch_set'][$key], $index);
  541. $tree['right_index'] = $index += 100;
  542. }
  543. }
  544. }
  545. /**
  546. * Iterates through the tree array and creates phylonodes in Chado.
  547. *
  548. * The function iterates through the tree in a top-down approach adding
  549. * parent internal nodes prior to leaf nodes. Each node of the tree should have
  550. * the following fields:
  551. *
  552. * -name: The name (or label) for this node.
  553. * -depth: The depth of the node in the tree.
  554. * -is_root: Set to 1 if this node is a root node.
  555. * -is_leaf: Set to 1 if this node is a leaf node.
  556. * -is_internal: Set to 1 if this node is an internal node.
  557. * -left_index: The index of the node to the left in the tree.
  558. * -right_index: The index of the node to the right in the tree.
  559. * -branch_set: An array containing a list of nodes of that are children
  560. * of the node.
  561. * -parent: The name of the parent node.
  562. * -organism_id: The organism_id for associtating the node with an organism.
  563. * -properties: An array of key/value pairs where the key is the cvterm_id
  564. * and the value is the property value. These properties
  565. * will be assocaited with the phylonode.
  566. *
  567. * Prior to importing the tree the indicies can be set by using the
  568. * chado_assign_phylogeny_tree_indices() function.
  569. *
  570. * @param $tree
  571. * The tree array.
  572. * @param $phylotree.
  573. * The phylotree object (from Chado).
  574. * @param $options
  575. * The options provide some direction for how the tree is imported. The
  576. * following keys can be used:
  577. * -taxonomy: Set to 1 if this tree is a taxonomic tree. Set to 0
  578. * otherwise.
  579. * -leaf_type: Set to the leaf type name. If this is a non-taxonomic tree
  580. * that is associated with features, then this should be the
  581. * Sequence Ontology term for the feature (e.g. polypeptide).
  582. * If this is a taxonomic tree then this option is not needed.
  583. * -match: Set to either 'name' or 'uniquename'. This is used for
  584. * matching the feature name or uniquename with the node name.
  585. * This is not needed for taxonomic trees.
  586. * -match_re: Set to a regular that can be used for matching the node
  587. * name with the feature name if the node name is not
  588. * identical to the feature name.
  589. * @param $vocab
  590. * Optional. An array containing a set of key/value pairs that maps node
  591. * types to CV terms. The keys must be 'root', 'internal' or 'leaf'. If
  592. * no vocab is provded then the terms provided by the tripal_phylogeny
  593. * CV will be used.
  594. * @param $parent
  595. * This argument is not needed when the funtion is first called. This
  596. * function is recursive and this argument is used on recursive calls.
  597. *
  598. * @ingroup tripal_phylotree_api
  599. */
  600. function chado_phylogeny_import_tree(&$tree, $phylotree, $options, $vocab = array(), $parent = NULL) {
  601. // Get the vocabulary terms used to describe nodes in the tree if one
  602. // wasn't provided.
  603. if (count($vocab) == 0) {
  604. $vocab = chado_phylogeny_get_node_types_vocab();
  605. }
  606. if (is_array($tree) and array_key_exists('name', $tree)) {
  607. $values = array(
  608. 'phylotree_id' => $phylotree->phylotree_id,
  609. 'left_idx' => $tree['left_index'],
  610. 'right_idx' => $tree['right_index'],
  611. );
  612. // Add in any optional values to the $values array if they are present.
  613. if (!empty($tree['name']) and $tree['name'] != '') {
  614. $values['label'] = $tree['name'];
  615. }
  616. if (!empty($tree['length']) and $tree['length'] != '') {
  617. $values['distance'] = $tree['length'];
  618. }
  619. // Set the type of node.
  620. if ($tree['is_root']) {
  621. $values['type_id'] = $vocab['root']->cvterm_id;
  622. }
  623. else if ($tree['is_internal']) {
  624. $values['type_id'] = $vocab['internal']->cvterm_id;
  625. $values['parent_phylonode_id'] = $parent['phylonode_id'];
  626. // TOOD: a feature may be associated here but it is recommended that it
  627. // be a feature of type SO:match and should represent the alignment of
  628. // all features beneath it.
  629. }
  630. else if ($tree['is_leaf']) {
  631. $values['type_id'] = $vocab['leaf']->cvterm_id;
  632. $values['parent_phylonode_id'] = $parent['phylonode_id'];
  633. // Match this leaf node with an organism or feature depending on the
  634. // type of tree. But we can't do that if we don't have a name.
  635. if (!empty($tree['name']) and $tree['name'] != '') {
  636. if (!$options['taxonomy']) {
  637. // This is a sequence-based tree. Try to match leaf nodes with
  638. // features.
  639. // First, Get the Name and uniquename for the feature.
  640. $matches = array();
  641. $sel_values = array();
  642. if ($options['match'] == "name") {
  643. $sel_values['name'] = $tree['name'];
  644. $re = $options['name_re'];
  645. if (preg_match("/$re/", $tree['name'], $matches)) {
  646. $sel_values['name'] = $matches[1];
  647. }
  648. }
  649. else {
  650. $sel_values['uniquename'] = $tree['name'];
  651. $re = $options['name_re'];
  652. if (preg_match("/$re/", $tree['name'], $matches)) {
  653. $sel_values['uniquename'] = $matches[1];
  654. }
  655. }
  656. $sel_values['type_id'] = array(
  657. 'name' => $options['leaf_type'],
  658. 'cv_id' => array(
  659. 'name' => 'sequence'
  660. ),
  661. );
  662. $sel_columns = array('feature_id');
  663. $feature = chado_select_record('feature', $sel_columns, $sel_values);
  664. if (count($feature) > 1) {
  665. // Found multiple features, cannot make an association.
  666. }
  667. else if (count($feature) == 1) {
  668. $values['feature_id'] = $feature[0]->feature_id;
  669. }
  670. else {
  671. // Could not find a feature that matches the name or uniquename
  672. }
  673. }
  674. }
  675. }
  676. // Insert the new node and then add it's assigned phylonode_id to the node.
  677. $phylonode = chado_insert_record('phylonode', $values);
  678. $tree['phylonode_id'] = $phylonode['phylonode_id'];
  679. // This is a taxonomic tree, so assocaite this node with an
  680. // organism if one is provided.
  681. if (array_key_exists('organism_id', $tree)) {
  682. $values = array(
  683. 'phylonode_id' => $tree['phylonode_id'],
  684. 'organism_id' => $tree['organism_id']
  685. );
  686. $pylonode_organism = chado_insert_record('phylonode_organism', $values);
  687. }
  688. // Associate any properties.
  689. if (array_key_exists('properties', $tree)) {
  690. foreach ($tree['properties'] as $type_id => $value) {
  691. $values = array(
  692. 'phylonode_id' => $tree['phylonode_id'],
  693. 'type_id' => $type_id,
  694. 'value' => $value,
  695. );
  696. $pylonode_organism = chado_insert_record('phylonodeprop', $values);
  697. }
  698. }
  699. }
  700. if (is_array($tree) and array_key_exists('branch_set', $tree)) {
  701. foreach ($tree['branch_set'] as $key => $node) {
  702. chado_phylogeny_import_tree($tree['branch_set'][$key], $phylotree, $options, $vocab, $tree);
  703. }
  704. }
  705. }
  706. /**
  707. * Get the vocabulary terms used to describe nodes in the tree.
  708. *
  709. * @return
  710. * Array of vocab info or FALSE on failure.
  711. *
  712. * @ingroup tripal_phylotree_api
  713. */
  714. function chado_phylogeny_get_node_types_vocab() {
  715. // Get the vocabulary terms used to describe nodes in the tree.
  716. $values = array(
  717. 'name' => 'phylo_leaf',
  718. 'cv_id' => array(
  719. 'name' => 'tripal_phylogeny',
  720. ),
  721. );
  722. $leaf = chado_generate_var('cvterm', $values);
  723. if (!$leaf) {
  724. tripal_report_error('tripal_phylogeny', TRIPAL_ERROR,
  725. "Could not find the leaf vocabulary term: 'phylo_leaf'. It should " .
  726. "already be present as part of the tripal_phylogeny vocabulary.");
  727. return FALSE;
  728. }
  729. $values['name'] = 'phylo_interior';
  730. $internal = chado_generate_var('cvterm', $values);
  731. if (!$internal) {
  732. tripal_report_error('tripal_phylogeny', TRIPAL_ERROR,
  733. "Could not find the leaf vocabulary term: 'phylo_interior'. It should " .
  734. "already be present as part of the tripal_phylogeny vocabulary.");
  735. return FALSE;
  736. }
  737. $values['name'] = 'phylo_root';
  738. $root = chado_generate_var('cvterm', $values);
  739. if (!$root) {
  740. tripal_report_error('tripal_phylogeny', TRIPAL_ERROR,
  741. "Could not find the leaf vocabulary term: 'phylo_root'. It should " .
  742. "already be present as part of the tripal_phylogeny vocabulary.");
  743. return FALSE;
  744. }
  745. $vocab = array(
  746. 'leaf' => $leaf,
  747. 'internal' => $internal,
  748. 'root' => $root,
  749. );
  750. return $vocab;
  751. }
  752. /**
  753. * Imports a tree file.
  754. *
  755. * This function is used as a wrapper for loading a phylogenetic tree using
  756. * any number of file loaders.
  757. *
  758. * @param $file_name
  759. * The name of the file containing the phylogenetic tree to import.
  760. * @param $format
  761. * The format of the file. Currently only the 'newick' file format is
  762. * supported.
  763. * @param $options
  764. * Options if the phylotree record already exists:
  765. * 'phylotree_id': The imported nodes will be associated with this tree.
  766. * 'leaf_type': A sequence ontology term or the word 'organism'. If the
  767. * type is 'organism' then this tree represents a
  768. * taxonomic tree. The default, if not specified, is the
  769. * term 'polypeptide'.
  770. * 'name_re': If the leaf type is NOT 'taxonomy', then the value of
  771. * this field can be a regular expression to pull out
  772. * the name of the feature from the node label in the
  773. * intput tree. If no value is provided the entire label is
  774. * used.
  775. * 'match': Set to 'uniquename' if the leaf nodes should be matched
  776. * with the feature uniquename.
  777. *
  778. * @ingroup tripal_phylotree_api
  779. */
  780. function chado_phylogeny_import_tree_file($file_name, $format, $options = array(), $job_id = NULL) {
  781. // Set some option details.
  782. if (!array_key_exists('leaf_type', $options)) {
  783. $options['leaf_type'] = 'polypeptide';
  784. }
  785. if (!array_key_exists('match', $options)) {
  786. $options['match'] = 'name';
  787. }
  788. if (!array_key_exists('name_re', $options)) {
  789. $options['name_re'] = '^(.*)$';
  790. }
  791. $options['name_re'] = trim($options['name_re']);
  792. // If a phylotree ID is not passed in then make sure we have the other
  793. // required fields for creating a tree.
  794. if (!array_key_exists('phylotree_id', $options)) {
  795. if (!array_key_exists('name', $options)) {
  796. tripal_report_error('tripal_phylogeny', TRIPAL_ERROR,
  797. 'The phylotree_id is required for importing the tree.');
  798. return FALSE;
  799. }
  800. }
  801. // Get the phylotree record.
  802. $values = array('phylotree_id' => $options['phylotree_id']);
  803. $phylotree = chado_generate_var('phylotree', $values);
  804. if (!$phylotree) {
  805. tripal_report_error('tripal_phylogeny', TRIPAL_ERROR,
  806. 'Could not find the phylotree using the ID provided: %phylotree_id.',
  807. array('%phylotree_id' => $options['phylotree_id']));
  808. return FALSE;
  809. }
  810. $transaction = db_transaction();
  811. print "\nNOTE: Loading of this tree file is performed using a database transaction. \n" .
  812. "If the load fails or is terminated prematurely then the entire set of \n" .
  813. "insertions/updates is rolled back and will not be found in the database\n\n";
  814. try {
  815. // Parse the file according to the format indicated.
  816. if ($format == 'newick') {
  817. // Parse the tree into the expected nested node format.
  818. module_load_include('inc', 'tripal_chado', 'includes/loaders/tripal_chado.phylotree_newick');
  819. $tree = tripal_phylogeny_parse_newick_file($file_name);
  820. // Assign the right and left indecies to the tree ndoes.
  821. chado_assign_phylogeny_tree_indices($tree);
  822. }
  823. // Iterate through the tree nodes and add them to Chado in accordance
  824. // with the details in the $options array.
  825. chado_phylogeny_import_tree($tree, $phylotree, $options);
  826. }
  827. catch (Exception $e) {
  828. $transaction->rollback();
  829. watchdog_exception('tripal_phylogeny', $e);
  830. }
  831. }