phylojs/lib/io/readers/newick.d.ts

A simple typescript library for phylogenetic trees

import { Tree, Node } from '../../';
/**
 * Parse a string in the New Hampshire (Newick) format and return a tree object.
 *
 * This function reads a Newick string from left to right. It is based on
 * the `kn_parse` function by Heng Li for jstreeview (https://github.com/lh3/jstreeview/blob/main/knhx.js),
 * modified for compatibility with our Tree object and to prevent ';' assignment as root label.
 *
 * Supports node annotations in both BEAST [&...] and NHX [&&NHX:...] formats through the annotationParser parameter.
 * Users can provide their own annotation parser function to handle custom formats.
 * Also handles hybrid nodes marked with # notation following Cardona et al. 2008.
 *
 * If the input string contains multiple trees (separated by newlines), only the first tree is parsed
 * and a warning is issued. Use readTreesFromNewick() to parse multiple trees.
 *
 * Node IDs are unique and allocated in order of parsing. Specifically, leaf node IDs are numbered
 * according to the order in which they are encountered. Where a close parenthesis ')' is
 * encountered, an internal node is added with an incremented ID. This means that leaf node IDs
 * are not guaranteed to be contiguous or numbered from 0 to n-1. For example, for `(A,B);`, leaf A has index 1,
 * leaf B has index 2, and the root node has index 3. In general the root will have the highest index.
 *
 * To renumber nodes, one could use `.preorderTraversal()` or `.postorderTraversal()` methods.
 *
 * @param {string} newick - The string in Newick format to parse
 * @returns {Tree} - The constructed phylogenetic tree
 */
export declare function readNewick(newick: string, annotationParser?: (annotations: string) => typeof Node.prototype.annotation): Tree;
/**
 * Reads .newick strings, separated by ';' and returns an array of Trees.
 * @param {string} newick
 * @returns {Tree[]} Tree
 */
export declare function readTreesFromNewick(newick: string): Tree[];
interface HybridInformation {
    label: string | undefined;
    hybridID: number;
}
/**
 * Function parses hybrid id labels, which are assumed to contain '#'.
 * Following Cardona et al. 2008, (https://doi.org/10.1186/1471-2105-9-532).
 * Function expects unparsed labels to be of the form [label]#[type]i[:branch-length]
 * where '#' and i (the hybrid node ID) are mandatory. PhyloJS ignores the type annotation
 * (H for hybridisation, LGT for lateral gene transfer, R for recombination) and extracts only
 * the label and hybridID, following icyTREE.
 * @param {string} label
 * @returns {HybridInformation}
 */
export declare function parseHybridLabels(label: string): HybridInformation;
/**
 * Users can provide theit own annotation parsers.
 *
 * Note that square brackets are hard-coded in readNewick() as open and close
 * delimiters for annotations. This is a limitation, but as far as we know, all
 * annotations in Newick format are enclosed in square brackets.
 *
 * In the future, we may want to add support for custom open and close
 * delimiters, but this would require a more complex parsing logic.
 *
 * In the complementary function custon annotation writers, users can define their own
 * open and close delimiters.
 *
 * @typedef {function} annotationParser
 * @param {string} annotations - The string containing annotations in Newick format
 * @returns {typeof Node.prototype.annotation} - The parsed annotations as key value pairs
 * @property {string} [key] - The key of the annotation
 * @property {any} [value] - The value of the annotation
 */
export type AnnotationParser = (annotations: string) => typeof Node.prototype.annotation;
/**
 * Parses BEAST-type annotations in format [&...] to object for storage
 * in `Node` object. Annotations in arrays are expected to be stored in braces,
 * and separated by ',' or ':'. For example ...Type={Blue,Red} or ...Type={Blue:Red}
 * @param {string} annotations - The string containing annotations in Newick format
 * @returns {typeof Node.prototype.annotation} - The parsed annotations as key value pairs
 * @property {string} [key] - The key of the annotation
 * @property {any} [value] - The value of the annotation
 */
export declare function parseBeastAnnotations(annotations: string): typeof Node.prototype.annotation;
/**
 * Parses NHX-type annotations in format [&&NHX:...] to object for storage
 * in `Node` object. Annotations in arrays are expected to be stored in braces.
 * @param {string} annotations - The string containing annotations in Newick format
 * @returns {typeof Node.prototype.annotation} - The parsed annotations as key value pairs
 * @property {string} [key] - The key of the annotation
 * @property {any} [value] - The value of the annotation
 */
export declare function parseNHXAnnotations(annotations: string): typeof Node.prototype.annotation;
/**
 * Default annotation parser that checks for both BEAST and NHX formats
 * @param {string} annotations - The string containing annotations in Newick format
 * @returns {typeof Node.prototype.annotation} - The parsed annotations as key value pairs
 * @property {string} [key] - The key of the annotation
 * @property {any} [value] - The value of the annotation
 */
export declare function parseNewickAnnotations(annotations: string): typeof Node.prototype.annotation;
export {};