Summary

Bio::Taxonomy::Node - A node in a represented taxonomy

Package variables

Included modules

Inherit

Bio::IdentifiableI Bio::Root::Root

Synopsis

  use Bio::Taxonomy::Node;
  # typically you will get a Node from a Bio::DB::Taxonomy object
  # but here is how you initialize one
  my $node = new Bio::Taxonomy::Node(-name      => $name,
                                     -object_id => $oid,
                                     -parent_id => $pid,
                                     -rank   => $rank,
                                     -division  => $div,
                                     -dbh       => $dbh);

  my $dbh = new Bio::DB::Taxonomy(-source   => 'flatfile',
                                  -directory=> '/tmp',
                                  -nodesfile=> '/path/to/nodes.dmp',
                                  -namesfile=> '/path/to/names.dmp');
  my $hum_node = $dbh->get_Taxonomy_Node(-name => 'Homo sapiens');
  my $hum_node2= $dbh->get_Taxonomy_Node(-taxonid => '9606');

  print "rank is ", $hum_node->rank, "\n";
  print "classification is ", join(" ", $hum_node->classification),"\n"; 
  print "division is ", $node->division, "\n";

Description

This is the next generation (for Bioperl) of representing Taxonomy
information. Previously all information was managed by a single
object called Bio::Species. This new implementation allows
representation of the intermediete nodes not just the species nodes
and can relate their connections.

Methods

Methods description

 Title   : new
 Usage   : my $obj = new Bio::Taxonomy::Node();
 Function: Builds a new Bio::Taxonomy::Node object 
 Returns : an instance of Bio::Taxonomy::Node
 Args    : -dbh       => a reference to a Bio::DB::Taxonomy object
           -name      => a string representing the node name
           -object_id => unique identifier - typically NCBI Taxid

 Title   : db_handle
 Usage   : $obj->db_handle($newval)
 Function: Get/Set Bio::DB::Taxonomy Handle
 Returns : value of db_handle (a scalar) (Bio::DB::Taxonomy object)
 Args    : on set, new value (a scalar or undef, optional) Bio::DB::Taxonomy object

  Title:    factory
  Usage:    $factory->factory($newval);
  Function: Get/Set Bio::Taxonomy::FactoryI implementation
  Returns:  Bio:;Taxonomy::FactoryI
  Args:     Bio::Taxonomy::FactoryI

 Title   : rank
 Usage   : $obj->rank($newval)
 Function: 
 Example : 
 Returns : value of rank (a scalar)
 Args    : on set, new value (a scalar or undef, optional)

 Title   : object_id
 Usage   : $obj->object_id($newval)
 Function: 
 Example : 
 Returns : value of object_id (a scalar)
 Args    : on set, new value (a scalar or undef, optional)

 Title   : version
 Usage   : $obj->version($newval)
 Function: 
 Example : 
 Returns : value of version (a scalar)
 Args    : on set, new value (a scalar or undef, optional)

 Title   : authority
 Usage   : $obj->authority($newval)
 Function: 
 Example : 
 Returns : value of authority (a scalar)
 Args    : on set, new value (a scalar or undef, optional)

 Title   : namespace
 Usage   : $obj->namespace($newval)
 Function: 
 Example : 
 Returns : value of namespace (a scalar)
 Args    : on set, new value (a scalar or undef, optional)

 Title   : parent_id
 Usage   : $obj->parent_id($newval)
 Function: 
 Example : 
 Returns : value of parent_id (a scalar)
 Args    : on set, new value (a scalar or undef, optional)

 Title   : get_Parent_Node
 Usage   : my $parentnode = $node->get_Parent_Node()
 Function: Retrieve the full Parent node from the database
 Returns : Bio::Taxonomy::Node
 Args    : none

 Title   : node_name
 Usage   : $obj->node_name($newval)
 Function: 
 Example : 
 Returns : value of node_name (a scalar)
 Args    : on set, new value (a scalar or undef, optional)

 Title   : classification
 Usage   : $self->classification(@class_array);
           @classification = $self->classification();
 Function: Fills Returns the classification list in
           the object.  The array provided must be in
           the order SPECIES, GENUS ---> KINGDOM.
           Checks are made that species is in lower case,
           and all other elements are in title case.
 Returns : Classification array
 Args    : none - this can be set directly

 Title   : division
 Usage   : $obj->division($newval)
 Function: 
 Example : 
 Returns : value of division (a scalar)
 Args    : on set, new value (a scalar or undef, optional)

 Title   : show_all
 Usage   : $obj->show_all($newval)
 Function: Boolean flag whether or not we should show all intermediete
           nodes that do not have actual ranks.
 Returns : value of show_all (a scalar)
 Args    : on set, new value (a scalar or undef, optional)

  
  Title:    name
  Usage:    $obj->name('scientific', 'sapiens');
            $obj->name('common', 'human', 'man');
            my @names = @{$obj->name('common')};
  Function: Get and set the names
  Returns:  names (a array reference)
  Args:     Arg1 => the name_class. You can assign any text, but the words
                'scientific' and 'common' have the special meaning, as
                scientific name and common name, respectively.
            Arg2 .. => the names

  Title:    scientific_name
  Usage:    my $new_val = $obj->scientific_name($newval);
  Function: Get/Set the scientific name
  Returns:  a scalar text value
  Args:     a scalar text value

  Title   : parent_taxon_id
  Usage   : $self->parent_taxon_id($newval);
            $val = $self->parent_taxon_id;
  Function: Get/Set for parent_taxon_id
  Return  : 
  Args    :

