NAME

Bio::Phylo::Matrices::Datum - The single observations object.

SYNOPSIS

 use Bio::Phylo::Matrices::Matrix;
 use Bio::Phylo::Matrices::Datum;
 use Bio::Phylo::Taxa::Taxon;

 # instantiating a datum object...
 my $datum = Bio::Phylo::Matrices::Datum->new(
    -name   => 'Tooth comb size,
    -type   => 'STANDARD',
    -desc   => 'number of teeth in lower jaw comb',
    -pos    => 1,
    -weight => 2,
    -char   => [ 6 ],
 );

 # ...and linking it to a taxon object
 my $taxon = Bio::Phylo::Taxa::Taxon->new( 
     -name => 'Lemur_catta' 
 );
 $datum->set_taxon( $taxon );
 
 # instantiating a matrix...
 my $matrix = Bio::Phylo::Matrices::Matrix->new;
 
 # ...and insert datum in matrix
 $matrix->insert($datum);

DESCRIPTION

The datum object models a single observation or a sequence of observations, which can be linked to a taxon object.

METHODS

CONSTRUCTOR

new()
 Type    : Constructor
 Title   : new
 Usage   : my $datum = Bio::Phylo::Matrices::Datum->new;
 Function: Instantiates a Bio::Phylo::Matrices::Datum 
           object.
 Returns : A Bio::Phylo::Matrices::Datum object.
 Args    : None required. Optional:
           -taxon  => $taxon,
           -weight => 0.234,
           -type   => DNA,
           -char   => [ 'G','A','T','T','A','C','A' ],
           -pos    => 2,
 

MUTATORS

set_taxon()
 Type    : Mutator
 Title   : set_taxon
 Usage   : $datum->set_taxon($taxon);
 Function: Assigns the taxon a datum refers to.
 Returns : Modified object.
 Args    : $taxon must be a Bio::Phylo::Taxa::Taxon 
           object.
set_weight()
 Type    : Mutator
 Title   : set_weight
 Usage   : $datum->set_weight($weight);
 Function: Assigns a datum's weight.
 Returns : Modified object.
 Args    : The $weight argument must be a 
           number in any of Perl's number
           formats.
set_type()
 Type    : Mutator
 Title   : set_type
 Usage   : $datum->set_type($type);
 Function: Assigns a datum's type.
 Returns : Modified object.
 Args    : $type must be one of [DNA|RNA|STANDARD|
           PROTEIN|NUCLEOTIDE|CONTINUOUS]. If DNA, 
           RNA or NUCLEOTIDE is defined, the
           subsequently set char is validated against 
           the IUPAC nucleotide one letter codes. If 
           PROTEIN is defined, the char is validated 
           against IUPAC one letter amino acid codes. 
           Likewise, a STANDARD char has to be a single 
           integer [0-9], while for CONTINUOUS all of 
           Perl's number formats are allowed.
set_char()
 Type    : Mutator
 Title   : set_char
 Usage   : $datum->set_char($char);
 Function: Assigns a datum's character value.
 Returns : Modified object.
 Args    : The $char argument is checked against 
           the allowed ranges for the various 
           character types: IUPAC nucleotide (for 
           types of DNA|RNA|NUCLEOTIDE), IUPAC 
           single letter amino acid codes (for type 
           PROTEIN), integers (STANDARD) or any of perl's
           decimal formats (CONTINUOUS). The $char can be: 
               * a single character;
               * a string of characters;
               * an array reference of characters;
 Comments: Note that on assigning characters to a datum,
           previously set annotations are removed.               
set_position()
 Type    : Mutator
 Title   : set_position
 Usage   : $datum->set_position($pos);
 Function: Assigns a datum's position.
 Returns : Modified object.
 Args    : $pos must be an integer.
set_annotation()
 Type    : Mutator
 Title   : set_annotation
 Usage   : $datum->set_annotation( 
               -char       => 1, 
               -annotation => { -codonpos => 1 } 
           );
 Function: Assigns an annotation to a 
           character in the datum.
 Returns : Modified object.
 Args    : Required: -char       => $int
           Optional: -annotation => $hashref
 Comments: Use this method to annotate
           a single character. To annotate
           multiple characters, use
           'set_annotations' (see below).
