Bio::Phylo::Matrices::DatumRole(3)

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>