Skip to content

docs: add a core concepts notebook - #224

Merged
Neclow merged 1 commit into
sbhattlab:mainfrom
Neclow:docs/core-concepts
Nov 2, 2026
Merged

Neclow merged 1 commit into
sbhattlab:mainfrom
Neclow:docs/core-concepts

Conversation

@Neclow

@Neclow Neclow commented Nov 2, 2026

Copy link
Copy Markdown
Collaborator

Summary

Adds a Core concepts notebook between Getting started and Tree operations, explaining what a Phylo2Vec vector encodes. Related to #170; follows up on #222.

The text and figures are adapted from the background and methods of Neil Scheidwasser's PhD thesis and the Phylo2Vec papers. Each claim is checked by a code cell against the current code (e.g., the 105 vectors with 5 leaves map to 105 distinct trees, and each step of the vector → tree figure matches to_newick).

Contents

  1. Phylogenetic trees: definitions and the size of tree space, (2n-3)!!
  2. Why a vector?: Newick strings are not one-to-one, vectors are
  3. The Phylo2Vec vector: node and branch labels, the definition v[j] ∈ {0, ..., 2j}, ordered and unordered vectors
  4. Other tree formats: edges, ancestry and pairs (moved from Getting started)
  5. From a vector to a tree: leaf-by-leaf construction, internal node relabelling, pairs
  6. From a Newick string to a vector: parsing, ancestry sorting (with and without parent labels), vector building with a Fenwick tree
  7. Branch lengths: the matrix format
  8. Complexity of the conversions

Figures

The thesis TikZ figures are added as SVGs in docs/notebooks/img/, with a white background so that they render in dark themes. One fix compared to the thesis: the last row of the relabelling figure now reads "Label the parent of 3 as 8" (it said 1).

Other changes

  • Getting started: the "Other tree formats" section moved to Core concepts; remaining sections renumbered, with links to Core concepts
  • Tree operations and Statistics link to Core concepts
  • _toc.yml and the CI notebook job include the new notebook

Explain what a Phylo2Vec vector encodes, adapted from the background
and methods of Neil Scheidwasser's PhD thesis and the Phylo2Vec papers:
phylogenetic trees and the size of tree space, why a vector, node and
branch labels, the vector definition, ordered and unordered vectors,
vector -> tree and Newick -> vector conversions, the matrix format for
branch lengths, and the complexity of the conversions. Each claim is
checked by a code cell (e.g., 105 vectors map to 105 distinct trees
with 5 leaves).

- Add the thesis TikZ figures as SVGs in docs/notebooks/img/ (fixing
  "Label the parent of 1 as 8" -> "3" in the relabelling figure)
- Move "Other tree formats" from getting-started to core concepts
- Link core concepts from the other notebooks
- Add core concepts to the table of contents and the CI notebook job

Related to sbhattlab#170

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Neclow
Neclow merged commit 13dd262 into sbhattlab:main Nov 2, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant