README

newick-js

A Node.js module that parses strings into graphs according to the Newick tree format, and writes graphs as Newick tree strings.

Requirements

This module minimally requires ECMAScript 2015 (ES6), since it uses Set objects.

Installation

npm

npm install newick-js --save

yarn

yarn add newick-js

Usage

JavaScript and TypeScript

Importing the Functions

To import the functions in JavaScript:

const { parse, write } = require("newick-js");

To import the functions in TypeScript:

import { parse, write } from "newick-js";

To import separately (minimizing file size for tree-shaking):

import { parse } from "newick-js/dist/src/parse";
import { write } from "newick-js/dist/src/write";

Interface

(The type declarations are written in TypeScript.)

Vertices

A vertex is a plain object with an optional label field.

interface Vertex {
    label?: string;
}

Arcs

An arc is an array which includes, in order:

a head vertex (the parent),
a tail vertex (the child), and
a weight (a number, possibly NaN).

type Arc = [Vertex, Vertex, number];

Graphs

A graph is an array which includes, in order:

a set of vertices, and
a set of arcs.

type Graph = [Set<Vertex>, Set<Arc>];

Functions

The parse() function takes a string and yields a parse result, including a graph, a root vertex, and a weight for the root vertex (possibly NaN).

declare function parse(s: string): ParseResult;
interface ParseResult {
  graph: Graph;
  root: Vertex;
  rootWeight: number;
}

The write() method takes a graph and yields a Newick tree string.

declare function write(graph: Graph): string;

Example Usage

(JavaScript or TypeScript, after importing the functions)

const result = parse("(Pongo:15.76,(Gorilla:9.06,(Pan:6.65,Homo:6.65):2.41)Homininae:6.70)Hominidae:4.43;");
const root = result.root;
console.log(`Root: ${result.root.label}`);
console.log(`Root Weight: ${result.rootWeight}`);
const vertices = result.graph[0];
console.log(`Number of Vertices: ${vertices.size}`);
const arcs = result.graph[1];
console.log(`Number of Arcs: ${arcs.size}`);
console.log(write(result.graph));

Output:

> Root: Hominidae
> Root Weight: 4.43
> Number of Vertices: 7
> Number of Arcs: 6
> ((Homo:6.65,Pan:6.65):2.41,Gorilla:9.06)Homininae:6.7,(Pongo:15.76)Hominidae;

See test/test.js for further examples.

AMD

define(function(require, exports, module) {
  var newick = require('newick-js');
});

Testing

yarn test

Usage no npm install needed!