NAME
Bio::NEXUS - An object-oriented Perl Applications Programming Interface (API) for the NEXUS file format
SYNOPSIS
my $nexus =Bio::NEXUS->new($file);
# if $file is not provided, an empty Bio::NEXUS object will be created
$nexus->write($newfile);DESCRIPTION
This is the base class for the Bio::NEXUS package, providing an object-oriented API to the NEXUS file format of Maddison, et al., 1997. This module provides methods to add/remove blocks, select blocks/trees/subtrees/OTUs/characters and so on. For a tutorial illustrating how to use Bio::NEXUS, see "Tutorial.pod" in doc.
FEEDBACK
All feedback (bugs, feature enhancements, etc.) are all greatly appreciated.
AUTHORS
Chengzhi Liang (liangc@umbi.umd.edu)
Weigang Qiu (weigang@genectr.hunter.cuny.edu)
Peter Yang (pyang@rice.edu)
Thomas Hladish (tjhladish at yahoo)
Arlin Stoltzfus (arlin.stoltzfus@nist.gov)METHODS
new
Title : new
Usage : my $nexus = Bio::NEXUS->new($filename, $verbose);
Function: Creates a new Bio::NEXUS object
Returns : Bio::NEXUS object
Args : $filename, $verbose, or noneget_bionexus_version
Title : get_bionexus_version
Usage : Bio::NEXUS->get_bionexus_version();
Function: gets the package version
Returns : value of \$VERSION
Args : noneread_file
Title : read_file
Usage : Bio::NEXUS->read_file($filename, $verbose);
Function: Reads the contents of the NEXUS file and populate the data in the Bio::NEXUS object
Returns : None
Args : $filename, $verbose, or noneread
Title : read
Usage : Bio::NEXUS->read({format => 'string', 'param' => $buffer, 'verbose' => $verbose});
Usage : Bio::NEXUS->read({format => 'file', 'param' => $filename, 'verbose' => $verbose});
Function: Reads the contents of the NEXUS file and populate the data in the NEXUS object
Returns : None
Args : $filename, $verbose, or nonecreate_block
Title : create_block
Usage : my $block = Bio::NEXUS->create_block($blocktype,$block_string, $verbose);
Function: Creates a block object based on the input block type and block content as string
Returns : A block object (If Block type is 'Characters' then 'Bio::NEXUS::CharactersBlock' is returned
Args : $block_type (as string), $block_content (as string), verboseclone
Name : clone
Usage : my $newnexus = $nexus->clone();
Function: clone a NEXUS object; each block is also (shallow) cloned.
Returns : new Bio::NEXUS object
Args : noneset_name
Title : set_name
Usage : Bio::NEXUS->set_name($name);
Function: Sets name for the NEXUS object (usually the filename).
Returns : Nothing
Args : $name (as string)get_name
Title : get_name
Usage : $name = Bio::NEXUS->get_name();
Function: Returns the name of the NEXUS object as string. (NEXUS filename).
Returns : NEXUS filename
Args : Noneadd_comment
Name : add_comment
Usage : $nexus->add_comment($comment);
Function: add a block of comments.
Returns : none
Args : a string objectget_comments
Name : get_comments
Usage : $nexus->get_comments();
Function: Retrieves all comments.
Returns : ref to an array of strings
Args : noneget_filename
Name : get_filename
Usage : $nexus->get_filename;
Function: get the NEXUS filename for this object.
Returns : A filename
Args : noneset_blocks
Name : set_blocks
Usage : $nexus->set_blocks($blocks);
Function: set the blocks in this nexus file.
Returns : none
Args : an array of Block objectsadd_block
Name : add_block
Usage : $nexus->add_block($block_obj);
Function: add a block.
Returns : none
Args : a Bio::NEXUS::*Block objectremove_block
Name : remove_block
Usage : $nexus->remove_block($blocktype, $title);
Function: remove a block
Returns : none
Args : block type and block name (strings)get_block
Name : get_block
Usage : $nexus->get_block($blocktype, $blockname);
Function: Retrieves NEXUS block.
Returns : A Bio::NEXUS::*Block object
Args : noneget_blocks
Name : get_blocks
Usage : $nexus->get_blocks($blocktype);
Function: Retrieves list of blocks of some type or all blocks.
Returns : Array of Bio::NEXUS::Block objects
Args : $blocktype or noneget_blocks_and_comments
Name : get_blocks_and_comments
Usage : @blocks_and_comments = @{ $nexus->get_blocks_and_comments() };
Function: get all comments and blocks in the NEXUS object
Returns : array of strings and block objects
Args : noneget_weights
Name : get_weights
Usage : $nexus->get_weights($charblockname);
Function: get all weights for a block.
Returns : the weights of alignments in a Characters Block
Args : an hash of weightset objectsget_taxlabels
Name : get_taxlabels
Usage : $nexus->get_taxlabels();
Function: get the taxa labels of the NEXUS object (obtained from TAXA block).
Returns : an arrayreference of taxa labels.
Args : noneget_otus
Name : get_otus
Usage : $nexus->get_otus();
Function: Retrieves list of OTUs
Returns : Array of OTU names or Bio::NEXUS::TaxUnit objects
Args : nonerename_otus
Name : rename_otus
Usage : $nexus->rename_otus(\%translation);
Function: rename all OTUs
Returns : a new nexus object with new OTU names
Args : a ref to hash based on OTU name pairsadd_otu_clone
Name : add_otu_clone
Usage : $nexus_object->add_otu_clone($original_otu_name, $copy_otu_name);
Function: creates a copy of a specified otu inside this Bio::NEXUS object
Returns : n/a
Args : $original_otu_name (string) - the name of the otu that will be cloned, $copy_otu_name (string) - the desired name for the new clone
Preconditions : $original_otu_name and $copy_otu_name are not equal, $original_otu_name is a valid otu name (existing otu)select_blocks
Name : select_blocks
Usage : $nexus->select_blocks(\@blocknames);
Function: select a subset of blocks
Returns : a new nexus object
Args : a ref to array of block names to be selectedexclude_blocks
Name : exclude_blocks
Usage : $nexus->exclude_blocks(\@blocknames);
Function: remove a subset of blocks
Returns : a new nexus object
Args : a ref to array of block names to be removedselect_otus
Name : select_otus
Usage : $nexus->select_otus(\@otunames);
Function: select a subset of OTUs
Returns : a new nexus object
Args : a ref to array of OTU namesexclude_otus
Name : exclude_otus
Usage : $nexus->exclude_otus(\@otunames);
Function: remove a subset of OTUs
Returns : a new nexus object
Args : a ref to array of OTU names to be removedselect_tree
Name : select_tree
Usage : $nexus->select_tree($treename);
Function: select a tree
Returns : a new nexus object
Args : a tree nameselect_subtree
Name : select_subtree
Usage : $nexus->select_subtree($inodename);
Function: select a subtree
Returns : a new nexus object
Args : an internal node name for subtree to be selectedexclude_subtree
Name : exclude_subtree
Usage : $nexus->exclude_subtree($inodename);
Function: remove a subtree
Returns : a new nexus object
Args : an internal node for subtree to be removedselect_chars
Name : select_chars
Usage : $nexus->select_chars(\@columns);
Function: select a subset of characters
Returns : a new nexus object
Args : a ref to array of character columnsexclude_chars
Name : exclude_chars
Usage : $nexus->exclude_chars($columns,block_type);
Function: exclude specified columns from a block.
Returns : new nexus object
Args : column numbers to exclude as array reference, block_type as stringreroot
Name : reroot
Usage : $nexus->reroot($outgroupname);
Function: reroot the tree using the new outgroup
Returns : a new nexus object
Args : a OTU name as new outgroupequals
Name : equals
Usage : $nexus->equals($another);
Function: compare if two Bio::NEXUS objects are equal
Returns : boolean
Args : a Bio::NEXUS objectwrite
Name : write
Usage : $nexus->write($filename, $verbose);
Function: Writes to NEXUS file from stored NEXUS data
Returns : none
Args : file name (string) for output to file or '-' or 'STDOUT' for standard outputset_taxablock
Name : set_taxablock
Usage : $nexus->set_taxablock();
Function: Sets taxablock if taxablock is not already defined in the nexus object
Returns : none
Args : none