Bio/Factory/SeqAnalysisParserFactory.pm

   1 #
   2 # BioPerl module for Bio::Factory::SeqAnalysisParserFactory
   3 #
   4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   5 #
   6 # Cared for by Jason Stajich <jason@bioperl.org>,
   7 # and Hilmar Lapp <hlapp@gmx.net>
   8 #
   9 # Copyright Jason Stajich, Hilmar Lapp
  10 #
  11 # You may distribute this module under the same terms as perl itself
  12
  13 # POD documentation - main docs before the code
  14
  15 =head1 NAME
  16
  17 Bio::Factory::SeqAnalysisParserFactory - class capable of creating
  18 SeqAnalysisParserI compliant parsers
  19
  20 =head1 SYNOPSIS
  21
  22     # initialize an object implementing this interface, e.g.
  23     $factory = Bio::Factory::SeqAnalysisParserFactory->new();
  24     # find out the methods it knows about
  25     print "registered methods: ",
  26           join(', ', keys %{$factory->driver_table}), "\n";
  27     # obtain a parser object
  28     $parser = $factory->get_parser(-input=>$inputobj,
  29                                    -params=>[@params],
  30                                    -method => $method);
  31     # $parser is an object implementing Bio::SeqAnalysisParserI
  32     # annotate sequence with features produced by parser
  33     while(my $feat = $parser->next_feature()) {
  34         $seq->add_SeqFeature($feat);
  35     }
  36
  37 =head1 DESCRIPTION
  38
  39 This is a factory class capable of instantiating SeqAnalysisParserI
  40 implementing parsers.
  41
  42 The concept behind this class and the interface it implements
  43 (Bio::Factory::SeqAnalysisParserFactoryI) is a generic analysis result
  44 parsing in high-throughput automated sequence annotation
  45 pipelines. See Bio::SeqAnalysisParserI for more documentation of this
  46 concept.
  47
  48 You can always find out the methods an instance of this class knows
  49 about by the way given in the SYNOPSIS section. By default, and
  50 assuming that the documentation is up-to-date, this will comprise of
  51 genscan, mzef, estscan, blast, hmmer, gff, and sim4 (all
  52 case-insensitive).
  53
  54 =head1 FEEDBACK
  55
  56 =head2 Mailing Lists
  57
  58 User feedback is an integral part of the evolution of this
  59 and other Bioperl modules. Send your comments and suggestions preferably
  60  to one of the Bioperl mailing lists.
  61 Your participation is much appreciated.
  62
  63   bioperl-l@bioperl.org                  - General discussion
  64   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  65
  66 =head2 Support
  67
  68 Please direct usage questions or support issues to the mailing list:
  69
  70 I<bioperl-l@bioperl.org>
  71
  72 rather than to the module maintainer directly. Many experienced and
  73 reponsive experts will be able look at the problem and quickly
  74 address it. Please include a thorough description of the problem
  75 with code and data examples if at all possible.
  76
  77 =head2 Reporting Bugs
  78
  79 Report bugs to the Bioperl bug tracking system to help us keep track
  80 the bugs and their resolution.  Bug reports can be submitted via the
  81 web:
  82
  83   https://github.com/bioperl/bioperl-live/issues
  84
  85 =head1 AUTHOR - Hilmar Lapp, Jason Stajich
  86
  87 Email Hilmar Lapp E<lt>hlapp@gmx.netE<gt>, Jason Stajich E<lt>jason@bioperl.orgE<gt>
  88
  89 =head1 APPENDIX
  90
  91 The rest of the documentation details each of the object
  92 methods. Internal methods are usually preceded with a _
  93
  94 =cut
  95
  96 package Bio::Factory::SeqAnalysisParserFactory;
  97 use strict;
  98
  99
 100 use base qw(Bio::Factory::DriverFactory Bio::Factory::SeqAnalysisParserFactoryI);
 101
 102 BEGIN {
 103     Bio::Factory::DriverFactory->register_driver
 104         (
 105          "genscan"   => "Bio::Tools::Genscan",
 106          "mzef"      => "Bio::Tools::MZEF",
 107          "estscan"   => "Bio::Tools::ESTScan",
 108          "hmmer"     => "Bio::Tools::HMMER::Result",
 109          "gff"       => "Bio::Tools::GFF",
 110          "sim4"      => "Bio::Tools::Sim4::Results",
 111          "epcr"      => "Bio::Tools::EPCR",
 112          "exonerate" => "Bio::Tools::Exonerate",
 113          );
 114 }
 115
 116 sub new {
 117     my ($class, @args) = @_;
 118     my $self = $class->SUPER::new(@args);
 119
 120     # no per-object initialization right now - registration of default drivers
 121     # is only done once when the module is loaded
 122     return $self;
 123 }
 124
 125 =head2 get_parser
 126
 127  Title   : get_parser
 128  Usage   : $factory->get_parser(-input=>$inputobj,
 129                                 [ -params=>[@params] ],
 130                                 -method => $method)
 131  Function: Creates and returns a parser object for the given input and method.
 132            Both file names and streams (filehandles) are allowed.
 133
 134            Parameters (-params argument) are passed on to the parser object
 135            and therefore are specific to the parser to be created.
 136  Example :
 137  Returns : A Bio::SeqAnalysisParserI implementing object. Exception if
 138            creation of the parser object fails.
 139  Args    : B<input>  - object/file where analysis results are coming from,
 140            B<params> - parameter to use when parsing/running analysis
 141            B<method> - method of analysis
 142
 143 =cut
 144
 145 sub get_parser {
 146     my ($self, @args) = @_;
 147     my $parser;
 148     my $module;
 149
 150     my ($input, $params, $method) =
 151         $self->_rearrange([qw(INPUT PARAMS METHOD)], @args);
 152
 153     # retrieve module name for requested method
 154     $method = lc $method; # method is case-insensitive
 155     $module = $self->get_driver($method);
 156     if(! defined($module)) {
 157         $self->throw("Analysis parser driver for method $method not registered.");
 158     }
 159     # load module
 160     $self->_load_module($module); # throws an exception on failure to load
 161     # make sure parameters is not undef
 162     $params = [] if( !defined $params );
 163     # figure out input method (file or stream)
 164     my $inputmethod = '-file';
 165     if( ref($input) =~ /GLOB/i ) {
 166         $inputmethod = '-fh';
 167     }
 168     # instantiate parser and return the result
 169     $parser = $module->new($inputmethod => $input, @$params);
 170     if(! $parser->isa('Bio::SeqAnalysisParserI')) {
 171         $self->throw("Driver $module registered for method $method does not ".
 172                      "implement Bio::SeqAnalyisParserI. How come?");
 173     }
 174     return $parser;
 175 }
 176
 177
 178 =head2 register_driver
 179
 180  Title   : register_driver
 181  Usage   : $factory->register_driver("genscan", "Bio::Tools::Genscan");
 182  Function: Registers a driver a factory class should be able to instantiate.
 183
 184            This method can be called both as an instance and as a
 185            class method.
 186
 187  Returns :
 188  Args    : Key of the driver (string) and the module implementing the driver
 189            (string).
 190
 191 =cut
 192
 193 =head2 driver_table
 194
 195  Title   : driver_table
 196  Usage   : $table = $factory->driver_table();
 197  Function: Returns a reference to the hash table storing associations of
 198            methods with drivers.
 199
 200            You use this table to look up registered methods (keys) and
 201            drivers (values).
 202
 203            In this implementation the table is class-specific and
 204            therefore shared by all instances. You can override this in
 205            a derived class, but note that this method can be called
 206            both as an instance and a class method.
 207
 208            This will be the table used by the object internally. You
 209            should definitely know what you're doing if you modify the
 210            table's contents.  Modifications are shared by _all_
 211            instances, those present and those yet to be created.
 212
 213  Returns : A reference to a hash table.
 214  Args    :
 215
 216
 217 =cut
 218
 219
 220 1;