Bio::Matrix::PSM::SiteMatrix.3pm

Langue: en

Version: 2010-05-19 (ubuntu - 24/10/10)

Section: 3 (Bibliothèques de fonctions)

NAME

Bio::Matrix::PSM::SiteMatrix - SiteMatrixI implementation, holds a position scoring matrix (or position weight matrix) and log-odds

SYNOPSIS

   use Bio::Matrix::PSM::SiteMatrix;
   # Create from memory by supplying probability matrix hash
   # both as strings or arrays
   # where the frequencies  $a,$c,$g and $t are supplied either as
   # arrayref or string. Accordingly, lA, lC, lG and lT are the log
   # odds (only as arrays, no checks done right now)
   my ($a,$c,$g,$t,$score,$ic, $mid)=@_; 
   #or
   my ($a,$c,$g,$t,$score,$ic,$mid)=('05a011','110550','400001',
                                     '100104',0.001,19.2,'CRE1');
   #Where a stands for all (this frequency=1), see explanation bellow
   my %param=(-pA=>$a,-pC=>$c,-pG=>$g,-pT=>$t,
              -lA=>$la, -lC=>$lc,-lG=>$lg,-lT=>$l,
              -IC=>$ic,-e_val=>$score, -id=>$mid);
   my $site=Bio::Matrix::PSM::SiteMatrix->new(%param);
   #Or get it from a file:
   use Bio::Matrix::PSM::IO;
   my $psmIO= Bio::Matrix::PSM::IO->new(-file=>$file, -format=>'transfac');
   while (my $psm=$psmIO->next_psm) {
     #Now we have a Bio::Matrix::PSM::Psm object, 
     # see Bio::Matrix::PSM::PsmI for details
     #This is a Bio::Matrix::PSM::SiteMatrix object now
     my $matrix=$psm->matrix;  
   }
 
   # Get a simple consensus, where alphabet is {A,C,G,T,N}, 
   # choosing the character that both satisfies a supplied or default threshold
   # frequency and is the most frequenct character at each position, or N.
   # So for the position with A, C, G, T frequencies of 0.5, 0.25, 0.10, 0.15,
   # the simple consensus character will be 'A', whilst for 0.5, 0.5, 0, 0 it
   # would be 'N'.
   my $consensus=$site->consensus;
 
   # Get the IUPAC ambiguity code representation of the data in the matrix.
   # Because the frequencies may have been pseudo-count corrected, insignificant
   # frequences (below 0.05 by default) are ignored. So a position with
   # A, C, G, T frequencies of 0.5, 0.5, 0.01, 0.01 will get the IUPAC code 'M',
   # while 0.97, 0.01, 0.01, 0.01 will get the code 'A' and
   # 0.25, 0.25, 0.25, 0.25 would get 'N'.
   my $iupac=$site->IUPAC;
 
   # Getting/using regular expression (a representation of the IUPAC string)
   my $regexp=$site->regexp;
   my $count=grep($regexp,$seq);
   my $count=($seq=~ s/$regexp/$1/eg);
   print "Motif $mid is present $count times in this sequence\n";
 
 

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
 
 

FEEDBACK

Mailing Lists

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
 
 

Support

Please direct usage questions or support issues to the mailing list:

bioperl-l@bioperl.org

rather than to the module maintainer directly. Many experienced and reponsive experts will be able look at the problem and quickly address it. Please include a thorough description of the problem with code and data examples if at all possible.

Reporting Bugs

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 Kirov

Email skirov@utk.edu

CONTRIBUTORS

Sendu Bala, bix@sendu.me.uk

APPENDIX

The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _

new

  Title   : new
  Usage   : my $site=Bio::Matrix::PSM::SiteMatrix->new(-pA=>$a,-pC=>$c,
                                                      -pG=>$g,-pT=>$t,
                                                      -IC=>$ic,
                                                      -e_val=>$score, 
                                                      -id=>$mid);
  Function: Creates a new Bio::Matrix::PSM::SiteMatrix object from memory
  Throws :  If inconsistent data for all vectors (A,C,G and T) is
            provided, if you mix input types (string vs array) or if a
            position freq is 0.
  Returns :  Bio::Matrix::PSM::SiteMatrix object
  Args    :  -pA    => vector with the frequencies or counts of A
             -pC    => vector for C
             -pG    => vector for G
             -pt    => vector for T
             -lA    => vector for the log of A
             -lC    => vector for the log of C
             -lG    => vector for the log of G
             -lT    => vector for the log of T
             -IC    => real number, the information content of this matrix
             -e_val => real number, the expect value
             -id    => string, an identifier
             -width => int, width of the matrix in nucleotides
             -sites => int, the number of sites that went into this matrix
             -model => hash ref, background frequencies for A, C, G and T
             -correction => number, the number to add to all positions to achieve
                            psuedo count correction (default 0: no correction)
                            NB: do not use correction when your input is
                            frequences!
             -accession_number => string, an accession number
 
             Vectors can be strings of the frequencies where the frequencies are
             multiplied by 10 and rounded to the nearest whole number, and where
             'a' is used to denote the maximal frequency 10. There should be no
             punctuation (spaces etc.) in the string. For example, 'a0501'.
             Alternatively frequencies or counts can be represented by an array
             ref containing the counts, frequencies or logs as any kind of
             number.
 
 

