standard-transform 1.4.0__tar.gz → 2.0.0__tar.gz

standard_transform-2.0.0/.bmv-post-commit.sh

@@ -0,0 +1,2 @@
+#!/bin/bash
+git push --tags

standard_transform-2.0.0/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(cd *)",
+      "Bash(uv run *)",
+      "Bash(git check-ignore *)"
+    ]
+  }
+}

standard_transform-2.0.0/.claude/worktrees/laplace-streamlines/.bmv-post-commit.sh

@@ -0,0 +1,2 @@
+#!/bin/bash
+git push --tags

standard_transform-2.0.0/.claude/worktrees/laplace-streamlines/.github/workflows/docs.yml

@@ -0,0 +1,49 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+# Allow one concurrent deployment, cancelling in-progress runs for the same ref.
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Sync dependencies
+        run: uv sync
+
+      - name: Build site (strict)
+        run: uv run mkdocs build --strict
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

standard_transform-2.0.0/.claude/worktrees/laplace-streamlines/.gitignore

@@ -0,0 +1,123 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+.DS_Store
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.vscode/settings.json
+
+movies/
+*_meshes/
+notebooks/
+*.pkl
+*.mp4
+*.png
+*.tiff
+# streamline analysis outputs (scripts)
+compare_*.npz
+validation_*.npz

standard_transform-2.0.0/.claude/worktrees/laplace-streamlines/.pre-commit-config.yaml

@@ -0,0 +1,13 @@
+files: src|tests
+
+repos:
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.11.2
+  hooks:
+    # Run the linter.
+    - id: ruff 
+      types_or: [ python, pyi]
+    - id: ruff
+      args: ["--select", "I", "--fix"]
+    - id: ruff-format
+      types_or: [ python, pyi]

standard_transform-2.0.0/.claude/worktrees/laplace-streamlines/CLAUDE.md

