OntologyTerm.pm 8.25 KB
Newer Older
1 2
=head1 LICENSE

3
  Copyright (c) 1999-2013 The European Bioinformatics Institute and
4 5 6 7 8 9 10 11 12 13
  Genome Research Limited.  All rights reserved.

  This software is distributed under a modified Apache license.
  For license details, please see

    http://www.ensembl.org/info/about/code_licence.html

=head1 CONTACT

  Please email comments or questions to the public Ensembl
14
  developers list at <dev@ensembl.org>.
15 16 17 18 19 20 21 22 23 24 25 26 27

  Questions may also be sent to the Ensembl help desk at
  <helpdesk@ensembl.org>.

=cut

=head1 NAME

Bio::EnsEMBL::OntologyTerm

=head1 DESCRIPTION

An ontology term object, (most often) created by
Andreas Kusalananda Kähäri's avatar
Andreas Kusalananda Kähäri committed
28
Bio::EnsEMBL::DBSQL::GOTermAdaptor and used in querying for
29 30 31 32 33 34 35 36 37 38 39 40 41 42
transcripts, genes, and translations using the relevant adaptors and
methods.

=head1 METHODS

=cut

package Bio::EnsEMBL::OntologyTerm;

use strict;
use warnings;

use Bio::EnsEMBL::Utils::Argument qw( rearrange );

43
use base qw( Bio::EnsEMBL::Storable );
44 45 46 47 48 49

=head2 new

  Arg [-ACCESSION]  : String
                      The accession of the ontology term.

50 51 52
  Arg [-ONTOLOGY]   : String
                      The ontology that the term belongs to.

53 54 55 56 57 58
  Arg [-NAMESPACE]  : String
                      The namespace of the ontology term.

  Arg [-NAME]       : String
                      The name of the ontology term.

59 60 61 62
  Arg [-SUBSETS]     : (optional) Listref of strings
                      The subsets within the ontology to which this
                      term belongs.

63
  Arg [-DEFINITION] : (optional) String
64 65
                      The definition of the ontology term.

66 67 68
  Arg [-SYNONYMS]   : (optional) Listref of strings
                      The synonyms of this term.

69 70 71 72 73 74 75 76
  Arg               : Further arguments required for parent class
                      Bio::EnsEMBL::Storable.

  Description   : Creates an ontology term object.

  Example       :

    my $term = Bio::EnsEMBL::OntologyTerm->new(
77
      '-accession'  => 'GO:0021785',
78
      '-ontology'   => 'GO',
79
      '-namespace'  => 'biological_process',
80 81 82 83 84 85 86 87 88 89
      '-name'       => 'branchiomotor neuron axon guidance',
      '-definition' => 'The process in which a branchiomotor '
        . 'neuron growth cone is directed to a specific target site. '
        . 'Branchiomotor neurons are located in the hindbrain and '
        . 'innervate branchial arch-derived muscles that control jaw '
        . 'movements, facial expression, the larynx, and the pharynx.',
      '-synonyms' => [ 'BMN axon guidance',
                       'branchial motor axon guidance',
                       'special visceral motor neuron axon guidance' ]

90 91 92 93 94 95 96 97 98 99 100 101
        # ... other arguments required by Bio::EnsEMBL::Storable.
    );

  Return type   : Bio::EnsEMBL::OntologyTerm

=cut

sub new {
  my $proto = shift(@_);

  my $this = $proto->SUPER::new(@_);

102
  my ( $accession, $ontology, $namespace, $name, $definition, $is_root, $is_obsolete, $subsets )
103
    = rearrange( [ 'ACCESSION',  'ONTOLOGY', 'NAMESPACE', 'NAME',
104
                   'DEFINITION', 'IS_ROOT', 'IS_OBSOLETE', 'SUBSETS' ],
105
                 @_ );
106 107

  $this->{'accession'}  = $accession;
108
  $this->{'ontology'}   = $ontology;
109 110 111
  $this->{'namespace'}  = $namespace;
  $this->{'name'}       = $name;
  $this->{'definition'} = $definition;
Magali Ruffier's avatar
Magali Ruffier committed
112
  $this->{'is_root'}    = $is_root;
113
  $this->{'is_obsolete'}= $is_obsolete;
114
  $this->{'subsets'}    = [ @{$subsets} ];
115 116 117 118 119 120 121 122 123

  $this->{'child_terms_fetched'}  = 0;
  $this->{'parent_terms_fetched'} = 0;

  return $this;
}

=head2 accession

124
  Arg           : None
125

126
  Description   : Returns the accession for the ontology term in question.
127 128 129 130 131 132 133 134

  Example       : my $accession = $term->accession();

  Return type   : String

=cut

sub accession {
135
  my ($this) = @_;
136 137 138
  return $this->{'accession'};
}

139 140
=head2 ontology

141
  Arg           : None
142

143
  Description   : Returns the ontology for the ontology term in question.
144 145 146 147 148 149 150 151 152

  Example       : my $ontology = $term->ontology();

  Return type   : String

=cut

sub ontology {
  my ($this) = @_;
153
  return $this->{'ontology'};
154 155
}

156 157
=head2 namespace

158
  Arg           : None
159

160
  Description   : Returns the namespace for the ontology term in question.