_calculate_consensus

  Title   : _calculate_consensus
  Function: Internal stuff
 
 

calc_weight

  Title   : calc_weight
  Usage   : $obj->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
  Returns : n/a
  Args    : reference to a hash with background frequencies for A,C,G and T
 
 

next_pos

  Title   : next_pos
  Usage   :
  Function: Retrives the next position features: frequencies 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
  Returns : hash (pA,pC,pG,pT,logA,logC,logG,logT,base,prob,rel)
  Args    : none
 
 

curpos

  Title   : curpos
  Usage   :
  Function: Gets/sets the current position. Converts to 0 if argument is minus
            and to width if greater than width
  Returns : integer
  Args    : integer
 
 

e_val

  Title   : e_val
  Usage   : 
  Function: Gets/sets the e-value
  Returns : real number
  Args    : none to get, real number to set
 
 

IC

  Title   : IC
  Usage   :
  Function: Get/set the Information Content
  Returns : real number
  Args    : none to get, real number to set
 
 

accession_number

  Title   : accession_number
  Function: Get/set the accession number, this will be unique id for the
            SiteMatrix object as well for any other object, inheriting from
            SiteMatrix
  Returns : string
  Args    : none to get, string to set
 
 

consensus

  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
 
 

width

  Title   : width
  Usage   :
  Function: Returns the length of the sites in used to make this matrix
  Returns : int
  Args    : none
 
 

sites

  Title   : sites
  Usage   :
  Function: Get/set the number of sites that were used to make this matrix
  Returns : int
  Args    : none to get, int to set
 
 

IUPAC

  Title   : IUPAC
  Usage   :
  Function: Returns IUPAC compliant consensus
  Returns : string
  Args    : optionally, also supply a whole number (int) of 1 or higher to set
            the significance level when considering the frequencies. 1 (the
            default) means a 0.05 significance level: frequencies lower than
            0.05 will be ignored. 2 Means a 0.005 level, and so on.
 
 

_to_IUPAC

  Title   : _to_IUPAC
  Usage   :
  Function: Converts a single position to IUPAC compliant symbol.
            For rules see the implementation
  Returns : char, real number
  Args    : real numbers for frequencies of A,C,G,T (positional)
 
            optionally, also supply a whole number (int) of 1 or higher to set
            the significance level when considering the frequencies. 1 (the
            default) means a 0.05 significance level: frequencies lower than
            0.05 will be ignored. 2 Means a 0.005 level, and so on.
 
 

_to_cons

  Title   : _to_cons
  Usage   :
  Function: Converts a single position to simple consensus character and returns
            its probability. For rules see the implementation
  Returns : char, real number
  Args    : real numbers for A,C,G,T (positional), and optional 5th argument of
            threshold (as a number between 1 and 10, where 5 is default and
            means the returned character had a 50% or higher presence at this
            position)
 
 

get_string

  Title   : get_string
  Usage   :
  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}
  Returns : string
  Args    : character {A,C,G,T}
 
 

get_array

  Title   : get_array
  Usage   :
  Function: Returns an array with frequencies for a specified base
  Returns : array
  Args    : char
 
 

get_logs_array

  Title   : get_logs_array
  Usage   :
  Function: Returns an array with log_odds for a specified base
  Returns : array
  Args    : char
 
 

id

  Title   : id
  Usage   :
  Function: Gets/sets the site id
  Returns : string
  Args    : string
 
 

regexp

  Title   : regexp
  Usage   :
  Function: Returns a regular expression which matches the IUPAC convention.
            N will match X, N, - and .
  Returns : string
  Args    : none (works at the threshold last used for making the IUPAC string)
 
 

regexp_array

  Title   : regexp_array
  Usage   :
  Function: Returns a regular expression which matches the IUPAC convention.
            N will match X, N, - and .
  Returns : array
  Args    : none (works at the threshold last used for making the IUPAC string)
  To do   : I have separated regexp and regexp_array, but
            maybe they can be rewritten as one - just check what should be returned
 
 

_compress_array

  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
  Returns : String
  Args    : array reference, followed by an max value and direction (optional,
            default 1-unsigned),1 unsigned, any other is signed.
 
 

_uncompress_string

  Title   : _uncompress_string
  Usage   :
  Function: Will uncompress a string (vector of bytes) to create an array of
            real signed numbers (opposite to_compress_array)
  Returns : string, followed by an max value and
                    direction (optional, default 1-unsigned), 1 unsigned, any other is signed.
  Args    : array
 
 

get_compressed_freq

  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.
  Example :  my $strA=$self->get_compressed_freq('A');
  Returns :  String
  Args    :  char
 
 

get_compressed_logs

  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.
  Example : my $strA=$self->get_compressed_logs('A');
  Returns : String
  Args    : char
 
 

sequence_match_weight

  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_vectors

  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