@@ -0,0 +1,40 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+`standard_transform` provides pre-baked affine transforms and curvilinear "streamlines" for orienting points from EM connectomics datasets (Minnie65 and V1dd) into a consistent frame: microns, with the y-axis running pia→white matter and the pial surface at approximately y=0. See README.md for the full user-facing API and worked examples.
+
+## Development commands
+
+This project uses `uv` and [poethepoet](https://poethepoet.natn.io/) (`poe`) tasks defined in `pyproject.toml`.
+
+- **Run tests with coverage:** `uv run poe test` (equivalent to `uv run pytest --cov=standard_transform tests`)
+- **Run a single test:** `uv run pytest tests/test_tform.py::test_name` or `uv run pytest -k pattern`
+- **Lint:** `uv run ruff check` — note the ruff config only selects a minimal set of error codes (`E9,F63,F7,F82`); pre-commit additionally runs import sorting (`I`) and `ruff-format`. Notebooks are excluded from ruff.
+- **Version bump (also git-tags and commits):** `uv run poe bump patch|minor|major` (dry run: `uv run poe drybump patch`). Bumping updates `__init__.py` and `pyproject.toml`, runs `uv sync`, and tags `v{version}`.
+- **Docs preview:** `uv run poe doc-preview` (mkdocs)
+- **Profiling:** `uv run poe profile` (pyinstrument) or `uv run poe profile-all` (scalene)
+
+Note: tests live in `tests/` (the empty `test/` dir is unused). The `build/` and `dist/` dirs contain build artifacts, not source — never edit them.
+
+## Architecture
+
+The package is small and layered. `standard_transform/__init__.py` re-exports only the dataset-specific factory functions and `Dataset` instances — that is the public surface.
+
+- **`base.py`** — the transform engine. A `TransformSequence` holds an ordered list of primitive transforms (`ScaleTransform`, `TranslateTransform`, `RotationTransform`, each with `apply`/`invert`). `apply` runs them forward; `invert` runs them in reverse order with each primitive inverted. All the input-shape polymorphism lives here: `apply`/`invert` dispatch on whether input is a `pd.Series` (of 3-vectors) vs an array; `apply_project` extracts a single axis (x/y/z ↔ 0/1/2); `apply_dataframe` accepts a column name and auto-detects split position columns; `apply_skeleton`/`apply_meshwork_vertices`/`apply_meshwork_annotations` transform MeshParty objects (imported lazily/duck-typed — MeshParty is not a dependency).
+
+- **`streamlines.py`** — the `Streamline` class models the curvilinear depth axis. It stores streamline points in *post-transform* space and builds 1-D interpolators giving x and z as functions of depth y. Every method takes a `transform_points` flag: `True` (default) means inputs are in the original pre-transform coordinates and get transformed first. Key methods: `streamline_at` (x,z of the streamline at a depth), `radial_distance` (in-plane distance accounting for curvature), `depth_along`/`depth_between` (path length along the curve), `radial_points` (map points into cylindrical-like radial/depth coordinates), and the `transform_*` methods that straighten skeletons/meshworks along the streamline (relocating root to origin).
+  - `StreamlineField(Streamline)` is the spatially-varying version: instead of one curve it holds a 3D grid of local tangent vectors `(dx/dy, dz/dy)` and integrates the streamline through any anchor, so the shape varies across the volume (a field uniform in x,z reduces to a plain `Streamline`). It overrides only `__init__`, `streamline_at` (now integrates the field), and `streamline_points_tform`; everything else is inherited. `streamline_at_point(soma)` returns a plain `Streamline` for a neuron — the intended per-cell workflow (integrate once at the soma, apply that fixed curve across the arbor). Query coords are clamped into the grid, so orientation is held constant outside the sampled depth band. `to_npz`/`from_npz` persist the grid (transform not stored — reattached on load). Build with `streamline_field_from_paths`, which bins per-segment tangents, restricts to a reliable `depth_band`, weights cells by precision `count/(var+prior)`, and regularizes via a precision-weighted diffusion (`_precision_smooth`). The method rationale (how the band and precision/diffusion were chosen) is written up in README.md under "Spatially-varying streamlines".
+  - **The field is the default streamline.** `v1dd_streamline_nm/_vx()` (and `v1dd_ds.streamline_nm/_vx`, which are lazy properties) return the `StreamlineField` loaded from `data/v1dd_streamline_field.npz`; pass `legacy=True` to the module functions for the old hand-drawn json streamline. This was an invisible-API but breaking-results change. Both v1dd and Minnie now default to a field (each `data/<dataset>_streamline_field.npz`, registry version "2.0"); `version="1.4"` recovers each dataset's hand json. The field npz is generated offline from ~17-18k skeleton apical paths (tall single dendritic paths, tip→root, in nm), not rebuilt at runtime. Reproduce it with `uv run python scripts/build_streamline_field.py --paths <dir> --dataset v1dd|minnie` (add `--validate N` for a held-out QC deviation). Depth bands differ per dataset — chosen from where per-cell tangent std rises: v1dd `[150, 700]`, Minnie `[150, 650]` (Minnie apical data thins out below ~650µm). `make_streamline_grid_state.py` (repo root, a `uv run` script) emits a neuroglancer QC visualization of the streamline grid.
+
+- **`datasets.py`** — dataset-specific constants and factories. Defines voxel resolutions and pia reference points, the per-dataset rotation/translation/scaling recipes (`_minnie_transforms`, `_v1dd_transforms`), and the public factory functions (`minnie_transform_nm/vx`, `v1dd_transform_nm/vx`, `*_streamline_nm/vx`). The `Dataset` class bundles a transform + streamline for each dataset; the exported singletons `minnie_ds` and `v1dd_ds` are the recommended entry points. Streamline point data is loaded from JSON in `standard_transform/data/`.
+
+- **`utils.py`** — dataframe helpers, chiefly split-position-column detection. Supports two naming conventions: type 1 (`pt_position_x/y/z`) and type 2 (`pt_position_x_suffix`); ambiguity between them raises.
+
+### Conventions when extending
+
+- Every transform primitive must implement both `apply` and `invert` so `TransformSequence.invert` round-trips.
+- Transforms and streamlines come in paired `_nm` (nanometer input) and `_vx` (voxel input, with a `voxel_resolution` argument) variants; a `_vx` factory scales by resolution first, then delegates to the shared transform recipe. Follow this pattern when adding a dataset.
+- Pia points are stored in nm; voxel variants derive their pia point by dividing by resolution.

standard_transform-2.0.0/.claude/worktrees/laplace-streamlines/MANIFEST.in

@@ -0,0 +1,3 @@
+include requirements.txt
+include standard_transform/data/*.json
+include standard_transform/data/*.npz

standard_transform-2.0.0/.claude/worktrees/laplace-streamlines/README.md

@@ -0,0 +1,87 @@
+# standard_transform
+
+Orient and scale points in EM connectomics datasets consistently and easily.
+
+📖 **Full documentation: https://caveconnectome.github.io/standard_transform/**
+
+When working with EM data, the orientation of the dataset often does not match the
+orientation you want to reason in. For cortical data you usually want "down" to mean
+the direction orthogonal to the pial surface, in microns, with the pia at `y ≈ 0`.
+`standard_transform` provides pre-baked affine transforms for two datasets
+(Minnie65 and V1dd) that map voxel or nanometer coordinates into that consistent
+oriented frame, plus **streamlines** — a curvilinear depth axis — for separating
+cortical depth from lateral (radial) distance even where cortex curves.
+
+## Install
+
+```bash
+pip install standard-transform
+```
+
+## Quickstart
+
+```python
+from standard_transform import minnie_ds, v1dd_ds
+
+# n x 3 points -> oriented microns (y = pia->white matter, pia at y≈0)
+# resolution defaults to "nm"; pass "vx" or an [x, y, z] list for other units.
+pts_um = minnie_ds.transform().apply(xyz_nm)
+
+# just the cortical depth (microns below pia)
+depth = minnie_ds.transform().apply_project("y", xyz_nm)
+
+# radial (in-plane) distance following the local streamline
+d = v1dd_ds.streamline().radial_distance(xyz0_nm, xyz1_nm)
+```
+
+`minnie_ds` and `v1dd_ds` bundle a transform and a streamline and are the
+recommended entry points. Both `.transform(resolution="nm", version=None)` and
+`.streamline(resolution="nm", version=None)` take the input resolution (`"nm"`,
+`"vx"`, or an `[x, y, z]` list) and an optional version.
+
+## What's in the box
+
+- **Transforms** — `apply`, `apply_project`, `apply_dataframe`, and `invert`. Point
+  units are selected with `resolution=` (`"nm"`, `"vx"`, or `[x, y, z]`). Accept
+  `n x 3` arrays, pandas Series, and split `_x/_y/_z` dataframe columns.
+- **Streamlines** — depth-along, radial distance, and cylindrical-like remapping
+  along a curvilinear pia-to-white-matter axis.
+
+> **Note:** transforming MeshParty morphology *objects* (skeletons/meshworks) is
+> deprecated and moving to [Ossify](https://csdashm.com/ossify/), where you pass the
+> transformation to the object. `standard_transform` focuses on coordinate arrays and
+> dataframes.
+
+## Streamline fields (breaking data change)
+
+The v1dd and Minnie65 streamlines are now **data-derived, spatially-varying
+`StreamlineField`s** by default, replacing the old single hand-drawn curves. This
+changes computed *results* but not the interface — `StreamlineField` is a drop-in
+subclass of `Streamline`. To recover the previous behavior:
+
+```python
+from standard_transform import minnie_ds, v1dd_ds
+sl     = v1dd_ds.streamline()                 # data-derived field (latest, default)
+sl_old = v1dd_ds.streamline(version="1.4")    # original hand-drawn streamline
+sl_m   = minnie_ds.streamline()               # Minnie65 field (latest, default)
+```
+
+See the docs for the
+[concept](https://caveconnectome.github.io/standard_transform/concepts/streamlines-vs-field/),
+the [per-neuron workflow](https://caveconnectome.github.io/standard_transform/guides/per-neuron-streamline/),
+and [how the field is built](https://caveconnectome.github.io/standard_transform/streamline-field-method/).
+Older definitions stay reachable via `version=` — see
+[Versioning & reproducibility](https://caveconnectome.github.io/standard_transform/concepts/versioning/).
+
+## Documentation
+
+The full guide — concepts, task-oriented tutorials, the streamline-field method, and
+the API reference — lives at
+**https://caveconnectome.github.io/standard_transform/**.
+
+## Development
+
+```bash
+uv run poe test          # run tests with coverage
+uv run poe doc-preview   # serve the docs locally with live reload
+```

standard_transform-2.0.0/.claude/worktrees/laplace-streamlines/docs/concepts/depth-and-radial-distance.md

@@ -0,0 +1,54 @@
+# Depth vs. radial distance in laminar cortex
+
+## Why a straight axis isn't enough
+
+Mammalian cortex is strongly **laminar**: neurons, connectivity, and cell types are
+organized in layers stacked from the pial surface down to white matter. Because of
+that organization, two very different questions constantly come up:
+
+- **Depth:** how far *along the pia → white matter direction* is a point? (Which
+  layer is it in?)
+- **Radial distance:** how far apart are two points *within the laminar plane*,
+  i.e. tangential to the layers?
+
+The [oriented frame](oriented-frame.md) gives you a single global depth axis (`y`).
+That works where cortex is flat. But cortex **curves** — the true "down" direction
+tilts and bends as you move across the volume. If you keep using one straight axis,
+then "depth" and "in-plane distance" get mixed together: a point that is actually
+directly *below* another (same lamina position, deeper) can look laterally
+displaced, and vice versa. The error grows with curvature and with distance from
+wherever the straight axis happened to be correct.
+
+## The streamline
+
+A **streamline** is a curvilinear depth axis: a curve that follows the local
+pia → white matter direction as it bends through the tissue. Think of it as the
+path a plumb line would trace if "down" were always the cortical down at each point.
+
+With a streamline you can measure the two quantities *separately and correctly*:
+
+- **Depth along the streamline** — path length down the curve from the pia, rather
+  than a raw `y` difference. This is what `depth_along` and `depth_between` compute.
+- **Radial distance** — in-plane distance measured relative to the streamline as the
+  `d = 0` reference, accounting for the fact that the curve is tilted. This is what
+  `radial_distance` computes.
+
+You can also remap points into a cylindrical-like coordinate system — radial
+distance as one axis, depth-along-the-streamline as the other — with
+`radial_points`. This is the basis for "straightening" a neuron along the cortical
+axis (see [Skeletons & meshworks](../guides/skeletons-meshworks.md)).
+
+## A worked intuition
+
+Imagine two synapses. In raw oriented `y` they differ by 50 µm, and they also
+differ in `x`. Are they at the same lamina depth but offset sideways, or genuinely
+at different depths? If the cortex is curved there, the straight `y` answer is
+biased. Measuring depth *along the streamline* answers the anatomical question:
+how far down the cortical column each one really is.
+
+## Next
+
+There are two ways a streamline can be defined: a single fixed curve applied
+everywhere, or a curve that varies with location. That distinction — and why the
+v1dd default recently changed — is covered in
+[Streamlines vs. fields](streamlines-vs-field.md).

standard_transform-2.0.0/.claude/worktrees/laplace-streamlines/docs/concepts/oriented-frame.md

@@ -0,0 +1,75 @@
+# The oriented frame
+
+## The problem
+
+An EM dataset is a volume of tissue imaged on a microscope. Its native coordinate
+system — voxels, or nanometers derived from them — is aligned to the imaging setup,
+not to the brain. Two things are usually "off":
+
+- **Units and scale.** Coordinates come in voxels (with anisotropic voxel sizes,
+  e.g. `[4, 4, 40]` nm for Minnie65) or in nanometers. Neither is convenient for
+  thinking about distances in tissue.
+- **Orientation.** The pial surface — the top of cortex — is not axis-aligned. The
+  cortical "down" direction (pia → white matter) points at some arbitrary angle
+  relative to the volume's axes, and it can be slightly different from one dataset
+  to the next.
+
+If you want to ask a simple anatomical question — *how deep below the pia is this
+synapse?* — you cannot just read off a coordinate, because no single native axis
+corresponds to depth.
+
+## What the transform does
+
+`standard_transform` applies a fixed sequence of **affine operations**
+(rotation → translation → scaling) that lands every dataset in the same frame:
+
+- **microns**, so distances are directly interpretable;
+- the **y-axis oriented from pia to white matter** — increasing `y` means deeper
+  into cortex;
+- the **pial surface at `y ≈ 0`**, so `y` reads directly as cortical depth.
+
+The x and z axes span the plane parallel to the pial surface (the laminar plane).
+Because every dataset is mapped into this same convention, analyses and figures
+built on top of it are comparable across datasets without per-dataset bookkeeping.
+
+The recipe for each dataset is pre-baked — you don't fit anything. Each is a small
+`TransformSequence` of primitives (a rotation derived from the dataset's measured
+"up" vector, a translation that puts pia at `y = 0`, and a scaling to microns).
+See [Datasets](../datasets.md) for the specific constants.
+
+## Input units: the `resolution` argument
+
+You tell the transform what units your points are in with `resolution`:
+
+- `resolution="nm"` (the default) — **nanometers**.
+- `resolution="vx"` — **voxels**, using the dataset's native voxel size.
+- `resolution=[x, y, z]` — an explicit voxel resolution; the transform scales to
+  nanometers first, then applies the shared recipe.
+
+```python
+minnie_ds.transform()                    # nm (default)
+minnie_ds.transform("vx")                # native voxels
+minnie_ds.transform([8, 8, 40])          # explicit resolution
+```
+
+All choices produce the same oriented microns for equivalent points, so results are
+unit-invariant — the only difference is what you put in.
+
+## It's invertible
+
+A `TransformSequence` runs its primitives forward under `apply` and in reverse
+(each inverted) under `invert`. So you can always take a point you've computed in
+the oriented frame and recover its original native coordinate — useful for, say,
+turning an analysis result back into a location you can look up in the dataset.
+
+```python
+pts_um   = tform.apply(pts_nm)     # native → oriented microns
+pts_back = tform.invert(pts_um)    # oriented microns → native
+```
+
+## Next
+
+The oriented frame gives you a straight, global depth axis. But cortex curves, and
+a single straight axis is not enough to measure depth and lateral distance
+accurately everywhere — that's what [streamlines](depth-and-radial-distance.md)
+are for.

standard_transform-2.0.0/.claude/worktrees/laplace-streamlines/docs/concepts/streamlines-vs-field.md

@@ -0,0 +1,76 @@
+# Streamlines vs. fields
+
+There are two ways `standard_transform` represents the curvilinear depth axis. They
+share an interface but differ in how much they can adapt to the tissue.
+
+## A fixed `Streamline`
+
+A `Streamline` stores **one curve** and applies its shape everywhere: to find the
+streamline through any point, it simply **translates** that single curve so it
+passes through the point. The shape is identical across the whole volume — only its
+position shifts.
+
+This is exactly right when the pia → white matter direction is roughly uniform
+across the region you care about. It is what the original, hand-drawn streamlines
+provided, and it is still a good approximation over a limited area.
+
+Its limitation: a single curve cannot represent a *spatially-varying* axis. If the
+cortical "down" direction genuinely differs between one side of the dataset and the
+other (curvature, or regional alignment drift), one fixed shape is accurate on one
+side and progressively wrong on the other.
+
+## A spatially-varying `StreamlineField`
+
+A `StreamlineField` (a subclass of `Streamline`, so it is a drop-in replacement)
+instead stores a **3D grid of local orientation vectors** — the pia → white matter
+direction at every location — estimated from many neurons. The streamline through a
+point is obtained by **integrating that field**, so its shape *varies across the
+volume*. A field that happens to be uniform in x and z reduces exactly to a single
+`Streamline`.
+
+Because the field is estimated directly from data, it captures local curvature and
+absorbs regional alignment drift that no single fixed curve can. How it is built and
+validated is described in [Streamline field: method](../streamline-field-method.md).
+
+## What changed (and how to opt out)
+
+As of the current release, both the v1dd and Minnie65 streamline accessors return a
+`StreamlineField` **by default**:
+
+```python
+from standard_transform import minnie_ds, v1dd_ds
+
+sl     = v1dd_ds.streamline()              # data-derived tangent field (latest, default)
+sl_old = v1dd_ds.streamline(version="1.4") # original hand-drawn single streamline
+sl_m   = minnie_ds.streamline()            # Minnie65 field (latest, default)
+```
+
+This is a **breaking change in results** — computed depths and radial distances
+differ from the old hand-drawn streamline — but **not a breaking change in
+interface**. Every method (`streamline_at`, `radial_distance`, `depth_along`,
+`radial_points`) works unchanged, because `StreamlineField` inherits them. Pin
+`version="1.4"` to recover the previous behavior exactly — see
+[Versioning & reproducibility](versioning.md).
+
+!!! note "Which datasets have a field?"
+    Both shipped datasets — v1dd and Minnie65 — default to a data-derived field. The
+    accessors always return a `Streamline`-compatible object regardless, so your code
+    does not need to branch. See [Datasets](../datasets.md) for the current status of
+    each.
+
+## The per-neuron workflow
+
+The intended way to use a field for a single neuron is **not** to re-derive the
+axis at every vertex. Instead, integrate the field **once at the cell body** to get
+the one streamline appropriate to that soma, then apply that fixed curve across the
+whole arbor:
+
+```python
+sl = v1dd_ds.streamline().streamline_at_point(soma_xyz)  # a plain Streamline
+verts_straight = sl.radial_points(soma_xyz, skel.vertices)
+```
+
+This measures the arbor *against its soma's cortical axis* without assuming the
+dendrites themselves follow the field — which they often don't (for example,
+inverted layer-6 apical dendrites). See the
+[per-neuron guide](../guides/per-neuron-streamline.md) for the full walkthrough.

standard_transform-2.0.0/.claude/worktrees/laplace-streamlines/docs/concepts/versioning.md

@@ -0,0 +1,84 @@
+# Versioning & reproducibility
+
+## Outputs are tied to the package version
+
+Everything `standard_transform` produces is defined by two things: the **rigid affine
+numbers** (rotation, pia point, scaling) that build the oriented frame, and the
+**streamline data**. Both are baked into the package. If either changes between
+releases — as the v1dd streamline does when it moves from a hand-drawn curve to a
+data-derived field — then every depth, radial distance, and transformed coordinate
+changes too.
+
+That makes results **version-dependent**: a figure made with one release is only
+directly comparable to another if they used the same definitions. To keep old work
+reproducible and to compare across releases, past definitions stay reachable by name.
+
+## Two independent version tracks
+
+The affine transform and the streamline are versioned **separately**, because they
+change on different schedules:
+
+- the **transform** track — the affine numbers;
+- the **streamline** track — the depth-axis data.
+
+For example, in the `2.0` release the v1dd and Minnie65 streamlines change (hand-drawn
+→ field) but the affine numbers do not, so each transform stays at its `1.4` version
+while the streamline advances to `2.0`.
+
+## Package-version-anchored labels
+
+A version label **is the release in which that definition became the default**. So
+`version="1.4"` means "the definition shipped as default through the 1.4 line," and
+`version="2.0"` means "the definition that became default in 2.0." Asking for a label
+reproduces exactly what that release produced.
+
+| dataset | track | version | what it is |
+|---|---|---|---|
+| v1dd | transform | `1.4` (latest) | the affine frame (unchanged) |
+| v1dd | streamline | `1.4` | original hand-drawn single streamline |
+| v1dd | streamline | `2.0` (latest) | data-derived spatially-varying field |
+| minnie65 | transform | `1.4` (latest) | the affine frame |
+| minnie65 | streamline | `1.4` | original hand-drawn single streamline |
+| minnie65 | streamline | `2.0` (latest) | data-derived spatially-varying field |
+
+## Pinning a version
+
+Pass `version=` to `transform()` / `streamline()` (or the module factories). Omitting
+it — or `version=None` — resolves to the latest for that track:
+
+```python
+from standard_transform import v1dd_ds
+
+sl_latest = v1dd_ds.streamline()               # latest: the field (2.0)
+sl_old    = v1dd_ds.streamline(version="1.4")  # reproduce the hand-drawn streamline
+
+tf        = v1dd_ds.transform(version="1.4")   # pin the affine frame
+```
+
+An unknown label raises a `ValueError` listing the valid versions.
+
+## Recording provenance
+
+Every transform and streamline carries a `.version` attribute, so an analysis can
+record exactly which definition produced its numbers:
+
+```python
+tf = v1dd_ds.transform()
+tf.version          # -> "1.4"
+v1dd_ds.streamline().version   # -> "2.0"
+```
+
+## Inspecting what's available
+
+`available_versions(dataset)` (also `dataset.available_versions()`) lists both tracks,
+their versions, and which release introduced each, plus the current latest:
+
+```python
+from standard_transform import available_versions
+
+available_versions("v1dd")
+# {
+#   "transform":  {"latest": "1.4", "versions": {"1.4": "1.4"}},
+#   "streamline": {"latest": "2.0", "versions": {"1.4": "1.4", "2.0": "2.0"}},
+# }
+```