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

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
[1]may be used in HSPs with multiple 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.

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.

Parameters:
  • fragments (iterable yielding HSPFragment) - fragments contained in the HSP object
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)