Bio/Matrix/PSM/PsmI.pm

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