Bio::Phylo::Matrices::Datatype(3)

NAME
Bio::Phylo::Matrices::Datatype - Validator of character state data

SYNOPSIS
 # No direct usage

DESCRIPTION
This is a superclass for objects that validate character data. Objects that inherit from this class (typically those in the Bio::Phylo::Matrices::Datatype::* namespace) can check strings and arrays of character data for invalid symbols, and split and join strings and arrays in a way appropriate for the type (on whitespace for continuous data, on single characters for categorical data). Bio::Phylo::Matrices::Matrix objects and Bio::Phylo::Matrices::Datum internally delegate validation of their contents to these datatype objects; there is no normal usage in which you'd have to deal with datatype objects directly.

METHODS

  CONSTRUCTOR

new()
    Datatype constructor.

     Type    : Constructor
     Title   : new
     Usage   : No direct usage, is called by TypeSafeData classes;
     Function: Instantiates a Datatype object
     Returns : a Bio::Phylo::Matrices::Datatype child class
     Args    : $type (optional, one of continuous, custom, dna,
               mixed, protein, restriction, rna, standard)

  MUTATORS

set_lookup()
    Sets state lookup table.

     Type    : Mutator
     Title   : set_lookup
     Usage   : $obj->set_lookup($hashref);
     Function: Sets the state lookup table.
     Returns : Modified object.
     Args    : Argument must be a hash
               reference that maps allowed
               single character symbols
               (including ambiguity symbols)
               onto the equivalent set of
               non-ambiguous symbols

set_missing()
    Sets missing data symbol.

     Type    : Mutator
     Title   : set_missing
     Usage   : $obj->set_missing('?');
     Function: Sets the symbol for missing data
     Returns : Modified object.
     Args    : Argument must be a single
               character, default is '?'

set_gap()
    Sets gap symbol.

     Type    : Mutator
     Title   : set_gap
     Usage   : $obj->set_gap('-');
     Function: Sets the symbol for gaps
     Returns : Modified object.
     Args    : Argument must be a single
               character, default is '-'

set_metas_for_states()
    Assigns all metadata annotations for all state symbols

     Type    : Mutator
     Title   : set_metas_for_states
     Usage   : $obj->set_metas_for_states({ $state => [ $m1, $m2 ] });
     Function: Assigns all metadata annotations for all state symbols
     Returns : Modified object.
     Args    : A hash reference of state symbols with metadata arrays

add_meta_for_state()
    Adds a metadata annotation for a state symbol

     Type    : Mutator
     Title   : add_meta_for_state
     Usage   : $obj->add_meta_for_state($meta,$state);
     Function: Adds a metadata annotation for a state symbol
     Returns : Modified object.
     Args    : A Bio::Phylo::NeXML::Meta object and a state symbol

remove_meta_for_state()
    Removes a metadata annotation for a state symbol

     Type    : Mutator
     Title   : remove_meta_for_state
     Usage   : $obj->remove_meta_for_state($meta,$state);
     Function: Removes a metadata annotation for a state symbol
     Returns : Modified object.
     Args    : A Bio::Phylo::NeXML::Meta object and a state symbol

  ACCESSORS

get_type()
    Gets data type as string.

     Type    : Accessor
     Title   : get_type
     Usage   : my $type = $obj->get_type;
     Function: Returns the object's datatype
     Returns : A string
     Args    : None

get_ids_for_special_symbols()
    Gets state-to-id mapping for missing and gap symbols

     Type    : Accessor
     Title   : get_ids_for_special_symbols
     Usage   : my %ids = %{ $obj->get_ids_for_special_symbols };
     Function: Returns state-to-id mapping
     Returns : A hash reference, keyed on symbol, with UID values
     Args    : Optional, a boolean:
               true  => prefix state ids with 's'
               false => keep ids numerical

get_ids_for_states()
    Gets state-to-id mapping

     Type    : Accessor
     Title   : get_ids_for_states
     Usage   : my %ids = %{ $obj->get_ids_for_states };
     Function: Returns state-to-id mapping
     Returns : A hash reference, keyed on symbol, with UID values
     Args    : Optional, a boolean:
               true  => prefix state ids with 's'
               false => keep ids numerical
     Note    : This returns a mapping to alphanumeric states; special
               symbols (for missing data and gaps) are handled separately

