/ 
Bio-Phylo-v2.0.1
River stage two • 9 direct dependents • 18 total dependents
/ Bio::Phylo::Matrices::DatumRole

NAME

Bio::Phylo::Matrices::DatumRole - Extra behaviours for a character state sequence

SYNOPSIS

use Bio::Phylo::Factory;
my $fac = Bio::Phylo::Factory->new;

# instantiating a datum object...
my $datum = $fac->create_datum(
   -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 = $fac->create_taxon(
    -name => 'Lemur_catta'
);
$datum->set_taxon( $taxon );

# instantiating a matrix...
my $matrix = $fac->create_matrix;

# ...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()

Datum object constructor.

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,           
          -pos    => 2,
new_from_bioperl()

Datum constructor from Bio::Seq argument.

Type    : Constructor
Title   : new_from_bioperl
Usage   : my $datum = 
          Bio::Phylo::Matrices::Datum->new_from_bioperl($seq);
Function: Instantiates a 
          Bio::Phylo::Matrices::Datum object.
Returns : A Bio::Phylo::Matrices::Datum object.
Args    : A Bio::Seq (or similar) object

MUTATORS

set_char()

Sets character state(s)

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;
              * an array of characters;
Comments: Note that on assigning characters to a datum,
          previously set annotations are removed.

ACCESSORS

get_matrix()

Gets the matrix (if any) this datum belongs to

Type    : Accessor
Title   : get_matrix
Usage   : my $matrix = $datum->get_matrix;
Function: Retrieves the matrix the datum belongs to
Returns : Bio::Phylo::Matrices::Matrix
Args    : NONE
get_char()

Gets characters.

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_unaligned_char()

Gets unaligned characters, i.e. without gap or missing symbols

Type    : Accessor
Title   : get_unaligned_char
Usage   : my $char = $datum->get_unaligned_char;
Function: Retrieves a datum's unaligned character sequence
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_length()

Gets invocant number of characters.

Type    : Accessor
Title   : get_length
Usage   : my $length = $datum->get_length;
Function: Retrieves a datum's length.
Returns : a SCALAR integer.
Args    : NONE
get_by_index()

Gets state at argument index.

Type    : Accessor
Title   : get_by_index
Usage   : my $val = $datum->get_by_index($i);
Function: Retrieves state at index $i.
Returns : a character state.
Args    : INT
get_index_of()

Returns the index of the first occurrence of the state observation in the datum or undef if the datum doesn't contain the argument

 Type    : Generic query
 Title   : get_index_of
 Usage   : my $i = $datum->get_index_of($state)
 Function: Returns the index of the first occurrence of the 
           state observation in the datum or undef if the datum 
		   doesn't contain the argument
 Returns : An index or undef
 Args    : A contained object

TESTS

can_contain()

Tests if invocant can contain argument.

Type    : Test
Title   : can_contain
Usage   : &do_something if $datum->can_contain( @args );
Function: Tests if $datum can contain @args
Returns : BOOLEAN
Args    : One or more arguments as can be provided to set_char

CALCULATIONS

calc_state_counts()

Calculates occurrences of states.

Type    : Calculation
Title   : calc_state_counts
Usage   : my %counts = %{ $datum->calc_state_counts };
Function: Calculates occurrences of states.
Returns : Hashref: keys are states, values are counts
Args    : Optional - one or more states to focus on
calc_distance()

Calculates the distance between the invocant and argument

Type    : Calculation
Title   : calc_distance
Usage   : my $dist = $datum1->calc_distance($datum2);
Function: Calculates pairwise distance
Returns : A number, the distance per site
Args    : Another datum to calculate the distance to
Comments: Assumes the sequences are aligned. Calculates
          substitutions / total non-missing and non-gapped sites.
calc_state_frequencies()

Calculates the frequencies of the states observed in the matrix.

 Type    : Calculation
 Title   : calc_state_frequencies
 Usage   : my %freq = %{ $object->calc_state_frequencies() };
 Function: Calculates state frequencies
 Returns : A hash, keys are state symbols, values are frequencies
 Args    : Optional:
           # if true, counts missing (usually the '?' symbol) as a state
	   # in the final tallies. Otherwise, missing states are ignored
           -missing => 1
           # if true, counts gaps (usually the '-' symbol) as a state
	   # in the final tallies. Otherwise, gap states are ignored
	   -gap => 1
 Comments: Throws exception if matrix holds continuous values

METHODS

reverse()

Reverses contents.

Type    : Method
Title   : reverse
Usage   : $datum->reverse;
Function: Reverses a datum's contained characters
Returns : Returns modified $datum
Args    : NONE
concat()

Appends argument to invocant.

Type    : Method
Title   : reverse
Usage   : $datum->concat($datum1);
Function: Appends $datum1 to $datum
Returns : Returns modified $datum
Args    : NONE
consense()

Creates consensus sequence out of arguments

Type    : Method
Title   : consense
Usage   : my @chars = $datum->consense($datum1,...);
Function: Creates consensus sequence out of arguments
Returns : Returns @chars or $seq
Args    : NONE
to_xml()

Serializes datum to nexml format.

Type    : Format convertor
Title   : to_xml
Usage   : my $xml = $datum->to_xml;
Function: Converts datum object into a nexml element structure.
Returns : Nexml block (SCALAR).
Args    : -chars   => [] # optional, an array ref of character IDs
          -states  => {} # optional, a hash ref of state IDs
          -symbols => {} # optional, a hash ref of symbols
          -special => {} # optional, a hash ref of special symbol IDs
to_dom()

Analog to to_xml.

Type    : Serializer
Title   : to_dom
Usage   : $datum->to_dom
Function: Generates a DOM subtree from the invocant
          and its contained objects
Returns : an XML::LibXML::Element object
Args    : none
copy_atts()
Not implemented!
complement()
Not implemented!
slice()
Not implemented!

SEE ALSO

There is a mailing list at https://groups.google.com/forum/#!forum/bio-phylo for any user or developer questions and discussions.

Bio::Phylo::Taxa::TaxonLinker

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

Bio::Phylo::Matrices::TypeSafeData

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

Bio::Phylo::Manual

Also see the manual: Bio::Phylo::Manual and http://rutgervos.blogspot.com.

CITATION

If you use Bio::Phylo in published research, please cite it:

Rutger A Vos, Jason Caravas, Klaas Hartmann, Mark A Jensen and Chase Miller, 2011. Bio::Phylo - phyloinformatic analysis using Perl. BMC Bioinformatics 12:63. http://dx.doi.org/10.1186/1471-2105-12-63