/ 
Bio-Phylo-0.23
/ Bio::Phylo::Matrices::Datatype

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 '-'

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_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

TESTS

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

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.

REVISION

$Id: Datatype.pm 1247 2010-03-04 15:47:17Z rvos $