Bio/Matrix/PSM/Psm.pm

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