get_states_for_symbol()
    Gets set of fundamental states for an ambiguity symbol

     Type    : Accessor
     Title   : get_states_for_symbol
     Usage   : my @states = @{ $obj->get_states_for_symbol('N') };
     Function: Returns the set of states for an ambiguity symbol
     Returns : An array ref of symbols
     Args    : An ambiguity symbol
     Comments: If supplied argument is a fundamental state, an array
               ref with just that state is returned, e.g. 'A' returns
               ['A'] for DNA and RNA

get_symbol_for_states()
    Gets ambiguity symbol for a set of states

     Type    : Accessor
     Title   : get_symbol_for_states
     Usage   : my $state = $obj->get_symbol_for_states('A','C');
     Function: Returns the ambiguity symbol for a set of states
     Returns : A symbol (SCALAR)
     Args    : A set of symbols
     Comments: If no symbol exists in the lookup
               table for the given set of states,
               a new - numerical - one is created

get_lookup()
    Gets state lookup table.

     Type    : Accessor
     Title   : get_lookup
     Usage   : my $lookup = $obj->get_lookup;
     Function: Returns the object's lookup hash
     Returns : A hash reference
     Args    : None

get_missing()
    Gets missing data symbol.

     Type    : Accessor
     Title   : get_missing
     Usage   : my $missing = $obj->get_missing;
     Function: Returns the object's missing data symbol
     Returns : A string
     Args    : None

get_gap()
    Gets gap symbol.

     Type    : Accessor
     Title   : get_gap
     Usage   : my $gap = $obj->get_gap;
     Function: Returns the object's gap symbol
     Returns : A string
     Args    : None

get_meta_for_state()
    Gets metadata annotations (if any) for the provided state symbol

     Type    : Accessor
     Title   : get_meta_for_state
     Usage   : my @meta = @{ $obj->get_meta_for_state };
     Function: Gets metadata annotations for a state symbol
     Returns : An array reference of Bio::Phylo::NeXML::Meta objects
     Args    : A state symbol

get_metas_for_states()
    Gets metadata annotations (if any) for all state symbols

     Type    : Accessor
     Title   : get_metas_for_states
     Usage   : my @meta = @{ $obj->get_metas_for_states };
     Function: Gets metadata annotations for state symbols
     Returns : An array reference of Bio::Phylo::NeXML::Meta objects
     Args    : None

  TESTS

is_ambiguous()
    Tests whether the supplied state symbol represents an ambiguous (polymorphic or uncertain) state. For example, for the most commonly-used alphabet for DNA states, the symbol 'N' represents complete uncertainty, the actual state could be any of 'A', 'C', 'G' or 'T', and so this method would return a true value.

     Type    : Test
     Title   : is_ambiguous
     Usage   : if ( $obj->is_ambiguous('N') ) {
                  # do something
               }
     Function: Returns true if argument is an ambiguous state symbol
     Returns : BOOLEAN
     Args    : A state symbol

is_valid()
    Validates argument.

     Type    : Test
     Title   : is_valid
     Usage   : if ( $obj->is_valid($datum) ) {
                  # do something
               }
     Function: Returns true if $datum only contains valid characters
     Returns : BOOLEAN
     Args    : A Bio::Phylo::Matrices::Datum object

is_same()
    Compares data type objects.

     Type    : Test
     Title   : is_same
     Usage   : if ( $obj->is_same($obj1) ) {
                  # do something
               }
     Function: Returns true if $obj1 contains the same validation rules
     Returns : BOOLEAN
     Args    : A Bio::Phylo::Matrices::Datatype::* object

  UTILITY METHODS

split()
    Splits argument string of characters following appropriate rules.

     Type    : Utility method
     Title   : split
     Usage   : $obj->split($string)
     Function: Splits $string into characters
     Returns : An array reference of characters
     Args    : A string

join()
    Joins argument array ref of characters following appropriate rules.

     Type    : Utility method
     Title   : join
     Usage   : $obj->join($arrayref)
     Function: Joins $arrayref into a string
     Returns : A string
     Args    : An array reference

  SERIALIZERS

to_xml()
    Writes data type definitions to xml

     Type    : Serializer
     Title   : to_xml
     Usage   : my $xml = $obj->to_xml
     Function: Writes data type definitions to xml
     Returns : An xml string representation of data type definition
     Args    : None

to_dom()
    Analog to to_xml.

     Type    : Serializer
     Title   : to_dom
     Usage   : $type->to_dom
     Function: Generates a DOM subtree from the invocant
               and its contained objects
     Returns : an <XML Package>::Element object
     Args    : none

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
    This object inherits from Bio::Phylo, so the methods defined therein are also applicable to Bio::Phylo::Matrices::Datatype 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>