Bio/Ontology/GOterm.pm

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