Bio/Matrix/PSM/Psm.pm

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