branch-1-6/Bio/Matrix/PSM/SiteMatrixI.pm

   1 # $Id$
   2
   3 =head1 NAME
   4
   5 Bio::Matrix::PSM::SiteMatrixI - SiteMatrixI implementation, holds a
   6 position scoring matrix (or position weight matrix) and log-odds
   7
   8 =head1 SYNOPSIS
   9
  10   # You cannot use this module directly; see Bio::Matrix::PSM::SiteMatrix
  11   # for an example implementation
  12
  13 =head1 DESCRIPTION
  14
  15 SiteMatrix is designed to provide some basic methods when working with position
  16 scoring (weight) matrices, such as transcription factor binding sites for
  17 example. A DNA PSM consists of four vectors with frequencies {A,C,G,T}. This is
  18 the minimum information you should provide to construct a PSM object. The
  19 vectors can be provided as strings with frequenciesx10 rounded to an int, going
  20 from {0..a} and 'a' represents the maximum (10). This is like MEME's compressed
  21 representation of a matrix and it is quite useful when working with relational
  22 DB. If arrays are provided as an input (references to arrays actually) they can
  23 be any number, real or integer (frequency or count).
  24
  25 When creating the object you can ask the constructor to make a simple pseudo
  26 count correction by adding a number (typically 1) to all positions (with the
  27 -correction option). After adding the number the frequencies will be
  28 calculated. Only use correction when you supply counts, not frequencies.
  29
  30 Throws an exception if: You mix as an input array and string (for example A
  31 matrix is given as array, C - as string). The position vector is (0,0,0,0). One
  32 of the probability vectors is shorter than the rest.
  33
  34 Summary of the methods I use most frequently (details bellow):
  35
  36   iupac - return IUPAC compliant consensus as a string
  37   score - Returns the score as a real number
  38   IC - information content. Returns a real number
  39   id - identifier. Returns a string
  40   accession - accession number. Returns a string
  41   next_pos - return the sequence probably for each letter, IUPAC
  42       symbol, IUPAC probability and simple sequence
  43   consenus letter for this position. Rewind at the end. Returns a hash.
  44   pos - current position get/set. Returns an integer.
  45   regexp - construct a regular expression based on IUPAC consensus.
  46       For example AGWV will be [Aa][Gg][AaTt][AaCcGg]
  47   width - site width
  48   get_string - gets the probability vector for a single base as a string.
  49   get_array - gets the probability vector for a single base as an array.
  50   get_logs_array - gets the log-odds vector for a single base as an array.
  51
  52 New methods, which might be of interest to anyone who wants to store PSM in a relational
  53 database without creating an entry for each position is the ability to compress the
  54 PSM vector into a string with losing usually less than 1% of the data.
  55 this can be done with:
  56
  57   my $str=$matrix->get_compressed_freq('A');
  58
  59 or
  60
  61   my $str=$matrix->get_compressed_logs('A');
  62
  63 Loading from a database should be done with new, but is not yest implemented.
  64 However you can still uncompress such string with:
  65
  66   my @arr=Bio::Matrix::PSM::_uncompress_string ($str,1,1); for PSM
  67
  68 or
  69
  70   my @arr=Bio::Matrix::PSM::_uncompress_string ($str,1000,2); for log odds
  71
  72 =head1 FEEDBACK
  73
  74 =head2 Mailing Lists
  75
  76 User feedback is an integral part of the evolution of this and other
  77 Bioperl modules. Send your comments and suggestions preferably to one
  78 of the Bioperl mailing lists.  Your participation is much appreciated.
  79
  80   bioperl-l@bioperl.org                  - General discussion
  81   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  82
  83 =head2 Support
  84
  85 Please direct usage questions or support issues to the mailing list:
  86
  87 I<bioperl-l@bioperl.org>
  88
  89 rather than to the module maintainer directly. Many experienced and
  90 reponsive experts will be able look at the problem and quickly
  91 address it. Please include a thorough description of the problem
  92 with code and data examples if at all possible.
  93
  94 =head2 Reporting Bugs
  95
  96 Report bugs to the Bioperl bug tracking system to help us keep track
  97 the bugs and their resolution.  Bug reports can be submitted via the
  98 web:
  99
 100   http://bugzilla.open-bio.org/
 101
 102 =head1 AUTHOR - Stefan Kirov
 103
 104 Email skirov@utk.edu
 105
 106 =head1 APPENDIX
 107
 108 =cut
 109
 110
 111 # Let the code begin...
 112
 113 package Bio::Matrix::PSM::SiteMatrixI;
 114
 115 # use strict;
 116 use base qw(Bio::Root::RootI);
 117
 118 =head2 calc_weight
 119
 120  Title   : calc_weight
 121  Usage   : $self->calc_weight({A=>0.2562,C=>0.2438,G=>0.2432,T=>0.2568});
 122  Function: Recalculates the PSM (or weights) based on the PFM (the frequency matrix)
 123            and user supplied background model.
 124  Throws  : if no model is supplied
 125  Example :
 126  Returns :
 127  Args    : reference to a hash with background frequencies for A,C,G and T
 128
 129 =cut
 130
 131 sub calc_weight {
 132   my $self = shift;
 133   $self->throw_not_implemented();
 134 }
 135
 136
 137 =head2 next_pos
 138
 139  Title   : next_pos
 140  Usage   : my %base=$site->next_pos;
 141  Function:
 142
 143            Retrieves the next position features: frequencies and weights for
 144            A,C,G,T, the main letter (as in consensus) and the
 145            probabilty for this letter to occur at this position and
 146            the current position
 147
 148  Throws  :
 149  Example :
 150  Returns : hash (pA,pC,pG,pT,lA,lC,lG,lT,base,prob,rel)
 151  Args    : none
 152
 153
 154 =cut
 155
 156 sub next_pos {
 157   my $self = shift;
 158   $self->throw_not_implemented();
 159 }
 160
 161 =head2 curpos
 162
 163  Title   : curpos
 164  Usage   : my $pos=$site->curpos;
 165  Function: Gets/sets the current position. Converts to 0 if argument is minus and
 166             to width if greater than width
 167  Throws  :
 168  Example :
 169  Returns : integer
 170  Args    : integer
 171
 172 =cut
 173
 174 sub curpos {
 175     my $self = shift;
 176    $self->throw_not_implemented();
 177 }
 178
 179 =head2 e_val
 180
 181  Title   : e_val
 182  Usage   : my $score=$site->e_val;
 183  Function: Gets/sets the e-value
 184  Throws  :
 185  Example :
 186  Returns : real number
 187  Args    : real number
 188
 189 =cut
 190
 191 sub e_val {
 192     my $self = shift;
 193     $self->throw_not_implemented();
 194 }
 195
 196 =head2 consensus
 197
 198  Title   : consensus
 199  Usage   :
 200  Function: Returns the consensus
 201  Returns : string
 202  Args    : (optional) threshold value 1 to 10, default 5
 203            '5' means the returned characters had a 50% or higher presence at
 204            their position
 205
 206 =cut
 207
 208 sub consensus {
 209   my $self = shift;
 210   $self->throw_not_implemented();
 211 }
 212
 213 =head2 accession_number
 214
 215  Title   : accession_number
 216  Usage   :
 217  Function: accession number, this will be unique id for the SiteMatrix object as
 218                         well for any other object, inheriting from SiteMatrix
 219  Throws  :
 220  Example :
 221  Returns : string
 222  Args    : string
 223
 224 =cut
 225
 226 sub accession_number {
 227   my $self = shift;
 228   $self->throw_not_implemented();
 229 }
 230
 231
 232 =head2 width
 233
 234  Title   : width
 235  Usage   : my $width=$site->width;
 236  Function: Returns the length of the site
 237  Throws  :
 238  Example :
 239  Returns : number
 240  Args    :
 241
 242 =cut
 243
 244 sub width {
 245   my $self = shift;
 246   $self->throw_not_implemented();
 247 }
 248
 249 =head2 IUPAC
 250
 251  Title   : IUPAC
 252  Usage   : my $iupac_consensus=$site->IUPAC;
 253  Function: Returns IUPAC compliant consensus
 254  Throws  :
 255  Example :
 256  Returns : string
 257  Args    :
 258
 259 =cut
 260
 261 sub IUPAC {
 262   my $self = shift;
 263   $self->throw_not_implemented();
 264 }
 265
 266 =head2 IC
 267
 268  Title   : IC
 269  Usage   : my $ic=$site->IC;
 270  Function: Information content
 271  Throws  :
 272  Example :
 273  Returns : real number
 274  Args    : none
 275
 276 =cut
 277
 278 sub IC {
 279 my $self=shift;
 280 $self->throw_not_implemented();
 281 }
 282
 283 =head2 get_string
 284
 285  Title   : get_string
 286  Usage   : my $freq_A=$site->get_string('A');
 287  Function: Returns given probability vector as a string. Useful if you want to
 288            store things in a rel database, where arrays are not first choice
 289  Throws  : If the argument is outside {A,C,G,T}
 290  Example :
 291  Returns : string
 292  Args    : character {A,C,G,T}
 293
 294 =cut
 295
 296 sub get_string {
 297  my $self=shift;
 298  $self->throw_not_implemented();
 299 }
 300
 301 =head2 id
 302
 303  Title   : id
 304  Usage   : my $id=$site->id;
 305  Function: Gets/sets the site id
 306  Throws  :
 307  Example :
 308  Returns : string
 309  Args    : string
 310
 311 =cut
 312
 313 sub id {
 314     my $self = shift;
 315     $self->throw_not_implemented();
 316 }
 317
 318 =head2 regexp
 319
 320  Title   : regexp
 321  Usage   : my $regexp=$site->regexp;
 322  Function: Returns a regular expression which matches the IUPAC convention.
 323            N will match X, N, - and .
 324  Throws  :
 325  Example :
 326  Returns : string
 327  Args    :
 328
 329 =cut
 330
 331 sub regexp {
 332  my $self=shift;
 333  $self->throw_not_implemented();
 334 }
 335
 336 =head2 regexp_array
 337
 338  Title   : regexp_array
 339  Usage   : my @regexp=$site->regexp;
 340  Function: Returns a regular expression which matches the IUPAC convention.
 341            N will match X, N, - and .
 342  Throws  :
 343  Example :
 344  Returns : array
 345  Args    :
 346  To do   : I have separated regexp and regexp_array, but
 347            maybe they can be rewritten as one - just check what
 348            should be returned
 349
 350 =cut
 351
 352 sub regexp_array {
 353  my $self=shift;
 354  $self->throw_not_implemented();
 355 }
 356
 357 =head2 get_array
 358
 359  Title   : get_array
 360  Usage   : my @freq_A=$site->get_array('A');
 361  Function: Returns an array with frequencies for a specified base
 362  Throws  :
 363  Example :
 364  Returns : array
 365  Args    : char
 366
 367 =cut
 368
 369 sub get_array {
 370   my $self=shift;
 371   $self->throw_not_implemented();
 372 }
 373
 374
 375 =head2 _to_IUPAC
 376
 377  Title   : _to_IUPAC
 378  Usage   :
 379  Function: Converts a single position to IUPAC compliant symbol and
 380             returns its probability. For rules see the implementation.
 381  Throws  :
 382  Example :
 383  Returns : char, real number
 384  Args    : real numbers for A,C,G,T (positional)
 385
 386 =cut
 387
 388 sub _to_IUPAC {
 389     my $self = shift;
 390     $self->throw_not_implemented();
 391 }
 392
 393 =head2 _to_cons
 394
 395  Title   : _to_cons
 396  Usage   :
 397  Function: Converts a single position to simple consensus character and
 398             returns its probability. For rules see the implementation,
 399  Throws  :
 400  Example :
 401  Returns : char, real number
 402  Args    : real numbers for A,C,G,T (positional)
 403
 404 =cut
 405
 406 sub _to_cons {
 407     my $self = shift;
 408     $self->throw_not_implemented();
 409 }
 410
 411
 412 =head2 _calculate_consensus
 413
 414  Title   : _calculate_consensus
 415  Usage   :
 416  Function: Internal stuff
 417  Throws  :
 418  Example :
 419  Returns :
 420  Args    :
 421
 422 =cut
 423
 424 sub _calculate_consensus {
 425     my $self = shift;
 426     $self->throw_not_implemented();
 427 }
 428
 429 =head2 _compress_array
 430
 431  Title   : _compress_array
 432  Usage   :
 433  Function:  Will compress an array of real signed numbers to a string (ie vector of bytes)
 434                         -127 to +127 for bi-directional(signed) and 0..255 for unsigned ;
 435  Throws  :
 436  Example :  Internal stuff
 437  Returns :  String
 438  Args    :  array reference, followed by an max value and
 439                         direction (optional, default 1-unsigned),1 unsigned, any other is signed.
 440
 441 =cut
 442
 443 sub _compress_array {
 444     my $self = shift;
 445     $self->throw_not_implemented();
 446 }
 447
 448 =head2 _uncompress_string
 449
 450  Title   : _uncompress_string
 451  Usage   :
 452  Function:  Will uncompress a string (vector of bytes) to create an array of real
 453             signed numbers (opposite to_compress_array)
 454  Throws  :
 455  Example :  Internal stuff
 456  Returns :  string, followed by an max value and
 457                         direction (optional, default 1-unsigned), 1 unsigned, any other is signed.
 458  Args    :  array
 459
 460 =cut
 461
 462 sub _uncompress_string {
 463     my $self = shift;
 464     $self->throw_not_implemented();
 465 }
 466
 467 =head2 get_compressed_freq
 468
 469  Title   : get_compressed_freq
 470  Usage   :
 471  Function:  A method to provide a compressed frequency vector. It uses one byte to
 472                         code the frequence for one of the probability vectors for one position.
 473                         Useful for relational database. Improvment of the previous 0..a coding.
 474  Throws  :
 475  Example :  my $strA=$self->get_compressed_freq('A');
 476  Returns :  String
 477  Args    :  char
 478
 479 =cut
 480
 481 sub get_compressed_freq {
 482     my $self = shift;
 483     $self->throw_not_implemented();
 484 }
 485
 486 =head2 get_compressed_logs
 487
 488  Title   : get_compressed_logs
 489  Usage   :
 490  Function:  A method to provide a compressed log-odd vector. It uses one byte to
 491                         code the log value for one of the log-odds vectors for one position.
 492  Throws  :
 493  Example :  my $strA=$self->get_compressed_logs('A');
 494  Returns :  String
 495  Args    :  char
 496
 497 =cut
 498
 499 sub get_compressed_logs {
 500     my $self = shift;
 501     $self->throw_not_implemented();
 502 }
 503
 504 =head2 sequence_match_weight
 505
 506  Title   : sequence_match_weight
 507  Usage   :
 508  Function:  This method will calculate the score of a match, based on the PWM
 509             if such is associated with the matrix object. Returns undef if no
 510              PWM data is available.
 511  Throws  :   if the length of the sequence is different from the matrix width
 512  Example :  my $score=$matrix->sequence_match_weight('ACGGATAG');
 513  Returns :  Floating point
 514  Args    :  string
 515
 516 =cut
 517
 518 sub sequence_match_weight {
 519     my $self = shift;
 520     $self->throw_not_implemented();
 521 }
 522
 523 =head2 get_all_vectors
 524
 525  Title   : get_all_vectors
 526  Usage   :
 527  Function:  returns all possible sequence vectors to satisfy the PFM under
 528             a given threshold
 529  Throws  :  If threshold outside of 0..1 (no sense to do that)
 530  Example :  my @vectors=$self->get_all_vectors(4);
 531  Returns :  Array of strings
 532  Args    :  (optional) floating
 533
 534 =cut
 535
 536 sub get_all_vectors {
 537  my $self = shift;
 538     $self->throw_not_implemented();
 539 }
 540 1;