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

NAME

       Bio::Matrix::PSM::ProtMatrix - SiteMatrixI implementation, holds a position scoring matrix
       (or position weight matrix) with log-odds scoring information.

SYNOPSIS

          use Bio::Matrix::PSM::ProtMatrix;
          # Create from memory by supplying probability matrix hash both as strings or
          # arrays where the frequencies   Hash entries of the form lN refer to an array
          # of position-specific log-odds scores for amino acid N. Hash entries of the
          # form pN represent the position-specific probability of finding amino acid N.

          my %param = (
                    'id' => 'A. thaliana protein atp1',
                    '-e_val' => $score,
                    'lS' => [ '-2', '3', '-3', '2', '-3', '1', '1', '3' ],
                    'lF' => [ '-1', '-4', '0', '-5', '0', '-5', '-4', '-4' ],
                    'lT' => [ '-1', '1', '0', '1', '-2', '-1', '0', '1' ],
                    'lN' => [ '-3', '-1', '-2', '3', '-5', '5', '-2', '0' ],
                    'lK' => [ '-2', '0', '-3', '2', '-3', '2', '-3', '-1' ],
                    'lY' => [ '-2', '-3', '-3', '-4', '-3', '-4', '-4', '-4' ],
                    'lE' => [ '-3', '4', '-3', '2', '-4', '-2', '-3', '2' ],
                    'lV' => [ '0', '-2', '1', '-4', '1', '-4', '-1', '-3' ],
                    'lQ' => [ '-1', '0', '-2', '3', '-4', '1', '-3', '0' ],
                    'lM' => [ '8', '-3', '8', '-3', '1', '-3', '-3', '-3' ],
                    'lC' => [ '-2', '-3', '-3', '-4', '-3', '-4', '-3', '-3' ],
                    'lL' => [ '1', '-3', '1', '-4', '3', '-4', '-2', '-4' ],
                    'lA' => [ '-2', '1', '-2', '0', '-2', '-2', '2', '2' ],
                    'lW' => [ '-2', '-4', '-3', '-5', '-4', '-5', '-5', '-5' ],
                    'lP' => [ '-3', '-2', '-4', '-3', '-1', '-3', '6', '-3' ],
                    'lH' => [ '-2', '-2', '-3', '-2', '-5', '-2', '-2', '-3' ],
                    'lD' => [ '-4', '-1', '-3', '1', '-3', '-1', '-3', '4' ],
                    'lR' => [ '-2', '-1', '-3', '0', '-4', '4', '-4', '-3' ],
                    'lI' => [ '0', '-3', '0', '-4', '6', '-4', '-2', '-2' ],
                    'lG' => [ '-4', '-2', '-4', '-2', '-5', '-3', '-1', '-2' ],
                    'pS' => [ '0', '33', '0', '16', '1', '12', '11', '25' ],
                    'pF' => [ '0', '0', '2', '0', '3', '0', '0', '0' ],
                    'pT' => [ '0', '8', '7', '10', '1', '2', '7', '8' ],
                    'pN' => [ '0', '0', '2', '13', '0', '36', '1', '4' ],
                    'pK' => [ '0', '5', '0', '13', '1', '15', '0', '2' ],
                    'pY' => [ '0', '0', '0', '0', '0', '0', '0', '0' ],
                    'pE' => [ '0', '41', '1', '12', '0', '0', '0', '15' ],
                    'pV' => [ '0', '3', '9', '0', '2', '0', '3', '1' ],
                    'pQ' => [ '0', '0', '0', '15', '0', '4', '0', '3' ],
                    'pM' => [ '100', '0', '66', '0', '2', '0', '0', '0' ],
                    'pC' => [ '0', '0', '0', '0', '0', '0', '0', '0' ],
                    'pL' => [ '0', '0', '8', '0', '25', '0', '4', '0' ],
                    'pA' => [ '0', '10', '1', '9', '2', '0', '22', '16' ],
                    'pW' => [ '0', '0', '0', '0', '0', '0', '0', '0' ],
                    'pP' => [ '0', '0', '0', '0', '3', '1', '45', '0' ],
                    'pH' => [ '0', '0', '0', '0', '0', '0', '1', '0' ],
                    'pD' => [ '0', '0', '1', '7', '2', '2', '0', '22' ],
                    'pR' => [ '0', '0', '0', '3', '0', '27', '0', '0' ],
                    'pI' => [ '0', '0', '3', '0', '59', '1', '2', '3' ],
                    'pG' => [ '0', '0', '0', '1', '0', '0', '4', '1' ],
          );

          my $matrix = Bio::Matrix::PSM::ProtMatrix( %param );

          my $site = Bio::Matrix::PSM::ProtMatrix->new(%param);
          # Or get it from a file:
          use Bio::Matrix::PSM::IO;
          my $psmIO = Bio::Matrix::PSM::IO->new(-file => $file, -format => 'psi-blast');
          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::ProtMatrix object now
             my $matrix = $psm->matrix;
          }

          # Get a simple consensus, where alphabet is:
          # {A, R, N, D, C, Q, E, G, H, I, L, K, M, F, P, S, T, W, Y, V,}
          # choosing the highest probability or N if prob is too low
          my $consensus = $site->consensus;

          # Retrieving and using regular expressions:
          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

       ProtMatrix is designed to provide some basic methods when working with position scoring
       (weight) matrices related to protein sequences.  A protein PSM consists of 20 vectors with
       20 frequencies (one per amino acid per position).  This is the minimum information you
       should provide to construct a PSM object.  The vectors can be provided as strings with
       frequencies where the frequency is {0..a} and a=1. This is the way MEME 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 the constructor will check for positions that equal 0.  If such
       is found it will increase the count for all positions by one and recalculate the
       frequency.  Potential bug - if you are using frequencies and one of the positions is 0 it
       will change significantly.  However, you should never have frequency that equals 0.

       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 yet 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 - James Thompson

       Email tex@biosysadmin.com

