NAME

Bio::Phylo::Matrices::Matrix - Character state matrix

SYNOPSIS

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

# instantiate taxa object
my $taxa = $fac->create_taxa;
for ( 'Homo sapiens', 'Pan paniscus', 'Pan troglodytes' ) {
    $taxa->insert( $fac->create_taxon( '-name' => $_ ) );
}

# instantiate matrix object, 'standard' data type. All categorical
# data types follow semantics like this, though with different
# symbols in lookup table and matrix
my $standard_matrix = $fac->create_matrix(
    '-type'   => 'STANDARD',
    '-taxa'   => $taxa,
    '-lookup' => { 
        '-' => [],
        '0' => [ '0' ],
        '1' => [ '1' ],
        '?' => [ '0', '1' ],
    },
    '-labels' => [ 'Opposable big toes', 'Opposable thumbs', 'Not a pygmy' ],
    '-matrix' => [
        [ 'Homo sapiens'    => '0', '1', '1' ],
        [ 'Pan paniscus'    => '1', '1', '0' ],
        [ 'Pan troglodytes' => '1', '1', '1' ],
    ],
);

# note: complicated constructor for mixed data!
my $mixed_matrix = Bio::Phylo::Matrices::Matrix->new( 
   
   # if you want to create 'mixed', value for '-type' is array ref...
   '-type' =>  [ 
   
       # ...with first field 'mixed'...                
       'mixed',
       
       # ...second field is an array ref...
       [
           
           # ...with _ordered_ key/value pairs...
           'dna'      => 10, # value is length of type range
           'standard' => 10, # value is length of type range
           
           # ... or, more complicated, value is a hash ref...
           'rna'      => {
               '-length' => 10, # value is length of type range
               
               # ...value for '-args' is an array ref with args 
               # as can be passed to 'unmixed' datatype constructors,
               # for example, here we modify the lookup table for
               # rna to allow both 'U' (default) and 'T'
               '-args'   => [
                   '-lookup' => {
                       'A' => [ 'A'                     ],
                       'C' => [ 'C'                     ],
                       'G' => [ 'G'                     ],
                       'U' => [ 'U'                     ],
                       'T' => [ 'T'                     ],
                       'M' => [ 'A', 'C'                ],
                       'R' => [ 'A', 'G'                ],
                       'S' => [ 'C', 'G'                ],
                       'W' => [ 'A', 'U', 'T'           ],
                       'Y' => [ 'C', 'U', 'T'           ],
                       'K' => [ 'G', 'U', 'T'           ],
                       'V' => [ 'A', 'C', 'G'           ],
                       'H' => [ 'A', 'C', 'U', 'T'      ],
                       'D' => [ 'A', 'G', 'U', 'T'      ],
                       'B' => [ 'C', 'G', 'U', 'T'      ],
                       'X' => [ 'G', 'A', 'U', 'T', 'C' ],
                       'N' => [ 'G', 'A', 'U', 'T', 'C' ],
                   },
               ],
           },
       ],
   ],
);

# prints 'mixed(Dna:1-10, Standard:11-20, Rna:21-30)'
print $mixed_matrix->get_type;

DESCRIPTION

This module defines a container object that holds Bio::Phylo::Matrices::Datum objects. The matrix object inherits from Bio::Phylo::Listable, so the methods defined there apply here.

METHODS

CONSTRUCTOR

new()

Matrix constructor.

Type    : Constructor
Title   : new
Usage   : my $matrix = Bio::Phylo::Matrices::Matrix->new;
Function: Instantiates a Bio::Phylo::Matrices::Matrix
          object.
Returns : A Bio::Phylo::Matrices::Matrix object.
Args    : -type   => optional, but if used must be FIRST argument, 
                     defines datatype, one of dna|rna|protein|
                     continuous|standard|restriction|[ mixed => [] ]

          -taxa   => optional, link to taxa object
          -lookup => character state lookup hash ref
          -labels => array ref of character labels
          -matrix => two-dimensional array, first element of every
                     row is label, subsequent are characters

