Provided by: libbio-perl-perl_1.7.2-2_all bug

NAME

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

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 below):

         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:

         https://github.com/bioperl/bioperl-live/issues

AUTHOR - Stefan Kirov

       Email skirov@utk.edu

APPENDIX

   calc_weight
        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_pos
        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

   curpos
        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_val
        Title   : e_val
        Usage   : my $score=$site->e_val;
        Function: Gets/sets the e-value
        Throws  :
        Example :
        Returns : real number
        Args    : real number

   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

   accession_number
        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

   width
        Title   : width
        Usage   : my $width=$site->width;
        Function: Returns the length of the site
        Throws  :
        Example :
        Returns : number
        Args    :

   IUPAC
        Title   : IUPAC
        Usage   : my $iupac_consensus=$site->IUPAC;
        Function: Returns IUPAC compliant consensus
        Throws  :
        Example :
        Returns : string
        Args    :

   IC
        Title   : IC
        Usage   : my $ic=$site->IC;
        Function: Information content
        Throws  :
        Example :
        Returns : real number
        Args    : none

   get_string
        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}

   id
        Title   : id
        Usage   : my $id=$site->id;
        Function: Gets/sets the site id
        Throws  :
        Example :
        Returns : string
        Args    : string

   regexp
        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_array
        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_array
        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_IUPAC
        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_cons
        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_consensus
        Title   : _calculate_consensus
        Usage   :
        Function: Internal stuff
        Throws  :
        Example :
        Returns :
        Args    :

   _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 ;
        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_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)
        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_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. Improvement of the previous 0..a coding.
        Throws  :
        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.
        Throws  :
        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