Bio/Matrix/PSM/PsmI.pm

   1 # $Id$
   2 #---------------------------------------------------------
   3 #ISA SiteMatrix, HAS InstanceSite
   4
   5 =head1 NAME
   6
   7 Bio::Matrix::PSM::PsmI - abstract interface to handler of site matricies
   8
   9 =head1 SYNOPSIS
  10
  11   use Bio::Matrix::PSM::IO;
  12
  13   # To get a Psm object from a file use the Psm parser:
  14   my $psmIO =  Bio::Matrix::PSM::IO->new(-format=>'meme', -file=>$file);
  15
  16   # Now go through all entities in the file with next_psm, which
  17   # returns a Psm object see Bio::Matrix::PSM::IO for detailed
  18   # documentation (matrix predictions or matrix sequence matches or
  19   # both):
  20
  21   while (my $psm=$psmIO->next_psm) {
  22    my %psm_header=$psm->header;
  23    my $ic=$psm_header{IC};
  24    my $sites=$psm_header{sites};
  25    my $width=$psm_header{width};
  26    my $score=$psm_header{e_val};
  27    my $IUPAC=$psm->IUPAC;
  28    my $instances=$psm->instances;
  29    foreach my $instance (@{$instances}) {
  30      my $id=$instance->primary_id;
  31      #Do something with the id
  32     }
  33    }
  34
  35   # or create from memmory:
  36   my $psm= Bio::Matrix::PSM::Psm->new( -pA=>\@pA,-pC=>\@pC,-pG=>\@pG,-pT=>\@pT,
  37                                       -id=>$id,
  38                                       -instances=>$instances, -e_val=>$e_val,
  39                                       -IC=>$ic, -width=>$width, -sites=>$sites)
  40
  41   # where pA through pG are the respective frequencies of the matrix (see also
  42   # Bio::Matrix::PSM::SiteMatrix), and everything else is self-explenatory,
  43   # except for
  44   #-instances (reference to an array of Bio::Matrix::PSM::InstanceSite objects)
  45   # which is documented bellow.
  46
  47 =head1 DESCRIPTION
  48
  49 Supposed to handle a combination of site matrices and/or their
  50 corresponding sequence matches (instances). This object inherits from
  51 Bio::Matrix::PSM::SiteMatrix, so you can use the respective
  52 methods. It may hold also an array of Bio::Matrix::PSM::InstanceSite
  53 object, but you will have to retrieve these through
  54 Bio::Matrix::PSM::Psm-E<gt>instances method (see below). To some extent
  55 this is an expanded SiteMatrix object, holding data from analysis that
  56 also deal with sequence matches of a particular matrix.
  57
  58 =head2 DESIGN ISSUES
  59
  60 This design is a bit of a compromise, so it might be a temporary
  61 solution I am mixing PSM with PSM sequence matches Though they are
  62 very closely related, I am not satisfied by the way this is
  63 implemented here.  Heikki suggested different objects when one has
  64 something like meme But does this mean we have to write a different
  65 objects for mast, meme, transfac, theiresias, etc.?  To me the best
  66 way is to return SiteMatrix object + arrray of InstanceSite objects
  67 and then mast will return undef for SiteMatrix and transfac will
  68 return undef for InstanceSite. Probably I cannot see some other design
  69 issues that might arise from such approach, but it seems more
  70 straightforward.  Hilmar does not like this beacause it is an
  71 exception from the general BioPerl rules Should I leave this as an
  72 option?  Also the header rightfully belongs the driver object, and
  73 could be retrieved as hashes.  I do not think it can be done any other
  74 way, unless we want to create even one more object with very unclear
  75 content.
  76
  77 =head1 SEE ALSO
  78
  79 L<Bio::Matrix::PSM::SiteMatrix>, L<Bio::Matrix::PSM::IO::meme>,
  80 L<Bio::Matrix::PSM::IO::transfac>, L<Bio::Matrix::PSM::InstanceSite>
  81
  82
  83 =head1 FEEDBACK
  84
  85 =head2 Mailing Lists
  86
  87 User feedback is an integral part of the evolution of this and other
  88 Bioperl modules. Send your comments and suggestions preferably to one
  89 of the Bioperl mailing lists.  Your participation is much appreciated.
  90
  91   bioperl-l@bioperl.org                  - General discussion
  92   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  93
  94 =head2 Support
  95
  96 Please direct usage questions or support issues to the mailing list:
  97
  98 L<bioperl-l@bioperl.org>
  99
 100 rather than to the module maintainer directly. Many experienced and
 101 reponsive experts will be able look at the problem and quickly
 102 address it. Please include a thorough description of the problem
 103 with code and data examples if at all possible.
 104
 105 =head2 Reporting Bugs
 106
 107 Report bugs to the Bioperl bug tracking system to help us keep track
 108 the bugs and their resolution.  Bug reports can be submitted via the
 109 web:
 110
 111   http://bugzilla.open-bio.org/
 112
 113 =head1 AUTHOR - Stefan Kirov
 114
 115 Email skirov@utk.edu
 116
 117 =head1 DISCLAIMER
 118
 119 This software is provided "as is" without warranty of any kind.
 120
 121 =head1 APPENDIX
 122
 123 =cut
 124
 125
 126 # Let the code begin...
 127 package Bio::Matrix::PSM::PsmI;
 128 use Bio::Matrix::PSM::SiteMatrix;
 129 use Bio::Matrix::PSM::InstanceSite;
 130 use strict;
 131
 132 use base qw(Bio::Matrix::PSM::SiteMatrixI);
 133
 134 =head2 new
 135
 136  Title   : new
 137  Usage   : my $psm= Bio::Matrix::PSM::Psm->new( -pA=>\@pA,-pC=>\@pC,-pG=>\@pG,
 138                                                -pT=>\@pT,-id=>$id,
 139                                                -instances=>$instances,
 140                                                -e_val=>$e_val,
 141                                                -IC=>$ic, -width=>$width,
 142                                                -sites=>$sites)
 143  Function: Creates a new Bio::Matrix::PSM::Psm object
 144  Throws  :
 145  Example :
 146  Returns :  Bio::Matrix::PSM::Psm object
 147  Args    :  hash
 148
 149
 150 =cut
 151
 152 sub new {
 153      my $self = shift;
 154     $self->throw_not_implemented();
 155 }
 156
 157
 158 =head2 instances
 159
 160  Title   : instances
 161  Usage   :   my @instances=@{$psm->instances};
 162  Function: Gets/sets the instances (Bio::Matrix::PSM::InstanceSite objects)
 163             associated with the Psm object
 164  Throws  :
 165  Example :
 166  Returns :  array reference (Bio::Matrix::PSM::InstanceSite objects)
 167  Args    :  array reference (Bio::Matrix::PSM::InstanceSite objects)
 168
 169 =cut
 170
 171 sub instances {
 172     my $self = shift;
 173     $self->throw_not_implemented();
 174 }
 175
 176
 177 =head2 matrix
 178
 179  Title   :  matrix
 180  Usage   :  my $matrix=$psm->matrix;
 181  Function:  Gets/sets the SiteMatrix related information
 182  Throws  :
 183  Example :
 184  Returns :  Bio::Matrix::PSM::SiteMatrix objects
 185  Args    :  Bio::Matrix::PSM::SiteMatrix objects
 186
 187 =cut
 188
 189 sub matrix {
 190     my $self = shift;
 191     $self->throw_not_implemented();
 192 }
 193
 194 =head2 header
 195
 196  Title   : header
 197  Usage   :  my %header=$psm->header;
 198             my $ic=$psm->header('IC');
 199  Function: Gets the general information, common for most files, dealing
 200            with PSM such as information content (IC), score (e-value,
 201            etc.), number of sites (sites) and width. This list may
 202            expand. The current list should be in
 203            @Bio::Matrix::PSM::Psm::HEADER. Returns undef if an argument
 204            is supplied that is not in @Bio::Matrix::PSM::meme::HEADER.
 205  Throws  :
 206  Example :
 207  Returns :  hash or string
 208  Args    :  string (IC, e_val...)
 209
 210 =cut
 211
 212 sub header {
 213     my $self = shift;
 214     $self->throw_not_implemented();
 215  }
 216
 217
 218 1;
 219