Package Bio :: Package SearchIO :: Package _model :: Module hsp :: Class HSP
[hide private]
[frames] | no frames]

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 = next(SearchIO.parse('Blast/mirna.xml', 'blast-xml'))
>>> 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                                             |
+--------------------+------------------------------------------------------+

Instance Methods [hide private]
 
__init__(self, fragments=[])
Initializes an HSP object.
source code
 
__repr__(self)
repr(x)
source code
 
__iter__(self) source code
 
__contains__(self, fragment) source code
 
__len__(self) source code
 
__bool__(self) source code
 
__nonzero__(self) source code
 
__str__(self)
str(x)
source code
 
__getitem__(self, idx) source code
 
__setitem__(self, idx, fragments) source code
 
__delitem__(self, idx) source code
 
_validate_fragment(self, fragment) source code
 
_aln_span_get(self) source code
 
_get_coords(self, seq_type, coord_type) source code
 
_hit_start_get(self) source code
 
_query_start_get(self) source code
 
_hit_end_get(self) source code
 
_query_end_get(self) source code
 
_hit_span_get(self) source code
 
_query_span_get(self) source code
 
_hit_range_get(self) source code
 
_query_range_get(self) source code
 
_inter_ranges_get(self, seq_type) source code
 
_hit_inter_ranges_get(self) source code
 
_query_inter_ranges_get(self) source code
 
_inter_spans_get(self, seq_type) source code
 
_hit_inter_spans_get(self) source code
 
_query_inter_spans_get(self) source code

Inherited from _base._BaseHSP (private): _str_hsp_header

Inherited from _base._BaseSearchObject (private): _transfer_attrs

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __setattr__, __sizeof__, __subclasshook__

Class Variables [hide private]
  _NON_STICKY_ATTRS = ('_items')
Properties [hide private]
  aln_span
Total number of columns in all HSPFragment objects.
  hit_start
Smallest coordinate value of all hit fragments
  query_start
Smallest coordinate value of all query fragments
  hit_end
Largest coordinate value of all hit fragments
  query_end
Largest coordinate value of all hit fragments
  hit_span
The number of hit residues covered by the HSP.
  query_span
The number of query residues covered by the HSP.
  hit_range
Tuple of HSP hit start and end coordinates.
  query_range
Tuple of HSP query start and end coordinates.
  hit_inter_ranges
Hit sequence coordinates of the regions between fragments
  query_inter_ranges
Query sequence coordinates of the regions between fragments
  hit_inter_spans
Lengths of regions between hit fragments
  query_inter_spans
Lengths of regions between query fragments
  is_fragmented
Whether the HSP has more than one HSPFragment objects
  hit_description
Description of the hit sequence
  query_description
Description of the query sequence
  hit_id
ID of the hit sequence
  query_id
ID of the query sequence
  alphabet
Alphabet used in hit and query SeqRecord objects
  fragment
HSPFragment object, first fragment
  hit
Hit sequence as a SeqRecord object, first fragment
  query
Query sequence as a SeqRecord object, first fragment
  aln
Alignment of the first fragment as a MultipleSeqAlignment object
  aln_annotation
Dictionary of annotation(s) of the first fragment's alignment
  hit_features
Hit sequence features, first fragment
  query_features
Query sequence features, first fragment
  hit_strand
Hit strand orientation, first fragment
  query_strand
Query strand orientation, first fragment
  hit_frame
Hit sequence reading frame, first fragment
  query_frame
Query sequence reading frame, first fragment
  fragments
List of all HSPFragment objects
  hit_all
List of all fragments' hit sequences as SeqRecord objects
  query_all
List of all fragments' query sequences as SeqRecord objects
  aln_all
List of all fragments' alignments as MultipleSeqAlignment objects
  aln_annotation_all
Dictionary of annotation(s) of all fragments' alignments
  hit_features_all
List of all hit sequence features
  query_features_all
List of all query sequence features
  hit_strand_all
List of all fragments' hit sequence strands
  query_strand_all
List of all fragments' query sequence strands
  hit_frame_all
List of all fragments' hit sequence reading frames
  query_frame_all
List of all fragments' query sequence reading frames
  hit_start_all
List of all fragments' hit start coordinates
  query_start_all
List of all fragments' query start coordinates
  hit_end_all
List of all fragments' hit end coordinates
  query_end_all
List of all fragments' query end coordinates
  hit_span_all
List of all fragments' hit sequence size
  query_span_all
List of all fragments' query sequence size
  hit_range_all
List of all fragments' hit start and end coordinates
  query_range_all
List of all fragments' query start and end coordinates

Inherited from object: __class__

Method Details [hide private]

__init__(self, fragments=[])
(Constructor)

source code 
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.

Overrides: object.__init__

__repr__(self)
(Representation operator)

source code 
repr(x)

Overrides: object.__repr__
(inherited documentation)

__str__(self)
(Informal representation operator)

source code 
str(x)

Overrides: object.__str__
(inherited documentation)

