lib/Bio/Matrix/PSM/ProtPsm.pm

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