@euphrasiologist/lwphylo 1.3.1 → 1.5.0

package/dist/index.cjs

@@ -950,6 +950,23 @@ function unrooted (node) {
   return data;
 }
 
+/**
+ * Reorder every node's children by descendant tip count, so the tree
+ * "ladders" from smallest to largest clade at each branching point
+ * (or the reverse, with ascending: false). Mutates the tree in place.
+ */
+function ladderize(tree, { ascending = true } = {}) {
+  const sign = ascending ? 1 : -1;
+
+  (function sort(node) {
+    if (node.children.length === 0) return;
+    node.children.forEach(sort);
+    node.children.sort((a, b) => sign * (numTips(a) - numTips(b)));
+  })(tree);
+
+  return tree;
+}
+
 function makeIndexById(rows, key = "thisId") {
   return new Map(rows.map(d => [d[key], d]));
 }
@@ -959,6 +976,20 @@ function parentFisheye(d, data) {
   return parent ? { px: parent.fisheye.x, py: parent.fisheye.y } : null;
 }
 
+/**
+ * Reverse the child order at one node, flipping which side of the tree
+ * that clade's descendants are drawn on. Defaults to the root. Mutates
+ * the tree in place.
+ */
+function rotate(tree, nodeId = tree.id) {
+  const target = preorder(tree).find((n) => n.id === nodeId);
+  if (!target) {
+    throw new Error(`No node with id ${nodeId} found in tree`);
+  }
+  target.children.reverse();
+  return tree;
+}
+
 /**
  * Generate a random bifurcating tree with `nTips` tips, in the same
  * parent/children node shape produced by readTree().
@@ -1173,8 +1204,52 @@ function serialize(node) {
   return `(${children})${label}${branch}`;
 }
 
+// Round a raw data-space length to a "nice" 1/2/5-of-a-power-of-ten value,
+// so an auto-sized scale bar doesn't show an ugly number like "0.347".
+function niceScaleLength(target) {
+  if (!(target > 0)) return 1;
+  const exp = Math.floor(Math.log10(target));
+  const base = Math.pow(10, exp);
+  const residual = target / base;
+  const niceResidual = residual < 1.5 ? 1 : residual < 3.5 ? 2 : residual < 7.5 ? 5 : 10;
+  return niceResidual * base;
+}
+
+// scaleBar: true | number (explicit data-units length) | { length, x, y, label }
+function addScaleBar(svg, { scale, basis, defaultX, defaultY, scaleBar, fontSize }) {
+  const opts = (scaleBar === true || typeof scaleBar === "number") ? {} : scaleBar;
+  const length = typeof scaleBar === "number" ? scaleBar : (opts.length ?? niceScaleLength(basis / 5));
+  const x = opts.x ?? defaultX;
+  const y = opts.y ?? defaultY;
+  const barPx = scale(length) - scale(0);
+
+  const g = svg.append("g").attr("class", "phylo_scale_bar");
+  g.append("line")
+    .attr("x1", x).attr("x2", x + barPx)
+    .attr("y1", y).attr("y2", y)
+    .attr("stroke", "#000")
+    .attr("stroke-width", 1);
+  [x, x + barPx].forEach((tx) => {
+    g.append("line")
+      .attr("x1", tx).attr("x2", tx)
+      .attr("y1", y - 4).attr("y2", y + 4)
+      .attr("stroke", "#000")
+      .attr("stroke-width", 1);
+  });
+  g.append("text")
+    .attr("x", x + barPx / 2)
+    .attr("y", y - 6)
+    .attr("text-anchor", "middle")
+    .attr("font-size", fontSize)
+    .text(opts.label ?? String(length));
+}
+
+// input: a Newick string, or an already-parsed tree (the node shape returned
+// by readTree()/randomTree()). Passing the same parsed tree object back in
+// across re-renders (e.g. after mutating it with rotate()) keeps node ids
+// stable, which onNodeClick below relies on.
 function drawPhylogeny(
-  treeText,
+  input,
   {
     layout = "rect", // rect/radial/unrooted
     width = 800,
@@ -1185,6 +1260,14 @@ function drawPhylogeny(
     radialMode = "outer", // "outer" (co-circular tips) or "phylo" (true terminals)
     tipLabels = true,
     labelFontSize = 10, // font size (px) for tip labels
+    tipRadius, // px radius of tip dots; defaults to each layout's original size
+    internalNodeCircles = false, // draw a circle at every internal (non-tip) node
+    internalNodeRadius = 3, // px radius for internal node circles
+    nodeLabels = false, // draw text labels at internal nodes (e.g. clade/support labels)
+    nodeLabelFontSize, // defaults to labelFontSize
+    scaleBar = false, // false | true | number (branch-length units) | { length, x, y, label }
+    alignTipLabels = false, // rect & radial only: align tip labels to a common column/ring, with dashed guide lines back to the true tip position
+    onNodeClick, // (node, event) => void — fires when an internal node circle is clicked (requires internalNodeCircles: true)
     showTooltips = true,
     tooltipFormatter = (d, rtt) =>
       `${d.thisLabel ?? "(unnamed)"}\nroot→tip: ${(+rtt).toFixed(4)}`,
@@ -1198,6 +1281,10 @@ function drawPhylogeny(
 
   // shared helpers
   const isNumber = (x) => typeof x === "number" && Number.isFinite(x);
+  const nodeLabelSize = nodeLabelFontSize ?? labelFontSize;
+  const parsedTree = (input && typeof input === "object" && Array.isArray(input.children))
+    ? input
+    : readTree(input);
   // Works for both radial (uses `r`) and rect (uses `x1`).
   // Falls back to summing branchLength up to the root if neither is present.
   function makeRootToTipGetter(byId, { prefer = "auto" } = {}) {
@@ -1226,7 +1313,7 @@ function drawPhylogeny(
 
   if (layout === "rect") {
     // RECTANGULAR LAYOUT
-    const tree_df = rectangleLayout(readTree(treeText));
+    const tree_df = rectangleLayout(parsedTree);
     const horizontal = tree_df.horizontal_lines;
     const vertical = tree_df.vertical_lines;
     const tips = horizontal.filter((d) => d.isTip);
@@ -1236,6 +1323,7 @@ function drawPhylogeny(
     const tipById = new Map(tips.map((d) => [d.thisId, d]));
     const tipByLabel = new Map(tips.map((d) => [d.thisLabel, d]));
     const rootToTip = makeRootToTipGetter(byId, { prefer: "x1" });
+    const R_TIP = tipRadius ?? 2;
 
     const maxY = d3__namespace.max(horizontal, (d) => d.y1);
     const minY = d3__namespace.min(horizontal, (d) => d.y1);
@@ -1293,7 +1381,7 @@ function drawPhylogeny(
       .join("circle")
       .attr("cx", (d) => xScale(d.x1))
       .attr("cy", (d) => yScale(d.y1))
-      .attr("r", 2)
+      .attr("r", R_TIP)
       .attr("fill", "black");
 
     // tooltips for rect dots
@@ -1308,13 +1396,78 @@ function drawPhylogeny(
       .on("mouseenter", function(_event, d) {
         hoverLayer.selectAll("*").remove();
         drawRectPath(d.thisId, hoverLayer, hoverStroke, hoverWidth);
-        d3__namespace.select(this).attr("r", 4);
+        d3__namespace.select(this).attr("r", R_TIP + 2);
       })
       .on("mouseleave", function() {
         hoverLayer.selectAll("*").remove();
-        d3__namespace.select(this).attr("r", 2);
+        d3__namespace.select(this).attr("r", R_TIP);
       });
 
+    // internal node circles (optional)
+    if (internalNodeCircles) {
+      const internalNodes = tree_df.data.filter((d) => !d.isTip);
+      const internalDots = group
+        .append("g")
+        .attr("class", "phylo_internal_dots")
+        .selectAll("circle")
+        .data(internalNodes)
+        .join("circle")
+        .attr("cx", (d) => xScale(d.x1))
+        .attr("cy", (d) => yScale(d.y1))
+        .attr("r", internalNodeRadius)
+        .attr("fill", "white")
+        .attr("stroke", "#555")
+        .attr("stroke-width", 1);
+
+      if (showTooltips) {
+        internalDots
+          .append("title")
+          .text((d) => tooltipFormatter(d, rootToTip(d.thisId)));
+      }
+
+      if (onNodeClick) {
+        internalDots
+          .style("cursor", "pointer")
+          .on("click", (event, d) => onNodeClick(d, event));
+      }
+    }
+
+    // internal node labels (optional)
+    if (nodeLabels) {
+      const labeledInternalNodes = tree_df.data.filter((d) => !d.isTip && d.thisLabel);
+      svg
+        .append("g")
+        .attr("class", "phylo_node_labels")
+        .selectAll("text")
+        .data(labeledInternalNodes)
+        .join("text")
+        .attr("x", (d) => xScale(d.x1) - 4)
+        .attr("y", (d) => yScale(d.y1) - 4)
+        .attr("text-anchor", "end")
+        .attr("font-size", nodeLabelSize)
+        .text((d) => d.thisLabel);
+    }
+
+    // column that tip labels align to when alignTipLabels is set
+    const alignX = xScale(maxX);
+
+    // dashed guide lines from each tip's true branch end to the aligned label column
+    if (tipLabels && alignTipLabels) {
+      group
+        .append("g")
+        .attr("class", "phylo_align_guides")
+        .selectAll("line")
+        .data(tips)
+        .join("line")
+        .attr("x1", (d) => xScale(d.x1))
+        .attr("x2", alignX)
+        .attr("y1", (d) => yScale(d.y1))
+        .attr("y2", (d) => yScale(d.y1))
+        .attr("stroke", "#999")
+        .attr("stroke-width", 1)
+        .attr("stroke-dasharray", "2,2");
+    }
+
     // labels
     if (tipLabels) {
       const labels = svg
@@ -1323,7 +1476,7 @@ function drawPhylogeny(
         .selectAll("text")
         .data(tips)
         .join("text")
-        .attr("x", (d) => xScale(d.x1) + 4)
+        .attr("x", (d) => (alignTipLabels ? alignX : xScale(d.x1)) + 4)
         .attr("y", (d) => yScale(d.y1))
         .attr("dy", "0.32em")
         .attr("font-size", labelFontSize)
@@ -1395,13 +1548,23 @@ function drawPhylogeny(
       }
     }
 
+    if (scaleBar) {
+      addScaleBar(svg, {
+        scale: xScale,
+        basis: maxX,
+        defaultX: margin.left,
+        defaultY: height - margin.bottom / 2,
+        scaleBar,
+        fontSize: labelFontSize
+      });
+    }
+
     return svg.node();
   } else if (layout === "radial") {
     // RADIAL LAYOUT
     if (width !== height) {
       throw new Error("width and height must be the same for radial layout");
     }
-    const parsedTree = readTree(treeText);
     const rad = radialLayout(parsedTree, {
       angleStrategy: "fan",
       arcsStyle: "fan"
@@ -1416,7 +1579,7 @@ function drawPhylogeny(
 
 
     // visuals (0 = let spokes reach the dots)
-    const DOT_R = 3;
+    const DOT_R = tipRadius ?? 3;
     const END_CAP = 0;
 
     // ===== SCALES / BOUNDS =====
@@ -1554,6 +1717,25 @@ function drawPhylogeny(
           .attr("stroke-width", strokeWidth);
       });
 
+    // ===== ALIGN GUIDES (optional) =====
+    // dashed lines from each tip's true position to the common label ring,
+    // for radialMode "phylo" (true terminals) where tips aren't already co-circular
+    if (tipLabels && alignTipLabels && !isOuter) {
+      group
+        .append("g")
+        .attr("class", "phylo_align_guides")
+        .selectAll("line")
+        .data(tips)
+        .join("line")
+        .attr("x1", (d) => xScaleRadial(d.x))
+        .attr("y1", (d) => yScaleRadial(d.y))
+        .attr("x2", (d) => xScaleRadial(tipMaxR * Math.cos(d.angle)))
+        .attr("y2", (d) => yScaleRadial(tipMaxR * Math.sin(d.angle)))
+        .attr("stroke", "#999")
+        .attr("stroke-width", 1)
+        .attr("stroke-dasharray", "2,2");
+    }
+
     // ===== TIP DOTS =====
     const tipDots = group
       .append("g")
@@ -1581,6 +1763,51 @@ function drawPhylogeny(
         .text((d) => tooltipFormatter(d, rootToTip(d.thisId)));
     }
 
+    // ===== INTERNAL NODE CIRCLES (optional) =====
+    if (internalNodeCircles) {
+      const internalNodes = rad.data.filter((d) => !d.isTip);
+      const internalDots = group
+        .append("g")
+        .attr("class", "phylo_internal_dots")
+        .selectAll("circle")
+        .data(internalNodes)
+        .join("circle")
+        .attr("cx", (d) => xScaleRadial(d.x))
+        .attr("cy", (d) => yScaleRadial(d.y))
+        .attr("r", internalNodeRadius)
+        .attr("fill", "white")
+        .attr("stroke", "#555")
+        .attr("stroke-width", 1);
+
+      if (showTooltips) {
+        internalDots
+          .append("title")
+          .text((d) => tooltipFormatter(d, rootToTip(d.thisId)));
+      }
+
+      if (onNodeClick) {
+        internalDots
+          .style("cursor", "pointer")
+          .on("click", (event, d) => onNodeClick(d, event));
+      }
+    }
+
+    // ===== INTERNAL NODE LABELS (optional) =====
+    if (nodeLabels) {
+      const labeledInternalNodes = rad.data.filter((d) => !d.isTip && d.thisLabel);
+      group
+        .append("g")
+        .attr("class", "phylo_node_labels")
+        .selectAll("text")
+        .data(labeledInternalNodes)
+        .join("text")
+        .attr("x", (d) => xScaleRadial(d.x) + 4)
+        .attr("y", (d) => yScaleRadial(d.y) - 4)
+        .attr("font-size", nodeLabelSize)
+        .attr("fill", "black")
+        .text((d) => d.thisLabel);
+    }
+
     // maps for fast lookup on hover (childId → spoke / arc)
     const key = (x) => (typeof x === "string" ? +x : x);
     const spokeByChild = new Map(rad.radii.map(s => [key(s.childId ?? s.thisId ?? s.id1), s]));
@@ -1601,7 +1828,8 @@ function drawPhylogeny(
           // same tip position rule as dots/spokes:
           //  - "outer": snap to common ring (tipMaxR)
           //  - otherwise (e.g. "align"/"phylo"): true tip radius
-          const r = isOuter ? tipMaxR : d.r;
+          //  - alignTipLabels forces the common ring regardless of mode
+          const r = (isOuter || alignTipLabels) ? tipMaxR : d.r;
           const x = r * Math.cos(d.angle);
           const y = r * Math.sin(d.angle);
           return `translate(${xScaleRadial(x)},${yScaleRadial(y)})`;
@@ -1748,10 +1976,20 @@ function drawPhylogeny(
       });
     }
 
+    if (scaleBar) {
+      addScaleBar(svg, {
+        scale: xScaleRadial,
+        basis: maxRadius,
+        defaultX: 20,
+        defaultY: h - 20,
+        scaleBar,
+        fontSize: labelFontSize
+      });
+    }
+
     return svg.node();
   } else if (layout === "unrooted") {
     // UNROOTED LAYOUT
-    const parsedTree = readTree(treeText);
     const unrootedPhylo = unrooted(parsedTree);
 
     const w = width;
@@ -1797,6 +2035,8 @@ function drawPhylogeny(
       .attr("stroke-width", strokeWidth)
       .attr("stroke", "#777");
 
+    const R_TIP = tipRadius ?? 4;
+
     const nodes = group
       .append("g")
       .attr("class", "phylo_points")
@@ -1804,13 +2044,35 @@ function drawPhylogeny(
       .data(unrootedPhylo.data)
       .join("circle")
       .attr("class", "dot")
-      .attr("r", (d) => (d.isTip ? 4 : 0))
+      .attr("r", (d) => (d.isTip ? R_TIP : (internalNodeCircles ? internalNodeRadius : 0)))
       .attr("cx", (d) => xScaleUnroot(d.x))
       .attr("cy", (d) => yScaleUnroot(d.y))
       .attr("stroke", "black")
       .attr("stroke-width", 2)
       .attr("fill", (d) => (d.isTip ? "black" : "white"));
 
+    if (internalNodeCircles && onNodeClick) {
+      nodes
+        .filter((d) => !d.isTip)
+        .style("cursor", "pointer")
+        .on("click", (event, d) => onNodeClick(d, event));
+    }
+
+    if (nodeLabels) {
+      const labeledInternalNodes = unrootedPhylo.data.filter((d) => !d.isTip && d.thisLabel);
+      group
+        .append("g")
+        .attr("class", "phylo_node_labels")
+        .selectAll("text")
+        .data(labeledInternalNodes)
+        .join("text")
+        .attr("x", (d) => xScaleUnroot(d.x) + 4)
+        .attr("y", (d) => yScaleUnroot(d.y) - 4)
+        .attr("font-size", nodeLabelSize)
+        .attr("fill", "black")
+        .text((d) => d.thisLabel);
+    }
+
     const byId = new Map(unrootedPhylo.data.map((d) => [d.thisId, d]));
     const tipById = new Map(
       unrootedPhylo.data.filter((d) => d.isTip).map((d) => [d.thisId, d])
@@ -1900,11 +2162,11 @@ function drawPhylogeny(
       .filter((d) => d.isTip)
       .on("mouseenter", function(_event, d) {
         drawUnrootedPath(d.thisId, hoverLayer, hoverStroke, hoverWidth);
-        d3__namespace.select(this).attr("r", 6);
+        d3__namespace.select(this).attr("r", R_TIP + 2);
       })
       .on("mouseleave", function() {
         hoverLayer.selectAll("*").remove();
-        d3__namespace.select(this).attr("r", 4);
+        d3__namespace.select(this).attr("r", R_TIP);
       });
 
     if (highlightTips && highlightTips.length) {
@@ -1947,6 +2209,17 @@ function drawPhylogeny(
       }
     }
 
+    if (scaleBar) {
+      addScaleBar(svg, {
+        scale: xScaleUnroot,
+        basis: maxRadius,
+        defaultX: 20,
+        defaultY: h - 20,
+        scaleBar,
+        fontSize: labelFontSize
+      });
+    }
+
     return svg.node();
   } else {
     throw new Error(
@@ -1958,6 +2231,7 @@ function drawPhylogeny(
 exports.describeArc = describeArc;
 exports.describeArcSweep = describeArcSweep;
 exports.drawPhylogeny = drawPhylogeny;
+exports.ladderize = ladderize;
 exports.parentFisheye = parentFisheye;
 exports.phisheye = phisheye;
 exports.polarToCartesian = polarToCartesian;
@@ -1965,6 +2239,7 @@ exports.radialLayout = radialLayout;
 exports.randomTree = randomTree;
 exports.readTree = readTree;
 exports.rectangleLayout = rectangleLayout;
+exports.rotate = rotate;
 exports.subTree = subTree;
 exports.toNewick = toNewick;
 exports.unrooted = unrooted;