set_annotations()
 Type    : Mutator
 Title   : set_annotations
 Usage   : $datum->set_annotations( 
               { '-codonpos' => 1 }, 
               { '-codonpos' => 2 }, 
               { '-codonpos' => 3 },              
           );
 Function: Assign annotations to
           characters in the datum.
 Returns : Modified object.
 Args    : Hash references, where 
           position in the argument
           list matches that of the
           specified characters in 
           the character list.
 Comments: Use this method to annotate
           multiple characters. To
           annotate a single character,
           use 'set_annotation' (see
           above).

ACCESSORS

get_taxon()
 Type    : Accessor
 Title   : get_taxon
 Usage   : my $taxon = $datum->get_taxon;
 Function: Retrieves the taxon a datum refers to.
 Returns : Bio::Phylo::Taxa::Taxon
 Args    : NONE
get_weight()
 Type    : Accessor
 Title   : get_weight
 Usage   : my $weight = $datum->get_weight;
 Function: Retrieves a datum's weight.
 Returns : FLOAT
 Args    : NONE
get_type()
 Type    : Accessor
 Title   : get_type
 Usage   : my $type = $datum->get_type;
 Function: Retrieves a datum's type.
 Returns : One of [DNA|RNA|STANDARD|PROTEIN|
           NUCLEOTIDE|CONTINUOUS]
 Args    : NONE
get_char()
 Type    : Accessor
 Title   : get_char
 Usage   : my $char = $datum->get_char;
 Function: Retrieves a datum's character value.
 Returns : In scalar context, returns a single 
           character, or a string of characters 
           (e.g. a DNA sequence, or a space 
           delimited series of continuous characters). 
           In list context, returns a list of characters
           (of zero or more characters).
 Args    : NONE
get_position()
 Type    : Accessor
 Title   : get_position
 Usage   : my $pos = $datum->get_position;
 Function: Retrieves a datum's position.
 Returns : a SCALAR integer.
 Args    : NONE
get_annotation()
 Type    : Accessor
 Title   : get_annotation
 Usage   : $datum->get_annotation( 
               '-char' => 1, 
               '-key'  => '-codonpos',
           );
 Function: Retrieves an annotation to 
           a character in the datum.
 Returns : SCALAR or HASH
 Args    : Optional: -char => $int
           Optional: -key => $key

METHODS

copy_atts()
 Type    : Method
 Title   : copy_atts
 Usage   : my $copy = $datum->copy_atts;
 Function: Creates an empty copy of invocant 
           (i.e. no data, but all the
           attributes).
 Returns : Bio::Phylo::Matrices::Datum 
           (shallow copy)
 Args    : None
reverse()
 Type    : Method
 Title   : reverse
 Usage   : my $reversed = $datum->reverse;
 Function: Reverse a datum's character string.
 Returns : Reversed datum.
 Args    : NONE
to_xml()
 Type    : Format converter
 Title   : to_xml
 Usage   : my $xml = $datum->to_xml;
 Function: Reverse a datum's XML representation.
 Returns : Valid XML string.
 Args    : NONE

DESTRUCTOR

DESTROY()
 Type    : Destructor
 Title   : DESTROY
 Usage   : $phylo->DESTROY
 Function: Destroys Phylo object
 Alias   :
 Returns : TRUE
 Args    : none
 Comments: You don't really need this, 
           it is called automatically when
           the object goes out of scope.

SEE ALSO

Bio::Phylo

This object inherits from Bio::Phylo, so the methods defined therein are also applicable to Bio::Phylo::Matrices::Datum objects.

Bio::Phylo::Manual

Also see the manual: Bio::Phylo::Manual.

FORUM

CPAN hosts a discussion forum for Bio::Phylo. If you have trouble using this module the discussion forum is a good place to start posting questions (NOT bug reports, see below): http://www.cpanforum.com/dist/Bio-Phylo

BUGS

Please report any bugs or feature requests to bug-bio-phylo@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Bio-Phylo. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. Be sure to include the following in your request or comment, so that I know what version you're using:

$Id: Datum.pm,v 1.28 2006/04/12 22:38:22 rvosa Exp $

AUTHOR

Rutger A. Vos,

email: rvosa@sfu.ca
web page: http://www.sfu.ca/~rvosa/

ACKNOWLEDGEMENTS

The author would like to thank Jason Stajich for many ideas borrowed from BioPerl http://www.bioperl.org, and CIPRES http://www.phylo.org and FAB* http://www.sfu.ca/~fabstar for comments and requests.

COPYRIGHT & LICENSE

Copyright 2005 Rutger A. Vos, All Rights Reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.