161 162 163 164 165 166 167 168

  Example       : my $acc = $term->namespace();

  Return type   : String

=cut

sub namespace {
169
  my ($this) = @_;
170 171 172 173 174
  return $this->{'namespace'};
}

=head2 name

175
  Arg           : None
176

177
  Description   : Returns the name for the ontology term in question.
178 179 180 181 182 183 184 185

  Example       : my $name = $term->name();

  Return type   : String

=cut

sub name {
186
  my ($this) = @_;
187 188 189 190 191
  return $this->{'name'};
}

=head2 definition

192
  Arg           : None
193

194
  Description   : Returns the definition for the ontology term in question.
195 196 197 198 199 200 201

  Example       : my $definition = $term->definition();

  Return type   : String

=cut

202
sub definition {
203
  my ($this) = @_;
204 205 206
  return $this->{'definition'};
}

Magali Ruffier's avatar
Magali Ruffier committed
207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223
=head2 is_root

  Arg           : None

  Description   : Returns true if the term is root of its ontology 

  Example       : my $is_root = $term->is_root();

  Return type   : Boolean (TRUE if it is a root, else FALSE)

=cut

sub is_root {
  my ($this) = @_;
  return $this->{'is_root'};
}

224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241
=head2 is_obsolete

  Arg           : None

  Description   : Returns true if the term is obsolete 

  Example       : my $is_obsolete = $term->is_obsolete();

  Return type   : Boolean (TRUE if it is obsolete, else FALSE)

=cut

sub is_obsolete {
  my ($this) = @_;
  return $this->{'is_obsolete'};
}


Magali Ruffier's avatar
Magali Ruffier committed
242

243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266
=head2 synonyms

  Arg           : None

  Description   : Returns the list of synonyms defined for this term
                  (if any).

  Example       : my @synonyms = @{ $term->synonyms() };

  Return type   : Listref of strings

=cut

sub synonyms {
  my ($this) = @_;

  if ( !exists( $this->{'synonyms'} ) ) {
    $this->{'synonyms'} =
      $this->adaptor()->_fetch_synonyms_by_dbID( $this->dbID() );
  }

  return $this->{'synonyms'};
}

267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284
=head2 subsets

  Arg           : None

  Description   : Returns a list of subsets that this term is part
                  of.  The list might be empty.

  Example       : my @subsets = @{ $term->subsets() };

  Return type   : listref of strings

=cut

sub subsets {
  my ($this) = @_;
  return $this->{'subsets'};
}

285 286
=head2 children

287
  Arg           : (optional) List of strings
288
                  The type of relations to retrieve children for.
289 290 291

  Description   : Returns the children terms of this ontology term.

292 293
  Example       : my @children =
                    @{ $term->children( 'is_a', 'part_of' ) };
294 295 296 297 298 299

  Return type   : listref of Bio::EnsEMBL::OntologyTerm

=cut

sub children {
300
  my ( $this, @relations ) = @_;
301

302
  my @terms = @{ $this->adaptor()->fetch_all_by_parent_term($this) };
303

304 305 306 307 308 309
  if (@relations) {
    @terms = ();
    foreach my $relation (@relations) {
      if ( exists( $this->{'children'}{$relation} ) ) {
        push( @terms, @{ $this->{'children'}{$relation} } );
      }
310 311 312 313 314 315 316 317 318 319
    }
  }

  return \@terms;
}

=head2 descendants

  Arg           : None

320 321 322
  Description   : Returns the complete set of 'is_a' and 'part_of'
                  descendant terms of this ontology term, down to
                  and including any leaf terms.
323

324
  Example       : my @descendants = @{ $term->descendants() };
325 326 327 328 329 330 331

  Return type   : listref of Bio::EnsEMBL::OntologyTerm

=cut

sub descendants {
  my ($this) = @_;
332
  return $this->adaptor()->fetch_all_by_ancestor_term($this);
333 334 335 336
}

=head2 parents

337
  Arg           : (optional) List of strings
338
                  The type of relations to retrieve parents for.
339 340 341

  Description   : Returns the parent terms of this ontology term.

342 343
  Example       : my @parents =
                    @{ $term->parents( 'is_a', 'part_of' ) };
344 345 346 347 348 349

  Return type   : listref of Bio::EnsEMBL::OntologyTerm

=cut

sub parents {
350
  my ( $this, @relations ) = @_;
351

352
  my @terms = @{ $this->adaptor()->fetch_all_by_child_term($this) };
353

354 355 356 357 358 359
  if (@relations) {
    @terms = ();
    foreach my $relation (@relations) {
      if ( exists( $this->{'parents'}{$relation} ) ) {
        push( @terms, @{ $this->{'parents'}{$relation} } );
      }
360 361 362 363 364 365 366 367 368 369
    }
  }

  return \@terms;
}

=head2 ancestors

  Arg           : None

370 371 372
  Description   : Returns the complete set of 'is_a' and 'part_of'
                  ancestor terms of this ontology term, up to and
                  including the root term.
373

374
  Example       : my @ancestors = @{ $term->ancestors() };
375 376 377 378 379 380 381

  Return type   : listref of Bio::EnsEMBL::OntologyTerm

=cut

sub ancestors {
  my ($this) = @_;
382
  return $this->adaptor()->fetch_all_by_descendant_term($this);
383 384 385
}

1;