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 use strict;
 108
 109 use base qw(Bio::Root::Root Bio::SeqAnalysisParserI Bio::AnalysisResultI Bio::Root::IO);
 110
 111 sub new {
 112     my ($class, @args) = @_;
 113     my $self = $class->SUPER::new(@args);
 114     $self->_initialize(@args);
 115     return $self;
 116 }
 117
 118 sub _initialize {
 119   my($self,@args) = @_;
 120
 121   my $make = $self->SUPER::_initialize(@args);
 122
 123   $self->_initialize_state(@args);
 124   return $make; # success - we hope!
 125 }
 126
 127 =head2 _initialize_state
 128
 129  Title   : _initialize_state
 130  Usage   : n/a; usually called by _initialize()
 131  Function: This method is for BioPerl B<developers> only, as indicated by the
 132            leading underscore in its name.
 133
 134            Performs initialization or reset of the state of this object. The
 135            difference to _initialize() is that it may be called at any time,
 136            and repeatedly within the lifetime of this object. B<Note>, however,
 137            that this is potentially dangerous in a multi-threading
 138            environment. In general, calling this method twice is discouraged
 139            for this reason.
 140
 141            This method is supposed to reset the state such that any 'history'
 142            is lost. State information that does not change during object
 143            lifetime is not considered as history, e.g. parent, name, etc shall
 144            not be reset. An inheriting object should only be concerned with
 145            state information it introduces itself, and for everything else
 146            call SUPER::_initialize_state(@args).
 147
 148            An example is parsing an input file: a state reset implies
 149            discarding any unread input, and the actual input itself, followed
 150            by setting the new input.
 151
 152            The argument syntax is the same as for L<new()|new> and L<_initialize()|_initialize>,
 153            i.e., named parameters following the -name=>$value convention.
 154            The following parameters are dealt with by the implementation
 155            provided here:
 156               -INPUT, -FH, -FILE
 157            (tags are case-insensitive).
 158  Example :
 159  Returns :
 160  Args    :
 161
 162 =cut
 163
 164 sub _initialize_state {
 165     my ($self,@args) = @_;
 166
 167     $self->close();
 168     $self->_initialize_io(@args);
 169
 170     $self->{'_analysis_sbjct'} = undef;
 171     $self->{'_analysis_query'} = undef;
 172     $self->{'_analysis_prog'} = undef;
 173     $self->{'_analysis_progVersion'} = undef;
 174     $self->{'_analysis_date'} = undef;
 175
 176     return 1;
 177 }
 178
 179 #  =head2 parse
 180 #
 181 #   Title   : parse
 182 #   Usage   : $obj->parse(-input=>$inputobj, [ -params=>[@params] ],
 183 #                      [ -method => $method ] )
 184 #   Function: Sets up parsing for feature retrieval from an analysis file,
 185 #             or object.
 186 #
 187 #             This method was originally required by SeqAnalysisParserI, but
 188 #             is now discouraged due to potential problems in a multi-
 189 #             threading environment (CORBA!). If called only once, it doesn't
 190 #             add any functionality to calling new() with the same
 191 #             parameters.
 192 #
 193 #             The implementation provided here calls automatically
 194 #             _initialize_state() and passes on -input=>$inputobj and
 195 #             @params as final arguments.
 196 #   Example :
 197 #   Returns : void
 198 #   Args    : B<input>  - object/file where analysis are coming from
 199 #          B<params> - parameter to use when parsing/running analysis
 200 #          B<method> - method of analysis
 201 #
 202 #  =cut
 203
 204 sub parse {
 205     my ($self, @args) = @_;
 206
 207     my ($input, $params, $method) =
 208         $self->_rearrange([qw(INPUT
 209                               PARAMS
 210                               METHOD
 211                               )],
 212                           @args);
 213
 214     # initialize with new input
 215     if($params) {
 216         $self->_initialize_state('-input' => $input, @$params);
 217     } else {
 218         $self->_initialize_state('-input' => $input);
 219     }
 220     $self->analysis_method($method) if $method;
 221 }
 222
 223 =head2 analysis_query
 224
 225  Usage     : $query_obj = $result->analysis_query();
 226  Purpose   : Set/Get the name of the query used to generate the result, that
 227              is, the entity on which the analysis was performed. Will mostly
 228              be a sequence object (Bio::PrimarySeq compatible).
 229  Argument  :
 230  Returns   : The object set before. Mostly a Bio::PrimarySeq compatible object.
 231
 232 =cut
 233
 234 #--------
 235 sub analysis_query {
 236     my ($self, $obj) = @_;
 237     if($obj) {
 238         $self->{'_analysis_query'} = $obj;
 239     }
 240     return $self->{'_analysis_query'};
 241 }
 242 #--------
 243
 244 =head2 analysis_subject
 245
 246  Usage     : $result->analyis_subject();
 247  Purpose   : Set/Get the subject of the analysis against which it was
 248              performed. For similarity searches it will probably be a database,
 249              and for sequence feature predictions (exons, promoters, etc) it
 250              may be a collection of models or homologous sequences that were
 251              used, or undefined.
 252  Returns   : The object that was set before, or undef.
 253  Argument  :
 254
 255 =cut
 256
 257 #---------------
 258 sub analysis_subject {
 259 #---------------
 260     my ($self, $sbjct_obj) = @_;
 261     if($sbjct_obj) {
 262         $self->{'_analysis_sbjct'} = $sbjct_obj;
 263     }
 264     return $self->{'_analysis_sbjct'};
 265 }
 266
 267
 268 =head2 analysis_date
 269
 270  Usage     : $result->analysis_date();
 271  Purpose   : Set/Get the date on which the analysis was performed.
 272  Returns   : String
 273  Argument  :
 274  Comments  :
 275
 276 =cut
 277
 278 #----------
 279 sub analysis_date {
 280     my ($self, $date) = @_;
 281     if($date) {
 282         $self->{'_analysis_date'} = $date;
 283     }
 284     return $self->{'_analysis_date'};
 285 }
 286 #----------
 287
 288 =head2 analysis_method
 289
 290  Usage     : $result->analysis_method();
 291  Purpose   : Set/Get the name of the sequence analysis method that was used
 292              to produce this result (BLASTP, FASTA, etc.). May also be the
 293              actual name of a program.
 294  Returns   : String
 295  Argument  : n/a
 296
 297 =cut
 298
 299 #-------------
 300 sub analysis_method {
 301 #-------------
 302     my ($self, $method) = @_;
 303     if($method) {
 304         $self->{'_analysis_prog'} = $method;
 305     }
 306     return $self->{'_analysis_prog'};
 307 }
 308
 309 =head2 analysis_method_version
 310
 311  Usage     : $result->analysis_method_version();
 312  Purpose   : Set/Get the version string of the analysis program.
 313            : (e.g., 1.4.9MP, 2.0a19MP-WashU).
 314  Returns   : String
 315  Argument  : n/a
 316
 317 =cut
 318
 319 #---------------------
 320 sub analysis_method_version {
 321 #---------------------
 322     my ($self, $version) = @_;
 323     if($version) {
 324         $self->{'_analysis_progVersion'} = $version;
 325     }
 326     return $self->{'_analysis_progVersion'};
 327 }
 328
 329
 330 1;