Table of Contents

• version
  • Examples
• Branch
  • Parameters
  • addChild
    • Parameters
  • addParent
    • Parameters
  • ancestors
  • clone
  • consolidate
  • copy
  • count
  • descendants
  • depthOf
    • Parameters
  • distanceBetween
    • Parameters
  • distanceTo
    • Parameters
  • each
    • Parameters
  • eachAfter
    • Parameters
  • eachBefore
    • Parameters
  • eachChild
    • Parameters
  • excise
  • fixDistances
  • fixParenthood
    • Parameters
  • flip
  • getAncestors
    • Parameters
  • getChild
    • Parameters
  • getDescendant
    • Parameters
  • getDescendants
    • Parameters
  • getLeafs
  • getLeaves
  • getMRCA
    • Parameters
  • getRoot
  • hasChild
    • Parameters
  • hasDescendant
    • Parameters
  • hasLeaf
    • Parameters
  • invert
  • isChildOf
    • Parameters
  • isConsistent
  • isDescendantOf
    • Parameters
  • isLeaf
  • isolate
  • isRoot
  • leafs
  • leaves
  • links
  • normalize
    • Parameters
    • Examples
  • path
    • Parameters
  • remove
  • replace
    • Parameters
  • reroot
    • Examples
  • rotate
    • Parameters
  • setLength
    • Parameters
  • setParent
    • Parameters
  • simplify
  • sort
    • Parameters
  • sources
    • Parameters
  • sum
    • Parameters
  • targets
    • Parameters
  • toJSON
  • toMatrix
  • toNewick
    • Parameters
  • toObject
  • toString
    • Parameters
• parseJSON
  • Parameters
• parseMatrix
  • Parameters
• parseNewick
  • Parameters

version

The SemVer version string of the patristic library

Type: String

Examples

console.log(patristic.version);

Branch

A class for representing Branches in trees. It’s written predominantly for phylogenetic trees (hence the Newick parser, neighbor-joining implementation, etc.), but could conceivably be useful for representing other types of trees as well.

Parameters

• data Object? An object containing data you wish to assign to this Branch object. In particular, intended to overwrite the default attributes of a Branch, namely id, parent, length, and children.
• children

addChild

Adds a new child to this Branch

Parameters

• data (Branch | Object) The new Branch, or data to attach to it. (optional, default {})

Returns Branch The (possibly new) child Branch

addParent

Adds a new parent to this Branch. This is a bit esoteric and generally not recommended.

Parameters

• data (Branch | Object) A Branch object, or the data to attach to one (optional, default {})
• siblings Array An array of Branches to be the children of the new parent Branch (i.e. siblings of this Branch) (optional, default [])

Returns Branch The Branch on which this was called

ancestors

Returns an array of Branches from this Branch to the root. d3-hierarchy compatibility method.

Type: Array

clone

Returns a deep clone of the Branch on which it is called. Note that this does not clone all descendants, rather than providing references to the existing descendant Branches.

Returns Branch A clone of the Branch on which it is called.

consolidate

All descendant Branches with near-zero length are excised

Returns Branch The Branch on which this method was called.

copy

Returns a clone of the Branch on which it is called. Note that this also clones all descendants, rather than providing references to the existing descendant Branches. (For a shallow clone, see Branch.clone. Finally, the cloned Branch will become the root of the cloned tree, having a parent of null. d3-hierarchy compatibility method.

Returns Branch A clone of the Branch on which it is called.

count

Sets the values of all nodes to be equal to the number of their descendants.

Returns Branch The Branch on which it was called

descendants

Returns an array pf descendants, starting with this Branch. d3-hierarchy compatibility method.

Type: Array

depthOf

Returns the depth of a given child, relative to the Branch on which it is called.

Parameters

• descendant (Branch | String) A descendant Branch (or id string thereof)

Returns Number The sum of the lengths of all Branches between the Branch on which it is called and descendant. Throws an error if descendant is not a descendant of this Branch.

distanceBetween

Computes the patristic distance between descendantA and descendantB.

Parameters

• descendantA Branch The Branch from which you wish to compute distance
• descendantB Branch The Branch to which you wish to compute distance

Returns number The patristic distance between the given descendants.

distanceTo

Computes the patristic distance between cousin and the Branch on which this method is called.

Parameters

• cousin Branch The Branch to which you wish to compute distance

Returns number The patristic distance between cousin and the Branch on this method is called.

each

Visits each Branch descended from the Branch on which it is called in Breadth First Search order and returns the Branch on which it was called.

Parameters

• callback Function The function to be run on each Branch

Returns Branch The Branch on which it was called.

eachAfter

Visits each Branch descended from the Branch on which it is called in post-traversal order and returns the Branch on which it was called.

Parameters

• callback Function Function to run on each Branch

Returns Branch The Branch on which it was called

eachBefore

Visits each Branch descended from the Branch on which it is called in pre-traversal order and returns the Branch on which it was called.

Parameters

• callback Function [description]

Returns [type] [description]

eachChild

Runs a function on each child of the Branch on which it is called.

Parameters

• callback Function The function to run on each child.

Returns Branch The Branch on which it was called.

excise

Excises the Branch on which it is called and updates its parent and children.

Returns Branch The parent of the excised Branch.

fixDistances

Sets the distance values (height and depth) for each Branch

Returns Branch The Branch on which it is called.

fixParenthood

Repairs incorrect links by recurively confirming that children reference their parents, and correcting those references if they do not.

If you need to call this, something has messed up the state of your tree and you should be concerned about that. Just FYI. ¯\(ツ)/¯

Parameters

• nonrecursive Boolean Should this just fix the children of the Branch on which it is called, or all descendants?

Returns Branch The Branch on which it was called.

flip

Reverses the order of (all of) the descendants of the Branch.

Returns Branch The Branch on which this was called.

getAncestors

Returns an Array of all the ancestors of the Branch on which it is called. Note that this does not include itself. For all ancestors and itself, see Branch.ancestors

Parameters

• includeSelf Boolean Should the Branch on which this is called be included in the results?

Returns Array Every Ancestor of the Branch on which it was called.

getChild

Given an childID, returns the child with that id (or undefined if no such child is present).

Parameters

• childID String the ID of the child to return.

Returns (Branch | undefined) The desired child Branch, or undefined if the child doesn’t exist.

getDescendant

Given an id string, returns the descendant Branch with that ID, or undefined if it doesn’t exist.

Parameters

• id String The id string of the Branch to find

Returns (Branch | undefined) The descendant Branch, or undefined if it doesn’t exist

getDescendants

Returns an array of all Branches which are descendants of this Branch

Parameters

• includeSelf Boolean? Is this not the Branch on which the user called the function? This is used internally and should be ignored.

Returns Array An array of all Branches descended from this Branch

getLeafs

Returns an array of all leaves which are descendants of this Branch. Alias of getLeaves for people whose strong suit isn’t spelling.

Returns Array An array of all leaves descended from this Branch

getLeaves

Returns an array of all leaves which are descendants of this Branch See also: getLeafs

Returns Array An array of all leaves descended from this Branch

getMRCA

Traverses the tree upward until it finds the Most Recent Common Ancestor (i.e. the first Branch for which both the Branch on which it was called and cousin are descendants).

Parameters

• cousin

Returns Branch The Most Recent Common Ancestor of both the Branch on which it was called and the cousin.

getRoot

Traverses the tree upward until it finds the root Branch, and returns the root.

Returns Branch The root Branch of the tree

hasChild

Determines if a given Branch (or ID) is a child of this Branch

Parameters

• child (Branch | String) The Branch (or the id thereof) to check for

Returns Boolean

hasDescendant

Checks to see if descendant is a descendant of the Branch on which this method is called.

Parameters

• descendant (Branch | String) Either the descendant Branch or its’ id.

Returns Boolean True if descendant is descended from the Branch from which this is called, otherwise false.

hasLeaf

Checks to see if a Branch has a descendant leaf.

Parameters

• leaf

Returns Boolean True if leaf is both a leaf and a descendant of the Branch on which this method is called, False otherwise.

invert

Swaps the branch on which it is called with its parent. This method is probably only useful as an internal component of Branch.reroot.

Returns Branch The Branch object on which it was called.

isChildOf

Returns whether the Branch on which it is called is a child of a given parent (or parent ID).

Parameters

• parent (Branch | String) A Branch (or ID thereof) to test for paternity of this Branch.

Returns Boolean True is parent is the parent of this Branch, false otherwise.

isConsistent

Tests whether this and each descendant Branch holds correct links to both its parent and its children.

Returns Boolean True if consistent, otherwise false

isDescendantOf

Returns whether a given Branch is an ancestor of the Branch on which this method is called. Uses recursive tree-climbing.

Parameters

• ancestor Branch The Branch to check for ancestorhood

Returns Boolean If this Branch is descended from ancestor

isLeaf

Returns a boolean indicating if this Branch is a leaf (i.e. has no children).

Returns Boolean True is this Branch is a leaf, otherwise false.

isolate

Returns a boolean indicating whether or not this Branch is olate.

…Just kidding!

Isolates a Branch and its subtree (i.e. removes everything above it, making it the root Branch). Similar to Branch.remove, only it returns the Branch on which it is called.

Returns Branch The Branch object on which it was called.

isRoot

Returns a boolean indicating if this Branch is the root of a tree (i.e. has no parents).

Returns Boolean True if this Branch is the root, otherwise false.

leafs

Returns the array of leaf nodes in traversal order; leaves are nodes with no children. Alias of Branch.getLeaves `cuz spelling is hard.

Type: Array

leaves

Returns the array of leaf nodes in traversal order; leaves are nodes with no children. Alias of Branch.getLeaves. d3-hierarchy compatibility method.

Type: Array

links

Returns an Array of links, which are plain javascript objects containing a source attribute (which is a reference to the parent Branch) and a target attribute (which is a reference to the child Branch). d3-hierarchy compatibility method

Returns Array An array of plain Javascript objects

normalize

Normalizes this and all descendant Branches value attributes to between newmin and newmax. Note that normalize can function as its own inverse when passed an original range. For example:

Parameters

• newmin Number The desired minimum value.
• newmax Number The desired maximum value.

Examples

tree.normalize().normalize(1, tree.getDescendants().length + 1);

Returns Branch The Branch on which it was called.

path

Gets the path from this Branch to target. If this Branch and target are the same, returns an array containing only the Branch on which it is called.

Parameters

• target Branch A Branch object

Returns Array An ordered Array of Branches following the path between this Branch and target

remove

Removes a Branch and its subtree from the tree. Similar to Branch.isolate, only it returns the root Branch of the tree from which this Branch is removed.

Returns Branch The root of the remaining tree.

replace

Removes a Branch and its subtree from the tree, and replaces it.

Parameters

• replacement Branch The branch to replace the branch on which the method is called.

Returns Branch The root of the modified tree.

reroot

Reroots a tree on this Branch. Use with caution, this returns the new root, which should typically supplant the existing root Branch object, but does not replace that root automatically.

Examples

tree = tree.children[0].children[0].reroot();

Returns Branch The new root Branch, which is the Branch on which this was called

rotate

Reverses the order of the children of the branch on which it is called.

Parameters

• recursive

Returns Branch The Branch on which this was called.

setLength

Set the length of a Branch

Parameters

• length number The new length to assign to the Branch

Returns Branch The Branch object on which this was called

setParent

Sets the parent of the Branch on which it is called.

Parameters

• parent Branch The Branch to set as parent

Returns Branch The Branch on which this method was called.

simplify

Collapses each descendant Branch with exactly one child into a single continuous branch.

Returns Branch The Branch on which this method was called.

sort

Sorts the Tree from the branch on which it is called downward.

Parameters

• comparator Function? A Function taking two Branches and returning a numberic value. For details, see MDN Array.sort

Returns Branch The Branch on which it was called

sources

Determines whether this Branch is likelier to be a source of cousin, or if cousin is a source of this Branch.

Parameters

• cousin Branch The other Branch to test

Returns Boolean True if this might be the source of cousin, otherwise false.

sum

Computes the value of each Branch according to some valuator function

Parameters

• value Function A Function taking a Branch and returning a (numeric?) value.

Returns Branch The Branch on which it was called.

targets

Determines whether this Branch is likelier to be a target of cousin, or if cousin is a target of this Branch.

Parameters

• cousin Branch The other Branch to test

Returns Boolean True if this might be the target of cousin, otherwise false.

toJSON

toJSON is an alias for toObject, enabling the safe use of JSON.stringify on Branch objects (in spite of their circular references).

Type: Function

Returns Object A serializable Object

toMatrix

Computes a matrix of all patristic distances between all leaves which are descendants of the Branch on which this method is called.

Returns Object An Object containing a matrix (an Array of Arrays) and Array of ids corresponding to the rows (and columns) of the matrix.

toNewick

Returns the Newick representation of this Branch and its descendants.

Parameters

• nonterminus Boolean Is this not the terminus of the Newick Tree? This should be falsy when called by a user (i.e. you). It’s used internally to decide whether or not in include a semicolon in the returned string. (optional, default falsy)

Returns String The Newick representation of the Branch.

toObject

Returns a simple Javascript object version of this Branch and its descendants. This is useful in cases where you want to serialize the tree (e.g. JSON.stringify(tree)) but can’t because the tree contains circular references (for simplicity, elegance, and performance reasons, each Branch tracks both its children and its parent).

Returns Object A serializable bare Javascript Object representing this Branch and its descendants.

toString

Returns a valid JSON-string version of this Branch and its descendants.

Parameters

• replacer Function A replacer function to pass to JSON.stringify.
• width
• space (Number | String) A string or number of spaces to use for indenting the output. See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Parameters for additional details.

Returns Object A valid JSON string representing this Branch and its descendants.

parseJSON

Parses a hierarchical JSON string (or Object) as a Branch object.

Parameters

• json (String | Object) A json string (or Javascript Object) representing hierarchical data.
• idLabel String The key used in the objects of json to indicate their identifiers. (optional, default "id")
• lengthLabel String The key used in the objects of json to indicate their length. (optional, default 'length')
• childrenLabel String The key used in the objects of json to indicate their children. (optional, default `children`)

Returns Branch The Branch representing the root of the hierarchy represented by json.

parseMatrix

Parses a matrix of distances and returns the root Branch of the output tree. This is adapted from Maciej Korzepa’s neighbor-joining, which is released for modification under the MIT License.

Parameters

• matrix Array An array of n arrays of length n
• labels Array An array of n strings, each corresponding to the values in matrix.

Returns Branch A Branch object representing the root Branch of the tree inferred by neighbor joining on matrix.

parseNewick

Parses a Newick String and returns a Branch object representing the root of the output Tree. This is adapted Jason Davies’ newick.js, which is released for modification under the MIT License.

Parameters

• newick string A Newick String

Returns Branch A Branch representing the root of the output tree