lib/Bio/Tools/AnalysisResult.pm

   1 #
   2 # BioPerl module for Bio::Tools::AnalysisResult
   3 #
   4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   5 #
   6 # Cared for by Hilmar Lapp <hlapp-at-gmx.net>
   7 #
   8 # Copyright Hilmar Lapp
   9 #
  10 # You may distribute this module under the same terms as perl itself
  11
  12 # POD documentation - main docs before the code
  13
  14 =head1 NAME
  15
  16 Bio::Tools::AnalysisResult - Base class for analysis result objects and parsers
  17
  18 =head1 SYNOPSIS
  19
  20     # obtain a AnalysisResult derived object somehow
  21
  22     print "Method ", $result->analysis_method(),
  23           ", version ", $result->analysis_method_version(),
  24           ", performed on ", $result->analysis_date(), "\n";
  25
  26     # annotate a sequence utilizing SeqAnalysisParserI methods
  27     while($feat = $result->next_feature()) {
  28         $seq->add_SeqFeature($feat);
  29     }
  30     $result->close();
  31
  32     # query object, e.g. a Bio::SeqI implementing object
  33     $queryseq = $result->analysis_query();
  34
  35     # Subject of the analysis -- may be undefined. Refer to derived module
  36     # to find out what is returned.
  37     $subject = $result->analysis_subject();
  38
  39 =head1 DESCRIPTION
  40
  41 The AnalysisResult module is supposed to be the base class for modules
  42 encapsulating parsers and interpreters for the result of a analysis
  43 that was carried out with a query sequence.
  44
  45 The notion of an analysis represented by this base class is that of a
  46 unary or binary operator, taking either one query or a query and a
  47 subject and producing a result. The query is e.g. a sequence, and a
  48 subject is either a sequence, too, or a database of sequences.
  49
  50 This module also implements the Bio::SeqAnalysisParserI interface, and
  51 thus can be used wherever such an object fits.  See
  52 L<Bio::SeqAnalysisParserI>.  Developers will
  53 find a ready-to-use B<parse()> method, but need to implement
  54 B<next_feature()> in an inheriting class. Support for initialization
  55 with input file names and reading from streams is also ready to use.
  56
  57 Note that this module does not provide support for B<running> an
  58 analysis.  Rather, it is positioned in the subsequent parsing step
  59 (concerned with turning raw results into BioPerl objects).
  60
  61 =head1 FEEDBACK
  62
  63 =head2 Mailing Lists
  64
  65 User feedback is an integral part of the evolution of this and other
  66 Bioperl modules. Send your comments and suggestions preferably to one
  67 of the Bioperl mailing lists.  Your participation is much appreciated.
  68
  69   bioperl-l@bioperl.org                  - General discussion
  70   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  71
  72 =head2 Support
  73
  74 Please direct usage questions or support issues to the mailing list:
  75
  76 I<bioperl-l@bioperl.org>
  77
  78 rather than to the module maintainer directly. Many experienced and
  79 reponsive experts will be able look at the problem and quickly
  80 address it. Please include a thorough description of the problem
  81 with code and data examples if at all possible.
  82
  83 =head2 Reporting Bugs
  84
  85 Report bugs to the Bioperl bug tracking system to help us keep track
  86 the bugs and their resolution.  Bug reports can be submitted via the
  87 web:
  88
  89   https://github.com/bioperl/bioperl-live/issues
  90
  91 =head1 AUTHOR - Hilmar Lapp
  92
  93 Email hlapp-at-gmx.net
  94
  95 =head1 APPENDIX
  96
  97 The rest of the documentation details each of the object
  98 methods. Internal methods are usually preceded with a _
  99
 100 =cut
 101
 102
 103 # Let the code begin...
 104
 105
 106 package Bio::Tools::AnalysisResult;
 107
 108 use strict;
 109
 110 use base qw(Bio::Root::Root Bio::SeqAnalysisParserI Bio::AnalysisResultI Bio::Root::IO);
 111
 112 sub new {
 113     my ($class, @args) = @_;
 114     my $self = $class->SUPER::new(@args);
 115     $self->_initialize(@args);
 116     return $self;
 117 }
 118
 119 sub _initialize {
 120   my($self,@args) = @_;
 121
 122   my $make = $self->SUPER::_initialize(@args);
 123
 124   $self->_initialize_state(@args);
 125   return $make; # success - we hope!
 126 }
 127
 128 =head2 _initialize_state
 129
 130  Title   : _initialize_state
 131  Usage   : n/a; usually called by _initialize()
 132  Function: This method is for BioPerl B<developers> only, as indicated by the
 133            leading underscore in its name.
 134
 135            Performs initialization or reset of the state of this object. The
 136            difference to _initialize() is that it may be called at any time,
 137            and repeatedly within the lifetime of this object. B<Note>, however,
 138            that this is potentially dangerous in a multi-threading
 139            environment. In general, calling this method twice is discouraged
 140            for this reason.
 141
 142            This method is supposed to reset the state such that any 'history'
 143            is lost. State information that does not change during object
 144            lifetime is not considered as history, e.g. parent, name, etc shall
 145            not be reset. An inheriting object should only be concerned with
 146            state information it introduces itself, and for everything else
 147            call SUPER::_initialize_state(@args).
 148
 149            An example is parsing an input file: a state reset implies
 150            discarding any unread input, and the actual input itself, followed
 151            by setting the new input.
 152
 153            The argument syntax is the same as for L<new()|new> and L<_initialize()|_initialize>,
 154            i.e., named parameters following the -name=>$value convention.
 155            The following parameters are dealt with by the implementation
 156            provided here:
 157               -INPUT, -FH, -FILE
 158            (tags are case-insensitive).
 159  Example :
 160  Returns :
 161  Args    :
 162
 163 =cut
 164
 165 sub _initialize_state {
 166     my ($self,@args) = @_;
 167
 168     $self->close();
 169     $self->_initialize_io(@args);
 170
 171     $self->{'_analysis_sbjct'} = undef;
 172     $self->{'_analysis_query'} = undef;
 173     $self->{'_analysis_prog'} = undef;
 174     $self->{'_analysis_progVersion'} = undef;
 175     $self->{'_analysis_date'} = undef;
 176
 177     return 1;
 178 }
 179
 180 #  =head2 parse
 181 #
 182 #   Title   : parse
 183 #   Usage   : $obj->parse(-input=>$inputobj, [ -params=>[@params] ],
 184 #                      [ -method => $method ] )
 185 #   Function: Sets up parsing for feature retrieval from an analysis file,
 186 #             or object.
 187 #
 188 #             This method was originally required by SeqAnalysisParserI, but
 189 #             is now discouraged due to potential problems in a multi-
 190 #             threading environment (CORBA!). If called only once, it doesn't
 191 #             add any functionality to calling new() with the same
 192 #             parameters.
 193 #
 194 #             The implementation provided here calls automatically
 195 #             _initialize_state() and passes on -input=>$inputobj and
 196 #             @params as final arguments.
 197 #   Example :
 198 #   Returns : void
 199 #   Args    : B<input>  - object/file where analysis are coming from
 200 #          B<params> - parameter to use when parsing/running analysis
 201 #          B<method> - method of analysis
 202 #
 203 #  =cut
 204
 205 sub parse {
 206     my ($self, @args) = @_;
 207
 208     my ($input, $params, $method) =
 209         $self->_rearrange([qw(INPUT
 210                               PARAMS
 211                               METHOD
 212                               )],
 213                           @args);
 214
 215     # initialize with new input
 216     if($params) {
 217         $self->_initialize_state('-input' => $input, @$params);
 218     } else {
 219         $self->_initialize_state('-input' => $input);
 220     }
 221     $self->analysis_method($method) if $method;
 222 }
 223
 224 =head2 analysis_query
 225
 226  Usage     : $query_obj = $result->analysis_query();
 227  Purpose   : Set/Get the name of the query used to generate the result, that
 228              is, the entity on which the analysis was performed. Will mostly
 229              be a sequence object (Bio::PrimarySeq compatible).
 230  Argument  :
 231  Returns   : The object set before. Mostly a Bio::PrimarySeq compatible object.
 232
 233 =cut
 234
 235 #--------
 236 sub analysis_query {
 237     my ($self, $obj) = @_;
 238     if($obj) {
 239         $self->{'_analysis_query'} = $obj;
 240     }
 241     return $self->{'_analysis_query'};
 242 }
 243 #--------
 244
 245 =head2 analysis_subject
 246
 247  Usage     : $result->analyis_subject();
 248  Purpose   : Set/Get the subject of the analysis against which it was
 249              performed. For similarity searches it will probably be a database,
 250              and for sequence feature predictions (exons, promoters, etc) it
 251              may be a collection of models or homologous sequences that were
 252              used, or undefined.
 253  Returns   : The object that was set before, or undef.
 254  Argument  :
 255
 256 =cut
 257
 258 #---------------
 259 sub analysis_subject {
 260 #---------------
 261     my ($self, $sbjct_obj) = @_;
 262     if($sbjct_obj) {
 263         $self->{'_analysis_sbjct'} = $sbjct_obj;
 264     }
 265     return $self->{'_analysis_sbjct'};
 266 }
 267
 268
 269 =head2 analysis_date
 270
 271  Usage     : $result->analysis_date();
 272  Purpose   : Set/Get the date on which the analysis was performed.
 273  Returns   : String
 274  Argument  :
 275  Comments  :
 276
 277 =cut
 278
 279 #----------
 280 sub analysis_date {
 281     my ($self, $date) = @_;
 282     if($date) {
 283         $self->{'_analysis_date'} = $date;
 284     }
 285     return $self->{'_analysis_date'};
 286 }
 287 #----------
 288
 289 =head2 analysis_method
 290
 291  Usage     : $result->analysis_method();
 292  Purpose   : Set/Get the name of the sequence analysis method that was used
 293              to produce this result (BLASTP, FASTA, etc.). May also be the
 294              actual name of a program.
 295  Returns   : String
 296  Argument  : n/a
 297
 298 =cut
 299
 300 #-------------
 301 sub analysis_method {
 302 #-------------
 303     my ($self, $method) = @_;
 304     if($method) {
 305         $self->{'_analysis_prog'} = $method;
 306     }
 307     return $self->{'_analysis_prog'};
 308 }
 309
 310 =head2 analysis_method_version
 311
 312  Usage     : $result->analysis_method_version();
 313  Purpose   : Set/Get the version string of the analysis program.
 314            : (e.g., 1.4.9MP, 2.0a19MP-WashU).
 315  Returns   : String
 316  Argument  : n/a
 317
 318 =cut
 319
 320 #---------------------
 321 sub analysis_method_version {
 322 #---------------------
 323     my ($self, $version) = @_;
 324     if($version) {
 325         $self->{'_analysis_progVersion'} = $version;
 326     }
 327     return $self->{'_analysis_progVersion'};
 328 }
 329
 330
 331 1;