phylojs/lib/esm/tree/tree.d.ts

A simple typescript library for phylogenetic trees

import { Node } from './node';
export declare class Tree {
    /** Public property used to construct tree */
    root: Node;
    /** A public property */
    private _nodeList;
    /** A public property */
    nodeIDMap: {
        [key: number]: Node;
    } | undefined;
    /** A public property */
    labelNodeMap: {
        [key: string]: Node;
    } | undefined;
    /** A public property */
    private _leafList;
    /** A public property */
    recombEdgeMap: {
        [key: string]: Node[];
    } | undefined;
    /** A public property*/
    ultrametric: boolean | undefined;
    /**
     * The constructor of the `Tree` class.
     *
     * @param {Node} root Root node
     */
    constructor(root: Node);
    /**
     * Convenience function applied function post-order to all nodes in the tree.
     * Is a wrapper for `Node.applyPostOrder()`
     * @param {function} func Function to apply to each node
     */
    applyPostOrder(func: (node: Node) => void): void;
    /**
     * Convenience function applied function pre-order to all nodes in the tree.
     * Is a wrapper for `Node.applyPreOrder()`
     * @param {function} func Function to apply to each node
     */
    applyPreOrder(func: (node: Node) => void): void;
    /**
     * Computes height of each node above the root. Automatically done if rerooting.
     * NaN if any undefined branch lengths ancestral to a particular node. Contrasts
     * `Tree.getRTTD()` in not converting undefined branch lengths to 0.0.
     */
    computeNodeHeights(): void;
    /**
     * Reflects whether all tips are the same age (0), equivalently if they are
     * all the same height about the root. Only makes sense for time trees.
     * Sets property on tree object and returns boolean. The tolerance for differences
     * in tip heights is 1e-6 as a default, but can be adjusted.
     * @param {number} tol
     * @returns {boolean}
     */
    isUltrametric(tol?: number): boolean;
    /**
     * Ladderises the tree.
     * Applies a pre-order search. For each node, child nodes are ordered by increasing number of descending tips
     */
    ladderise(): void;
    /** Return branch lengths in order matching .nodeList */
    getBranchLengths(): (number | undefined)[];
    /** Returns root to tip distances. Counts undefined branch lengths as zero */
    getRTTDist(): number[];
    /** Assign new node IDs (use with care!) */
    reassignNodeIDs(): void;
    /** Clear various node caches */
    clearCaches(): void;
    /** A getter that returns an array of nodes (`Node[]`) from private `_nodeList` property in order determined by a pre-order search*/
    get nodeList(): Node[];
    /**
     * Get node given its numerical `id`
     * @param {number} nodeID Numerical id of node
     */
    getNode(nodeID: number): Node | null;
    /** A getter that returns an array of nodes (`Node[]`) from private `_nodeList` property in order determined by a pre-order search*/
    get leafList(): Node[];
    /**
     * Retrieve node having given label
     * @param {string} label Node's label
     */
    getNodeByLabel(label: string): Node | null;
    /** Retrieve map from recomb edge IDs to src/dest node pairs */
    getRecombEdgeMap(): {
        [key: string]: Node[];
    };
    /**
     * Check if node is a source node for a hybrid edge in the tree.
     * @param {Node} node
     * @returns {boolean}
     */
    isRecombSrcNode(node: Node): boolean;
    /**
     * Check if node is a destination node for a hybrid edge in the tree.
     * @param {Node} node
     * @returns {boolean}
     */
    isRecombDestNode(node: Node): boolean;
    /**
     * Check if the tree is a phylogenetic network.
     * @param {Node} node
     * @returns {boolean}
     */
    isNetwork(): boolean;
    /**
     * Return sub-stree descending from a given `node`
     * @parm {Node} root node root of desired subtree
     */
    getClade(node: Node): Tree;
    /**
     * Get the most recent common ancestor of a set of nodes
     * @param {Node[]} nodes Nodes for which the MRCA is sought
     */
    getMRCA(nodes: Node[]): Node | null;
    /**
     * Get all tip names from tree or descending from a `node`
     * @param {Node | undefined} node Optional node whose descending tips are returned. Defaults to root
     */
    getTipLabels(node?: Node): string[];
    /** Sum of all defined branch lengths. Elsewhere referred to tree "length" if all baranch lengths are defined */
    getTotalBranchLength(): number;
    /**
     * Reroot a tree at a given node.
     * @param {Node} edgeBaseNode `Node` to reroot at
     * @param {number|undefined} prop Proportion of the branch descending from `edgeBaseNode` at which to cut and place the root. Defaults ot 0.5
     */
    reroot(edgeBaseNode: Node, prop?: number): void;
    /**
     * Returns height above the root for each internal node. Root height is assumed to be 0
     * and undefined branch lengths are assumed to be zero.
     * @returns {number[]}
     */
    getInternalNodeHeights(): number[];
    /**
     * Calculates Gamma statistic from Pybus and Harvey 2000 (10.1098/rspb.2000.1278 ).
     * The Gamma statistic measures deviation from a constant rate pure-birth process
     * in the underlying population (also known as a Yule process). Values above 0 indicate
     *  longer external branches, while values corresond to internal branches. Calculating the Gamma statistic involves
     * manipulations that mean the statistic should follow a standard normal distribution,
     * such that one can perform a frequentist test to measure consistency with the pure birth
     * process.
     *
     * Since the Gamma statistic applies to a pure birth process, the tree is expected to be
     * ultrametric and the method throws an error if it is not. It also returns NaN if any node
     * node heights are undefined, due to undefined branch lengths.
     *
     * @param {number} tol Tolerance for ultrametricity passed to `.isUltrametric()`
     * @returns {number}
     *
     */
    gammaStatistic(tol?: number): number;
    /**
     * Returns the Sackin Index, which measures imbalance as the sum of the number of tips
     * descending from each internal node. The sum increases for more imbalances (ladder-like) trees.
     * See Chapter 5 in "Tree balance indices: a comprehensive survey" (https://doi.org/10.1007/978-3-031-39800-1_5)
     * for further details, a reference we point to from the treebalance R package
     * @returns {number}
     */
    sackinIndex(): number;
    /**
     * Check whether the tree is binary (each internal node has <= 2 descendents)
     * @returns {any}
     */
    isBinary(): boolean;
    /**
     * Returns the Colless Imbalance (CI) index, with an option to normalise or use the standard method.
     * The CI is defined for binary trees, so NaN is returned if the tree is not binary.
     * In essence, the CI adds the difference between the number of tips descending from each internal node.
     * The square of each difference is taking if the method selected is quadratic. If the method is set to
     * "corrected", then the overall sum is scaled by the number of tips. If method is "standard", then
     * sum is returned.
     * The value should be smaller for more balanced trees (less ladder-like). As for the Sacking Index,
     * see "Tree balance indices: a comprehensive survey
     * (https://doi.org/10.1007/978-3-031-39800-1_12, https://doi.org/10.1007/978-3-031-39800-1_13, https://doi.org/10.1007/978-3-031-39800-1_15)
     * for further details.
     * @param {"standard" | "normalised" | "quadratic"} method
     * @returns {number}
     */
    collessIndex(method?: 'standard' | 'corrected' | 'quadratic'): number;
}