Phylo.API

The Phylo.API submodule provides the API that must be extended for new AbstractTree, AbstractNode and AbstractBranch subtypes.

Usage

Providing additional code to extend the functionality of the system is simple:

using Phylo

struct SimplestTree <: AbstractTree{Int, Int}
    nodes::OrderedDict{Int, BinaryNode{Int}}
    branches::Dict{Int, Branch{Int}}
end

import Phylo.API: _addnode!
function _addnode!(tree::SimplestTree, num)
    _setnode!(tree, num, BinaryNode{Int}())
    return num
end

creates a new SimplestTree type (a subtype of AbstractTree) and extends Phylo.API._addnode!() (and therefore the directly accessible addnode!() interface) to handle the SimplestTree subtype of AbstractTree. See docs here to see which Phylo.API functions have to be extended for any new subtype, and which have default implementations.

Phylo.API — Module

Phylo.API submodule

The Phylo.API submodule should be imported if you want to create a new phylogeny, node or branch subtype. Otherwise it can be ignored.

Phylo.API._addconnection! — Function

_addconnection!(tree::AbstractTree, node::AbstractNode, branch)

Add a connection to an unrooted node. Must be implemented for any unrooted AbstractNode subtype unless this happens when a branch is added.

Phylo.API._addinbound! — Function

_addinbound!(tree::AbstractTree, node::AbstractNode, inbound)

Adds a branch to the input of a rooted node. Must be implemented for any rooted AbstractNode subtype unless this happens when a branch is created.

Phylo.API._addoutbound! — Function

_addoutbound!(tree::AbstractTree, node::AbstractNode, branch)

Add an outbound branch to a rooted node. Must be implemented for any Rooted AbstractNode subtype unless this happens when a branch is created.

Phylo.API._branchdatatype — Function

_branchdatatype(::Type{<:AbstractTree})

Returns the type of the branch info data.

Phylo.API._branchdims — Function

_branchdims(::Type{<:AbstractTree})

Returns the dimensions of the branch lengths for the tree.

Phylo.API._clearrootheight! — Function

_clearrootheight!(::AbstractTree)

Phylo.API._conn — Function

_conn(branch::AbstractBranch, exclude::AbstractNode)

Return the connection for a branch that isn't the exclude node. May be implemented for any Unrooted AbstractBranch subtype, otherwise will use _conns.

Phylo.API._conns — Function

_conns(tree::AbstractTree, branch::AbstractBranch)

Return a vector of connections for a branch. Must be implemented for any Unrooted AbstractBranch subtype, otherwise can combine _src and _dst.

Phylo.API._createbranch! — Function

_createbranch!(tree::AbstractTree, source, destination[,
               length][, data])

Create a new branch and add it to a tree. Must be implemented for any AbstractTree subtype.

Phylo.API._createnode! — Function

_createnode!(tree::AbstractTree, nodename[, data])

Must be implemented for any AbstractTree subtype.

Phylo.API._degree — Function

_degree(tree::AbstractTree, node::AbstractNode)

Degree of node. Must be implemented for Unrooted nodes, otherwise can be inferred from indegree and outdegree.

Phylo.API._deletebranch! — Function

_deletebranch!(tree::AbstractTree, branch)

Delete a branch, reoving it from a tree. Must be implemented for any AbstractTree subtype.

Phylo.API._deletenode! — Function

_deletenode!(tree::AbstractTree, nodename)

Must be implemented for any AbstractTree subtype.

Phylo.API._dst — Function

_dst(branch::AbstractBranch)

Return destination node for a branch. Must be implemented for any rooted AbstractBranch subtype.

Phylo.API._getbranch — Function

_getbranch(::AbstractTree, id)

Returns the branch or name associated with id (which could be a name or a branch) from a tree. Must be implemented for any PreferBranchObjects tree and branch label type.

Phylo.API._getbranches — Function

_getbranches(tree::AbstractTree)

