Package Bio :: Package SearchIO :: Package HmmerIO
[hide private]
[frames] | no frames]

Source Code for Package Bio.SearchIO.HmmerIO

  1  # Copyright 2012 by Wibowo Arindrarto.  All rights reserved. 
  2  # This code is part of the Biopython distribution and governed by its 
  3  # license.  Please see the LICENSE file that should have been included 
  4  # as part of this package. 
  5   
  6  """Bio.SearchIO support for HMMER output formats. 
  7   
  8  This module adds support for parsing HMMER outputs. HMMER is a 
  9  suite of programs implementing the profile hidden Markov models to find 
 10  homology across protein sequences. 
 11   
 12  Bio.SearchIO.HmmerIO was tested on the following HMMER versions and flavors: 
 13   
 14      - HMMER3 flavors: hmmscan, hmmsearch, phmmer 
 15      - HMMER2 flavors: hmmpfam, hmmsearch 
 16   
 17  More information on HMMER are available through these links: 
 18    - Web page: http://hmmer.janelia.org/ 
 19    - User guide: ftp://selab.janelia.org/pub/software/hmmer3/3.0/Userguide.pdf 
 20   
 21   
 22  Supported formats 
 23  ================= 
 24   
 25  Bio.SearchIO.HmmerIO supports the following HMMER output formats: 
 26   
 27      - Plain text, v3.0   - 'hmmer3-text'    - parsing, indexing 
 28      - Table, v3.0        - 'hmmer3-tab'     - parsing, indexing, writing 
 29      - Domain table, v3.0 - 'hmmer3-domtab'* - parsing, indexing, writing 
 30      - Plain text, v2.x   - 'hmmer2-text'    - parsing, indexing 
 31   
 32  * For the domain table output, due to the way HMMER outputs the sequence 
 33    coordinates, you have to specify what HMMER flavor produced the output as the 
 34    file format. So instead of using 'hmmer3-domtab', you have to use either 
 35    'hmmscan3-domtab', 'hmmsearch3-domtab', or 'phmmer3-domtab' as the file format 
 36    name. 
 37   
 38  Note that for all output formats, HMMER uses its own convention of input and 
 39  output coordinates. It does not use the term 'hit' or 'query', instead it 
 40  uses 'hmm' or 'ali'. For example, 'hmmfrom' is the start coordinate of the HMM 
 41  sequence while 'alifrom' is the start coordinate of the protein sequence. 
 42   
 43  HmmerIO is aware of this different naming scheme and will adjust them 
 44  accordingly to fit SearchIO's object model. If HmmerIO sees that the output file 
 45  to parse was written by hmmsearch or phmmer, all 'hmm' coordinates will be the 
 46  hit coordinates and 'ali' coordinates will be the query coordinates. Conversely, 
 47  if the HMMER flavor is hmmscan, 'hmm' will be query and 'ali' will be hit. 
 48   
 49  This is why the 'hmmer3-domtab' format has to be specified with the source HMMER 
 50  flavor. The parsers need to know which is the hit and which is the query. 
 51  'hmmer3-text' has its source program information present in the file, while 
 52  'hmmer3-tab' does not output any coordinates. That's why both of these formats 
 53  do not need direct flavor specification like 'hmmer3-domtab'. 
 54   
 55  Also note that when using the domain table format writers, it will use HMMER's 
 56  naming convention ('hmm' and 'ali') so the files you write will be similar to 
 57  files written by a real HMMER program. 
 58   
 59   
 60  hmmer2-text and hmmer3-text 
 61  =========================== 
 62   
 63  The parser for HMMER 3.0 plain text output can parse output files with alignment 
 64  blocks (default) or without (with the '--noali' flag). If the alignment blocks 
 65  are present, you can also parse files with variable alignment width (using the 
 66  '--notextw' or '--textw' flag). 
 67   
 68  The following SearchIO objects attributes are provided. Rows marked with '*' 
 69  denotes attributes not available in the hmmer2-text format: 
 70   
 71  +-----------------+-------------------------+----------------------------------+ 
 72  | Object          | Attribute               | Value                            | 
 73  +=================+=========================+==================================+ 
 74  | QueryResult     | accession               | accession (if present)           | 
 75  |                 +-------------------------+----------------------------------+ 
 76  |                 | description             | query sequence description       | 
 77  |                 +-------------------------+----------------------------------+ 
 78  |                 | id                      | query sequence ID                | 
 79  |                 +-------------------------+----------------------------------+ 
 80  |                 | program                 | HMMER flavor                     | 
 81  |                 +-------------------------+----------------------------------+ 
 82  |                 | seq_len*                | full length of query sequence    | 
 83  |                 +-------------------------+----------------------------------+ 
 84  |                 | target                  | target search database           | 
 85  |                 +-------------------------+----------------------------------+ 
 86  |                 | version                 | BLAST version                    | 
 87  +-----------------+-------------------------+----------------------------------+ 
 88  | Hit             | bias*                   | hit-level bias                   | 
 89  |                 +-------------------------+----------------------------------+ 
 90  |                 | bitscore                | hit-level score                  | 
 91  |                 +-------------------------+----------------------------------+ 
 92  |                 | description             | hit sequence description         | 
 93  |                 +-------------------------+----------------------------------+ 
 94  |                 | domain_exp_num*         | expected number of domains in    | 
 95  |                 |                         | the hit (exp column)             | 
 96  |                 +-------------------------+----------------------------------+ 
 97  |                 | domain_obs_num          | observed number of domains in    | 
 98  |                 |                         | the hit (N column)               | 
 99  |                 +-------------------------+----------------------------------+ 
100  |                 | evalue                  | hit-level e-value                | 
101  |                 +-------------------------+----------------------------------+ 
102  |                 | id                      | hit sequence ID                  | 
103  |                 +-------------------------+----------------------------------+ 
104  |                 | is_included*            | boolean, whether the hit is in   | 
105  |                 |                         | the inclusion threshold or not   | 
106  +-----------------+-------------------------+----------------------------------+ 
107  | HSP             | acc_avg*                | expected accuracy per alignment  | 
108  |                 |                         | residue (acc column)             | 
109  |                 +-------------------------+----------------------------------+ 
110  |                 | bias*                   | hsp-level bias                   | 
111  |                 +-------------------------+----------------------------------+ 
112  |                 | bitscore                | hsp-level score                  | 
113  |                 +-------------------------+----------------------------------+ 
114  |                 | domain_index            | the domain index set by HMMER    | 
115  |                 +-------------------------+----------------------------------+ 
116  |                 | env_end*                | end coordinate of the envelope   | 
117  |                 +-------------------------+----------------------------------+ 
118  |                 | env_endtype*            | envelope end types (e.g. '[]',   | 
119  |                 |                         | '..', '[.', etc.)                | 
120  |                 +-------------------------+----------------------------------+ 
121  |                 | env_start*              | start coordinate of the envelope | 
122  |                 +-------------------------+----------------------------------+ 
123  |                 | evalue                  | hsp-level independent e-value    | 
124  |                 +-------------------------+----------------------------------+ 
125  |                 | evalue_cond*            | hsp-level conditional e-value    | 
126  |                 +-------------------------+----------------------------------+ 
127  |                 | hit_endtype             | hit sequence end types           | 
128  |                 +-------------------------+----------------------------------+ 
129  |                 | is_included*            | boolean, whether the hit of the  | 
130  |                 |                         | hsp is in the inclusion          | 
131  |                 |                         | threshold                        | 
132  |                 +-------------------------+----------------------------------+ 
133  |                 | query_endtype           | query sequence end types         | 
134  +-----------------+-------------------------+----------------------------------+ 
135  | HSPFragment     | aln_annotation          | alignment homology string and    | 
136  | (also via HSP)  |                         | other annotations (e.g. PP, CS)  | 
137  |                 +-------------------------+----------------------------------+ 
138  |                 | aln_span                | length of alignment fragment     | 
139  |                 +-------------------------+----------------------------------+ 
140  |                 | hit                     | hit sequence                     | 
141  |                 +-------------------------+----------------------------------+ 
142  |                 | hit_end                 | hit sequence end coordinate, may | 
143  |                 |                         | be 'hmmto' or 'alito' depending  | 
144  |                 |                         | on the HMMER flavor              | 
145  |                 +-------------------------+----------------------------------+ 
146  |                 | hit_start               | hit sequence start coordinate,   | 
147  |                 |                         | may be 'hmmfrom' or 'alifrom'    | 
148  |                 |                         | depending on the HMMER flavor    | 
149  |                 +-------------------------+----------------------------------+ 
150  |                 | hit_strand              | hit sequence strand              | 
151  |                 +-------------------------+----------------------------------+ 
152  |                 | query                   | query sequence                   | 
153  |                 +-------------------------+----------------------------------+ 
154  |                 | query_end               | query sequence end coordinate,   | 
155  |                 |                         | may be 'hmmto' or 'alito'        | 
156  |                 |                         | depending on the HMMER flavor    | 
157  |                 +-------------------------+----------------------------------+ 
158  |                 | query_start             | query sequence start coordinate, | 
159  |                 |                         | may be 'hmmfrom' or 'alifrom'    | 
160  |                 |                         | depending on the HMMER flavor    | 
161  |                 +-------------------------+----------------------------------+ 
162  |                 | query_strand            | query sequence strand            | 
163  +-----------------+-------------------------+----------------------------------+ 
164   
165   
166  hmmer3-tab 
167  ========== 
168  The following SearchIO objects attributes are provided: 
169   
170  +-----------------+-------------------------+----------------------------------+ 
171  | Object          | Attribute               | Column / Value                   | 
172  +=================+=========================+==================================+ 
173  | QueryResult     | accession               | query accession (if present)     | 
174  |                 +-------------------------+----------------------------------+ 
175  |                 | description             | query sequence description       | 
176  |                 +-------------------------+----------------------------------+ 
177  |                 | id                      | query name                       | 
178  +-----------------+-------------------------+----------------------------------+ 
179  | Hit             | accession               | hit accession                    | 
180  |                 +-------------------------+----------------------------------+ 
181  |                 | bias                    | hit-level bias                   | 
182  |                 +-------------------------+----------------------------------+ 
183  |                 | bitscore                | hit-level score                  | 
184  |                 +-------------------------+----------------------------------+ 
185  |                 | description             | hit sequence description         | 
186  |                 +-------------------------+----------------------------------+ 
187  |                 | cluster_num             | clu column                       | 
188  |                 +-------------------------+----------------------------------+ 
189  |                 | domain_exp_num          | exp column                       | 
190  |                 +-------------------------+----------------------------------+ 
191  |                 | domain_included_num     | inc column                       | 
192  |                 +-------------------------+----------------------------------+ 
193  |                 | domain_obs_num          | dom column                       | 
194  |                 +-------------------------+----------------------------------+ 
195  |                 | domain_reported_num     | rep column                       | 
196  |                 +-------------------------+----------------------------------+ 
197  |                 | env_num                 | env column                       | 
198  |                 +-------------------------+----------------------------------+ 
199  |                 | evalue                  | hit-level evalue                 | 
200  |                 +-------------------------+----------------------------------+ 
201  |                 | id                      | target name                      | 
202  |                 +-------------------------+----------------------------------+ 
203  |                 | overlap_num             | ov column                        | 
204  |                 +-------------------------+----------------------------------+ 
205  |                 | region_num              | reg column                       | 
206  +-----------------+-------------------------+----------------------------------+ 
207  | HSP             | bias                    | bias of the best domain          | 
208  |                 +-------------------------+----------------------------------+ 
209  |                 | bitscore                | bitscore of the best domain      | 
210  |                 +-------------------------+----------------------------------+ 
211  |                 | evalue                  | evalue of the best domain        | 
212  +-----------------+-------------------------+----------------------------------+ 
213   
214   
215  hmmer3-domtab 
216  ============= 
217  To parse domain table files, you must use the HMMER flavor that produced the 
218  file. So instead of using 'hmmer3-domtab', use either 'hmmsearch3-domtab', 
219  'hmmscan3-domtab', or 'phmmer3-domtab'. 
220   
221  The following SearchIO objects attributes are provided: 
222   
223  +-----------------+-------------------------+----------------------------------+ 
224  | Object          | Attribute               | Value                            | 
225  +=================+=========================+==================================+ 
226  | QueryResult     | accession               | accession                        | 
227  |                 +-------------------------+----------------------------------+ 
228  |                 | description             | query sequence description       | 
229  |                 +-------------------------+----------------------------------+ 
230  |                 | id                      | query sequence ID                | 
231  |                 +-------------------------+----------------------------------+ 
232  |                 | seq_len                 | full length of query sequence    | 
233  +-----------------+-------------------------+----------------------------------+ 
234  | Hit             | accession               | accession                        | 
235  |                 +-------------------------+----------------------------------+ 
236  |                 | bias                    | hit-level bias                   | 
237  |                 +-------------------------+----------------------------------+ 
238  |                 | bitscore                | hit-level score                  | 
239  |                 +-------------------------+----------------------------------+ 
240  |                 | description             | hit sequence description         | 
241  |                 +-------------------------+----------------------------------+ 
242  |                 | evalue                  | hit-level e-value                | 
243  |                 +-------------------------+----------------------------------+ 
244  |                 | id                      | hit sequence ID                  | 
245  +-----------------+-------------------------+----------------------------------+ 
246  | HSP             | acc_avg                 | expected accuracy per alignment  | 
247  |                 |                         | residue (acc column)             | 
248  |                 +-------------------------+----------------------------------+ 
249  |                 | bias                    | hsp-level bias                   | 
250  |                 +-------------------------+----------------------------------+ 
251  |                 | bitscore                | hsp-level score                  | 
252  |                 +-------------------------+----------------------------------+ 
253  |                 | domain_index            | the domain index set by HMMER    | 
254  |                 +-------------------------+----------------------------------+ 
255  |                 | env_end                 | end coordinate of the envelope   | 
256  |                 +-------------------------+----------------------------------+ 
257  |                 | env_start               | start coordinate of the envelope | 
258  |                 +-------------------------+----------------------------------+ 
259  |                 | evalue                  | hsp-level independent e-value    | 
260  |                 +-------------------------+----------------------------------+ 
261  |                 | evalue_cond             | hsp-level conditional e-value    | 
262  +-----------------+-------------------------+----------------------------------+ 
263  | HSPFragment     | hit_end                 | hit sequence end coordinate, may | 
264  | (also via HSP)  |                         | be 'hmmto' or 'alito' depending  | 
265  |                 |                         | on the HMMER flavor              | 
266  |                 +-------------------------+----------------------------------+ 
267  |                 | hit_start               | hit sequence start coordinate,   | 
268  |                 |                         | may be 'hmmfrom' or 'alifrom'    | 
269  |                 |                         | depending on the HMMER flavor    | 
270  |                 +-------------------------+----------------------------------+ 
271  |                 | hit_strand              | hit sequence strand              | 
272  |                 +-------------------------+----------------------------------+ 
273  |                 | query_end               | query sequence end coordinate,   | 
274  |                 |                         | may be 'hmmto' or 'alito'        | 
275  |                 |                         | depending on the HMMER flavor    | 
276  |                 +-------------------------+----------------------------------+ 
277  |                 | query_start             | query sequence start coordinate, | 
278  |                 |                         | may be 'hmmfrom' or 'alifrom'    | 
279  |                 |                         | depending on the HMMER flavor    | 
280  |                 +-------------------------+----------------------------------+ 
281  |                 | query_strand            | query sequence strand            | 
282  +-----------------+-------------------------+----------------------------------+ 
283   
284  """ 
285   
286  from .hmmer2_text import Hmmer2TextParser, Hmmer2TextIndexer 
287  from .hmmer3_domtab import Hmmer3DomtabParser, Hmmer3DomtabHmmhitParser, Hmmer3DomtabHmmqueryParser 
288  from .hmmer3_domtab import Hmmer3DomtabHmmhitIndexer, Hmmer3DomtabHmmqueryIndexer 
289  from .hmmer3_domtab import Hmmer3DomtabHmmhitWriter, Hmmer3DomtabHmmqueryWriter 
290  from .hmmer3_text import Hmmer3TextParser, Hmmer3TextIndexer 
291  from .hmmer3_tab import Hmmer3TabParser, Hmmer3TabIndexer, Hmmer3TabWriter 
292   
293   
294  # if not used as a module, run the doctest 
295  if __name__ == "__main__": 
296      from Bio._utils import run_doctest 
297      run_doctest() 
298