GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  BIO::PHYLO::MATRICES::MATRIXROLE (3)

.ds Aq ’

NAME

Bio::Phylo::Matrices::MatrixRole - Extra behaviours for a character state matrix

CONTENTS

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 dont accidentally use the
           same symbol for missing AND gap



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



    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_charlabels() Retrieves character labels.



 Type    : Accessor
 Title   : get_charlabels
 Usage   : my @charlabels = @{ $matrix->get_charlabels };
 Function: Retrieves character labels.
 Returns : ARRAY
 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_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 matrixs contents.
 Returns : A two-dimensional array; first dimension contains matrix rows,
           second dimension contains taxon name and characters.
 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.



prune_missing_and_gaps() Creates a cloned matrix that omits all characters for which the invocant only has missing and/or gap states.



 Type    : Utility method
 Title   : prune_missing_and_gaps
 Usage   : my $clone = $object->prune_missing_and_gaps;
 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 perls 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 perls 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.



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

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

<B>Rutger A VosB>, <B>Jason CaravasB>, <B>Klaas HartmannB>, <B>Mark A JensenB> and <B>Chase MillerB>, 2011. Bio::Phylo - phyloinformatic analysis using Perl. BMC Bioinformatics <B>12B>:63. <http://dx.doi.org/10.1186/1471-2105-12-63>

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 BIO::PHYLO::MATRICES::MATRIXROLE (3) 2014-03-27

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.