Returns a vector of branches for a OneTree tree. Either _getbranches() or _getbranchnames() must be implemented for any OneTree tree type.

Phylo.API._getbranchname — Function

_getbranchname(::AbstractTree, id)

Returns the name of a branch associated with id (which could be a name or a branch) from a tree. Must be implemented for PreferBranchObjects tree types.

Phylo.API._getbranchnames — Function

_getbranchnames(tree::AbstractTree)

Returns a vector of branch names for a OneTree tree. Either _getbranches() or _getbranchnames() must be implemented for any OneTree tree type.

Phylo.API._getchildren — Function

_getchildren(tree::AbstractTree, node)
_getchildren(tree::AbstractTree, nodename)

Return the child node(s) for this node. May be implemented for any rooted AbstractNode subtype.

Phylo.API._getconnections — Function

_getconnections(tree::AbstractTree, node::AbstractNode)

Returns all of the connections of a node. Must be implemented for any unrooted AbstractNode subtype, can be inferred from _getinbound and _getoutbounds for a rooted node.

Phylo.API._getheight — Method

_getheight(tree::AbstractTree, nodename)

Phylo.API._getinbound — Function

_getinbound(tree::AbstractTree, node::AbstractNode)

Get the inbound connection. Must be implemented for any rooted AbstractNode subtype.

Phylo.API._getleafnames — Function

_getleafnames(::AbstractTree, ::TraversalOrder)

Returns the leaf names of a tree. May be implemented for any tree type (otherwise determined from _getnodenames() and _isleaf() functions).

Phylo.API._getleaves — Function

_getleaves(::AbstractTree)

Returns the leaves (tips) of a single tree. May be implemented for any OneTree type (otherwise determined from _getnodes() and _isleaf() functions).

Phylo.API._getlength — Function

_getlength

Return length of a branch. May be implemented for any AbstractBranch subtype.

Phylo.API._getnode — Function

_getnode(::AbstractTree, id)

Returns the node or name associated with id (which could be a name or a node) from a tree. Must be implemented for any PreferNodeObjects tree and node label type.

Phylo.API._getnodename — Function

_getnodename(::AbstractTree, id)

Returns the name of a node associated with id (which could be a name or a node) from a tree. Must be implemented for PreferNodeObjects tree types.

Phylo.API._getnodenames — Function

_getnodenames(tree::AbstractTree{OneTree})

Returns an iterable collection of node names for a OneTree tree. Can be implemented for any OneTree tree type, especially PreferNodeObjects trees.

Phylo.API._getnodes — Function

_getnodes(tree::AbstractTree{OneTree}[, order::TraversalOrder])

Returns an interable collection of nodes for a OneTree tree. _getnodes(tree) must be implemented for a OneTree tree type as a base mechanisms for extracting the node list.

Phylo.API._getoutbounds — Function

_getoutbounds(tree::AbstractTree, node::AbstractNode)

Returns the outbound connections of a rooted node. Must be implemented for any rooted AbstractNode subtype.

Phylo.API._getparent — Function

_getparent(tree::AbstractTree, node)

Return the parent node for this node. Can be implemented for Rooted node types.

Phylo.API._getroot — Function

_getroot(::AbstractTree)

Returns the unique root of a rooted tree. May be implemented for any OneTree type (otherwise determined from _getroots()).

Phylo.API._getrootheight — Function

_getrootheight(::AbstractTree)

Phylo.API._getroots — Method

_getroots(::AbstractTree)

Returns the root(s) of a tree. May be implemented for any OneTree type (otherwise determined from _getnodes() and _isroot() functions).

Phylo.API._getsiblings — Function

_getsiblings(tree::AbstractTree, node::AbstractNode)

Returns all of the siblings (actually immediate connections) of a node. May be implemented for any AbstractNode subtype, can be inferred from _getparent and _getchildren for a rooted node or _getconnections for an unrooted node.

Phylo.API._gettree — Function

_gettree(::Pair{Label, AbstractTree})
_gettree(::AbstractTree, id)

