lib/Bio/Network/IO.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::Network::IO
   4 #
   5 # You may distribute this module under the same terms as perl itself
   6 # POD documentation - main docs before the code
   7
   8 =head1  NAME
   9
  10 Bio::Network::IO - Class for reading and writing biological network data.
  11
  12 =head1  SYNOPSIS
  13
  14 This is a modules for reading and writing protein-protein interaction
  15 and creating networks from this data.
  16
  17   # Read protein interaction data in some format
  18   my $io = Bio::Network::IO->new(-file => 'bovine.xml',
  19                                  -format => 'psi25' );
  20   my $network = $io->next_network;
  21
  22 =head1  DESCRIPTION
  23
  24 This class is analagous to the SeqIO and AlignIO classes. To read in a
  25 file of a particular format, file and format are given as key/value
  26 pairs as arguments.  The Bio::Network::IO checks that the appropriate
  27 module is available and loads it.
  28
  29 At present only the DIP tab-delimited format and PSI XML format are
  30 supported.
  31
  32 =head1 METHODS
  33
  34 The main methods are:
  35
  36 =head2  $net = $io-E<gt>next_network
  37
  38 The next_network method does not imply that multiple networks are
  39 contained in a file, this is to maintain a consistent nomenclature
  40 with Bioperl methods like $seqio-E<gt>next_seq and $alnio-E<gt>next_aln.
  41
  42 =head2  $io-E<gt>write_network($network)
  43
  44 UNIMPLEMENTED.
  45
  46 =head1 REQUIREMENTS
  47
  48 To read from PSI XML you will need the XML::Twig module,
  49 available from CPAN.
  50
  51 =head1 FEEDBACK
  52
  53 =head2 Mailing Lists
  54
  55 User feedback is an integral part of the evolution of this and other
  56 Bioperl modules. Send your comments and suggestions preferably to one
  57 of the Bioperl mailing lists.
  58
  59 Your participation is much appreciated.
  60
  61   bioperl-l@bioperl.org                  - General discussion
  62   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  63
  64 =head2 Support
  65
  66 Please direct usage questions or support issues to the mailing list:
  67
  68 I<bioperl-l@bioperl.org>
  69
  70 rather than to the module maintainer directly. Many experienced and
  71 reponsive experts will be able look at the problem and quickly
  72 address it. Please include a thorough description of the problem
  73 with code and data examples if at all possible.
  74
  75 =head2 Reporting Bugs
  76
  77 Report bugs to the Bioperl bug tracking system to help us keep track
  78 the bugs and their resolution.  Bug reports can be submitted via the
  79 web:
  80
  81   http://bugzilla.open-bio.org/
  82
  83 =head1 AUTHORS
  84
  85 Brian Osborne bosborne at alum.mit.edu
  86 Richard Adams richard.adams@ed.ac.uk
  87
  88 =cut
  89
  90 package Bio::Network::IO;
  91 use strict;
  92 use base 'Bio::Root::IO';
  93 use vars qw(%DBNAMES);
  94
  95 # these values are used to standardize database names
  96 %DBNAMES = (
  97                                 DIP => "DIP",     # found in DIP files
  98                                 SWP => "UniProt", # found in DIP files
  99                                 PIR => "PIR",     # found in DIP files
 100                                 GI  => "GenBank"  # found id DIP files
 101                           );
 102
 103 =head2  new
 104
 105  Name       : new
 106  Usage      : $io = Bio::Network::IO->new(-file => 'myfile.xml',
 107                                           -format => 'psi25');
 108  Returns    : A Bio::Network::IO stream initialised to the appropriate format.
 109  Args       : Named parameters:
 110               -file      => $filename
 111               -format    => format
 112                                   -threshold => a confidence score for the interaction, optional
 113               -source    => optional database name (e.g. "intact")
 114               -verbose   => optional, set to 1 to get commentary
 115
 116 =cut
 117
 118 sub new {
 119         my ($caller, @args) = @_;
 120         my $class = ref($caller) || $caller;
 121         if ($class =~ /Bio::Network::IO::(\S+)/){
 122                 my $self = $class->SUPER::new(@args);
 123                 $self->_initialize_io(@args);
 124                 return $self;
 125         } else {
 126                 my %param = @args;
 127                 @param{ map { lc $_ } keys %param } = values %param;
 128                 if (!exists($param{'-format'})) {
 129                         Bio::Root::Root->throw("Must specify a valid format!");
 130                 }
 131                 my $format = $param{'-format'};
 132                 $format = "\L$format";
 133                 return undef unless ($class->_load_format_module($format));
 134                 return "Bio::Network::IO::$format"->new(@args);
 135         }
 136 }
 137
 138 =head2 next_network
 139
 140  Name       : next_network
 141  Usage      : $gr = $io->next_network
 142  Returns    : A Bio::Network::ProteinNet object.
 143  Args       : None
 144
 145 =cut
 146
 147 sub next_network {
 148    my ($self, $gr) = @_;
 149    $self->throw("Sorry, you cannot read from a generic Bio::Network::IO object.");
 150 }
 151
 152 =head2 write_network
 153
 154  Name       : write_network
 155  Usage      : $gr = $io->write_network($net).
 156  Args       : A Bio::Network::ProteinNet object.
 157  Returns    : None
 158
 159 =cut
 160
 161 sub write_network {
 162    my ($self, $gr) = @_;
 163    $self->throw("Sorry, you can't write from a generic Bio::NetworkIO object.");
 164 }
 165
 166 =head2 threshold
 167
 168  Name       : get or set a threshold
 169  Usage      : $io->threshold($val)
 170  Returns    : The threshold
 171  Args       : A number or none
 172
 173 =cut
 174
 175 sub threshold {
 176    my $self = shift;
 177    $self->{_th} = @_ if @_;
 178    return $self->{_th};
 179 }
 180
 181 =head2 verbose
 182
 183  Name       : get or set verbosity
 184  Usage      : $io->verbose(1)
 185  Returns    : The verbosity setting
 186  Args       : 1 or none
 187
 188 =cut
 189
 190 sub verbose {
 191    my $self = shift;
 192    $self->{_verbose} = @_ if @_;
 193    return $self->{_verbose};
 194 }
 195
 196 =head2 _load_format_module
 197
 198  Title   : _load_format_module
 199  Usage   : INTERNAL Bio::Network::IO stuff
 200  Function: Loads up (like use) a module at run time on demand
 201  Returns :
 202  Args    :
 203
 204 =cut
 205
 206 sub _load_format_module {
 207         my ($self, $format) = @_;
 208         my $module = "Bio::Network::IO::" . $format;
 209         my $ok;
 210
 211         eval {
 212                 $ok = $self->_load_module($module);
 213         };
 214         if ( $@ ) {
 215                 print STDERR <<END
 216 $self: $format cannot be found
 217 Exception $@
 218 For more information about the Bio::Network::IO system please see the Bio:Network::IO docs.
 219 END
 220 ;
 221         }
 222         return $ok;
 223 }
 224
 225 =head2 _initialize_io
 226
 227  Title   : _initialize_io
 228  Usage   : *INTERNAL Bio::Network::IO stuff*
 229  Function:
 230  Returns :
 231  Args    :
 232
 233 =cut
 234
 235 sub _initialize_io {
 236         my ($self, @args) = @_;
 237         $self->SUPER::_initialize_io(@args);
 238         my ($th,$verbose) = $self->_rearrange( [qw(THRESHOLD VERBOSE)], @args);
 239         $self->{'_th'} = $th;
 240         $self->{'_verbose'} = $verbose;
 241         return $self;
 242 }
 243
 244 =head2 _get_standard_name
 245
 246  Title   : _get_standard_name
 247  Usage   :
 248  Function: Returns some standard name for a database, uses global
 249            %DBNAMES
 250  Returns :
 251  Args    :
 252
 253 =cut
 254
 255 sub _get_standard_name {
 256         my ($self,$name) = @_;
 257         $DBNAMES{$name};
 258 }
 259
 260 1;
 261
 262 __END__