.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Bio::Matrix::PSM::SiteMatrixI 3pm"
.TH Bio::Matrix::PSM::SiteMatrixI 3pm "2020-10-28" "perl v5.30.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Bio::Matrix::PSM::SiteMatrixI \- SiteMatrixI implementation, holds a
position scoring matrix (or position weight matrix) and log\-odds
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  # You cannot use this module directly; see Bio::Matrix::PSM::SiteMatrix
\&  # for an example implementation
.Ve
.SH "DESCRIPTION"
.IX Header "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 \s-1DNA PSM\s0 consists of four vectors with frequencies {A,C,G,T}. This is
the minimum information you should provide to construct a \s-1PSM\s0 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 \s-1MEME\s0's compressed
representation of a matrix and it is quite useful when working with relational
\&\s-1DB.\s0 If arrays are provided as an input (references to arrays actually) they can
be any number, real or integer (frequency or count).
.PP
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.
.PP
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.
.PP
Summary of the methods I use most frequently (details below):
.PP
.Vb 10
\&  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.
.Ve
.PP
New methods, which might be of interest to anyone who wants to store \s-1PSM\s0 in a relational
database without creating an entry for each position is the ability to compress the
\&\s-1PSM\s0 vector into a string with losing usually less than 1% of the data.
this can be done with:
.PP
.Vb 1
\&  my $str=$matrix\->get_compressed_freq(\*(AqA\*(Aq);
.Ve
.PP
or
.PP
.Vb 1
\&  my $str=$matrix\->get_compressed_logs(\*(AqA\*(Aq);
.Ve
.PP
Loading from a database should be done with new, but is not yest implemented.
However you can still uncompress such string with:
.PP
.Vb 1
\&  my @arr=Bio::Matrix::PSM::_uncompress_string ($str,1,1); for PSM
.Ve
.PP
or
.PP
.Vb 1
\&  my @arr=Bio::Matrix::PSM::_uncompress_string ($str,1000,2); for log odds
.Ve
.SH "FEEDBACK"
.IX Header "FEEDBACK"
.SS "Mailing Lists"
.IX Subsection "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.
.PP
.Vb 2
\&  bioperl\-l@bioperl.org                  \- General discussion
\&  http://bioperl.org/wiki/Mailing_lists  \- About the mailing lists
.Ve
.SS "Support"
.IX Subsection "Support"
Please direct usage questions or support issues to the mailing list:
.PP
\&\fIbioperl\-l@bioperl.org\fR
.PP
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.
.SS "Reporting Bugs"
.IX Subsection "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:
.PP
.Vb 1
\&  https://github.com/bioperl/bioperl\-live/issues
.Ve
.SH "AUTHOR \- Stefan Kirov"
.IX Header "AUTHOR - Stefan Kirov"
Email skirov@utk.edu
.SH "APPENDIX"
.IX Header "APPENDIX"
.SS "calc_weight"
.IX Subsection "calc_weight"
.Vb 8
\& 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
.Ve
.SS "next_pos"
.IX Subsection "next_pos"
.Vb 3
\& 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
.Ve
.SS "curpos"
.IX Subsection "curpos"
.Vb 8
\& 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
.Ve
.SS "e_val"
.IX Subsection "e_val"
.Vb 7
\& Title   : e_val
\& Usage   : my $score=$site\->e_val;
\& Function: Gets/sets the e\-value
\& Throws  :
\& Example :
\& Returns : real number
\& Args    : real number
.Ve
.SS "consensus"
.IX Subsection "consensus"
.Vb 7
\& Title   : consensus
\& Usage   :
\& Function: Returns the consensus
\& Returns : string
\& Args    : (optional) threshold value 1 to 10, default 5
\&           \*(Aq5\*(Aq means the returned characters had a 50% or higher presence at
\&           their position
.Ve
.SS "accession_number"
.IX Subsection "accession_number"
.Vb 8
\& 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
.Ve
.SS "width"
.IX Subsection "width"
.Vb 7
\& Title   : width
\& Usage   : my $width=$site\->width;
\& Function: Returns the length of the site
\& Throws  :
\& Example :
\& Returns : number
\& Args    :
.Ve
.SS "\s-1IUPAC\s0"
.IX Subsection "IUPAC"
.Vb 7
\& Title   : IUPAC
\& Usage   : my $iupac_consensus=$site\->IUPAC;
\& Function: Returns IUPAC compliant consensus
\& Throws  :
\& Example :
\& Returns : string
\& Args    :
.Ve
.SS "\s-1IC\s0"
.IX Subsection "IC"
.Vb 7
\& Title   : IC
\& Usage   : my $ic=$site\->IC;
\& Function: Information content
\& Throws  :
\& Example :
\& Returns : real number
\& Args    : none
.Ve
.SS "get_string"
.IX Subsection "get_string"
.Vb 8
\& Title   : get_string
\& Usage   : my $freq_A=$site\->get_string(\*(AqA\*(Aq);
\& 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}
.Ve
.SS "id"
.IX Subsection "id"
.Vb 7
\& Title   : id
\& Usage   : my $id=$site\->id;
\& Function: Gets/sets the site id
\& Throws  :
\& Example :
\& Returns : string
\& Args    : string
.Ve
.SS "regexp"
.IX Subsection "regexp"
.Vb 8
\& 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    :
.Ve
.SS "regexp_array"
.IX Subsection "regexp_array"
.Vb 11
\& 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
.Ve
.SS "get_array"
.IX Subsection "get_array"
.Vb 7
\& Title   : get_array
\& Usage   : my @freq_A=$site\->get_array(\*(AqA\*(Aq);
\& Function: Returns an array with frequencies for a specified base
\& Throws  :
\& Example :
\& Returns : array
\& Args    : char
.Ve
.SS "_to_IUPAC"
.IX Subsection "_to_IUPAC"
.Vb 8
\& 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)
.Ve
.SS "_to_cons"
.IX Subsection "_to_cons"
.Vb 8
\& 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)
.Ve
.SS "_calculate_consensus"
.IX Subsection "_calculate_consensus"
.Vb 7
\& Title   : _calculate_consensus
\& Usage   :
\& Function: Internal stuff
\& Throws  :
\& Example :
\& Returns :
\& Args    :
.Ve
.SS "_compress_array"
.IX Subsection "_compress_array"
.Vb 9
\& 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.
.Ve
.SS "_uncompress_string"
.IX Subsection "_uncompress_string"
.Vb 9
\& 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
.Ve
.SS "get_compressed_freq"
.IX Subsection "get_compressed_freq"
.Vb 9
\& 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(\*(AqA\*(Aq);
\& Returns :  String
\& Args    :  char
.Ve
.SS "get_compressed_logs"
.IX Subsection "get_compressed_logs"
.Vb 8
\& 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(\*(AqA\*(Aq);
\& Returns :  String
\& Args    :  char
.Ve
.SS "sequence_match_weight"
.IX Subsection "sequence_match_weight"
.Vb 9
\& 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(\*(AqACGGATAG\*(Aq);
\& Returns :  Floating point
\& Args    :  string
.Ve
.SS "get_all_vectors"
.IX Subsection "get_all_vectors"
.Vb 8
\& 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
.Ve