Bio/Ontology/GOterm.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::Ontology::GOterm
   4 #
   5 # Cared for by Christian M. Zmasek <czmasek@gnf.org> or <cmzmasek@yahoo.com>
   6 #
   7 # (c) Christian M. Zmasek, czmasek@gnf.org, 2002.
   8 # (c) GNF, Genomics Institute of the Novartis Research Foundation, 2002.
   9 #
  10 # You may distribute this module under the same terms as perl itself.
  11 # Refer to the Perl Artistic License (see the license accompanying this
  12 # software package, or see http://www.perl.com/language/misc/Artistic.html)
  13 # for the terms under which you may use, modify, and redistribute this module.
  14 #
  15 # THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
  16 # WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
  17 # MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  18 #
  19 # You may distribute this module under the same terms as perl itself
  20
  21 # POD documentation - main docs before the code
  22
  23
  24 =head1 NAME
  25
  26 Bio::Ontology::GOterm - representation of GO terms
  27
  28 =head1 SYNOPSIS
  29
  30   $term = Bio::Ontology::GOterm->new
  31     ( -go_id       => "GO:0016847",
  32       -name        => "1-aminocyclopropane-1-carboxylate synthase",
  33       -definition  => "Catalysis of ...",
  34       -is_obsolete => 0,
  35       -comment     => "" );
  36
  37   $term->add_definition_references( @refs );
  38   $term->add_secondary_GO_ids( @ids );
  39   $term->add_aliases( @aliases );
  40
  41   foreach my $dr ( $term->each_definition_reference() ) {
  42       print $dr, "\n";
  43   }
  44
  45   # etc.
  46
  47 =head1 DESCRIPTION
  48
  49 This is "dumb" class for GO terms (it provides no functionality
  50 related to graphs). Implements Bio::Ontology::TermI.
  51
  52 =head1 FEEDBACK
  53
  54 =head2 Mailing Lists
  55
  56 User feedback is an integral part of the evolution of this and other
  57 Bioperl modules. Send your comments and suggestions preferably to one
  58 of the Bioperl mailing lists.  Your participation is much appreciated.
  59
  60   bioperl-l@bioperl.org                  - General discussion
  61   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  62
  63 =head2 Reporting Bugs
  64
  65 Report bugs to the Bioperl bug tracking system to help us keep track
  66 the bugs and their resolution.  Bug reports can be submitted via the web:
  67
  68   http://bugzilla.open-bio.org/
  69
  70 =head1 AUTHOR
  71
  72 Christian M. Zmasek
  73
  74 Email: czmasek@gnf.org  or  cmzmasek@yahoo.com
  75
  76 WWW:   http://www.genetics.wustl.edu/eddy/people/zmasek/
  77
  78 Address:
  79
  80   Genomics Institute of the Novartis Research Foundation
  81   10675 John Jay Hopkins Drive
  82   San Diego, CA 92121
  83
  84 =head1 APPENDIX
  85
  86 The rest of the documentation details each of the object
  87 methods.
  88
  89 =cut
  90
  91
  92 # Let the code begin...
  93
  94 package Bio::Ontology::GOterm;
  95 use strict;
  96
  97 use constant GOID_DEFAULT => "GO:0000000";
  98 use constant TRUE         => 1;
  99 use constant FALSE        => 0;
 100
 101 use base qw(Bio::Ontology::Term);
 102
 103 =head2 new
 104
 105  Title   : new
 106  Usage   : $term = Bio::Ontology::GOterm->new(
 107        -go_id       => "GO:0016847",
 108        -name        => "1-aminocyclopropane-1-carboxylate synthase",
 109        -definition  => "Catalysis of ...",
 110        -is_obsolete => 0,
 111        -comment     => "" );
 112  Function: Creates a new Bio::Ontology::GOterm.
 113  Returns : A new Bio::Ontology::GOterm object.
 114  Args    : -go_id         => the goid of this GO term [GO:nnnnnnn]
 115                              or [nnnnnnn] (nnnnnnn is a zero-padded
 116                              integer of seven digits)
 117            -name          => the name of this GO term [scalar]
 118            -definition    => the definition of this GO term [scalar]
 119            -ontology      => the ontology for this term (a
 120                              Bio::Ontology::OntologyI compliant object)
 121            -version       => version information [scalar]
 122            -is_obsolete   => the obsoleteness of this GO term [0 or 1]
 123            -comment       => a comment [scalar]
 124
 125 =cut
 126
 127 sub new {
 128
 129     my( $class,@args ) = @_;
 130
 131     my $self = $class->SUPER::new( @args );
 132
 133     my ( $GO_id )
 134         = $self->_rearrange( [ qw( GO_ID ) ], @args );
 135
 136     $GO_id && $self->GO_id( $GO_id );
 137
 138
 139     return $self;
 140
 141 } # new
 142
 143
 144 =head2 init
 145
 146  Title   : init()
 147  Usage   : $term->init();
 148  Function: Initializes this GOterm to all "" and empty lists.
 149  Returns :
 150  Args    :
 151
 152 =cut
 153
 154 sub init {
 155
 156     my $self = shift;
 157
 158     # first call the inherited version to properly chain up the hierarchy
 159     $self->SUPER::init(@_);
 160
 161     # then only initialize what we implement ourselves here
 162     #$self->GO_id( GOID_DEFAULT );
 163
 164 } # init
 165
 166
 167 =head2 GO_id
 168
 169  Title   : GO_id
 170  Usage   : $term->GO_id( "GO:0003947" );
 171            or
 172            print $term->GO_id();
 173  Function: Set/get for the goid of this GO term.
 174
 175            This is essentially an alias to identifier(), with added
 176            format checking.
 177
 178  Returns : The goid [GO:nnnnnnn].
 179  Args    : The goid [GO:nnnnnnn] or [nnnnnnn] (nnnnnnn is a
 180            zero-padded integer of seven digits) (optional).
 181
 182 =cut
 183
 184 sub GO_id {
 185     my $self = shift;
 186     my $value;
 187
 188     if ( @_ ) {
 189         $value = $self->_check_go_id( shift );
 190         unshift(@_, $value);
 191     }
 192
 193     return $self->identifier( @_ );
 194
 195 } # GO_id
 196
 197
 198 =head2 get_secondary_GO_ids
 199
 200  Title   : get_secondary_GO_ids
 201  Usage   : @ids = $term->get_secondary_GO_ids();
 202  Function: Returns a list of secondary goids of this Term.
 203
 204            This is aliased to remove_secondary_ids().
 205
 206  Returns : A list of secondary goids [array of [GO:nnnnnnn]]
 207            (nnnnnnn is a zero-padded integer of seven digits).
 208  Args    :
 209
 210 =cut
 211
 212 sub get_secondary_GO_ids {
 213     return shift->get_secondary_ids(@_);
 214 } # get_secondary_GO_ids
 215
 216
 217 =head2 add_secondary_GO_id
 218
 219  Title   : add_secondary_GO_id
 220  Usage   : $term->add_secondary_GO_id( @ids );
 221            or
 222            $term->add_secondary_GO_id( $id );
 223  Function: Pushes one or more secondary goids into
 224            the list of secondary goids.
 225
 226            This is aliased to remove_secondary_ids().
 227
 228  Returns :
 229  Args    : One secondary goid [GO:nnnnnnn or nnnnnnn] or a list
 230            of secondary goids [array of [GO:nnnnnnn or nnnnnnn]]
 231            (nnnnnnn is a zero-padded integer of seven digits).
 232
 233 =cut
 234
 235 sub add_secondary_GO_id {
 236     return shift->add_secondary_id(@_);
 237 } # add_secondary_GO_id
 238
 239
 240 =head2 remove_secondary_GO_ids
 241
 242  Title   : remove_secondary_GO_ids()
 243  Usage   : $term->remove_secondary_GO_ids();
 244  Function: Deletes (and returns) the secondary goids of this Term.
 245
 246            This is aliased to remove_secondary_ids().
 247
 248  Returns : A list of secondary goids [array of [GO:nnnnnnn]]
 249            (nnnnnnn is a zero-padded integer of seven digits).
 250  Args    :
 251
 252 =cut
 253
 254 sub remove_secondary_GO_ids {
 255     return shift->remove_secondary_ids(@_);
 256 } # remove_secondary_GO_ids
 257
 258
 259 =head2 to_string
 260
 261  Title   : to_string()
 262  Usage   : print $term->to_string();
 263  Function: to_string method for GO terms.
 264  Returns : A string representation of this GOterm.
 265  Args    :
 266
 267 =cut
 268
 269 sub to_string {
 270     my( $self ) = @_;
 271
 272     my $s = "";
 273
 274     $s .= "-- GO id:\n";
 275     $s .= ($self->GO_id() || '')."\n";
 276     $s .= "-- Name:\n";
 277     $s .= ($self->name() || '') ."\n";
 278     $s .= "-- Definition:\n";
 279     $s .= ($self->definition() || '') ."\n";
 280     $s .= "-- Category:\n";
 281     if ( defined( $self->ontology() ) ) {
 282         $s .= $self->ontology()->name()."\n";
 283     }
 284     else {
 285         $s .= "\n";
 286     }
 287     $s .= "-- Version:\n";
 288     $s .= ($self->version() || '') ."\n";
 289     $s .= "-- Is obsolete:\n";
 290     $s .= $self->is_obsolete()."\n";
 291     $s .= "-- Comment:\n";
 292     $s .= ($self->comment() || '') ."\n";
 293     $s .= "-- Definition references:\n";
 294     $s .= $self->_array_to_string( $self->get_dbxrefs() )."\n";
 295     $s .= "-- Secondary GO ids:\n";
 296     $s .= $self->_array_to_string( $self->get_secondary_GO_ids() )."\n";
 297     $s .= "-- Aliases:\n";
 298     $s .= $self->_array_to_string( $self->get_synonyms() );
 299
 300     return $s;
 301
 302 } # to_string
 303
 304
 305
 306
 307 # Title   : _check_go_id
 308 # Function: Checks whether the argument is [GO:nnnnnnn].
 309 #           If "GO:" is not present, it adds it.
 310 # Returns : The canonical GO id.
 311 # Args    : The value to be checked.
 312 sub _check_go_id {
 313     my ( $self, $value ) = @_;
 314     unless ( $value =~ /^(GO:)?\d{7}$/ || $value eq GOID_DEFAULT ) {
 315         $self->throw( "Found [" . $value
 316         . "] where [GO:nnnnnnn] or [nnnnnnn] expected" );
 317     }
 318     unless ( $value =~ /^GO:/ ) {
 319         $value = "GO:".$value;
 320     }
 321     return $value;
 322 } # _check_go_id
 323
 324
 325
 326 # Title   : _array_to_string
 327 # Function:
 328 # Returns :
 329 # Args    :
 330 sub _array_to_string {
 331     my( $self, @value ) = @_;
 332
 333     my $s = "";
 334
 335     for ( my $i = 0; $i < scalar( @value ); ++$i ) {
 336         if ( ! ref( $value[ $i ] ) ) {
 337             $s .= "#" . $i . "\n--  " . $value[ $i ] . "\n";
 338         }
 339     }
 340
 341     return $s;
 342
 343 } # _array_to_string
 344
 345 #################################################################
 346 # aliases or forwards to maintain backward compatibility
 347 #################################################################
 348
 349 *each_secondary_GO_id = \&get_secondary_GO_ids;
 350 *add_secondary_GO_ids = \&add_secondary_GO_id;
 351
 352 1;