@gmod/newick

中文文档
1.1.0发布于 2026/11/11MITTypeScriptESM + CJS零依赖构建来源已验证近 30 天下载 2.3万

Newick parsing and stack-safe tree traversals, with no dependencies

原始使用文档

@gmod/newick

NPM version Build Status

Newick parsing and small tree utilities. No dependencies.

npm install @gmod/newick
import { hierarchy, leaves, parseNewick } from '@gmod/newick'

const tree = parseNewick('(A:0.1,B:0.2,(C:0.3,D:0.4)E:0.5)F;')
// { name: 'F', children: [
//   { name: 'A', length: 0.1 },
//   { name: 'B', length: 0.2 },
//   { name: 'E', length: 0.5, children: [
//     { name: 'C', length: 0.3 },
//     { name: 'D', length: 0.4 },
//   ] },
// ] }

const root = hierarchy(tree, d => d.children)
leaves(root).map(n => n.data.name) // ['A', 'B', 'C', 'D']

react-msaview and jbrowse-components use it for the parts of d3-hierarchy they needed, without the pure ESM requirement and with somewhat simpler types.

Every field parseNewick produces is optional — a node is { name?: string, length?: number, children?: NewickNode[] } — so a node with no children is a leaf, and a whole tree can be one bare node:

parseNewick('A;') // { name: 'A' }
parseNewick('(A,B)Foo;') // { name: 'Foo', children: [{ name: 'A' }, { name: 'B' }] }
parseNewick('(A:0.1,B:0.2)F:0.5;')
// { name: 'F', length: 0.5, children: [
//   { name: 'A', length: 0.1 },
//   { name: 'B', length: 0.2 },
// ] }

Single-quoted labels keep a name containing ,, : or parens in one piece, with '' for a literal quote. Without them a comma inside a label splits one leaf into two, which returns the wrong tree rather than merely a bad name:

parseNewick("('A,x','B (y)','it''s')Root;")
// { name: 'Root', children: [
//   { name: 'A,x' },
//   { name: 'B (y)' },
//   { name: "it's" },
// ] }

Square brackets are a comment, and the parser drops what is inside them. NHX and BEAST put their per-node metadata in brackets, and without the drop the parser would read the : characters inside an [&&NHX:...] block as branch lengths:

parseNewick('(A:0.1[&&NHX:S=human],B:0.2[&&NHX:S=mouse]);')
// { children: [{ name: 'A', length: 0.1 }, { name: 'B', length: 0.2 }] }

A bare number after a ) is a bootstrap value (a name) in a phylogeny, but a cluster height (a length) in a dendrogram. parseNewick reads it as a length only when the tree has no : branch length anywhere:

parseNewick('((A:1,B:1)95,(C:1,D:1)80);') // 95 and 80 are names
parseNewick('(A,B)1.5;') // { length: 1.5, children: [{ name: 'A' }, { name: 'B' }] }

The postParenNumeric option pins the reading; see docs/dialects.md.

hierarchy wraps any nested data, Newick or otherwise, in nodes with parent, depth and height. The traversals are free functions that walk the subtree under the node you pass:

import { descendants, find, leaves, links, sum } from '@gmod/newick'

const root = hierarchy(
  parseNewick('(A:0.1,B:0.2,(C:0.3,D:0.4)E:0.5)F;'),
  d => d.children,
)
const e = root.children[2]

descendants(root).map(n => n.data.name) // ['F', 'A', 'B', 'E', 'C', 'D']
leaves(root).map(n => n.data.name) // ['A', 'B', 'C', 'D']
leaves(e).map(n => n.data.name) // ['C', 'D'] — only under E
links(root).length // 5 — { source, target } per branch
find(root, n => n.data.name === 'C').data.length // 0.3
sum(root, d => (d.children ? 0 : 1)).value // 4 — leaves under the root

docs/hierarchy.md covers eachAfter, sort, the allocation-free forEachDescendant and forEachLink, and each one's visit order. Every traversal is iterative, so a deep tree does not overflow the stack.

writeNewick writes a parsed tree back out, quoting any name that holds Newick punctuation, and parseNewick reads the result back to the same tree. midpointRoot roots a tree halfway along the longest path between two tips, the usual choice for the unrooted tree FastTree, IQ-TREE or neighbor joining writes. rerootTree roots it on the branch above a given node, at the middle of that branch or an offset up from the node:

import {
  midpointRoot,
  parseNewick,
  rerootTree,
  writeNewick,
} from '@gmod/newick'

const tree = parseNewick('((A:1,B:1):1,(C:1,D:5):1);')
writeNewick(midpointRoot(tree)) // '(D:4,(C:1,(A:1,B:1):2):1);'

const a = tree.children[0].children[0]
writeNewick(rerootTree(tree, a)) // '(A:0.5,(B:1,(C:1,D:5):2):0.5);'
writeNewick(rerootTree(tree, a, 0.25)) // '(A:0.25,(B:1,(C:1,D:5):2):0.75);'

Neither function modifies the tree passed in.

@gmod/newick has no layout algorithms or stratify; use d3-hierarchy for those. docs/drawing.md builds a dendrogram layout in a dozen lines.

Docs

License

MIT

版本与发布记录

@gmod/newick 共发布 6 个版本,首次发布于 2026/08/16;过去 12 个月发布了 6 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
1.1.0latest2026/11/116 天前
1.0.32026/09/142 个月前
1.0.22026/08/163 个月前
1.0.12026/08/163 个月前
1.0.02026/08/163 个月前
0.1.02026/08/163 个月前

关于 @gmod/newick 的常见问题

@gmod/newick 是什么?

Newick parsing and stack-safe tree traversals, with no dependencies

如何安装 @gmod/newick?

在项目目录运行 npm install @gmod/newick,或使用 pnpm add / yarn add / bun add。

@gmod/newick 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gmod/newick 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@gmod/newick 可以商用吗?

@gmod/newick 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gmod/newick 的下载量有多少?

根据 npm 官方下载统计,@gmod/newick 在 2026/10/17 – 2026/11/15 这 30 天内被下载 23,483 次,日均约 783 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gmod/newick 还在维护吗?

最新版本 1.1.0 发布于 2026/11/11(6 天前);至今共发布 6 个版本,其中过去 12 个月发布了 6 个;首次发布于 2026/08/16。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。