APPENDIX

   new
        Title    : new
        Usage    : my $site = Bio::Matrix::PSM::ProtMatrix->new(
                      %probs,
                      %logs,
                      -IC    => $ic,
                      -e_val => $score,
                      -id    => $mid
                      -model => \%model
                   );
        Function : Creates a new Bio::Matrix::PSM::ProtMatrix object from memory
        Throws   : If inconsistent data for all vectors (all 20 amino acids) is
                      provided, if you mix input types (string vs array) or if a
                      position freq is 0.
        Example  :
        Returns  : Bio::Matrix::PSM::ProtMatrix object
        Args     : Hash references to log-odds scores and probabilities for
                   position-specific scoring info, e-value (optional), information
                   content (optional), id (optional), model for background distribution
                   of proteins (optional).

   alphabet
        Title    : Returns an array (or array reference if desired) to the alphabet
        Usage    :
        Function : Returns an array (or array reference) containing all of the
                   allowable characters for this matrix.
        Throws   :
        Example  :
        Returns  : Array or arrary reference.
        Args     :

   _calculate_consensus
        Title    : _calculate_consensus
        Usage    :
        Function : Calculates the consensus sequence for this matrix.
        Throws   :
        Example  :
        Returns  :
        Args     :

   next_pos
        Title    : next_pos
        Usage    :
        Function : Retrieves the next position features: frequencies for all 20 amino
                   acids, log-odds scores for all 20 amino acids at this position,
                   the main (consensus) letter at this position, the probability
                   for the consensus letter to occur at this position and the relative
                   current position as an integer.
        Throws   :
        Example  :
        Returns  : hash (or hash reference) (pA,pR,pN,pD,...,logA,logR,logN,logD,aa,prob,rel)
                   - pN entries represent the probability for amino acid N
                   to be at this position
                   - logN entries represent the log-odds score for having amino acid
                   N at this position
                   - aa is the consensus amino acid
                   - prob is the probability for the consensus amino acid to be at this
                   position
                   - rel is the relative index of the current position (integer)
        Args      : none

   curpos
        Title    : curpos
        Usage    :
        Function : Gets/sets the current position.
        Throws   :
        Example  :
        Returns  : Current position (integer).
        Args     : New position (integer).

   e_val
        Title    : e_val
        Usage    :
        Function : Gets/sets the e-value
        Throws   :
        Example  :
        Returns  :
        Args     : real number

   IC
        Title    : IC
        Usage    :
        Function : Position-specific information content.
        Throws   :
        Example  :
        Returns  : Information content for current position.
        Args     : Information content for current position.

   accession_number
        Title    : accession_number
        Usage    :
        Function: accession number, this will be unique id for the ProtMatrix object as
                   well for any other object, inheriting from ProtMatrix.
        Throws   :
        Example  :
        Returns  : New accession number (string)
        Args     : Accession number (string)

   consensus
        Title    : consensus
        Usage    :
        Function : Returns the consensus sequence for this PSM.
        Throws   : if supplied with thresold outisde 5..10 range
        Example  :
        Returns  : string
        Args     : (optional) threshold value 5 to 10 (corresponds to 50-100% at each 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}
        Example :
        Returns : string
        Args    : character {A,C,G,T}

   width
        Title    : width
        Usage    :
        Function : Returns the length of the site
        Throws   :
        Example  :
        Returns  : number
        Args     :

   get_array
        Title    : get_array
        Usage    :
        Function : Returns an array with frequencies for a specified amino acid.
        Throws   :
        Example  :
        Returns  : Array representing frequencies for specified amino acid.
        Args     : Single amino acid (character).

   get_logs_array
        Title    : get_logs_array
        Usage    :
        Function : Returns an array with log_odds for a specified base
        Throws   :
        Example  :
        Returns  : Array representing log-odds scores for specified amino acid.
        Args     : Single amino acid (character).

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

   regexp
        Title    : regexp
        Usage    :
        Function : Returns a case-insensitive regular expression which matches the
                   IUPAC convention.  X's in consensus sequence will match anything.
        Throws   :
        Example  :
        Returns  : string
        Args     : Threshold for calculating consensus sequence (number in range 0-100
                   representing a percentage). Threshold defaults to 20.

   regexp_array
        Title    : regexp_array
        Usage    :
        Function : Returns an array of position-specific regular expressions.
                    X's in consensus sequence will match anything.
        Throws   :
        Example  :
        Returns  : Array of position-specific regular expressions.
        Args     : Threshold for calculating consensus sequence (number in range 0-100
                   representing a percentage). Threshold defaults to 20.
        Notes    : Simply calls regexp method in list context.

   _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 max value and direction (optional, defaults to 1),
                    direction of 1 is unsigned, anything else 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 max value and direction (optional, defaults to 1),
                     direction of 1 is unsigned, anything else 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

   sequence_match_weight
        Title    : sequence_match_weight
        Usage    :
        Function :   This method will calculate the score of a match, based on the PSM
                     if such is associated with the matrix object. Returns undef if no
                     PSM 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

   _to_IUPAC
        Title   : _to_IUPAC
        Usage   :
        Function: Converts a single position to IUPAC compliant symbol and returns its probability.
                   Currently returns the most likely amino acid/probability combination.
        Throws  :
        Example :
        Returns : char, real number representing an amino acid and a probability.
        Args    : real numbers for all 20 amino acids (ordered by alphabet contained
                   in $self->{_alphabet}, minimum probability threshold.

   _to_cons
        Title   : _to_cons
        Usage   :
        Function: Converts a single position to simple consensus character and returns
                   its probability. Currently just calls the _to_IUPAC subroutine.
        Throws  :
        Example :
        Returns : char, real number
        Args    : real numbers for A,C,G,T (positional)

   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