Class HSP

source code

             object --+        
                      |        
_base._BaseSearchObject --+    
                          |    
             _base._BaseHSP --+
                              |
                             HSP

Class representing high-scoring region(s) between query and hit.

HSP (high-scoring pair) objects are contained by Hit objects (see Hit).
In most cases, HSP objects store the bulk of the statistics and results
(e.g. e-value, bitscores, query sequence, etc.) produced by a search
program.

Depending on the search output file format, a given HSP will contain one
or more HSPFragment object(s). Examples of search programs that produce HSP
with one HSPFragments are BLAST, HMMER, and FASTA. Other programs such as
BLAT or Exonerate may produce HSPs containing more than one HSPFragment.
However, their native terminologies may differ: in BLAT these fragments
are called 'blocks' while in Exonerate they are called exons or NER.

Here are examples from each type of HSP. The first one comes from a BLAST
search:

>>> from Bio import SearchIO
>>> blast_qresult = SearchIO.parse('Blast/mirna.xml', 'blast-xml').next()
>>> blast_hsp = blast_qresult[1][0]     # the first HSP from the second hit
>>> blast_hsp
HSP(hit_id='gi|301171311|ref|NR_035856.1|', query_id='33211', 1 fragments)
>>> print blast_hsp
      Query: 33211 mir_1
        Hit: gi|301171311|ref|NR_035856.1| Pan troglodytes microRNA mir-520b ...
Query range: [1:61] (1)
  Hit range: [0:60] (1)
Quick stats: evalue 1.7e-22; bitscore 109.49
  Fragments: 1 (60 columns)
     Query - CCTCTACAGGGAAGCGCTTTCTGTTGTCTGAAAGAAAAGAAAGTGCTTCCTTTTAGAGGG
             ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
       Hit - CCTCTACAGGGAAGCGCTTTCTGTTGTCTGAAAGAAAAGAAAGTGCTTCCTTTTAGAGGG

For HSPs with a single HSPFragment, you can invoke `print` on it and see the
underlying sequence alignment, if it exists. This is not the case for HSPs
with more than one HSPFragment. Below is an example, using an HSP from a
BLAT search. Invoking `print` on these HSPs will instead show a table of the
HSPFragment objects it contains:

>>> blat_qresult = SearchIO.read('Blat/mirna.pslx', 'blat-psl', pslx=True)
>>> blat_hsp = blat_qresult[1][0]       # the first HSP from the second hit
>>> blat_hsp
HSP(hit_id='chr11', query_id='blat_1', 2 fragments)
>>> print blat_hsp
      Query: blat_1 <unknown description>
        Hit: chr11 <unknown description>
Query range: [42:67] (-1)
  Hit range: [59018929:59018955] (1)
Quick stats: evalue ?; bitscore ?
  Fragments: ---  --------------  ----------------------  ----------------------
               #            Span             Query range               Hit range
             ---  --------------  ----------------------  ----------------------
               0               6                 [61:67]     [59018929:59018935]
               1              16                 [42:58]     [59018939:59018955]

Notice that in HSPs with more than one HSPFragments, the HSP's `query_range`
`hit_range` properties encompasses all fragments it contains.

You can check whether an HSP has more than one HSPFragments or not using the
`is_fragmented` property:

>>> blast_hsp.is_fragmented
False
>>> blat_hsp.is_fragmented
True

Since HSP objects are also containers similar to Python lists, you can
access a single fragment in an HSP using its integer index:

>>> blat_fragment = blat_hsp[0]
>>> print blat_fragment
      Query: blat_1 <unknown description>
        Hit: chr11 <unknown description>
Query range: [61:67] (-1)
  Hit range: [59018929:59018935] (1)
  Fragments: 1 (6 columns)
     Query - tatagt
       Hit - tatagt

This applies to HSPs objects with a single fragment as well:

>>> blast_fragment = blast_hsp[0]
>>> print blast_fragment
      Query: 33211 mir_1
        Hit: gi|301171311|ref|NR_035856.1| Pan troglodytes microRNA mir-520b ...