new_from_bioperl()

Matrix constructor from Bio::Align::AlignI argument.

Type    : Constructor
Title   : new_from_bioperl
Usage   : my $matrix = 
          Bio::Phylo::Matrices::Matrix->new_from_bioperl(
              $aln           
          );
Function: Instantiates a 
          Bio::Phylo::Matrices::Matrix object.
Returns : A Bio::Phylo::Matrices::Matrix object.
Args    : An alignment that implements Bio::Align::AlignI

MUTATORS

set_special_symbols

Sets three special symbols in one call

Type    : Mutator
Title   : set_special_symbols
Usage   : $matrix->set_special_symbols( 
		       -missing   => '?', 
		       -gap       => '-', 
		       -matchchar => '.' 
		   );
Function: Assigns state labels.
Returns : $self
Args    : Three args (with distinct $x, $y and $z):
 		       -missing   => $x, 
		       -gap       => $y, 
		       -matchchar => $z
Notes   : This method is here to ensure
          you don't accidentally use the
          same symbol for missing AND gap

set_statelabels()

Sets argument state labels.

Type    : Mutator
Title   : set_statelabels
Usage   : $matrix->set_statelabels( [ [ 'state1', 'state2' ] ] );
Function: Assigns state labels.
Returns : $self
Args    : ARRAY, or nothing (to reset);
          The array is two-dimensional, 
          the first index is to indicate
          the column the labels apply to,
          the second dimension the states
          (sorted numerically or alphabetically,
          depending on what's appropriate)

set_characters()

Sets the character set manager object Bio::Phylo::Matrices::Characters. Normally you never have to use this.

Type    : Mutator
Title   : set_characters
Usage   : $matrix->set_characters( $characters );
Function: Assigns Bio::Phylo::Matrices::Characters object
Returns : $self
Args    : Bio::Phylo::Matrices::Characters

set_charlabels()

Sets argument character labels.

Type    : Mutator
Title   : set_charlabels
Usage   : $matrix->set_charlabels( [ 'char1', 'char2', 'char3' ] );
Function: Assigns character labels.
Returns : $self
Args    : ARRAY, or nothing (to reset);

set_gapmode()

Defines matrix gapmode.

Type    : Mutator
Title   : set_gapmode
Usage   : $matrix->set_gapmode( 1 );
Function: Defines matrix gapmode ( false = missing, true = fifth state )
Returns : $self
Args    : boolean

set_matchchar()

Assigns match symbol.

Type    : Mutator
Title   : set_matchchar
Usage   : $matrix->set_matchchar( $match );
Function: Assigns match symbol (default is '.').
Returns : $self
Args    : ARRAY

set_polymorphism()

Defines matrix 'polymorphism' interpretation.

Type    : Mutator
Title   : set_polymorphism
Usage   : $matrix->set_polymorphism( 1 );
Function: Defines matrix 'polymorphism' interpretation
          ( false = uncertainty, true = polymorphism )
Returns : $self
Args    : boolean

set_raw()

Set contents using two-dimensional array argument.

Type    : Mutator
Title   : set_raw
Usage   : $matrix->set_raw( [ [ 'taxon1' => 'acgt' ], [ 'taxon2' => 'acgt' ] ] );
Function: Syntax sugar to define $matrix data contents.
Returns : $self
Args    : A two-dimensional array; first dimension contains matrix rows,
          second dimension contains taxon name / character string pair.

set_respectcase()

Defines matrix case sensitivity interpretation.

Type    : Mutator
Title   : set_respectcase
Usage   : $matrix->set_respectcase( 1 );
Function: Defines matrix case sensitivity interpretation
          ( false = disregarded, true = "respectcase" )
Returns : $self
Args    : boolean

ACCESSORS

get_special_symbols()

Retrieves hash ref for missing, gap and matchchar symbols

Type    : Accessor
Title   : get_special_symbols
Usage   : my %syms = %{ $matrix->get_special_symbols };
Function: Retrieves special symbols
Returns : HASH ref, e.g. { -missing => '?', -gap => '-', -matchchar => '.' }
Args    : None.

get_characters()

Retrieves characters object.

Type    : Accessor
Title   : get_characters
Usage   : my $characters = $matrix->get_characters
Function: Retrieves characters object.
Returns : Bio::Phylo::Matrices::Characters
Args    : None.

get_statelabels()

Retrieves state labels.

Type    : Accessor
Title   : get_statelabels
Usage   : my @statelabels = @{ $matrix->get_statelabels };
Function: Retrieves state labels.
Returns : ARRAY
Args    : None.

get_charlabels()

Retrieves character labels.

Type    : Accessor
Title   : get_charlabels
Usage   : my @charlabels = @{ $matrix->get_charlabels };
Function: Retrieves character labels.
Returns : ARRAY
Args    : None.

get_gapmode()

Returns matrix gapmode.

Type    : Accessor
Title   : get_gapmode
Usage   : do_something() if $matrix->get_gapmode;
Function: Returns matrix gapmode ( false = missing, true = fifth state )
Returns : boolean
Args    : none

get_matchchar()

Returns matrix match character.

Type    : Accessor
Title   : get_matchchar
Usage   : my $char = $matrix->get_matchchar;
Function: Returns matrix match character (default is '.')
Returns : SCALAR
Args    : none

get_nchar()

Calculates number of characters.

Type    : Accessor
Title   : get_nchar
Usage   : my $nchar = $matrix->get_nchar;
Function: Calculates number of characters (columns) in matrix (if the matrix
          is non-rectangular, returns the length of the longest row).
Returns : INT
Args    : none

get_ntax()

Calculates number of taxa (rows) in matrix.

Type    : Accessor
Title   : get_ntax
Usage   : my $ntax = $matrix->get_ntax;
Function: Calculates number of taxa (rows) in matrix
Returns : INT
Args    : none

get_polymorphism()

Returns matrix 'polymorphism' interpretation.

Type    : Accessor
Title   : get_polymorphism
Usage   : do_something() if $matrix->get_polymorphism;
Function: Returns matrix 'polymorphism' interpretation
          ( false = uncertainty, true = polymorphism )
Returns : boolean
Args    : none

get_raw()

Retrieves a 'raw' (two-dimensional array) representation of the matrix's contents.

Type    : Accessor
Title   : get_raw
Usage   : my $rawmatrix = $matrix->get_raw;
Function: Retrieves a 'raw' (two-dimensional array) representation
          of the matrix's contents.
Returns : A two-dimensional array; first dimension contains matrix rows,
          second dimension contains taxon name and characters.
Args    : NONE

get_respectcase()

Returns matrix case sensitivity interpretation.

Type    : Accessor
Title   : get_respectcase
Usage   : do_something() if $matrix->get_respectcase;
Function: Returns matrix case sensitivity interpretation
          ( false = disregarded, true = "respectcase" )
Returns : boolean
Args    : none

CALCULATIONS

calc_prop_invar()

Calculates proportion of invariant sites.

 Type    : Calculation
 Title   : calc_prop_invar
 Usage   : my $pinvar = $matrix->calc_prop_invar;
 Function: Calculates proportion of invariant sites.
 Returns : Scalar: a number
 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

calc_state_counts()

Calculates occurrences of states.

Type    : Calculation
Title   : calc_state_counts
Usage   : my %counts = %{ $matrix->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_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

calc_distinct_site_patterns()

Identifies the distinct distributions of states for all characters and counts their occurrences. Returns an array-of-arrays, where the first cell of each inner array holds the occurrence count, the second cell holds the pattern, i.e. an array of states. For example, for a matrix like this:

taxon1 GTGTGTGTGTGTGTGTGTGTGTG
taxon2 AGAGAGAGAGAGAGAGAGAGAGA
taxon3 TCTCTCTCTCTCTCTCTCTCTCT
taxon4 TCTCTCTCTCTCTCTCTCTCTCT
taxon5 AAAAAAAAAAAAAAAAAAAAAAA
taxon6 CGCGCGCGCGCGCGCGCGCGCGC
taxon7 AAAAAAAAAAAAAAAAAAAAAAA

The following data structure will be returned:

 [
	[ 12, [ 'G', 'A', 'T', 'T', 'A', 'C', 'A' ] ],
	[ 11, [ 'T', 'G', 'C', 'C', 'A', 'G', 'A' ] ]
 ]

The patterns are sorted from most to least frequently occurring, the states for each pattern are in the order of the rows in the matrix. (In other words, the original matrix can more or less be reconstructed by inverting the patterns, and multiplying them by their occurrence, although the order of the columns will be lost.)

Type    : Calculation
Title   : calc_distinct_site_patterns
Usage   : my $patterns = $object->calc_distinct_site_patterns;
Function: Calculates distinct site patterns.
Returns : A multidimensional array, see above.
Args    : NONE
Comments:

calc_gc_content()

Calculates the G+C content as a fraction on the total

 Type    : Calculation
 Title   : calc_gc_content
 Usage   : my $fraction = $obj->calc_gc_content;
 Function: Calculates G+C content
 Returns : A number between 0 and 1 (inclusive)
 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 'BadArgs' exception if matrix holds anything other than DNA
           or RNA. The calculation also takes the IUPAC symbol S (which is C|G)
	   into account, but no other symbols (such as V, for A|C|G);

METHODS

keep_chars()

Creates a cloned matrix that only keeps the characters at the supplied (zero-based) indices.

Type    : Utility method
Title   : keep_chars
Usage   : my $clone = $object->keep_chars([6,3,4,1]);
Function: Creates spliced clone.
Returns : A spliced clone of the invocant.
Args    : Required, an array ref of integers
Comments: The columns are retained in the order in 
          which they were supplied.

prune_chars()

Creates a cloned matrix that omits the characters at the supplied (zero-based) indices.

Type    : Utility method
Title   : prune_chars
Usage   : my $clone = $object->prune_chars([6,3,4,1]);
Function: Creates spliced clone.
Returns : A spliced clone of the invocant.
Args    : Required, an array ref of integers
Comments: The columns are retained in the order in 
          which they were supplied.

prune_invariant()

Creates a cloned matrix that omits the characters for which all taxa have the same state (or missing);

Type    : Utility method
Title   : prune_invariant
Usage   : my $clone = $object->prune_invariant;
Function: Creates spliced clone.
Returns : A spliced clone of the invocant.
Args    : None
Comments: The columns are retained in the order in 
          which they were supplied.

prune_uninformative()

Creates a cloned matrix that omits all uninformative characters. Uninformative are considered characters where all non-missing values are either invariant or autapomorphies.

Type    : Utility method
Title   : prune_uninformative
Usage   : my $clone = $object->prune_uninformative;
Function: Creates spliced clone.
Returns : A spliced clone of the invocant.
Args    : None
Comments: The columns are retained in the order in 
          which they were supplied.

bootstrap()

Creates bootstrapped clone.

Type    : Utility method
Title   : bootstrap
Usage   : my $bootstrap = $object->bootstrap;
Function: Creates bootstrapped clone.
Returns : A bootstrapped clone of the invocant.
Args    : Optional, a subroutine reference that returns a random
          integer between 0 (inclusive) and the argument provided
          to it (exclusive). The default implementation is to use
          sub { int( rand( shift ) ) }, a user might override this
          by providing an implementation with a better random number
          generator.
Comments: The bootstrapping algorithm uses perl's random number
          generator to create a new series of indices (without
          replacement) of the same length as the original matrix.
          These indices are first sorted, then applied to the 
          cloned sequences. Annotations (if present) stay connected
          to the resampled cells.

jackknife()

Creates jackknifed clone.

Type    : Utility method
Title   : jackknife
Usage   : my $bootstrap = $object->jackknife(0.5);
Function: Creates jackknifed clone.
Returns : A jackknifed clone of the invocant.
Args    : * Required, a number between 0 and 1, representing the
            fraction of characters to jackknife. 
          * Optional, a subroutine reference that returns a random
            integer between 0 (inclusive) and the argument provided
            to it (exclusive). The default implementation is to use
            sub { int( rand( shift ) ) }, a user might override this
            by providing an implementation with a better random number
            generator.
Comments: The jackknife algorithm uses perl's random number
          generator to create a new series of indices of cells to keep.
          These indices are first sorted, then applied to the 
          cloned sequences. Annotations (if present) stay connected
          to the resampled cells.

clone()

Clones invocant.

Type    : Utility method
Title   : clone
Usage   : my $clone = $object->clone;
Function: Creates a copy of the invocant object.
Returns : A copy of the invocant.
Args    : NONE

insert()

Insert argument in invocant.

Type    : Listable method
Title   : insert
Usage   : $matrix->insert($datum);
Function: Inserts $datum in $matrix.
Returns : Modified object
Args    : A datum object
Comments: This method re-implements the method by the same
          name in Bio::Phylo::Listable

compress_lookup()

Removes unused states from lookup table

Type    : Method
Title   : validate
Usage   : $obj->compress_lookup
Function: Removes unused states from lookup table
Returns : $self
Args    : None

check_taxa()

Validates taxa associations.

Type    : Method
Title   : check_taxa
Usage   : $obj->check_taxa
Function: Validates relation between matrix and taxa block 
Returns : Modified object
Args    : None
Comments: This method implements the interface method by the same
          name in Bio::Phylo::Taxa::TaxaLinker

make_taxa()

Creates a taxa block from the objects contents if none exists yet.

Type    : Method
Title   : make_taxa
Usage   : my $taxa = $obj->make_taxa
Function: Creates a taxa block from the objects contents if none exists yet.
Returns : $taxa
Args    : NONE

SERIALIZERS

to_xml()

Serializes matrix to nexml format.

Type    : Format convertor
Title   : to_xml
Usage   : my $data_block = $matrix->to_xml;
Function: Converts matrix object into a nexml element structure.
Returns : Nexml block (SCALAR).
Args    : Optional:
		   -compact => 1 (for compact representation of matrix)

to_nexus()

Serializes matrix to nexus format.

Type    : Format convertor
Title   : to_nexus
Usage   : my $data_block = $matrix->to_nexus;
Function: Converts matrix object into a nexus data block.
Returns : Nexus data block (SCALAR).
Args    : The following options are available:

           # if set, writes TITLE & LINK tokens
           '-links' => 1
           
           # if set, writes block as a "data" block (deprecated, but used by mrbayes),
           # otherwise writes "characters" block (default)
           -data_block => 1
           
           # if set, writes "RESPECTCASE" token
           -respectcase => 1
           
           # if set, writes "GAPMODE=(NEWSTATE or MISSING)" token
           -gapmode => 1
           
           # if set, writes "MSTAXA=(POLYMORPH or UNCERTAIN)" token
           -polymorphism => 1
           
           # if set, writes character labels
           -charlabels => 1
           
           # if set, writes state labels
           -statelabels => 1
           
           # if set, writes mesquite-style charstatelabels
           -charstatelabels => 1
           
           # by default, names for sequences are derived from $datum->get_name, if 
           # 'internal' is specified, uses $datum->get_internal_name, if 'taxon'
           # uses $datum->get_taxon->get_name, if 'taxon_internal' uses 
           # $datum->get_taxon->get_internal_name, if $key, uses $datum->get_generic($key)
           -seqnames => one of (internal|taxon|taxon_internal|$key)

to_dom()

Analog to to_xml.

Type    : Serializer
Title   : to_dom
Usage   : $matrix->to_dom
Function: Generates a DOM subtree from the invocant
          and its contained objects
Returns : an Element object
Args    : Optional:
          -compact => 1 : renders characters as sequences,
                          not individual cells

SEE ALSO

Bio::Phylo::Taxa::TaxaLinker

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