@euphrasiologist/lwphylo 1.2.26 → 1.3.1

package/README.md

@@ -2,16 +2,15 @@
 
 A lightweight, low level javascript library to plot phylogenies from a Newick file. It uses no dependencies on any other package, but is designed to be given to the D3 library for visualisation.
 
-### Functionality
+## Website
 
-Newick trees can be parsed using the `readTree()` function. This object can then be wrapped in three main functions; `rectangleLayout()` to produce a "regular" phylogenetic tree, `radialLayout()` to produce a circular phylogeny, and `unrooted()` to produce an unrooted tree via the equal angle layout algorithm.
+Visit https://euphrasiologist.github.io/lwPhylo/ to see examples and live rendering of trees. Can even paste your own in.
 
-### Examples
+### Functionality
 
-A quick tutorial is now available to see on Observable: https://observablehq.com/@euphrasiologist/lwphylo-tutorial \
-It goes over the three tree layout functions, and hopefully is all quite straightforward. 
+Newick trees can be parsed using the `readTree()` function. This object can then be wrapped in three main functions; `rectangleLayout()` to produce a "regular" phylogenetic tree, `radialLayout()` to produce a circular phylogeny, and `unrooted()` to produce an unrooted tree via the equal angle layout algorithm.
 
-Stay tuned for examples in the browser.
+Need a tree to experiment with? `randomTree(nTips, { maxBranchLength, labelPrefix, seed })` generates a random bifurcating tree in the same node shape as `readTree()`, ready to pass straight into any of the layout functions.
 
 ### Acknowledgements
 

package/dist/index.cjs

@@ -959,6 +959,85 @@ function parentFisheye(d, data) {
   return parent ? { px: parent.fisheye.x, py: parent.fisheye.y } : null;
 }
 
+/**
+ * Generate a random bifurcating tree with `nTips` tips, in the same
+ * parent/children node shape produced by readTree().
+ *
+ * Topology is grown by repeatedly picking a random extant lineage to split
+ * (a Yule/coalescent-style process), so internal branching order is random
+ * rather than a fixed balanced/caterpillar shape. Branch lengths are drawn
+ * uniformly from [0, maxBranchLength).
+ */
+
+function randomTree(nTips = 10, {
+  maxBranchLength = 1,
+  labelPrefix = 't',
+  seed = null
+} = {}) {
+  if (!Number.isInteger(nTips) || nTips < 1) {
+    throw new Error("nTips must be a positive integer");
+  }
+
+  const random = seed == null ? Math.random : mulberry32(seed);
+
+  let nodeId = 0;
+  const makeNode = (parent) => ({
+    parent,
+    children: [],
+    id: nodeId++,
+    label: '',
+    branchLength: null
+  });
+
+  const root = makeNode(null);
+
+  if (nTips === 1) {
+    root.label = `${labelPrefix}1`;
+    return root;
+  }
+
+  // start with two lineages hanging off the root
+  let lineages = [makeNode(root), makeNode(root)];
+  root.children.push(...lineages);
+
+  // repeatedly split a random lineage until we have nTips of them
+  while (lineages.length < nTips) {
+    const i = Math.floor(random() * lineages.length);
+    const parent = lineages[i];
+    const left = makeNode(parent);
+    const right = makeNode(parent);
+    parent.children.push(left, right);
+    lineages.splice(i, 1, left, right);
+  }
+
+  // assign branch lengths to every non-root node, and tip labels in
+  // left-to-right order
+  let tipIndex = 0;
+  const assign = (node) => {
+    for (const child of node.children) {
+      child.branchLength = random() * maxBranchLength;
+      assign(child);
+    }
+    if (node.children.length === 0) {
+      node.label = `${labelPrefix}${++tipIndex}`;
+    }
+  };
+  assign(root);
+
+  return root;
+}
+
+// small deterministic PRNG so `seed` gives reproducible trees
+function mulberry32(seed) {
+  let a = seed >>> 0;
+  return function () {
+    a |= 0; a = (a + 0x6D2B79F5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
 /**
  * Parse a Newick tree string into a doubly-linked list of JS Objects.
  * Assigns labels, branch lengths, and node IDs (tips before internals if input emits them that way).
@@ -1073,6 +1152,27 @@ function subTree (tree, node) {
     return Object.fromEntries(data.concat(filtered));
 }
 
+/**
+ * Serialize a parsed tree (the parent/children node shape produced by
+ * readTree() and randomTree()) back into a Newick string.
+ */
+
+function toNewick(node) {
+  return `${serialize(node)};`;
+}
+
+function serialize(node) {
+  const label = node.label || '';
+  const branch = node.branchLength == null ? '' : `:${node.branchLength}`;
+
+  if (node.children.length === 0) {
+    return `${label}${branch}`;
+  }
+
+  const children = node.children.map(serialize).join(',');
+  return `(${children})${label}${branch}`;
+}
+
 function drawPhylogeny(
   treeText,
   {
@@ -1862,8 +1962,10 @@ exports.parentFisheye = parentFisheye;
 exports.phisheye = phisheye;
 exports.polarToCartesian = polarToCartesian;
 exports.radialLayout = radialLayout;
+exports.randomTree = randomTree;
 exports.readTree = readTree;
 exports.rectangleLayout = rectangleLayout;
 exports.subTree = subTree;
+exports.toNewick = toNewick;
 exports.unrooted = unrooted;
 //# sourceMappingURL=index.cjs.map