Bio::Matrix::PSM SiteMatrixI
SummaryIncluded librariesPackage variablesSynopsisDescriptionGeneral documentationMethods
Summary
Bio::Matrix::PSM::SiteMatrixI - SiteMatrixI implementation, holds a
position scoring matrix (or position weight matrix) and log-odds
Package variables
No package variables defined.
Inherit
Bio::Root::RootI
Synopsis
  # You cannot use this module directly; see Bio::Matrix::PSM::SiteMatrix
  # for an example implementation
Description
SiteMatrix is designed to provide some basic methods when working with position
scoring (weight) matrices, such as transcription factor binding sites for
example. A DNA PSM consists of four vectors with frequencies {A,C,G,T}. This is
the minimum information you should provide to construct a PSM object. The
vectors can be provided as strings with frequenciesx10 rounded to an int, going
from {0..a} and 'a' represents the maximum (10). This is like MEME's compressed
representation of a matrix and it is quite useful when working with relational
DB. If arrays are provided as an input (references to arrays actually) they can
be any number, real or integer (frequency or count).
When creating the object you can ask the constructor to make a simple pseudo
count correction by adding a number (typically 1) to all positions (with the
-correction option). After adding the number the frequencies will be
calculated. Only use correction when you supply counts, not frequencies.
Throws an exception if: You mix as an input array and string (for example A
matrix is given as array, C - as string). The position vector is (0,0,0,0). One
of the probability vectors is shorter than the rest.
Summary of the methods I use most frequently (details bellow):
  iupac - return IUPAC compliant consensus as a string
  score - Returns the score as a real number
  IC - information content. Returns a real number
  id - identifier. Returns a string
  accession - accession number. Returns a string
  next_pos - return the sequence probably for each letter, IUPAC
      symbol, IUPAC probability and simple sequence
  consenus letter for this position. Rewind at the end. Returns a hash.
  pos - current position get/set. Returns an integer.
  regexp - construct a regular expression based on IUPAC consensus.
      For example AGWV will be [Aa][Gg][AaTt][AaCcGg]
  width - site width
  get_string - gets the probability vector for a single base as a string.
  get_array - gets the probability vector for a single base as an array.
  get_logs_array - gets the log-odds vector for a single base as an array.
New methods, which might be of interest to anyone who wants to store PSM in a relational
database without creating an entry for each position is the ability to compress the
PSM vector into a string with losing usually less than 1% of the data.
this can be done with:
  my $str=$matrix->get_compressed_freq('A');
or
  my $str=$matrix->get_compressed_logs('A');
Loading from a database should be done with new, but is not yest implemented.
However you can still uncompress such string with:
  my @arr=Bio::Matrix::PSM::_uncompress_string ($str,1,1); for PSM
or
  my @arr=Bio::Matrix::PSM::_uncompress_string ($str,1000,2); for log odds
Methods
calc_weightDescriptionCode
next_posDescriptionCode
curposDescriptionCode
e_valDescriptionCode
consensusDescriptionCode
accession_numberDescriptionCode
widthDescriptionCode
IUPACDescriptionCode
ICDescriptionCode
get_stringDescriptionCode
idDescriptionCode
regexpDescriptionCode
regexp_arrayDescriptionCode
get_arrayDescriptionCode
_to_IUPACDescriptionCode
_to_consDescriptionCode
_calculate_consensusDescriptionCode
_compress_arrayDescriptionCode
_uncompress_stringDescriptionCode
get_compressed_freqDescriptionCode
get_compressed_logsDescriptionCode
sequence_match_weightDescriptionCode
get_all_vectorsDescriptionCode
Methods description
calc_weightcode    nextTop
 Title   : calc_weight
 Usage   : $self->calc_weight({A=>0.2562,C=>0.2438,G=>0.2432,T=>0.2568});
 Function: Recalculates the PSM (or weights) based on the PFM (the frequency matrix)
           and user supplied background model.
 Throws  : if no model is supplied
 Example :
 Returns :
 Args    : reference to a hash with background frequencies for A,C,G and T
next_poscodeprevnextTop
 Title   : next_pos
 Usage   : my %base=$site->next_pos;
 Function: 

           Retrieves the next position features: frequencies and weights for
           A,C,G,T, the main letter (as in consensus) and the
           probabilty for this letter to occur at this position and
           the current position

 Throws  :
 Example :
 Returns : hash (pA,pC,pG,pT,lA,lC,lG,lT,base,prob,rel)
 Args    : none
curposcodeprevnextTop
 Title   : curpos
 Usage   : my $pos=$site->curpos;
 Function: Gets/sets the current position. Converts to 0 if argument is minus and
            to width if greater than width
 Throws  :
 Example :
 Returns : integer
 Args    : integer
e_valcodeprevnextTop
 Title   : e_val
 Usage   : my $score=$site->e_val;
 Function: Gets/sets the e-value
 Throws  :
 Example :
 Returns : real number
 Args    : real number
consensuscodeprevnextTop
 Title   : consensus
 Usage   :
 Function: Returns the consensus
 Returns : string
 Args    : (optional) threshold value 1 to 10, default 5
           '5' means the returned characters had a 50% or higher presence at
           their position
accession_numbercodeprevnextTop
 Title   : accession_number
 Usage   :
 Function: accession number, this will be unique id for the SiteMatrix object as
 			well for any other object, inheriting from SiteMatrix
 Throws  :
 Example :
 Returns : string
 Args    : string
widthcodeprevnextTop
 Title   : width
 Usage   : my $width=$site->width;
 Function: Returns the length of the site
 Throws  :
 Example :
 Returns : number
 Args    :
IUPACcodeprevnextTop
 Title   : IUPAC
 Usage   : my $iupac_consensus=$site->IUPAC;
 Function: Returns IUPAC compliant consensus
 Throws  :
 Example :
 Returns : string
 Args    :
ICcodeprevnextTop
 Title   : IC
 Usage   : my $ic=$site->IC;
 Function: Information content
 Throws  :
 Example :
 Returns : real number
 Args    : none
get_stringcodeprevnextTop
 Title   : get_string
 Usage   : my $freq_A=$site->get_string('A');
 Function: Returns given probability vector as a string. Useful if you want to
           store things in a rel database, where arrays are not first choice
 Throws  : If the argument is outside {A,C,G,T}
 Example :
 Returns : string
 Args    : character {A,C,G,T}
idcodeprevnextTop
 Title   : id
 Usage   : my $id=$site->id;
 Function: Gets/sets the site id
 Throws  :
 Example :
 Returns : string
 Args    : string
regexpcodeprevnextTop
 Title   : regexp
 Usage   : my $regexp=$site->regexp;
 Function: Returns a regular expression which matches the IUPAC convention.
           N will match X, N, - and .
 Throws  :
 Example :
 Returns : string
 Args    :
regexp_arraycodeprevnextTop
 Title   : regexp_array
 Usage   : my @regexp=$site->regexp;
 Function: Returns a regular expression which matches the IUPAC convention.
           N will match X, N, - and .
 Throws  :
 Example :
 Returns : array
 Args    :
 To do   : I have separated regexp and regexp_array, but
           maybe they can be rewritten as one - just check what
           should be returned
get_arraycodeprevnextTop
 Title   : get_array
 Usage   : my @freq_A=$site->get_array('A');
 Function: Returns an array with frequencies for a specified base
 Throws  :
 Example :
 Returns : array
 Args    : char
_to_IUPACcodeprevnextTop
 Title   : _to_IUPAC
 Usage   :
 Function: Converts a single position to IUPAC compliant symbol and
            returns its probability. For rules see the implementation.
 Throws  :
 Example :
 Returns : char, real number
 Args    : real numbers for A,C,G,T (positional)
_to_conscodeprevnextTop
 Title   : _to_cons
 Usage   :
 Function: Converts a single position to simple consensus character and
            returns its probability. For rules see the implementation,
 Throws  :
 Example :
 Returns : char, real number
 Args    : real numbers for A,C,G,T (positional)
_calculate_consensuscodeprevnextTop
 Title   : _calculate_consensus
 Usage   :
 Function: Internal stuff
 Throws  :
 Example :
 Returns :
 Args    :
_compress_arraycodeprevnextTop
 Title   : _compress_array
 Usage   :
 Function:  Will compress an array of real signed numbers to a string (ie vector of bytes)
 			-127 to +127 for bi-directional(signed) and 0..255 for unsigned ;
 Throws  :
 Example :  Internal stuff
 Returns :  String
 Args    :  array reference, followed by an max value and
 			direction (optional, default 1-unsigned),1 unsigned, any other is signed.
_uncompress_stringcodeprevnextTop
 Title   : _uncompress_string
 Usage   :
 Function:  Will uncompress a string (vector of bytes) to create an array of real
            signed numbers (opposite to_compress_array)
 Throws  :
 Example :  Internal stuff
 Returns :  string, followed by an max value and
 			direction (optional, default 1-unsigned), 1 unsigned, any other is signed.
 Args    :  array
get_compressed_freqcodeprevnextTop
 Title   : get_compressed_freq
 Usage   :
 Function:  A method to provide a compressed frequency vector. It uses one byte to
 			code the frequence for one of the probability vectors for one position.
			Useful for relational database. Improvment of the previous 0..a coding.
 Throws  :
 Example :  my $strA=$self->get_compressed_freq('A');
 Returns :  String
 Args    :  char
get_compressed_logscodeprevnextTop
 Title   : get_compressed_logs
 Usage   :
 Function:  A method to provide a compressed log-odd vector. It uses one byte to
 			code the log value for one of the log-odds vectors for one position.
 Throws  :
 Example :  my $strA=$self->get_compressed_logs('A');
 Returns :  String
 Args    :  char
sequence_match_weightcodeprevnextTop
 Title   : sequence_match_weight
 Usage   :
 Function:  This method will calculate the score of a match, based on the PWM
            if such is associated with the matrix object. Returns undef if no
             PWM data is available.
 Throws  :   if the length of the sequence is different from the matrix width
 Example :  my $score=$matrix->sequence_match_weight('ACGGATAG');
 Returns :  Floating point
 Args    :  string
get_all_vectorscodeprevnextTop
 Title   : get_all_vectors
 Usage   :
 Function:  returns all possible sequence vectors to satisfy the PFM under
            a given threshold
 Throws  :  If threshold outside of 0..1 (no sense to do that)
 Example :  my @vectors=$self->get_all_vectors(4);
 Returns :  Array of strings
 Args    :  (optional) floating
Methods code
calc_weightdescriptionprevnextTop
sub calc_weight {
  my $self = shift;
  $self->throw_not_implemented();
}
next_posdescriptionprevnextTop
sub next_pos {
  my $self = shift;
  $self->throw_not_implemented();
}
curposdescriptionprevnextTop
sub curpos {
    my $self = shift;
   $self->throw_not_implemented();
}
e_valdescriptionprevnextTop
sub e_val {
    my $self = shift;
    $self->throw_not_implemented();
}
consensusdescriptionprevnextTop
sub consensus {
  my $self = shift;
  $self->throw_not_implemented();
}
accession_numberdescriptionprevnextTop
sub accession_number {
  my $self = shift;
  $self->throw_not_implemented();
}
widthdescriptionprevnextTop
sub width {
  my $self = shift;
  $self->throw_not_implemented();
}
IUPACdescriptionprevnextTop
sub IUPAC {
  my $self = shift;
  $self->throw_not_implemented();
}
ICdescriptionprevnextTop
sub IC {
my $self=shift;
$self->throw_not_implemented();
}
get_stringdescriptionprevnextTop
sub get_string {
 my $self=shift;
 $self->throw_not_implemented();
}
iddescriptionprevnextTop
sub id {
    my $self = shift;
    $self->throw_not_implemented();
}
regexpdescriptionprevnextTop
sub regexp {
 my $self=shift;
 $self->throw_not_implemented();
}
regexp_arraydescriptionprevnextTop
sub regexp_array {
 my $self=shift;
 $self->throw_not_implemented();
}
get_arraydescriptionprevnextTop
sub get_array {
  my $self=shift;
  $self->throw_not_implemented();
}
_to_IUPACdescriptionprevnextTop
sub _to_IUPAC {
    my $self = shift;
    $self->throw_not_implemented();
}
_to_consdescriptionprevnextTop
sub _to_cons {
    my $self = shift;
    $self->throw_not_implemented();
}
_calculate_consensusdescriptionprevnextTop
sub _calculate_consensus {
    my $self = shift;
    $self->throw_not_implemented();
}
_compress_arraydescriptionprevnextTop
sub _compress_array {
    my $self = shift;
    $self->throw_not_implemented();
}
_uncompress_stringdescriptionprevnextTop
sub _uncompress_string {
    my $self = shift;
    $self->throw_not_implemented();
}
get_compressed_freqdescriptionprevnextTop
sub get_compressed_freq {
    my $self = shift;
    $self->throw_not_implemented();
}
get_compressed_logsdescriptionprevnextTop
sub get_compressed_logs {
    my $self = shift;
    $self->throw_not_implemented();
}
sequence_match_weightdescriptionprevnextTop
sub sequence_match_weight {
    my $self = shift;
    $self->throw_not_implemented();
}
get_all_vectorsdescriptionprevnextTop
sub get_all_vectors {
 my $self = shift;
    $self->throw_not_implemented();
}
General documentation
FEEDBACKTop
Mailing ListsTop
User feedback is an integral part of the evolution of this and other
Bioperl modules. Send your comments and suggestions preferably to one
of the Bioperl mailing lists. Your participation is much appreciated.
  bioperl-l@bioperl.org                  - General discussion
  http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
Reporting BugsTop
Report bugs to the Bioperl bug tracking system to help us keep track
the bugs and their resolution. Bug reports can be submitted via the
web:
  http://bugzilla.open-bio.org/
AUTHOR - Stefan KirovTop
Email skirov@utk.edu
APPENDIXTop