Bio/Assembly/IO.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::Assembly::IO
   4 #
   5 #   based on the Bio::SeqIO module
   6 #       by Ewan Birney <birney@ebi.ac.uk>
   7 #       and Lincoln Stein  <lstein@cshl.org>
   8 #
   9 # Copyright Robson Francisco de Souza
  10 #
  11 # You may distribute this module under the same terms as perl itself
  12 #
  13 # _history
  14
  15 # POD documentation - main docs before the code
  16
  17 =head1 NAME
  18
  19 Bio::Assembly::IO - Handler for Assembly::IO Formats
  20
  21 =head1 SYNOPSIS
  22
  23     use Bio::Assembly::IO;
  24
  25     $in  = Bio::Assembly::IO->new(-file=>"<inputfilename",
  26                                   -format=>'phrap');
  27     $out = Bio::Assembly::IO->new(-file=>">outputfilename",
  28                                   -format=>'phrap');
  29
  30     while ( my $scaffold = $in->next_assembly() ) {
  31        # do something with Bio::Assembly::Scaffold instance
  32        # ...
  33        $out->write_assembly(-scaffold => $scaffold);
  34     }
  35
  36     $in->close;
  37     $out->close;
  38
  39 =head1 DESCRIPTION
  40
  41 Bio::Assembly::IO is a handler module for formats in the Assembly::IO set
  42 (e.g. Bio::Assembly::IO::phrap).
  43
  44 =head1 FEEDBACK
  45
  46 =head2 Mailing Lists
  47
  48 User feedback is an integral part of the evolution of this and other
  49 Bioperl modules. Send your comments and suggestions preferably to the
  50 Bioperl mailing lists  Your participation is much appreciated.
  51
  52   bioperl-l@bioperl.org                  - General discussion
  53   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  54
  55 =head2 Reporting Bugs
  56
  57 Report bugs to the Bioperl bug tracking system to help us keep track
  58 the bugs and their resolution.  Bug reports can be submitted via the
  59 web:
  60
  61   http://bugzilla.open-bio.org/
  62
  63 =head1 AUTHOR
  64
  65 Robson Francisco de Souza
  66
  67 E-mail: rfsouza@citri.iq.usp.br
  68
  69 =head1 CONTRIBUTORS
  70
  71 #
  72
  73 =head1 APPENDIX
  74
  75 The rest of the documentation details each of the object
  76 methods. Internal methods are usually preceded with a _
  77
  78 =cut
  79
  80 package Bio::Assembly::IO;
  81
  82
  83 use strict;
  84
  85 use base qw(Bio::Root::Root Bio::Root::IO);
  86
  87 =head2 new
  88
  89  Title   : new
  90  Usage   : Bio::Assembly::IO->new(-file =>$filename,-format=>'format')
  91  Function: Returns a new assembly stream
  92  Returns : A Bio::Assembly::IO::Handler initialised
  93            with the appropriate format
  94  Args    : -file => $filename
  95            -format => format
  96
  97 =cut
  98
  99 sub new {
 100     my ($caller,@args) = @_;
 101     my $class = ref($caller) || $caller;
 102
 103     # or do we want to call SUPER on an object if $caller is an
 104     # object?
 105     if( $class =~ /Bio::Assembly::IO::(\S+)/ ) {
 106         my ($self) = $class->SUPER::new(@args);
 107         $self->_initialize(@args);
 108         return $self;
 109     } else {
 110
 111         my %param = @args;
 112         @param{ map { lc $_ } keys %param } = values %param; # lowercase keys
 113
 114         $class->throw("Need at least a file name to proceed!")
 115             unless (defined $param{'-file'} || defined $ARGV[0]);
 116
 117         my $format = $param{'-format'} ||
 118             $class->_guess_format( $param{-file} || $ARGV[0] );
 119         $format = "\L$format";  # normalize capitalization to lower case
 120
 121         # normalize capitalization
 122         return unless( $class->_load_format_module($format) );
 123         return "Bio::Assembly::IO::$format"->new(@args);
 124     }
 125 }
 126
 127 # _initialize is chained for all SeqIO classes
 128
 129 sub _initialize {
 130     my($self, @args) = @_;
 131     # initialize the IO part
 132     $self->_initialize_io(@args);
 133 }
 134
 135 =head2 next_assembly
 136
 137  Title   : next_assembly
 138  Usage   : $cluster = $stream->next_assembly()
 139  Function: Reads the next assembly object from the stream and returns it.
 140  Returns : a Bio::Assembly::ScaffoldI compliant object
 141  Args    : none
 142
 143 =cut
 144
 145 sub next_assembly {
 146    my ($self, $seq) = @_;
 147    $self->throw("Sorry, you cannot read from a generic Bio::Assembly::IO object.");
 148 }
 149
 150 =head2 write_assembly
 151
 152   Title   : write_assembly
 153   Usage   : $ass_io->write_assembly($assembly)
 154   Function: Write the assembly object in Phrap compatible ACE format
 155   Returns : 1 on success, 0 for error
 156   Args    : A Bio::Assembly::Scaffold object
 157
 158 =cut
 159
 160 sub write_assembly {
 161    shift->throw_not_implemented;
 162 }
 163
 164 =head2 _load_format_module
 165
 166  Title   : _load_format_module
 167  Usage   : *INTERNAL Assembly::IO stuff*
 168  Function: Loads up (like use) a module at run time on demand
 169  Example :
 170  Returns :
 171  Args    :
 172
 173 =cut
 174
 175 sub _load_format_module {
 176   my ($self,$format) = @_;
 177   my $module = "Bio::Assembly::IO::" . $format;
 178   my $ok;
 179
 180   eval {
 181       $ok = $self->_load_module($module);
 182   };
 183   if ( $@ ) {
 184     print STDERR <<END;
 185 $self: could not load $format - for more details on supported formats please see the Assembly::IO docs
 186 Exception $@
 187 END
 188   ;
 189   }
 190   return $ok;
 191 }
 192
 193 =head2 _guess_format
 194
 195  Title   : _guess_format
 196  Usage   : $obj->_guess_format($filename)
 197  Function: guess format based on file suffix
 198  Example :
 199  Returns : guessed format of filename (lower case)
 200  Args    :
 201  Notes   : formats that _filehandle() will guess includes
 202            only phrap, by now.
 203
 204 =cut
 205
 206 sub _guess_format {
 207    my $class = shift;
 208    my $arg   = shift;
 209
 210    return unless defined($arg);
 211    return 'ace' if ($arg =~ /\.ace\.\d+$/i);
 212    return 'phrap' if ($arg =~ /\.phrap\.out$/i);
 213 }
 214
 215 sub DESTROY {
 216     my $self = shift;
 217
 218     $self->close();
 219 }
 220
 221 # I need some direction on these!! The module works so I haven't fiddled with them!
 222 # Me neither! (rfsouza)
 223
 224 sub TIEHANDLE {
 225     my ($class,$val) = @_;
 226     return bless {'seqio' => $val}, $class;
 227 }
 228
 229 sub READLINE {
 230   my $self = shift;
 231   return $self->{'seqio'}->next_seq() unless wantarray;
 232   my (@list, $obj);
 233   push @list, $obj while $obj = $self->{'seqio'}->next_seq();
 234   return @list;
 235 }
 236
 237 sub PRINT {
 238   my $self = shift;
 239   $self->{'seqio'}->write_seq(@_);
 240 }
 241
 242 1;
 243