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

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

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

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

source
Phylo.API._connFunction
_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.

source
Phylo.API._connsFunction
_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.

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

source
Phylo.API._createnode!Function
_createnode!(tree::AbstractTree, nodename[, data])

Must be implemented for any AbstractTree subtype.

source
Phylo.API._degreeFunction
_degree(tree::AbstractTree, node::AbstractNode)

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

source
Phylo.API._deletebranch!Function
_deletebranch!(tree::AbstractTree, branch)

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

source
Phylo.API._dstFunction
_dst(branch::AbstractBranch)

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

source
Phylo.API._getbranchFunction
_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.

source
Phylo.API._getbranchesFunction
_getbranches(tree::AbstractTree)

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

source
Phylo.API._getbranchnameFunction
_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.

source
Phylo.API._getbranchnamesFunction
_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.

source
Phylo.API._getchildrenFunction
_getchildren(tree::AbstractTree, node)
_getchildren(tree::AbstractTree, nodename)

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

source
Phylo.API._getconnectionsFunction
_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.

source
Phylo.API._getinboundFunction
_getinbound(tree::AbstractTree, node::AbstractNode)

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

source
Phylo.API._getleafnamesFunction
_getleafnames(::AbstractTree)

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

source
Phylo.API._getleavesFunction
_getleaves(::AbstractTree)

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

source
Phylo.API._getnodeFunction
_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.

source
Phylo.API._getnodenameFunction
_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.

source
Phylo.API._getnodenamesFunction
_getnodenames(tree::AbstractTree{OneTree})

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

source
Phylo.API._getnodesFunction
_getnodes(tree::AbstractTree{OneTree})

Returns a vector of nodes for a OneTree tree. Either _getnodes() must be implemented for any OneTree tree type.

source
Phylo.API._getoutboundsFunction
_getoutbounds(tree::AbstractTree, node::AbstractNode)

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

source
Phylo.API._getparentFunction
_getparent(tree::AbstractTree, node)

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

source
Phylo.API._getrootFunction
_getroot(::AbstractTree)

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

source
Phylo.API._getrootsMethod
_getroots(::AbstractTree)

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

source
Phylo.API._getsiblingsFunction
_getsiblings(tree::AbstractTree, node::AbstractNode)

Returns all of the siblings 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.

source
Phylo.API._gettreeFunction
_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.

source
Phylo.API._gettreeinfoFunction
_gettreeinfo(tree::AbstractTree)
_gettreeinfo(tree::AbstractTree, treename)

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

source
Phylo.API._gettreenameFunction
_gettreename(::AbstractTree)

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

source
Phylo.API._gettreenamesFunction
_gettreenames(::AbstractTree)

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

source
Phylo.API._gettreesFunction
_gettrees(::AbstractTree)

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

source
Phylo.API._hasbranchFunction
_hasbranch(tree::AbstractTree, node[name])

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

source
Phylo.API._hasinboundFunction
_hasinbound(tree::AbstractTree, node::AbstractNode)

Must be implemented for any AbstractNode subtype.

source
Phylo.API._hasnodeFunction
_hasnode(tree::AbstractTree, node[name])

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

source
Phylo.API._hasoutboundspaceFunction
_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)

source
Phylo.API._hasspaceFunction
_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)

source
Phylo.API._indegreeFunction
_indegree(tree::AbstractTree, node)

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

source
Phylo.API._invalidate!Function
_invalidate!(::AbstractTree, state)

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

source
Phylo.API._isleafFunction
_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.

source
Phylo.API._matchbranchnodetypeFunction
_matchbranchnodetype(::Type{<:AbstractTree},
                     ::Type{<:AbstractBranch},
                     ::Type{<:AbstractNode})

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

source
Phylo.API._matchbranchtypeFunction
_matchbranchtype(::Type{<:AbstractTree}, ::Type{<:AbstractBranch})

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

source
Phylo.API._matchnodetypeFunction
_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?

source
Phylo.API._nbranchesMethod
_nbranches(::AbstractTree)

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

source
Phylo.API._nleavesMethod
_nleaves(::AbstractTree)

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

source
Phylo.API._nnodesMethod
_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()).

source
Phylo.API._nrootsFunction
_nroots(::AbstractTree)

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

source
Phylo.API._ntreesFunction
_ntrees(::AbstractTree)

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

source
Phylo.API._preferbranchobjectsFunction
_preferbranchobjects(::Type{<:AbstractTree})

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

source
Phylo.API._prefernodeobjectsFunction
_prefernodeobjects(::Type{<:AbstractTree})

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

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

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

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

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

source
Phylo.API._srcFunction
_src(tree, branch)

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

source
Phylo.API._traversalFunction
_traversal(tree::AbstractTree, order::TraversalOrder, todo, sofar)

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

source
Phylo.API._treenametypeFunction
_treenametype(::Type{AbstractTree})

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

source