new¶

 Title   : new
 Usage   : my $pfm = TFBS::Matrix::PFM->new(%args)
 Function: constructor for the TFBS::Matrix::PFM object
 Returns : a new TFBS::Matrix::PFM object
 Args    : # you must specify either one of the following three:
 
           -matrix,      # reference to an array of arrays of integers
              #or
           -matrixstring,# a string containing four lines
                         # of tab- or space-delimited integers
              #or
           -matrixfile,  # the name of a file containing four lines
                         # of tab- or space-delimited integers
           #######
 
           -name,        # string, OPTIONAL
           -ID,          # string, OPTIONAL
           -class,       # string, OPTIONAL
           -tags         # an array reference, OPTIONAL
Warnings  : Warns if the matrix provided has columns with different
            sums. Columns with different sums contradict the usual
            origin of matrix data and, unless you are absolutely sure
            that column sums _should_ be different, it would be wise to
            check your matrices.

column_sum¶

 Title   : column_sum
 Usage   : my $nr_sequences = $pfm->column_sum()
 Function: calculates the sum of elements of one column
           (the first one by default) which normally equals the
           number of sequences used to derive the PFM. 
 Returns : the sum of elements of one column (an integer)
 Args    : columnn number (starting from 1), OPTIONAL - you DO NOT
           need to specify it unless you are dealing with a matrix

to_PWM¶

 Title   : to_PWM
 Usage   : my $pwm = $pfm->to_PWM()
 Function: converts a raw frequency matrix (a TFBS::Matrix::PFM object)
           to position weight matrix. At present it assumes uniform
           background distribution of nucleotide frequencies.
 Returns : a new TFBS::Matrix::PWM object
 Args    : none; in the future releases, it should be able to accept
           a user defined background probability of the four
           nucleotides

to_ICM¶

 Title   : to_ICM
 Usage   : my $icm = $pfm->to_ICM()
 Function: converts a raw frequency matrix (a TFBS::Matrix::PFM object)
           to information content matrix. At present it assumes uniform
           background distribution of nucleotide frequencies.
 Returns : a new TFBS::Matrix::ICM object
 Args    : -small_sample_correction # undef (default), 'schneider' or 'pseudocounts'

How a PFM is converted to ICM:

For a PFM element PFM[i,k], the probability without pseudocounts is estimated to be simply

  p[i,k] = PFM[i,k] / Z

where - Z equals the column sum of the matrix i.e. the number of motifs used to construct the PFM. - i is the column index (position in the motif) - k is the row index (a letter in the alphacer, here k is one of (A,C,G,T)

Here is how one normally calculates the pseudocount-corrected positional probability p'[i,j]:

  p'[i,k] = (PFM[i,k] + 0.25*sqrt(Z)) / (Z + sqrt(Z))

0.25 is for the flat distribution of nucleotides, and sqrt(Z) is the recommended pseudocount weight. In the general case,

  p'[i,k] = (PFM[i,k] + q[k]*B) / (Z + B)

where q[k] is the background distribution of the letter (nucleotide) k, and B an arbitrary pseudocount value or expression (for no pseudocounts B=0).

For a given position i, the deviation from random distribution in bits is calculated as (Baldi and Brunak eq. 1.9 (2ed) or 1.8 (1ed)):

- for an arbitrary alphabet of A letters:

  D[i] = log2(A) + sum_for_all_k(p[i,k]*log2(p[i,k]))

- special case for nucleotides (A=4)

  D[i] = 2 + sum_for_all_k(p[i,k]*log2(p[i,k]))

D[i] equals the information content of the position i in the motif. To calculate the entire ICM, you have to calculate the contrubution of each nucleotide at a position i to D[i], i.e.

ICM[i,k] = p'[i,k] * D[i]

draw_logo¶

 Title   : draw_logo
 Usage   : my $gd_image = $pfm->draw_logo()
 Function: draws a sequence logo; similar to the 
           method in TFBS::Matrix::ICM, but can automatically calculate
           error bars for drawing
 Returns : a GD image object (see documentation of GD module)
 Args    : many; PFM-specific options are:
           -small_sample_correction # One of 
                                    # "Schneider" (uses correction 
                                    #   described by Schneider et al.
                                    #   (Schneider t et al. (1986) J.Biol.Chem.
                                    # "pseudocounts" - standard pseudocount 
                                    #   correction,  more suitable for 
                                    #   PFMs with large r column sums
                                    # If the parameter is omitted, small
                                    # sample correction is not applied
           -draw_error_bars         # if true, adds error bars to each position
                                    # in the logo. To calculate the error bars,
                                    # it uses the -small_sample_connection
                                    # argument if explicitly set,  
                                    # or "Schneider" by default
For other args, see draw_logo entry in TFBS::Matrix::ICM documentation

add_PFM¶

 Title   : add_PFM
 Usage   : $pfm->add_PFM($another_pfm)
 Function: adds the values of $pnother_pfm matrix to $pfm
 Returns : reference to the updated $pfm object
 Args    : a TFBS::Matrix::PFM object

name¶

ID¶

class¶

matrix¶

length¶

revcom¶

rawprint¶

prettyprint¶

The above methods are common to all matrix objects. Please consult TFBS::Matrix to find out how to use them.