Returns a tree - either itself if it is a single tree, or the single tree in a set with label id. Must be implemented for any ManyTrees type.

Phylo.API._gettreeinfo — Function

_gettreeinfo(tree::AbstractTree)
_gettreeinfo(tree::AbstractTree, treename)

Returns the info data associated with the tree(s).

Phylo.API._gettreename — Function

_gettreename(::AbstractTree)

Returns the name for a single tree. Should be implemented for any OneTree type where they have names.

Phylo.API._gettreenames — Function

_gettreenames(::AbstractTree)

Returns the names for the trees. Can be implemented for any ManyTrees type.

Phylo.API._gettrees — Function

_gettrees(::AbstractTree)

Returns the trees in an object. Must be implemented for any ManyTrees type.

Phylo.API._hasbranch — Function

_hasbranch(tree::AbstractTree, node[name])

Does the tree contain this branch? Must be implemented for any PreferBranchObjects tree type with a branch label.

Phylo.API._hasheight — Method

_hasheight(tree::AbstractTree, nodename)

Phylo.API._hasinbound — Function

_hasinbound(tree::AbstractTree, node::AbstractNode)

Must be implemented for any AbstractNode subtype.

Phylo.API._hasinboundspace — Function

_hasinboundspace(tree::AbstractTree, node::AbstractNode)

Is there space for a new inbound connection on a node?

Phylo.API._haslength — Function

_haslength

Return length of a branch. May be implemented for any AbstractBranch subtype.

Phylo.API._hasnode — Function

_hasnode(tree::AbstractTree, node[name])

Does the tree contain this node? Must be implemented for any PreferNodeObjects tree type with a node label.

Phylo.API._hasoutboundspace — Function

_hasoutboundspace(tree::AbstractTree, node::AbstractNode)

Is there space for a new outbound connection on a node? Must be implemented if a node has a limit on the number of outbound connections (eg for a binary tree)

Phylo.API._hasrootheight — Method

_hasrootheight(::AbstractTree)

Phylo.API._hasspace — Function

_hasspace(tree::AbstractTree, node::AbstractNode)

Is there space for a new connection on a node? Must be implemented if a node has a limit on the number of connections (eg for a binary tree)

Phylo.API._indegree — Function

_indegree(tree::AbstractTree, node)

In degree of node. Can be implemented for rooted nodes, otherwise inferred from _hasinbound.

Phylo.API._invalidate! — Function

_invalidate!(::AbstractTree, state)

Confirm that the tree is no longer necessarily valid, and remove cache information.

Phylo.API._isinternal — Function

_isinternal(tree::AbstractTree, node)

Is the node internal to the tree?

Phylo.API._isleaf — Function

_isleaf(tree::AbstractTree, node)

Is the node a leaf? Does not need to be implemented for any node type – inferred from _outdegree or _degree - unless tree knows which nodes are leaves and not nodes.

Phylo.API._isroot — Function

_isroot(tree::AbstractTree, node)

Is the node a root node of the tree?

Phylo.API._isunattached — Method

_isunattached(tree::AbstractTree, node)

Does the node currently form its own (sub)tree?

Phylo.API._leafinfotype — Function

_leafinfotype(::Type{<:AbstractTree})

Returns the type of the leaf info data.

Phylo.API._matchbranchnodetype — Function

_matchbranchnodetype(::Type{<:AbstractTree},
                     ::Type{<:AbstractBranch},
                     ::Type{<:AbstractNode})

Does this tree type prefer the branch and node types provided?

Phylo.API._matchbranchtype — Function

_matchbranchtype(::Type{<:AbstractTree}, ::Type{<:AbstractBranch})

Does this tree type prefer the branch or branch label type provided?

Phylo.API._matchnodetype — Function

_matchnodetype(::Type{<:AbstractTree{TT, RT, NL, N, B}}, ::Type{N})
_matchnodetype(::Type{<:AbstractTree{TT, RT, NL, N, B}}, ::Type{NL})

