/ 
bioperl-1.4
/ Bio::Matrix::PSM::SiteMatrix

NAME

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

SYNOPSIS

use Bio::Matrix::PSM::SiteMatrix;
# Create from memory by supplying probability matrix hash
# both as strings or arrays
# where $a,$c,$g and $t are either arrayref or string
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,
           -IC=>$ic,-e_val=>$score, -id=>$mid);
my $site=new Bio::Matrix::PSM::SiteMatrix(%param);
#Or get it from a file:
use Bio::Matrix::PSM::IO;
my $psmIO= new Bio::Matrix::PSM::IO(-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 highest probability or N if prob is too low
my $consensus=$site->consensus;

#Getting/using regular expression
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 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 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.

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://bio.perl.org/MailList.html     - About the mailing lists

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 email or the web:

bioperl-bugs@bio.perl.org
http://bugzilla.bioperl.org/

AUTHOR - Stefan Kirov

Email skirov@utk.edu

APPENDIX

new

 Title   : new
 Usage   : my $site=new Bio::Matrix::PSM::SiteMatrix(-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.
 Example :
 Returns :  Bio::Matrix::PSM::SiteMatrix object
 Args    :  hash

_calculate_consensus

Title   : _calculate_consensus
Usage   :
Function: Internal stuff
Throws  :
Example :
Returns :
Args    :

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
Throws  :
Example :
Returns : hash (pA,pC,pG,pT,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
Throws  :
Example :
Returns : integer
Args    : integer

e_val

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

IC

Title   : IC
Usage   :
Function: Information content
Throws  :
Example :
Returns : real number
Args    : none

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

consensus

Title   : consensus
Usage   :
Function: Returns the consensus
Throws  :
Example :
Returns : string
Args    :

width

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

IUPAC

Title   : IUPAC
Usage   :
Function: Returns IUPAC compliant consensus
Throws  :
Example :
Returns : string
Args    :

_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)

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}

get_array

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

id

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

regexp

Title   : regexp
Usage   :
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   :
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