Query range: [1:61] (1)
  Hit range: [0:60] (1)
  Fragments: 1 (60 columns)
     Query - CCTCTACAGGGAAGCGCTTTCTGTTGTCTGAAAGAAAAGAAAGTGCTTCCTTTTAGAGGG
             ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
       Hit - CCTCTACAGGGAAGCGCTTTCTGTTGTCTGAAAGAAAAGAAAGTGCTTCCTTTTAGAGGG

Regardless of the search output file format, HSP objects provide the
properties listed below. These properties always return values in a list,
due to the HSP object itself being a list-like container. However, for
HSP objects with a single HSPFragment, shortcut properties that fetches
the item from the list are also provided.

+----------------------+---------------------+-----------------------------+
| Property             | Shortcut            | Value                       |
+======================+=====================+=============================+
| aln_all              | aln                 | HSP alignments as           |
|                      |                     | MultipleSeqAlignment object |
+----------------------+---------------------+-----------------------------+
| aln_annotation_all   | aln_annotation      | dictionary of annotation(s) |
|                      |                     | of all fragments' alignments|
+----------------------+---------------------+-----------------------------+
| fragments            | fragment            | HSPFragment objects         |
+----------------------+---------------------+-----------------------------+
| hit_all              | hit                 | hit sequence as SeqRecord   |
|                      |                     | objects                     |
+----------------------+---------------------+-----------------------------+
| hit_features_all     | hit_features        | SeqFeatures of all hit      |
|                      |                     | fragments                   |
+----------------------+---------------------+-----------------------------+
| hit_start_all        | hit_start*          | start coordinates of the    |
|                      |                     | hit fragments               |
+----------------------+---------------------+-----------------------------+
| hit_end_all          | hit_end*            | end coordinates of the hit  |
|                      |                     | fragments                   |
+----------------------+---------------------+-----------------------------+
| hit_span_all         | hit_span*           | sizes of each hit fragments |
+----------------------+---------------------+-----------------------------+
| hit_strand_all       | hit_strand          | strand orientations of the  |
|                      |                     | hit fragments               |
+----------------------+---------------------+-----------------------------+
| hit_frame_all        | hit_frame           | reading frames of the hit   |
|                      |                     | fragments                   |
+----------------------+---------------------+-----------------------------+
| hit_range_all        | hit_range           | tuples of start and end     |
|                      |                     | coordinates of each hit     |
|                      |                     | fragment                    |
+----------------------+---------------------+-----------------------------+
| query_all            | query               | query sequence as SeqRecord |
|                      |                     | object                      |
+----------------------+---------------------+-----------------------------+
| query_features_all   | query_features      | SeqFeatures of all query    |
|                      |                     | fragments                   |
+----------------------+---------------------+-----------------------------+
| query_start_all      | query_start*        | start coordinates of the    |
|                      |                     | fragments                   |
+----------------------+---------------------+-----------------------------+
| query_end_all        | query_end*          | end coordinates of the      |
|                      |                     | query fragments             |
+----------------------+---------------------+-----------------------------+
| query_span_all       | query_span*         | sizes of each query         |
|                      |                     | fragments                   |
+----------------------+---------------------+-----------------------------+
| query_strand_all     | query_strand        | strand orientations of the  |
|                      |                     | query fragments             |
+----------------------+---------------------+-----------------------------+
| query_frame_all      | query_frame         | reading frames of the query |
|                      |                     | fragments                   |
+----------------------+---------------------+-----------------------------+
| query_range_all      | query_range         | tuples of start and end     |
|                      |                     | coordinates of each query   |
|                      |                     | fragment                    |
+----------------------+---------------------+-----------------------------+
* may be used in HSPs with multiple fragments

For all types of HSP objects, the property will return the values in a list.
Shorcuts are only applicable for HSPs with one fragment. Except the ones
noted, if they are used on an HSP with more than one fragments, an exception
will be raised.

For properties that may be used in HSPs with multiple or single fragments
(`*_start`, `*_end`, and `*_span` properties), their interpretation depends
on how many fragment the HSP has:

+------------+---------------------------------------------------+
| Property   | Value                                             |
+============+===================================================+
| hit_start  | smallest coordinate value of all hit fragments    |
+------------+---------------------------------------------------+
| hit_end    | largest coordinate value of all hit fragments     |
+------------+---------------------------------------------------+
| hit_span   | difference between `hit_start` and `hit_end`      |
+------------+---------------------------------------------------+
| query_start| smallest coordinate value of all query fragments  |
+------------+---------------------------------------------------+
| query_end  | largest coordinate value of all query fragments   |
+------------+---------------------------------------------------+
| query_span | difference between `query_start` and `query_end`  |
+------------+---------------------------------------------------+

In addition to the objects listed above, HSP objects also provide the
following properties:

+--------------------+------------------------------------------------------+
| Property           | Value                                                |
+====================+======================================================+
| aln_span           | total number of residues in all HSPFragment objects  |
+--------------------+------------------------------------------------------+
| alphabet           | alphabet used in hit and query SeqRecord objects     |
+--------------------+------------------------------------------------------+
| is_fragmented      | boolean, whether there are multiple fragments or not |
+--------------------+------------------------------------------------------+
| hit_id             | ID of the hit sequence                               |
+--------------------+------------------------------------------------------+
| hit_description    | description of the hit sequence                      |
+--------------------+------------------------------------------------------+
| hit_inter_ranges   | list of hit sequence coordinates of the regions      |
|                    | between fragments                                    |
+--------------------+------------------------------------------------------+
| hit_inter_spans    | list of lengths of the regions between hit fragments |
+--------------------+------------------------------------------------------+
| query_id           | ID of the query sequence                             |
+--------------------+------------------------------------------------------+
| query_description  | description of the query sequence                    |
+--------------------+------------------------------------------------------+
| query_inter_ranges | list of query sequence coordinates of the regions    |
|                    | between fragments                                    |
+--------------------+------------------------------------------------------+
| query_inter_spans  | list of lengths of the regions between query         |
|                    |fragments                                             |
+--------------------+------------------------------------------------------+

Initializes an HSP object.

Arguments:
fragments -- List of HSPFragment objects.

HSP objects must be initialized with a list containing at least one
HSPFragment object. If multiple HSPFragment objects are used for
initialization, they must all have the same `query_id`,
`query_description`, `hit_id`, `hit_description`, and alphabet
properties.

repr(x)

str(x)

Total number of columns in all HSPFragment objects.

Smallest coordinate value of all hit fragments

Smallest coordinate value of all query fragments

Largest coordinate value of all hit fragments

Largest coordinate value of all hit fragments

The number of hit residues covered by the HSP.

The number of query residues covered by the HSP.

Tuple of HSP hit start and end coordinates.

Tuple of HSP query start and end coordinates.

Hit sequence coordinates of the regions between fragments

Query sequence coordinates of the regions between fragments

Lengths of regions between hit fragments

Lengths of regions between query fragments

Whether the HSP has more than one HSPFragment objects

Description of the hit sequence

Description of the query sequence

ID of the hit sequence

ID of the query sequence

Alphabet used in hit and query SeqRecord objects

HSPFragment object, first fragment

Hit sequence as a SeqRecord object, first fragment

Query sequence as a SeqRecord object, first fragment

Alignment of the first fragment as a MultipleSeqAlignment object

Dictionary of annotation(s) of the first fragment's alignment

Hit sequence features, first fragment

Query sequence features, first fragment

Hit strand orientation, first fragment

Query strand orientation, first fragment

Hit sequence reading frame, first fragment

Query sequence reading frame, first fragment

List of all HSPFragment objects

List of all fragments' hit sequences as SeqRecord objects

List of all fragments' query sequences as SeqRecord objects

List of all fragments' alignments as MultipleSeqAlignment objects

Dictionary of annotation(s) of all fragments' alignments

List of all hit sequence features

List of all query sequence features

List of all fragments' hit sequence strands

List of all fragments' query sequence strands

List of all fragments' hit sequence reading frames

List of all fragments' query sequence reading frames

List of all fragments' hit start coordinates

List of all fragments' query start coordinates

List of all fragments' hit end coordinates

List of all fragments' query end coordinates

List of all fragments' hit sequence size

List of all fragments' query sequence size

List of all fragments' hit start and end coordinates

List of all fragments' query start and end coordinates