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 L<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 =cut
 116
 117 sub new {
 118         my ($caller, @args) = @_;
 119         my $class = ref($caller) || $caller;
 120         if ($class =~ /Bio::Network::IO::(\S+)/){
 121                 my $self = $class->SUPER::new(@args);
 122                 $self->_initialize_io(@args);
 123                 return $self;
 124         } else {
 125                 my %param = @args;
 126                 @param{ map { lc $_ } keys %param } = values %param;
 127                 if (!exists($param{'-format'})) {
 128                         Bio::Root::Root->throw("Must specify a valid format!");
 129                 }
 130                 my $format = $param{'-format'};
 131                 $format = "\L$format";
 132                 return undef unless ($class->_load_format_module($format));
 133                 return "Bio::Network::IO::$format"->new(@args);
 134         }
 135 }
 136
 137 =head2 next_network
 138
 139  Name       : next_network
 140  Usage      : $gr = $io->next_network
 141  Returns    : A Bio::Network::ProteinNet object.
 142  Args       : None
 143
 144 =cut
 145
 146 sub next_network {
 147    my ($self, $gr) = @_;
 148    $self->throw("Sorry, you cannot read from a generic Bio::Network::IO object.");
 149 }
 150
 151 =head2 write_network
 152
 153  Name       : write_network
 154  Usage      : $gr = $io->write_network($net).
 155  Args       : A Bio::Network::ProteinNet object.
 156  Returns    : None
 157
 158 =cut
 159
 160 sub write_network {
 161    my ($self, $gr) = @_;
 162    $self->throw("Sorry, you can't write from a generic Bio::NetworkIO object.");
 163 }
 164
 165 =head2 threshold
 166
 167  Name       : get or set a threshold
 168  Usage      : $io->threshold($val)
 169  Returns    : The threshold
 170  Args       : A number or none
 171
 172 =cut
 173
 174 sub threshold {
 175    my $self = shift;
 176    $self->{_th} = @_ if @_;
 177    return $self->{_th};
 178 }
 179
 180 =head2 verbose
 181
 182  Name       : get or set verbosity
 183  Usage      : $io->verbose(1)
 184  Returns    : The verbosity setting
 185  Args       : 1 or none
 186
 187 =cut
 188
 189 sub verbose {
 190    my $self = shift;
 191    $self->{_verbose} = @_ if @_;
 192    return $self->{_verbose};
 193 }
 194
 195 =head2 _load_format_module
 196
 197  Title   : _load_format_module
 198  Usage   : INTERNAL Bio::Network::IO stuff
 199  Function: Loads up (like use) a module at run time on demand
 200  Returns :
 201  Args    :
 202
 203 =cut
 204
 205 sub _load_format_module {
 206         my ($self, $format) = @_;
 207         my $module = "Bio::Network::IO::" . $format;
 208         my $ok;
 209
 210         eval {
 211                 $ok = $self->_load_module($module);
 212         };
 213         if ( $@ ) {
 214                 print STDERR <<END
 215 $self: $format cannot be found
 216 Exception $@
 217 For more information about the Bio::Network::IO system please see the Bio:Network::IO docs.
 218 END
 219 ;
 220         }
 221         return $ok;
 222 }
 223
 224 =head2 _initialize_io
 225
 226  Title   : _initialize_io
 227  Usage   : *INTERNAL Bio::Network::IO stuff*
 228  Function:
 229  Returns :
 230  Args    :
 231
 232 =cut
 233
 234 sub _initialize_io {
 235         my ($self, @args) = @_;
 236         $self->SUPER::_initialize_io(@args);
 237         my ($th,$verbose) = $self->_rearrange( [qw(THRESHOLD VERBOSE)], @args);
 238         $self->{'_th'} = $th;
 239         $self->{'_verbose'} = $verbose;
 240         return $self;
 241 }
 242
 243 =head2 _get_standard_name
 244
 245  Title   : _get_standard_name
 246  Usage   :
 247  Function: Returns some standard name for a database, uses global
 248            %DBNAMES
 249  Returns :
 250  Args    :
 251
 252 =cut
 253
 254 sub _get_standard_name {
 255         my ($self,$name) = @_;
 256         $DBNAMES{$name};
 257 }
 258
 259 1;
 260
 261 __END__