blast_ui.api.inc 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341
  1. <?php
  2. /**
  3. * @file
  4. * Contains more generally applicable functions as well as some meant to help developers
  5. * Plug-in to the BLAST UI functionality
  6. */
  7. /**
  8. * Get a specific BlastDB.
  9. *
  10. * @param $identifiers
  11. * An array of identifiers used to determine which BLAST DB to retrieve.
  12. *
  13. * @return
  14. * A fully-loaded BLAST DB Node
  15. */
  16. function get_blast_database($identifiers) {
  17. $node = FALSE;
  18. if (isset($identifiers['nid'])) {
  19. $node = node_load($identifiers['nid']);
  20. }
  21. elseif (isset($identifiers['name'])) {
  22. $nid = db_query('SELECT nid FROM {blastdb} WHERE name=:name', array(':name' => $identifiers['name']))->fetchField();
  23. $node = node_load($nid);
  24. } elseif (isset($identifiers['path'])) {
  25. $nid = db_query('SELECT nid FROM {blastdb} WHERE path LIKE :path', array(':path' => db_like($identifiers['path']) . '%'))->fetchField();
  26. $node = node_load($nid);
  27. }
  28. return $node;
  29. }
  30. /**
  31. * Returns a list BLAST DATABASE options
  32. *
  33. * @param $type
  34. * The type of BLAST dabases to restrict the list to (ie: n: nucleotide or p: protein)
  35. *
  36. * @return
  37. * An array where the nid is the key and the value is the human-readable name of the option
  38. */
  39. function get_blast_database_options($type) {
  40. global $user;
  41. // Use the Entity API to get a list of BLAST Nodes to load
  42. // We use this function in order respect node access control so that
  43. // administrators can use this module in combination with a node access module
  44. // of their choice to limit access to specific BLAST databases.
  45. $query = new EntityFieldQuery();
  46. $query->entityCondition('entity_type', 'node')
  47. // Restrict to BLASTDB nodes.
  48. ->entityCondition('bundle', 'blastdb')
  49. // Restrict to Published nodes.
  50. ->propertyCondition('status', 1)
  51. // Restrict to nodes the current user has permission to view.
  52. ->addTag('node_access');
  53. $entities = $query->execute();
  54. // Get all BlastDB nodes
  55. $nodes = node_load_multiple(array_keys($entities['node']));
  56. // Support obsolete database type n/p
  57. $obs_type = '';
  58. if ($type == 'protein') {
  59. $obs_type = 'p';
  60. }
  61. else {
  62. $obs_type = 'n';
  63. }
  64. $options = array();
  65. foreach ($nodes as $node) {
  66. if ( isset($node) && isset($node->db_dbtype) ) {
  67. if ( ($node->db_dbtype == $type) OR ($node->db_dbtype == $obs_type) ) {
  68. $options[$node->nid] = $node->db_name;
  69. }
  70. }
  71. }
  72. asort($options);
  73. $options[0] = 'Select a Dataset';
  74. return $options;
  75. }
  76. /**
  77. * Run BLAST (should be called from the command-line)
  78. *
  79. * @param $program
  80. * Which BLAST program to run (ie: 'blastn', 'tblastn', tblastx', 'blastp','blastx')
  81. * @param $query
  82. * The full path and filename of the query FASTA file
  83. * @param $database
  84. * The full path and filename prefix (excluding .nhr, .nin, .nsq, etc.)
  85. * @param $output_filestub
  86. * The filename (not including path) to give the results. Should not include file type suffix
  87. * @param $options
  88. * An array of additional option where the key is the name of the option used by
  89. * BLAST (ie: 'num_alignments') and the value is relates to this particular
  90. * BLAST job (ie: 250)
  91. */
  92. function run_BLAST_tripal_job($program, $query, $database, $output_filestub, $options, $job_id = NULL) {
  93. $output_file = file_directory_temp() . DIRECTORY_SEPARATOR . $output_filestub . '.blast.asn';
  94. $output_dir = variable_get('file_public_path', conf_path() . '/files')
  95. . DIRECTORY_SEPARATOR . 'tripal' . DIRECTORY_SEPARATOR . 'tripal_blast';
  96. $output_file_xml = $output_dir . DIRECTORY_SEPARATOR . $output_filestub . '.blast.xml';
  97. $output_file_tsv = $output_dir . DIRECTORY_SEPARATOR . $output_filestub . '.blast.tsv';
  98. $output_file_html = $output_dir . DIRECTORY_SEPARATOR . $output_filestub . '.blast.html';
  99. print "\nExecuting $program\n\n";
  100. print "Query: $query\n";
  101. print "Database: $database\n";
  102. print "Results File: $output_file\n";
  103. print "Options:\n";
  104. // Allow administrators to use an absolute path for these commands.
  105. // Defaults to using $PATH.
  106. $blast_path = variable_get('blast_path', '');
  107. $blast_threads = variable_get('blast_threads', '');
  108. // Strip the extension off the BLAST target
  109. $database = preg_replace("/(.*)\.[pn]\w\w/", '$1', $database);
  110. // The executables:
  111. $program = $blast_path . $program;
  112. $blast_formatter_command = $blast_path . 'blast_formatter';
  113. $blast_cmd = "$program -query '$query' -db '$database' -out '$output_file' -outfmt=11";
  114. if (!empty($options)) {
  115. foreach ($options as $opt => $val) {
  116. print "\t$opt: $val\n";
  117. $blast_cmd .= " -$opt $val";
  118. }
  119. }
  120. print "\nExecuting the following BLAST command:\n" . $blast_cmd . "\n";
  121. system($blast_cmd);
  122. if(!file_exists($output_file)) {
  123. tripal_report_error(
  124. 'blast_ui',
  125. TRIPAL_ERROR,
  126. "BLAST did not complete successfully as is implied by the lack of output file (%file). The command run was @command",
  127. array('%file' => $output_file, '@command' => $blast_cmd),
  128. array('print' => TRUE)
  129. );
  130. return FALSE;
  131. }
  132. print "\nGenerating additional download formats...\n";
  133. print "\tXML\n";
  134. $format_cmd = "$blast_formatter_command -archive $output_file -outfmt 5 -out $output_file_xml";
  135. print "\nExecuting $format_cmd\n\n";
  136. system($format_cmd);
  137. if(!file_exists($output_file_xml)) {
  138. tripal_report_error(
  139. 'blast_ui',
  140. TRIPAL_ERROR,
  141. "Unable to convert BLAST ASN.1 archive (%archive) to XML (%file).",
  142. array('%archive' => $output_file, '%file' => $output_file_xml),
  143. array('print' => TRUE)
  144. );
  145. }
  146. print "\tTab-delimited\n";
  147. system("$blast_formatter_command -archive $output_file -outfmt 7 -out $output_file_tsv");
  148. if(!file_exists($output_file_tsv)) {
  149. tripal_report_error(
  150. 'blast_ui',
  151. TRIPAL_WARNING,
  152. "Unable to convert BLAST ASN.1 archive (%archive) to Tabular Output (%file).",
  153. array('%archive' => $output_file, '%file' => $output_file_tsv),
  154. array('print' => TRUE)
  155. );
  156. }
  157. print "\tHTML (includes alignments)\n";
  158. system("$blast_formatter_command -archive $output_file -outfmt 0 -out $output_file_html -html");
  159. if(!file_exists($output_file_tsv)) {
  160. tripal_report_error(
  161. 'blast_ui',
  162. TRIPAL_WARNING,
  163. "Unable to convert BLAST ASN.1 archive (%archive) to HTML Output (%file).",
  164. array('%archive' => $output_file, '%file' => $output_file_html),
  165. array('print' => TRUE)
  166. );
  167. }
  168. print "\nDone!\n";
  169. }
  170. /**
  171. * FASTA validating parser
  172. *
  173. * A sequence in FASTA format begins with a single-line description, followed
  174. * by lines of sequence data.The description line is distinguished from the
  175. * sequence data by a greater-than (">") symbol in the first column. The word
  176. * following the ">" symbol is the identifier of the sequence, and the rest of
  177. * the line is the description (both are optional). There should be no space
  178. * between the ">" and the first letter of the identifier. The sequence ends
  179. * if another line starting with a ">" appears which indicates the start of
  180. * another sequence.
  181. *
  182. * @param $type
  183. * The type of sequence to be validated (ie: either nucleotide or protein).
  184. * @param $sequence
  185. * A string of characters to be validated.
  186. *
  187. * @return
  188. * Return a boolean. 1 if the sequence does not pass the format valifation stage and 0 otherwise.
  189. *
  190. */
  191. function validate_fasta_sequence($type, $sequence) {
  192. if ($type == 'nucleotide') {
  193. $fastaIdRegEx = '/^>.*(\\n|\\r)/';
  194. $fastaSeqRegEx = '/[^acgntuACGNTU\n\r]/';
  195. if ( preg_match($fastaSeqRegEx,$sequence) && !(preg_match($fastaIdRegEx,$sequence)) ) {
  196. return TRUE;
  197. } else {
  198. return FALSE;
  199. }
  200. } elseif ($type == 'protein') {
  201. $fastaIdRegEx = '/^>.*(\\n|\\r)/';
  202. $fastaSeqRegEx = '/[^acgturykmswbdhvnxACGTURYKMSWBDHVNX\*\-\n\r]/';
  203. if ( preg_match($fastaSeqRegEx,$sequence) && !(preg_match($fastaIdRegEx,$sequence)) ) {
  204. return TRUE;
  205. } else {
  206. return FALSE;
  207. }
  208. }
  209. return FALSE;
  210. }
  211. /**
  212. * Retrieve the regex to capture the Link-out Accession from the Hit Def.
  213. *
  214. * @param $nid
  215. * The node ID of the BLAST database the hit is from.
  216. * @param $options
  217. * An array of options that can be passed to this function. Supported
  218. * options include:
  219. * -
  220. *
  221. * @return
  222. * A PHP regex for use with preg_match to cature the Link-out Accession.
  223. */
  224. function get_blastdb_linkout_regex($node, $options = array()) {
  225. if (empty($node->linkout->regex)) {
  226. switch ($node->linkout->regex_type) {
  227. case 'default':
  228. $regex = '/^(\S+).*/';
  229. break;
  230. case 'genbank':
  231. $regex = '/^gb\|([^\|])*\|.*/';
  232. break;
  233. case 'embl':
  234. $regex = '/^embl\|([^\|])*\|.*/';
  235. break;
  236. case 'swissprot':
  237. $regex = '/^sp\|([^\|])*\|.*/';
  238. break;
  239. }
  240. }
  241. else {
  242. $regex = $node->linkout->regex;
  243. }
  244. return $regex;
  245. }
  246. /**
  247. * Return a list of recent blast jobs to be displayed to the user.
  248. *
  249. * NOTE: The calling function will be expected to do the rendering.
  250. *
  251. * @return
  252. * An array of recent jobs.
  253. */
  254. function get_recent_blast_jobs($programs = array()) {
  255. $filter_jobs = !empty($programs);
  256. // Retrieve any recent jobs from the session variable.
  257. $sid = session_id();
  258. if (isset($_SESSION['all_jobs'][$sid])) {
  259. $jobs = array();
  260. foreach ($_SESSION['all_jobs'][$sid] as $job_id => $job) {
  261. $add = TRUE;
  262. // @TODO: Check that the results are still available.
  263. // This is meant to replace the arbitrary only show jobs executed less than 48 hrs ago.
  264. // Remove jobs from the list that are not of the correct program.
  265. if ($filter_jobs AND !in_array($job['program'], $programs)) {
  266. $add = FALSE;
  267. }
  268. if ($add) {
  269. // Format the query information for display.
  270. // Easiest case: if there is only one query header then show it.
  271. if (sizeof($job['query_defs']) == 1 AND isset($job['query_defs'][0])) {
  272. $job['query_info'] = $job['query_defs'][0];
  273. }
  274. // If we have at least one header then show that along with the count of queries.
  275. elseif (isset($job['query_defs'][0])) {
  276. $job['query_info'] = sizeof($job['query_defs']) . ' queries including "' . $job['query_defs'][0] . '"';
  277. }
  278. // If they provided a sequence with no header.
  279. elseif (empty($job['query_defs'])) {
  280. $job['query_info'] = 'Unnamed Query';
  281. }
  282. // At the very least show the count of queries.
  283. else {
  284. $job['query_info'] = sizeof($job['query_defs']) . ' queries';
  285. }
  286. $jobs[$job_id] = $job;
  287. }
  288. }
  289. return $jobs;
  290. }
  291. else {
  292. return array();
  293. }
  294. }