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

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-1.4.1 → standard_transform-2.0.0/.claude/worktrees/laplace-streamlines}/.gitignore

@@ -117,4 +117,7 @@ notebooks/
 *.pkl
 *.mp4
 *.png
-*.tiff
+*.tiff
+# streamline analysis outputs (scripts)
+compare_*.npz
+validation_*.npz

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"}},
+# }
+```

standard_transform-2.0.0/.claude/worktrees/laplace-streamlines/docs/datasets.md

@@ -0,0 +1,61 @@
+# Datasets
+
+A **`Dataset`** bundles a transform and a streamline together and is the easiest way
+to get started. Two are provided as ready-to-use singletons: `minnie_ds` and
+`v1dd_ds`.
+
+```python
+from standard_transform import minnie_ds, v1dd_ds
+
+v1dd_ds.transform().apply(xyz_nm)                   # transform points (nm default)
+v1dd_ds.streamline().radial_distance(xyz0, xyz1)    # streamline query
+```
+
+Each dataset exposes two methods (plus the module-level factories `minnie_transform`,
+`v1dd_transform`, `minnie_streamline`, `v1dd_streamline`, which take the same
+arguments):
+
+- `transform(resolution="nm", version=None)` — a [transform](concepts/oriented-frame.md).
+- `streamline(resolution="nm", version=None)` — a
+  [streamline](concepts/depth-and-radial-distance.md) (built lazily and cached).
+
+`resolution` is `"nm"` (default), `"vx"` (native voxel size), or an explicit
+`[x, y, z]`. `version` pins a historical definition; see
+[Versioning & reproducibility](concepts/versioning.md).
+
+## Minnie65
+
+Native voxel resolution `[4, 4, 40]` nm.
+
+- `minnie_ds.transform()` — nanometers → oriented microns (pia flat in x,z at y≈0).
+- `minnie_ds.transform("vx")` — native voxels; `minnie_ds.transform([8, 8, 40])` for
+  a different scale.
+- `minnie_ds.streamline(...)` — returns a data-derived, spatially-varying
+  [`StreamlineField`](concepts/streamlines-vs-field.md) **by default** (depth band
+  `[150, 650]` µm). Pass `version="1.4"` for the original hand-drawn single streamline.
+
+## V1dd
+
+Native voxel resolution `[9, 9, 45]` nm.
+
+- `v1dd_ds.transform(...)` — same as Minnie65 with the v1dd recipe and `[9, 9, 45]`
+  native voxels.
+- `v1dd_ds.streamline(...)` — returns a data-derived, spatially-varying
+  [`StreamlineField`](concepts/streamlines-vs-field.md) **by default** (depth band
+  `[150, 700]` µm). Pass `version="1.4"` for the original hand-drawn single streamline.
+
+## Streamline field status
+
+| dataset | default streamline |
+|---|---|
+| V1dd | data-derived `StreamlineField` (pass `version="1.4"` for the hand-drawn curve) |
+| Minnie65 | data-derived `StreamlineField` (pass `version="1.4"` for the hand-drawn curve) |
+
+Both datasets now default to a data-derived, spatially-varying field. The
+field-building procedure is dataset-agnostic and described in
+[Streamline field: method](streamline-field-method.md).
+
+## Identity
+
+- `identity_transform` — returns the input unchanged (optionally axis-projected).
+  Useful for compatibility when a code path expects a transform object.

standard_transform-2.0.0/.claude/worktrees/laplace-streamlines/docs/guides/build-a-field.md

@@ -0,0 +1,87 @@
+# Build a field for a new dataset
+
+A [`StreamlineField`](../concepts/streamlines-vs-field.md) is estimated offline from
+a collection of **pia → white matter paths** — one per neuron — and shipped as a
+compressed `.npz`. This guide shows how to build one. For the reasoning behind each
+step (depth band, precision, diffusion), read
+[Streamline field: method](../streamline-field-method.md).
+
+## The input: one tall path per neuron
+
+Each path is an ordered `n x 3` array of points running along the cortical axis —
+in practice, a tall single dendritic path from a deep soma up the apical trunk to a
+tip in upper cortex, ordered tip → root. Where the paths come from (skeletons,
+neuroglancer annotations) does not matter. Paths are in the dataset's **native
+nanometers** unless you say otherwise.
+
+## Build from a script (recommended)
+
+The repo ships `scripts/build_streamline_field.py`, a `uv run` script that loads a
+directory of per-neuron `.npy` files and writes the field `.npz`:
+
+```bash
+uv run python scripts/build_streamline_field.py \
+    --paths /path/to/apical_paths \
+    --dataset v1dd
+```
+
+Arguments:
+
+| flag | meaning |
+|---|---|
+| `--paths` | directory of per-neuron `.npy` files (native nm; only x,y,z used) |
+| `--dataset` | selects the nm transform and default output name (`v1dd` or `minnie`) |
+| `--out` | output `.npz` path (default `standard_transform/data/<dataset>_streamline_field.npz`) |
+| `--bin-size` | grid spacing X Y Z in microns (default `30 20 30`) |
+| `--depth-band` | in-band depth range LO HI in microns (default `150 700`) |
+| `--validate N` | hold out `N` paths, rebuild on the rest, and report held-out median lateral deviation as a QC check |
+
+The shipped field is always built on **all** paths; `--validate` only builds a
+throwaway field for quality reporting.
+
+## Build programmatically
+
+To build a field in your own code, call `streamline_field_from_paths` directly:
+
+```python
+from standard_transform import streamline_field_from_paths, v1dd_transform
+
+field = streamline_field_from_paths(
+    paths,                     # list of n_i x 3 arrays, native nm, tip -> root
+    tform=v1dd_transform(),    # transform into oriented microns (nm input)
+    bin_size=(30.0, 20.0, 30.0),
+    depth_band=(150.0, 700.0),
+)
+field.to_npz("my_field.npz")
+```
+
+Useful parameters (see the [API reference](../reference/streamlines.md) for the full
+list):
+
+- `weights` — per-path or per-segment weights to down-weight unreliable structure
+  (e.g. by Strahler index / inverse branch order).
+- `depth_band` — only segments in this depth range inform the field, and the grid
+  spans exactly this range; outside it, orientation is held constant.
+- `smoothing_passes` / `smoothing_strength` — control the precision-weighted
+  diffusion that fills empty cells and denoises.
+
+## Persist and reload
+
+```python
+field.to_npz("my_field.npz")
+
+from standard_transform import StreamlineField, v1dd_transform
+field = StreamlineField.from_npz("my_field.npz", tform=v1dd_transform())
+```
+
+The grid is stored in **unit-agnostic post-transform microns**, so a single `.npz`
+serves both the nm and voxel variants of a dataset — only the attached transform
+differs. The transform is not saved in the file; you reattach one on load.
+
+## Wire it into a dataset
+
+Once a field `.npz` exists in `standard_transform/data/`, add a row to the streamline
+version registry in `datasets.py` pointing at it and mark it latest — the dataset's
+`streamline()` then returns it by default, while the prior `version="1.4"` hand-drawn
+curve stays reachable. This mirrors how v1dd is wired; see
+[Versioning & reproducibility](../concepts/versioning.md).