| 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 | 34 | $Bio::Tools::AnalysisResult::VERSION = '1.7.8'; | |||||||||
| 108 | 34 | ▶ | use strict; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 109 | |||||||||||
| 110 | 34 | ▶ | use base qw(Bio::Root::Root Bio::SeqAnalysisParserI Bio::AnalysisResultI Bio::Root::IO); | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 111 | |||||||||||
| 112 | 22 | ▶ | sub new { | ||||||||
|
Subroutine
new: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||
| 113 | 22 | my ($class, @args) = @_; | |||||||||
| 114 | 22 | my $self = $class->SUPER::new(@args); | |||||||||
| 115 | 22 | $self->_initialize(@args); | |||||||||
| 116 | 22 | return $self; | |||||||||
| 117 | } | ||||||||||
| 118 | |||||||||||
| 119 | 22 | ▶ | sub _initialize { | ||||||||
|
Subroutine
_initialize: called CC=1 SCAR=0.0
| |||||||||||
| 120 | 22 | my($self,@args) = @_; | |||||||||
| 121 | |||||||||||
| 122 | 22 | my $make = $self->SUPER::_initialize(@args); | |||||||||
| 123 | |||||||||||
| 124 | 22 | $self->_initialize_state(@args); | |||||||||
| 125 | 22 | 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 | 22 | ▶ | sub _initialize_state { | ||||||||
|
Subroutine
_initialize_state: called CC=1 SCAR=0.0
| |||||||||||
| 166 | 22 | my ($self,@args) = @_; | |||||||||
| 167 | |||||||||||
| 168 | 22 | $self->close(); | |||||||||
| 169 | 22 | $self->_initialize_io(@args); | |||||||||
| 170 | |||||||||||
| 171 | 22 | $self->{'_analysis_sbjct'} = undef; | |||||||||
| 172 | 22 | $self->{'_analysis_query'} = undef; | |||||||||
| 173 | 22 | $self->{'_analysis_prog'} = undef; | |||||||||
| 174 | 22 | $self->{'_analysis_progVersion'} = undef; | |||||||||
| 175 | 22 | $self->{'_analysis_date'} = undef; | |||||||||
| 176 | |||||||||||
| 177 | 22 | 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 | 0 | ▶ | sub parse { | ||||||||
|
Subroutine
parse: not called CC=3 SCAR=24.8
Pod
undocumented
| |||||||||||
| 206 | 0 | my ($self, @args) = @_; | |||||||||
| 207 | |||||||||||
| 208 | 0 | my ($input, $params, $method) = | |||||||||
| 209 | $self->_rearrange([qw(INPUT | ||||||||||
| 210 | PARAMS | ||||||||||
| 211 | METHOD | ||||||||||
| 212 | )], | ||||||||||
| 213 | @args); | ||||||||||
| 214 | |||||||||||
| 215 | # initialize with new input | ||||||||||
| 216 | 0 | ▶ | if($params) { | ||||||||
|
Branch: 1 branch
| |||||||||||
| 217 | 0 | $self->_initialize_state('-input' => $input, @$params); | |||||||||
| 218 | } else { | ||||||||||
| 219 | 0 | $self->_initialize_state('-input' => $input); | |||||||||
| 220 | } | ||||||||||
| 221 | 0 | ▶ | $self->analysis_method($method) if $method; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 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 | 2 | ▶ | sub analysis_query { | ||||||||
|
Subroutine
analysis_query: called CC=2 SCAR=7.6
Pod
documented
| |||||||||||
| 237 | 2 | my ($self, $obj) = @_; | |||||||||
| 238 | 2 | ▶ | if($obj) { | ||||||||
|
Branch: 1 branch
| |||||||||||
| 239 | 0 | $self->{'_analysis_query'} = $obj; | |||||||||
| 240 | } | ||||||||||
| 241 | 2 | 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 | 5 | ▶ | sub analysis_subject { | ||||||||
|
Subroutine
analysis_subject: called CC=2 SCAR=7.0
Pod
documented
| |||||||||||
| 260 | #--------------- | ||||||||||
| 261 | 5 | my ($self, $sbjct_obj) = @_; | |||||||||
| 262 | 5 | ▶ | if($sbjct_obj) { | ||||||||
|
Branch: 1 branch
| |||||||||||
| 263 | 5 | $self->{'_analysis_sbjct'} = $sbjct_obj; | |||||||||
| 264 | } | ||||||||||
| 265 | 5 | 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 | 3 | ▶ | sub analysis_date { | ||||||||
|
Subroutine
analysis_date: called CC=2 SCAR=6.9
Pod
documented
| |||||||||||
| 281 | 3 | my ($self, $date) = @_; | |||||||||
| 282 | 3 | ▶ | if($date) { | ||||||||
|
Branch: 1 branch
| |||||||||||
| 283 | 2 | $self->{'_analysis_date'} = $date; | |||||||||
| 284 | } | ||||||||||
| 285 | 3 | 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 | 134 | ▶ | sub analysis_method { | ||||||||
|
Subroutine
analysis_method: called CC=2 SCAR=6.9
Pod
documented
| |||||||||||
| 302 | #------------- | ||||||||||
| 303 | 134 | my ($self, $method) = @_; | |||||||||
| 304 | 134 | ▶ | if($method) { | ||||||||
|
Branch: 1 branch
| |||||||||||
| 305 | 14 | $self->{'_analysis_prog'} = $method; | |||||||||
| 306 | } | ||||||||||
| 307 | 134 | 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 | 8 | ▶ | sub analysis_method_version { | ||||||||
|
Subroutine
analysis_method_version: called CC=2 SCAR=6.9
Pod
documented
| |||||||||||
| 322 | #--------------------- | ||||||||||
| 323 | 8 | my ($self, $version) = @_; | |||||||||
| 324 | 8 | ▶ | if($version) { | ||||||||
|
Branch: 1 branch
| |||||||||||
| 325 | 7 | $self->{'_analysis_progVersion'} = $version; | |||||||||
| 326 | } | ||||||||||
| 327 | 8 | return $self->{'_analysis_progVersion'}; | |||||||||
| 328 | } | ||||||||||
| 329 | |||||||||||
| 330 | |||||||||||
| 331 | 34 | 1; | |||||||||