Bio/AnalysisResultI.pm

   1 #-----------------------------------------------------------------
   2 # $Id$
   3 #
   4 # BioPerl module Bio::AnalysisResultI
   5 #
   6 # Cared for by Steve Chervitz <sac@bioperl.org>
   7 #
   8 # Derived from Bio::Tools::AnalysisResult by Hilmar Lapp <hlapp@gmx.net>
   9 #
  10 # You may distribute this module under the same terms as perl itself
  11 #-----------------------------------------------------------------
  12
  13 # POD documentation - main docs before the code
  14
  15 =head1 NAME
  16
  17 Bio::AnalysisResultI - Interface for analysis result objects
  18
  19 =head1 SYNOPSIS
  20
  21 Bio::AnalysisResultI defines an interface that must be implemented by
  22 a subclass. So you cannot create Bio::AnalysisResultI objects,
  23 only objects that inherit from Bio::AnalysisResultI.
  24
  25 =head1 DESCRIPTION
  26
  27 The AnalysisResultI module provides an interface for modules
  28 encapsulating the result of an analysis that was carried out with a
  29 query sequence and an optional subject dataset.
  30
  31 The notion of an analysis represented by this base class is that of a unary or
  32 binary operator, taking either one query or a query and a subject and producing
  33 a result. The query is e.g. a sequence, and a subject is either a sequence,
  34 too, or a database of sequences.
  35
  36 This interface defines methods to access analysis result data and does
  37 not impose any contraints on how the analysis result data is acquired.
  38
  39 Note that this module does not provide support for B<running> an analysis.
  40 Rather, it is positioned in the subsequent parsing step (concerned with
  41 turning raw results into BioPerl objects).
  42
  43 =head1 FEEDBACK
  44
  45 =head2 Mailing Lists
  46
  47 User feedback is an integral part of the evolution of this and other
  48 Bioperl modules. Send your comments and suggestions preferably to one
  49 of the Bioperl mailing lists.  Your participation is much appreciated.
  50
  51   bioperl-l@bioperl.org                  - General discussion
  52   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  53
  54 =head2 Reporting Bugs
  55
  56 Report bugs to the Bioperl bug tracking system to help us keep track
  57 the bugs and their resolution.  Bug reports can be submitted via the web:
  58
  59   http://bugzilla.open-bio.org/
  60
  61 =head1 AUTHOR - Steve Chervitz, Hilmar Lapp
  62
  63 Email sac@bioperl.org
  64 Email hlapp@gmx.net (author of Bio::Tools::AnalysisResult on which this module is based)
  65
  66 =head1 COPYRIGHT
  67
  68 Copyright (c) 2001 Steve Chervitz. All Rights Reserved.
  69
  70 =head1 DISCLAIMER
  71
  72 This software is provided "as is" without warranty of any kind.
  73
  74 =head1 APPENDIX
  75
  76 The rest of the documentation details each of the object
  77 methods. Internal methods are usually preceded with a _
  78
  79 =cut
  80
  81
  82 # Let the code begin...
  83
  84
  85 package Bio::AnalysisResultI;
  86 use strict;
  87
  88
  89 use base qw(Bio::Root::RootI);
  90
  91
  92 =head2 analysis_query
  93
  94  Usage     : $query_obj = $result->analysis_query();
  95  Purpose   : Get a Bio::PrimarySeqI-compatible object representing the entity
  96              on which the analysis was performed. Lacks sequence information.
  97  Argument  : n/a
  98  Returns   : A Bio::PrimarySeqI-compatible object without sequence information.
  99              The sequence will have display_id, description, moltype, and length data.
 100
 101 =cut
 102
 103 #---------------------
 104 sub analysis_query {
 105 #---------------------
 106     my ($self) = @_;
 107     $self->throw_not_implemented;
 108 }
 109
 110
 111 =head2 analysis_subject
 112
 113  Usage     : $obj = $result->analyis_subject();
 114  Purpose   : Get the subject of the analysis against which it was
 115              performed. For similarity searches it will probably be a database,
 116              and for sequence feature predictions (exons, promoters, etc) it
 117              may be a collection of models or homologous sequences that were
 118              used, or undefined.
 119  Returns   : An object of a type the depends on the implementation
 120              May also return undef for analyses that don\'t involve subjects.
 121  Argument  : n/a
 122  Comments  : Implementation of this method is optional.
 123              AnalysisResultI provides a default behavior of returning undef.
 124
 125 =cut
 126
 127 #---------------
 128 sub analysis_subject {
 129 #---------------
 130     my ($self) = @_;
 131     return;
 132 }
 133
 134 =head2 analysis_subject_version
 135
 136  Usage     : $vers = $result->analyis_subject_version();
 137  Purpose   : Get the version string of the subject of the analysis.
 138  Returns   : String or undef for analyses that don\'t involve subjects.
 139  Argument  : n/a
 140  Comments  : Implementation of this method is optional.
 141              AnalysisResultI provides a default behavior of returning undef.
 142
 143 =cut
 144
 145 #---------------
 146 sub analysis_subject_version {
 147 #---------------
 148     my ($self) = @_;
 149     return;
 150 }
 151
 152
 153 =head2 analysis_date
 154
 155  Usage     : $date = $result->analysis_date();
 156  Purpose   : Get the date on which the analysis was performed.
 157  Returns   : String
 158  Argument  : n/a
 159
 160 =cut
 161
 162 #---------------------
 163 sub analysis_date {
 164 #---------------------
 165     my ($self) = @_;
 166     $self->throw_not_implemented;
 167 }
 168
 169 =head2 analysis_method
 170
 171  Usage     : $meth = $result->analysis_method();
 172  Purpose   : Get the name of the sequence analysis method that was used
 173              to produce this result (BLASTP, FASTA, etc.). May also be the
 174              actual name of a program.
 175  Returns   : String
 176  Argument  : n/a
 177
 178 =cut
 179
 180 #-------------
 181 sub analysis_method {
 182 #-------------
 183     my ($self) = @_;
 184     $self->throw_not_implemented;
 185 }
 186
 187 =head2 analysis_method_version
 188
 189  Usage     : $vers = $result->analysis_method_version();
 190  Purpose   : Get the version string of the analysis program.
 191            : (e.g., 1.4.9MP, 2.0a19MP-WashU).
 192  Returns   : String
 193  Argument  : n/a
 194
 195 =cut
 196
 197 #---------------------
 198 sub analysis_method_version {
 199 #---------------------
 200     my ($self) = @_;
 201     $self->throw_not_implemented;
 202 }
 203
 204 =head2 next_feature
 205
 206  Title   : next_feature
 207  Usage   : $seqfeature = $obj->next_feature();
 208  Function: Returns the next feature available in the analysis result, or
 209            undef if there are no more features.
 210  Example :
 211  Returns : A Bio::SeqFeatureI implementing object, or undef if there are no
 212            more features.
 213  Args    : none
 214
 215 =cut
 216
 217 #---------------------
 218 sub next_feature {
 219 #---------------------
 220     my ($self);
 221     $self->throw_not_implemented;
 222 }
 223
 224
 225 1;