Property Details [hide private]

aln_span

Total number of columns in all HSPFragment objects.

Get Method:
_aln_span_get(self)

hit_start

Smallest coordinate value of all hit fragments

Get Method:
_hit_start_get(self)

query_start

Smallest coordinate value of all query fragments

Get Method:
_query_start_get(self)

hit_end

Largest coordinate value of all hit fragments

Get Method:
_hit_end_get(self)

query_end

Largest coordinate value of all hit fragments

Get Method:
_query_end_get(self)

hit_span

The number of hit residues covered by the HSP.

Get Method:
_hit_span_get(self)

query_span

The number of query residues covered by the HSP.

Get Method:
_query_span_get(self)

hit_range

Tuple of HSP hit start and end coordinates.

Get Method:
_hit_range_get(self)

query_range

Tuple of HSP query start and end coordinates.

Get Method:
_query_range_get(self)

hit_inter_ranges

Hit sequence coordinates of the regions between fragments

Get Method:
_hit_inter_ranges_get(self)

query_inter_ranges

Query sequence coordinates of the regions between fragments

Get Method:
_query_inter_ranges_get(self)

hit_inter_spans

Lengths of regions between hit fragments

Get Method:
_hit_inter_spans_get(self)

query_inter_spans

Lengths of regions between query fragments

Get Method:
_query_inter_spans_get(self)

is_fragmented

Whether the HSP has more than one HSPFragment objects

Get Method:
unreachable(self)

hit_description

Description of the hit sequence

Get Method:
unreachable.getter(self)
Set Method:
unreachable.setter(self, value)

query_description

Description of the query sequence

Get Method:
unreachable.getter(self)
Set Method:
unreachable.setter(self, value)

hit_id

ID of the hit sequence

Get Method:
unreachable.getter(self)
Set Method:
unreachable.setter(self, value)

query_id

ID of the query sequence

Get Method:
unreachable.getter(self)
Set Method:
unreachable.setter(self, value)

alphabet

Alphabet used in hit and query SeqRecord objects

Get Method:
unreachable.getter(self)
Set Method:
unreachable.setter(self, value)

fragment

HSPFragment object, first fragment

Get Method:
unreachable.getter(self)

hit

Hit sequence as a SeqRecord object, first fragment

Get Method:
unreachable.getter(self)

query

Query sequence as a SeqRecord object, first fragment

Get Method:
unreachable.getter(self)

aln

Alignment of the first fragment as a MultipleSeqAlignment object

Get Method:
unreachable.getter(self)

aln_annotation

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

Get Method:
unreachable.getter(self)

hit_features

Hit sequence features, first fragment

Get Method:
unreachable.getter(self)

query_features

Query sequence features, first fragment

Get Method:
unreachable.getter(self)

hit_strand

Hit strand orientation, first fragment

Get Method:
unreachable.getter(self)

query_strand

Query strand orientation, first fragment

Get Method:
unreachable.getter(self)

hit_frame

Hit sequence reading frame, first fragment

Get Method:
unreachable.getter(self)

query_frame

Query sequence reading frame, first fragment

Get Method:
unreachable.getter(self)

fragments

List of all HSPFragment objects

Get Method:
unreachable.getter(self)

hit_all

List of all fragments' hit sequences as SeqRecord objects

Get Method:
unreachable.getter(self)

query_all

List of all fragments' query sequences as SeqRecord objects

Get Method:
unreachable.getter(self)

aln_all

List of all fragments' alignments as MultipleSeqAlignment objects

Get Method:
unreachable.getter(self)

aln_annotation_all

Dictionary of annotation(s) of all fragments' alignments

Get Method:
unreachable.getter(self)

hit_features_all

List of all hit sequence features

Get Method:
unreachable.getter(self)

query_features_all

List of all query sequence features

Get Method:
unreachable.getter(self)

hit_strand_all

List of all fragments' hit sequence strands

Get Method:
unreachable.getter(self)

query_strand_all

List of all fragments' query sequence strands

Get Method:
unreachable.getter(self)

hit_frame_all

List of all fragments' hit sequence reading frames

Get Method:
unreachable.getter(self)

query_frame_all

List of all fragments' query sequence reading frames

Get Method:
unreachable.getter(self)

hit_start_all

List of all fragments' hit start coordinates

Get Method:
unreachable.getter(self)

query_start_all

List of all fragments' query start coordinates

Get Method:
unreachable.getter(self)

hit_end_all

List of all fragments' hit end coordinates

Get Method:
unreachable.getter(self)

query_end_all

List of all fragments' query end coordinates

Get Method:
unreachable.getter(self)

hit_span_all

List of all fragments' hit sequence size

Get Method:
unreachable.getter(self)

query_span_all

List of all fragments' query sequence size

Get Method:
unreachable.getter(self)

hit_range_all

List of all fragments' hit start and end coordinates

Get Method:
unreachable.getter(self)

query_range_all

List of all fragments' query start and end coordinates

Get Method:
unreachable.getter(self)