Does this tree type prefer the node or node label type provided?

Phylo.API._matchtreenametype — Method

_matchtreenametype(::Type{<:AbstractTree}, ::Type{X})

Does this tree type prefer the node or node label type provided?

Phylo.API._nbranches — Method

_nbranches(::AbstractTree)

Returns the number of branches in a single tree. May be implemented for any OneTree tree type (otherwise infers from _getbranches()).

Phylo.API._newbranchlabel — Function

_newbranchlabel(tree::AbstractTree)

Returns a new unique branch name for a tree.

Phylo.API._newnodelabel — Function

_newnodelabel(tree::AbstractTree)

Returns a new unique node name for a tree.

Phylo.API._nleaves — Method

_nleaves(::AbstractTree)

Returns the number of leaves (tips) in a tree. May be implemented for any tree type (otherwise determined from the _getleafnames() function).

Phylo.API._nnodes — Method

_nnodes(::AbstractTree)

Returns the number of nodes (internal nodes and leaves) in a single tree. May be implemented for any OneTree tree type (otherwise infers from _getnodes()).

Phylo.API._nodedatatype — Function

_nodedatatype(::Type{<:AbstractTree})

Returns the type of the node info data.

Phylo.API._nroots — Function

_nroots(::AbstractTree)

Returns the number of roots (subtrees) in a OneTree tree. May be implemented for any ManyRoots type (otherwise infers from _getroots()).

Phylo.API._ntrees — Function

_ntrees(::AbstractTree)

Returns the number of trees in an object. Must be implemented for any ManyTrees type.

Phylo.API._outdegree — Function

_outdegree(tree::AbstractTree, node::AbstractNode)

Out degree of node.

Phylo.API._preferbranchobjects — Function

_preferbranchobjects(::Type{<:AbstractTree})

Does this tree or branch type prefer branches to be objects or names? Must be implemented for every branch type.

Phylo.API._prefernodeobjects — Function

_prefernodeobjects(::Type{<:AbstractTree})

Does this tree or node type prefer nodes to be objects or names? Must be implemented for every node type.

Phylo.API._removeconnection! — Function

_removeconnection!(tree::AbstractTree, node::AbstractNode, branch)

Remove a connection from an unrooted node. Must be implemented for any Unrooted AbstractNode subtype unless this happens when a branch is deleted.

Phylo.API._removeinbound! — Function

_removeinbound!(tree::AbstractTree, node::AbstractNode, inbound)

Removes a branch from the input of a rooted node. Must be implemented for any rooted AbstractNode subtype unless this happens when a branch is deleted.

Phylo.API._removeoutbound! — Function

_removeoutbound!(tree::AbstractTree, node::AbstractNode, branch)

Remove an outbound branch from a rooted node. Must be implemented for any AbstractNode subtype unless this happens when a branch is deleted.

Phylo.API._renamenode! — Function

_renamenode!(tree::AbstractTree, oldnode[name], newname)

Renames a node in a tree. Optional - not implemented for most tree types.

Phylo.API._resetleaves! — Function

_resetleaves!(::AbstractTree)

Fixes leaf naming after creation or deletion of nodes or branches. Must be implemented by tree types where this is handled separately.

Phylo.API._setheight! — Method

_setheight!(::AbstractTree, nodename, value)

Phylo.API._setrootheight! — Function

_setrootheight!(::AbstractTree, value)

Phylo.API._src — Function

_src(tree, branch)

Return source node for a branch. Must be implemented for any rooted branch type.

Phylo.API._traversal — Function

_traversal(tree::AbstractTree, order::TraversalOrder, todo, sofar)

Return an iterable object containing nodes in given order - preorder, inorder, postorder or breadthfirst

Phylo.API._treenametype — Function

_treenametype(::Type{AbstractTree})

Returns the label type for a tree type. Must be implemented for any tree type.

Phylo.API._validate! — Function

_validate!(::AbstractTree)

Check whether the tree is internally valid.