Methods code

sub new {

  my($class,@args) = @_;
  my $self = $class->SUPER::new(@args);
  my ($name,$uniqueid,$parentid,$rank,$div,$dbh, $factory) = 
      $self->_rearrange([qw(NAME OBJECT_ID PARENT_ID RANK DIVISION
			    DBH FACTORY)],
			@args);

  $uniqueid && $self->object_id($uniqueid);
  $name && $self->node_name($name);
  $rank && $self->rank($rank);
  $div  && $self->division($div);
  $factory && $self->factory($factory);
  unless(defined $factory){
      $self->db_handle($dbh 
        || Bio::DB::Taxonomy->new(-source => 'entrez'));
  }
  $self->parent_id($parentid);
  return $self;

}

sub db_handle {

    my $self = shift;
    if( @_ ) {
	my $v = shift;
	# until we establish some other higher level TaxonomyDB interface
	if( ! ref($v) || ! $v->isa('Bio::DB::Taxonomy') ) {
	  $self->throw("Must have provided a valid Bio::DB::Taxonomy object");
	}
	$self->{'db_handle'} = $v;
    }
    return $self->{'db_handle'};

}

sub factory {

    my $self = shift;
    if(@_){
        my $v = shift;
        unless(ref($v) || $v->isa('Bio::Taxonomy::FactoryI')){
            $self->throw('A Bio::Taxonomy::FactoryI object required');
        }
        $self->{_factory} = $v;
    }
    return $self->{_factory};

}

sub rank {

    my $self = shift;

    return $self->{'rank'} = shift if @_;
    return $self->{'rank'};

}

sub object_id {

    my $self = shift;

    return $self->{'object_id'} = shift if @_;
    return $self->{'object_id'};

}

sub version {

    my $self = shift;

    return $self->{'version'} = shift if @_;
    return $self->{'version'};

}

sub authority {

    my $self = shift;

    return $self->{'authority'} = shift if @_;
    return $self->{'authority'};

}

sub namespace {

    my $self = shift;

    return $self->{'namespace'} = shift if @_;
    return $self->{'namespace'};

}

sub parent_id {

    my $self = shift;

    return $self->{'parent_id'} = shift if @_;
    return $self->{'parent_id'};

}

sub get_Parent_Node {

   my ($self) = @_;
   
   my $node = $self->db_handle->get_Taxonomy_Node(-taxonid => $self->parent_id);
   unless ( $node ) {
       $self->warn("Could not find node for parent id ". $self->parent_id);
       return undef;
   }
   return $node;

}

sub node_name {

    my $self = shift;
    return $self->{'node_name'} = shift if @_;
    return $self->{'node_name'};

}

sub classification {

   my ($self,@vals) = @_;
   my $p;
   if( defined($p = $self->get_Parent_Node()) &&
	       $p->object_id != 1  ) {
       # okay this won't really work - need to do proper recursion
       push @vals, $p->classification;
   }
   if( $self->show_all || $self->rank ne 'no rank') {
       push @vals,$self->node_name();
   }
   return @vals;

}

sub division {

    my $self = shift;

    return $self->{'division'} = shift if @_;
    return $self->{'division'};

}

sub show_all {

    my $self = shift;

    return $self->{'show_all'} = shift if @_;
    return $self->{'show_all'};

}

sub name {

    my ($self, $name_class, @names) = @_;
    $self->throw('No name class specified') unless defined $name_class;
    # scientific name should be special, because of its uniqueness.
    return [$self->scientific_name(@names)] if $name_class =~ /scientific/i;
    $self->{_names_hash} = {} unless exists $self->{_names_hash};
    if(@names){
        $self->{_names_hash}->{$name_class} = [] 
            unless exists $self->{_names_hash}->{$name_class};
        push @{$self->{_names_hash}->{$name_class}}, @names;
    }
    return $self->{_names_hash}->{$name_class};

}

sub scientific_name {

    my $self = shift;
    if(@_){
        my $scientific_name = shift;
        if(defined $self->{_scientific_name}){
            my $current = $self->{_scientific_name};
            $self->throw("Scientific name can be set once only![$current]");
        }
        return $self->{_scientific_name} = $scientific_name;
    }
    return $self->{_scientific_name};

}

sub parent_taxon_id {

    my $self = shift;
    return $self->{_parent_taxon_id} = shift if @_;
    return $self->{_parent_taxon_id};

}

General documentation

User feedback is an integral part of the evolution of this and other
Bioperl modules. Send your comments and suggestions preferably to
the Bioperl mailing list. Your participation is much appreciated.

  bioperl-l@bioperl.org              - General discussion
  http://bioperl.org/MailList.shtml  - About the mailing lists

Report bugs to the Bioperl bug tracking system to help us keep track
of the bugs and their resolution. Bug reports can be submitted via
the web:

  http://bugzilla.bioperl.org/

Email jason-at-bioperl-dot-org
Describe contact details here

Juguang Xiao, juguang@tll.org.sg
Additional contributors names and emails here

The rest of the documentation details each of the object methods.
Internal methods are usually preceded with a _