zarr-vectors-tools 0.2.0__tar.gz

zarr_vectors_tools-0.2.0/.github/actions/install-for-tests/action.yml

@@ -0,0 +1,100 @@
+name: Install for tests
+description: >-
+  Set up Python, install zarr-vectors core from git at the pinned commit, then
+  this package with its dev toolchain and every optional reader the runner can
+  install.  Used by both test tiers in .github/workflows/tests.yml.
+
+inputs:
+  python-version:
+    description: Python version to set up.
+    required: true
+  core-repo:
+    description: Git URL of zarr-vectors-py.
+    required: true
+  core-sha:
+    description: Full commit SHA of zarr-vectors-py to install.
+    required: true
+
+runs:
+  using: composite
+  steps:
+    - uses: actions/setup-python@v7
+      with:
+        python-version: ${{ inputs.python-version }}
+        cache: pip
+        cache-dependency-path: pyproject.toml
+
+    - name: Install core at the pin, this package, and the optional readers
+      shell: bash
+      env:
+        CORE: zarr-vectors @ git+${{ inputs.core-repo }}@${{ inputs.core-sha }}
+        PY: ${{ inputs.python-version }}
+      run: |
+        set -euo pipefail
+        python -m pip install --upgrade pip
+
+        # Core is named by URL in every install below, so the resolver can
+        # never swap it for a PyPI release (none of those carries the
+        # `zarr_vectors.building` surface this package imports).
+        if python -m pip install "$CORE" -e ".[all,dev]"; then
+          exit 0
+        fi
+
+        # One optional reader has no wheel, or fails to build, for this OS and
+        # Python.  Core, this package and pytest must still install; the extras
+        # then go one at a time so a broken reader costs only its own tests,
+        # which skip through pytest.importorskip.  The annotation keeps that
+        # visible on the run page instead of leaving a quietly thinner suite.
+        echo "::warning title=Optional readers::'.[all,dev]' did not install on $RUNNER_OS / Python $PY; installing the extras one at a time"
+        python -m pip install "$CORE" -e ".[dev]"
+        for extra in las ply trk trx surfaces graph h5ad points-enrichment mesh precomputed parallel; do
+          python -m pip install "$CORE" -e ".[$extra]" \
+            || echo "::warning title=Optional extra not installed::[$extra] did not install on $RUNNER_OS / Python $PY; its tests will be skipped"
+        done
+
+    - name: Check the pin, and report which optional readers are present
+      shell: bash
+      env:
+        CORE_SHA: ${{ inputs.core-sha }}
+      run: |
+        python - <<'EOF'
+        import importlib
+        import json
+        import os
+        import platform
+        from importlib.metadata import distribution
+
+        # pip records the commit it built from; refuse to test anything else.
+        direct = json.loads(distribution("zarr-vectors").read_text("direct_url.json") or "{}")
+        got = direct.get("vcs_info", {}).get("commit_id")
+        if got != os.environ["CORE_SHA"]:
+            raise SystemExit(f"zarr-vectors is at {got!r}, not the pinned {os.environ['CORE_SHA']}")
+        import zarr_vectors
+        import zarr_vectors.building  # this package fails at import without it
+        import zarr_vectors_tools
+
+        readers = {
+            "laspy": "las", "plyfile": "ply", "nibabel": "trk, surfaces", "trx": "trx",
+            "networkx": "graph", "anndata": "h5ad", "scipy": "points-enrichment, mesh",
+            "pyfqmr": "mesh", "cloudvolume": "precomputed", "mapbuffer": "precomputed",
+            "cloudfiles": "precomputed", "dask.distributed": "parallel",
+        }
+        rows = [
+            f"### {platform.system()}, Python {platform.python_version()}",
+            f"zarr-vectors {zarr_vectors.__version__} at `{got}`",
+            "",
+            "| module | extra | importable |",
+            "| --- | --- | --- |",
+        ]
+        for module, extra in readers.items():
+            try:
+                importlib.import_module(module)
+                ok = "yes"
+            except Exception as exc:  # a broken binary counts as missing too
+                ok = f"**no** ({type(exc).__name__}): its tests skip"
+            rows.append(f"| `{module}` | `{extra}` | {ok} |")
+        text = "\n".join(rows) + "\n"
+        print(text)
+        with open(os.environ["GITHUB_STEP_SUMMARY"], "a", encoding="utf-8") as fh:
+            fh.write(text)
+        EOF

zarr_vectors_tools-0.2.0/.github/workflows/tests.yml

@@ -0,0 +1,141 @@
+name: Tests
+
+# Two tiers, split by the `slow` marker (see [tool.pytest.ini_options] in
+# pyproject.toml):
+#
+#   lint + fast tier   every push to main / APEX-hackathon, and every PR
+#   full tier          nightly, and on demand (Actions tab -> Run workflow)
+#
+# Runners are shared with zarr-vectors-py's own suite, so this workflow keeps
+# its footprint small: push runs only on the long-lived branches (a feature
+# branch is tested through its PR, not twice), docs-only changes skip it, and
+# a newer push cancels the run it supersedes.
+#
+# GitHub only fires `schedule` from the default branch, and only offers
+# "Run workflow" once this file is on it.  So the nightly tests main; to run
+# the full tier on another branch, dispatch it with that ref:
+#
+#   gh workflow run tests.yml --ref APEX-hackathon -f tier=full
+
+on:
+  push:
+    branches: [main, APEX-hackathon]
+    paths-ignore: ["docs/**", "examples/**", "benchmarks/**", "assets/**", "**/*.md", ".readthedocs.yaml"]
+  pull_request:
+    paths-ignore: ["docs/**", "examples/**", "benchmarks/**", "assets/**", "**/*.md", ".readthedocs.yaml"]
+  schedule:
+    - cron: "17 7 * * *"   # 07:17 UTC; off the hour, when scheduled load peaks
+  workflow_dispatch:
+    inputs:
+      tier:
+        description: Which tier to run
+        type: choice
+        options: [full, fast]
+        default: full
+
+permissions:
+  contents: read
+
+# The event is part of the group so a push to main cannot cancel the nightly
+# that happens to be running on main.  Only push/PR runs cancel each other.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'push' || github.event_name == 'pull_request' }}
+
+env:
+  # This package needs an UNRELEASED core: the merged links/<delta>/<offsets>/
+  # layout and the `zarr_vectors.building` surface (see the comment on the
+  # zarr-vectors dependency in pyproject.toml), which are on core's main but
+  # not yet in a release.  No version specifier can express that, so CI
+  # installs core from git at this one pinned commit.
+  #
+  # To bump: pick a commit that is pushed to the core repo (a local-only
+  # commit will not clone), check this package's tests pass against it, and
+  # paste its full 40-character SHA here.  For the commit your local core
+  # checkout is on:
+  #
+  #   git -C ../zarr-vectors-py log -1 --format=%H
+  #   git -C ../zarr-vectors-py branch -r --contains <sha>   # must list a branch
+  #
+  # Currently core's main at the merge of core PR #35 (its APEX-hackathon).
+  CORE_SHA: 6794461a5f03e8defe936ca88a5536fce6ea4f49
+  CORE_REPO: https://github.com/AllenInstitute/zarr-vectors-py
+  PIP_DISABLE_PIP_VERSION_CHECK: "1"
+
+defaults:
+  run:
+    shell: bash   # Git Bash on Windows, so every step reads the same
+
+jobs:
+  lint:
+    if: github.event_name == 'push' || github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+      # Pinned so a new ruff release cannot turn a clean tree red overnight;
+      # bump it deliberately and fix what it finds.
+      - run: python -m pip install "ruff==0.15.13"
+      # The package, not the repo: zarr_vectors_tools/ is lint-clean, while
+      # older test files still carry ~15 known cosmetic violations (long
+      # lines, `l` as a name, `a; b`).  Widen this once tests/ is cleaned up.
+      - run: ruff check --output-format=github zarr_vectors_tools
+
+  fast:
+    name: fast tier (${{ matrix.os }}, py${{ matrix.python }})
+    if: >-
+      github.event_name == 'push' ||
+      github.event_name == 'pull_request' ||
+      (github.event_name == 'workflow_dispatch' && inputs.tier == 'fast')
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # Lowest and highest supported Python on Linux ...
+          - {os: ubuntu-latest, python: "3.11"}
+          - {os: ubuntu-latest, python: "3.13"}
+          # ... and Windows, whose process pools spawn rather than fork and
+          # whose atomic renames fail where POSIX ones succeed.
+          - {os: windows-latest, python: "3.13"}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ./.github/actions/install-for-tests
+        with:
+          python-version: ${{ matrix.python }}
+          core-repo: ${{ env.CORE_REPO }}
+          core-sha: ${{ env.CORE_SHA }}
+      # Budget: under 5 minutes.  The step limit is looser so runner noise
+      # does not fail it, but a test that belongs in the slow tier still gets
+      # caught here; --durations names the culprit.
+      - name: pytest -m "not slow"
+        timeout-minutes: 15
+        run: python -m pytest -m "not slow" -rs --durations=20 --basetemp="$RUNNER_TEMP/pytest"
+
+  full:
+    name: full tier (${{ matrix.os }}, py${{ matrix.python }})
+    if: >-
+      github.event_name == 'schedule' ||
+      (github.event_name == 'workflow_dispatch' && inputs.tier == 'full')
+    runs-on: ${{ matrix.os }}
+    # About 30 minutes on an idle workstation; hosted runners are slower.
+    timeout-minutes: 180
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ["3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ./.github/actions/install-for-tests
+        with:
+          python-version: ${{ matrix.python }}
+          core-repo: ${{ env.CORE_REPO }}
+          core-sha: ${{ env.CORE_SHA }}
+      # A short --basetemp keeps deep store paths clear of Windows' 260-char limit.
+      - name: pytest
+        run: python -m pytest -rs --durations=30 --basetemp="$RUNNER_TEMP/pytest"

zarr_vectors_tools-0.2.0/.gitignore

@@ -0,0 +1,23 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# Pytest
+.pytest_cache/
+
+# Docs build artifacts
+docs/_build/
+
+# Editor / OS
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+.claude/

zarr_vectors_tools-0.2.0/.readthedocs.yaml

@@ -0,0 +1,20 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+  jobs:
+    install:
+      # zarr-vectors isn't on PyPI and isn't needed at docs build time —
+      # docs/conf.py mocks it via autodoc_mock_imports. Install the on-PyPI
+      # extras, then this package with --no-deps so pip doesn't try to
+      # resolve zarr-vectors, then the Sphinx toolchain.
+      - pip install numpy pandas laspy plyfile nibabel trx-python networkx scipy
+      - pip install --no-deps .
+      - pip install -r docs/requirements-docs.txt
+
+sphinx:
+  builder: html
+  configuration: docs/conf.py
+  fail_on_warning: false

zarr_vectors_tools-0.2.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: zarr-vectors-tools
+Version: 0.2.0
+Summary: Ingest and export workflows for the Zarr Vectors. Wraps third-party readers/writers (nibabel, laspy, plyfile, networkx, trx-python) on top of zarr-vectors.
+Author: Andrew Keenlyside, Forrest Collman
+License: BSD-3-Clause
+Keywords: zarr,point-cloud,mesh,skeleton,streamline,connectomics,spatial,ingest,export
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: zarr-vectors>=0.2.1.dev0
+Requires-Dist: zarr>=3.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Provides-Extra: las
+Requires-Dist: laspy>=2.4; extra == "las"
+Provides-Extra: ply
+Requires-Dist: plyfile>=1.0; extra == "ply"
+Provides-Extra: trk
+Requires-Dist: nibabel>=5.0; extra == "trk"
+Provides-Extra: trx
+Requires-Dist: trx-python>=0.3; extra == "trx"
+Provides-Extra: streamlines
+Requires-Dist: zarr-vectors-tools[trk,trx]; extra == "streamlines"
+Provides-Extra: surfaces
+Requires-Dist: nibabel>=5.0; extra == "surfaces"
+Provides-Extra: graph
+Requires-Dist: networkx>=3.0; extra == "graph"
+Provides-Extra: h5ad
+Requires-Dist: anndata>=0.10; extra == "h5ad"
+Provides-Extra: points-enrichment
+Requires-Dist: scipy>=1.10; extra == "points-enrichment"
+Provides-Extra: mesh
+Requires-Dist: pyfqmr>=0.2; extra == "mesh"
+Requires-Dist: scipy>=1.10; extra == "mesh"
+Provides-Extra: precomputed
+Requires-Dist: cloud-volume>=8.0; extra == "precomputed"
+Requires-Dist: mapbuffer>=0.7; extra == "precomputed"
+Requires-Dist: cloud-files>=4.0; extra == "precomputed"
+Provides-Extra: parallel
+Requires-Dist: dask[distributed]>=2024.0; extra == "parallel"
+Provides-Extra: recipes
+Requires-Dist: pyyaml>=6.0; extra == "recipes"
+Provides-Extra: gpu
+Requires-Dist: cudf; extra == "gpu"
+Provides-Extra: all
+Requires-Dist: laspy>=2.4; extra == "all"
+Requires-Dist: plyfile>=1.0; extra == "all"
+Requires-Dist: nibabel>=5.0; extra == "all"
+Requires-Dist: trx-python>=0.3; extra == "all"
+Requires-Dist: networkx>=3.0; extra == "all"
+Requires-Dist: anndata>=0.10; extra == "all"
+Requires-Dist: scipy>=1.10; extra == "all"
+Requires-Dist: pyfqmr>=0.2; extra == "all"
+Requires-Dist: cloud-volume>=8.0; extra == "all"
+Requires-Dist: mapbuffer>=0.7; extra == "all"
+Requires-Dist: cloud-files>=4.0; extra == "all"
+Requires-Dist: dask[distributed]>=2024.0; extra == "all"
+Requires-Dist: pyyaml>=6.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-xdist>=3.5; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: jupyter>=1.0; extra == "dev"
+Requires-Dist: matplotlib>=3.7; extra == "dev"
+
+> [!NOTE]
+> This package is under development and will change. It will also be migrated to another location once completed.
+
+<img src="assets/zarr-vectors.png" alt="zarr-vectors" width="60%" />
+
+# zarr-vectors-tools
+
+**File format workflows, algorithms, and multiresolution for Zarr Vectors.**
+
+**`zarr-vectors-tools` is an extension of [`zarr-vectors-py`](https://github.com/Andrew-Keenlyside/zarr-vectors-py).** It is not a standalone library, and neither this README nor its documentation restates that package's.
+
+`zarr-vectors-py` owns **Zarr Vectors** — the specification and the Python API over it: store layout, chunk and bin geometry, fragments, links, the object model, resolution-level metadata, validation, and the two supported surfaces `zarr_vectors.api` and `zarr_vectors.building`. Anything about the format or the core API is documented [there](https://zarr-vectors-py.readthedocs.io/en/latest) and only there.
+
+This package adds the layers built on top of it: format-conversion workflows wrapping third-party readers and writers, streaming graph and mesh algorithms, the rich multiresolution coarsening layer, and the `zvtools` CLI.
+
+*Zarr Vectors was originally specified by Forrest Collman, Allen Institute for Brain Sciences.*
+
+| | |
+| --- | --- |
+| Documentation (this package) | [zarr-vectors-tools docs](https://zarr-vectors-tools.readthedocs.io/en/latest) |
+| **Parent package** | [zarr-vectors-py](https://github.com/Andrew-Keenlyside/zarr-vectors-py) · [docs](https://zarr-vectors-py.readthedocs.io/en/latest) |
+| **Specification** | [Zarr Vectors specification](https://zarr-vectors-py.readthedocs.io/en/latest/spec/index.html) |
+| **Core API reference** | [zarr_vectors.api / zarr_vectors.building](https://zarr-vectors-py.readthedocs.io/en/latest/api/index.html) |
+| Upstream specification | [AllenInstitute/zarr_vectors](https://github.com/AllenInstitute/zarr_vectors) |
+
+---
+
+## Install
+
+```bash
+pip install zarr-vectors-tools
+```
+
+Python ≥ 3.11. Every file format is gated behind an extra, so a base install stays slim:
+
+```bash
+pip install "zarr-vectors-tools[trk]"           # nibabel (TRK)
+pip install "zarr-vectors-tools[streamlines]"   # nibabel + trx-python
+pip install "zarr-vectors-tools[all]"           # everything except gpu
+```
+
+Extras: `las`, `ply`, `trk`, `trx`, `streamlines`, `graph`, `points-enrichment`, `mesh`, `precomputed`, `parallel`, `gpu`, `all`, `dev`.
+
+> [!IMPORTANT]
+> This package requires the merged `links/<delta>/<offsets>/` layout — on-disk **format 0.9.0** — in which connectivity is a single family and there is no `cross_chunk_links/` to fall back to. That format ships in the current core *development* line, whose *package* version is still 0.2.x; format version and package version are independent. The reliable install is an editable core working tree:
+>
+> ```bash
+> git clone https://github.com/Andrew-Keenlyside/zarr-vectors-py
+> pip install -e ./zarr-vectors-py
+> ```
+
+## Quick start
+
+From the terminal:
+
+```bash
+zvtools convert cells.csv cells.zarrvectors --chunk-shape 100,100,100
+zvtools pyramid cells.zarrvectors --coarsen 8,8 --sparsity 2,2
+zvtools convert cells.zarrvectors cells.ply --level 1   # and back out again
+zvtools merge cells.zarrvectors more_cells.csv       # append, don't replace
+zvtools split cells.zarrvectors parts/ --by groups
+zvtools info cells.zarrvectors
+zvtools validate cells.zarrvectors --level 3
+```
+
+From Python — note that `convert.ingest` and `convert.export` have no re-exports, so import from the concrete module:
+
+```python
+from zarr_vectors_tools.convert.ingest.csv_points import ingest_csv
+from zarr_vectors_tools.multiresolution.coarsen import build_pyramid
+from zarr_vectors_tools.algorithms import compute_connected_components
+
+ingest_csv("cells.csv", "cells.zarrvectors", chunk_shape=(100.0, 100.0, 100.0))
+build_pyramid("cells.zarrvectors", factors=[(8.0, 2.0), (8.0, 2.0)])
+```
+
+## What's in it
+
+| Subpackage | Purpose |
+| --- | --- |
+| `convert.ingest` | CSV/XYZ, LAS/LAZ, PLY, line CSV, TCK, TRK, TRX, SWC, precomputed skeletons, OBJ, STL, edge-list CSV, GraphML, GIFTI, FreeSurfer |
+| `convert.export` | CSV, PLY, TRK, TRX, SWC, OBJ, h5ad |
+| `compose` | merge a file or another store into an existing one; split a store by group, label or merged source |
+| `multiresolution` | pyramid building: skeleton/polyline/point/mesh/graph coarsening, five object-selection strategies, cross-level links |
+| `algorithms` | streaming graph search, connected components, clustering; mesh summary, attributes, spatial queries |
+| `headers` | format-specific metadata preservation |
+| `cli` | the `zvtools` command line |
+
+Coarsening and sparsity are two orthogonal axes — coarsening reduces vertices *within* each object, sparsity drops whole objects while preserving the IDs of survivors. See [Coarsening versus sparsity](https://zarr-vectors-tools.readthedocs.io/en/latest/multiresolution/concepts.html).
+
+## Development
+
+```bash
+git clone https://github.com/AllenInstitute/zarr-vectors-tools
+cd zarr-vectors-tools
+pip install -e ".[all,dev]"
+pytest
+```
+
+Build the docs locally:
+
+```bash
+pip install -r docs/requirements-docs.txt
+python -m sphinx -b html docs docs/_build/html
+```
+
+## License
+
+BSD-3-Clause.

zarr_vectors_tools-0.2.0/README.md

@@ -0,0 +1,109 @@
+> [!NOTE]
+> This package is under development and will change. It will also be migrated to another location once completed.
+
+<img src="assets/zarr-vectors.png" alt="zarr-vectors" width="60%" />
+
+# zarr-vectors-tools
+
+**File format workflows, algorithms, and multiresolution for Zarr Vectors.**
+
+**`zarr-vectors-tools` is an extension of [`zarr-vectors-py`](https://github.com/Andrew-Keenlyside/zarr-vectors-py).** It is not a standalone library, and neither this README nor its documentation restates that package's.
+
+`zarr-vectors-py` owns **Zarr Vectors** — the specification and the Python API over it: store layout, chunk and bin geometry, fragments, links, the object model, resolution-level metadata, validation, and the two supported surfaces `zarr_vectors.api` and `zarr_vectors.building`. Anything about the format or the core API is documented [there](https://zarr-vectors-py.readthedocs.io/en/latest) and only there.
+
+This package adds the layers built on top of it: format-conversion workflows wrapping third-party readers and writers, streaming graph and mesh algorithms, the rich multiresolution coarsening layer, and the `zvtools` CLI.
+
+*Zarr Vectors was originally specified by Forrest Collman, Allen Institute for Brain Sciences.*
+
+| | |
+| --- | --- |
+| Documentation (this package) | [zarr-vectors-tools docs](https://zarr-vectors-tools.readthedocs.io/en/latest) |
+| **Parent package** | [zarr-vectors-py](https://github.com/Andrew-Keenlyside/zarr-vectors-py) · [docs](https://zarr-vectors-py.readthedocs.io/en/latest) |
+| **Specification** | [Zarr Vectors specification](https://zarr-vectors-py.readthedocs.io/en/latest/spec/index.html) |
+| **Core API reference** | [zarr_vectors.api / zarr_vectors.building](https://zarr-vectors-py.readthedocs.io/en/latest/api/index.html) |
+| Upstream specification | [AllenInstitute/zarr_vectors](https://github.com/AllenInstitute/zarr_vectors) |
+
+---
+
+## Install
+
+```bash
+pip install zarr-vectors-tools
+```
+
+Python ≥ 3.11. Every file format is gated behind an extra, so a base install stays slim:
+
+```bash
+pip install "zarr-vectors-tools[trk]"           # nibabel (TRK)
+pip install "zarr-vectors-tools[streamlines]"   # nibabel + trx-python
+pip install "zarr-vectors-tools[all]"           # everything except gpu
+```
+
+Extras: `las`, `ply`, `trk`, `trx`, `streamlines`, `graph`, `points-enrichment`, `mesh`, `precomputed`, `parallel`, `gpu`, `all`, `dev`.
+
+> [!IMPORTANT]
+> This package requires the merged `links/<delta>/<offsets>/` layout — on-disk **format 0.9.0** — in which connectivity is a single family and there is no `cross_chunk_links/` to fall back to. That format ships in the current core *development* line, whose *package* version is still 0.2.x; format version and package version are independent. The reliable install is an editable core working tree:
+>
+> ```bash
+> git clone https://github.com/Andrew-Keenlyside/zarr-vectors-py
+> pip install -e ./zarr-vectors-py
+> ```
+
+## Quick start
+
+From the terminal:
+
+```bash
+zvtools convert cells.csv cells.zarrvectors --chunk-shape 100,100,100
+zvtools pyramid cells.zarrvectors --coarsen 8,8 --sparsity 2,2
+zvtools convert cells.zarrvectors cells.ply --level 1   # and back out again
+zvtools merge cells.zarrvectors more_cells.csv       # append, don't replace
+zvtools split cells.zarrvectors parts/ --by groups
+zvtools info cells.zarrvectors
+zvtools validate cells.zarrvectors --level 3
+```
+
+From Python — note that `convert.ingest` and `convert.export` have no re-exports, so import from the concrete module:
+
+```python
+from zarr_vectors_tools.convert.ingest.csv_points import ingest_csv
+from zarr_vectors_tools.multiresolution.coarsen import build_pyramid
+from zarr_vectors_tools.algorithms import compute_connected_components
+
+ingest_csv("cells.csv", "cells.zarrvectors", chunk_shape=(100.0, 100.0, 100.0))
+build_pyramid("cells.zarrvectors", factors=[(8.0, 2.0), (8.0, 2.0)])
+```
+
+## What's in it
+
+| Subpackage | Purpose |
+| --- | --- |
+| `convert.ingest` | CSV/XYZ, LAS/LAZ, PLY, line CSV, TCK, TRK, TRX, SWC, precomputed skeletons, OBJ, STL, edge-list CSV, GraphML, GIFTI, FreeSurfer |
+| `convert.export` | CSV, PLY, TRK, TRX, SWC, OBJ, h5ad |
+| `compose` | merge a file or another store into an existing one; split a store by group, label or merged source |
+| `multiresolution` | pyramid building: skeleton/polyline/point/mesh/graph coarsening, five object-selection strategies, cross-level links |
+| `algorithms` | streaming graph search, connected components, clustering; mesh summary, attributes, spatial queries |
+| `headers` | format-specific metadata preservation |
+| `cli` | the `zvtools` command line |
+
+Coarsening and sparsity are two orthogonal axes — coarsening reduces vertices *within* each object, sparsity drops whole objects while preserving the IDs of survivors. See [Coarsening versus sparsity](https://zarr-vectors-tools.readthedocs.io/en/latest/multiresolution/concepts.html).
+
+## Development
+
+```bash
+git clone https://github.com/AllenInstitute/zarr-vectors-tools
+cd zarr-vectors-tools
+pip install -e ".[all,dev]"
+pytest
+```
+
+Build the docs locally:
+
+```bash
+pip install -r docs/requirements-docs.txt
+python -m sphinx -b html docs docs/_build/html
+```
+
+## License
+
+BSD-3-Clause.

zarr_vectors_tools-0.2.0/benchmarks/README.md

@@ -0,0 +1,74 @@
+# Benchmarks
+
+Two suites, answering two different questions. Both live here rather
+than in `zarr-vectors-py` so the core package keeps its dependency
+surface at `numpy` / `numcodecs` / `zarr` — the benchmarks need
+`pandas`, `matplotlib`, `jupyter`, and (for the format comparisons)
+the third-party readers this package already wraps.
+
+| Suite | Question | Contents |
+|-------|----------|----------|
+| [`paper/`](paper/) | *The three claims the paper makes, and nothing else.* | scripts — 8 panels as separate files + one supplementary table |
+| [`formats/`](formats/) | *How does Zarr Vectors compare to the format I use today?* | 3 notebooks — Zarr Vectors reads/filters vs PLY, CSV, TRX, GraphML, SWC, OBJ |
+| [`internals/`](internals/) | *How does Zarr Vectors scale along axis X?* | 8 notebooks — size, geometry type, backend, pyramid, bbox query, chunk shape, codec, edit cost |
+
+`formats/` and `internals/` are exploratory: each has its own
+`README.md`, its own `_build.py`, and its own `01..N` numbering. They
+share no code; the small timing/stats helpers (`_time`, `_store_bytes`,
+`_mean_ci95`, `N_RUNS = 10`, `T95_DF9 = 2.262`) are duplicated into each
+generated notebook, which is what keeps a notebook runnable standalone.
+
+`paper/` is different in kind — it is a publication artefact, not an
+exploration. It is scripts rather than notebooks so that the measurement
+can be re-run on reference hardware and the panels regenerated from the
+committed CSV without re-measuring; the panels are written one per file
+so the figure can be composed wherever the paper is being written. Start there if you want the headline
+comparison; start in the other two if you want to understand a
+particular axis.
+
+## Running
+
+```bash
+pip install -e ".[all]" jupyter matplotlib
+jupyter lab benchmarks/
+```
+
+Then open a notebook and run all cells. Budget ~5 minutes for the
+long ones (`formats/01_size_scaling`, `internals/01_size_scaling`,
+`internals/08_edit_operations`).
+
+`paper/` is scripts, not notebooks, so it runs from a shell instead:
+
+```bash
+python benchmarks/paper/run_sweep.py     # 10^3..10^6, ~20-30 min
+python benchmarks/paper/run_large.py     # 10^3..10^7, ~1.5 h, resumable
+python benchmarks/paper/make_figure.py   # seconds
+```
+
+The default sweep stops at 10^6 because one more decade roughly triples
+its wall time, and it is mostly run to check that nothing regressed.
+`run_large.py` drives the same measurement code one decade further, block
+by block into `paper/results/large/`, so the long run is opt-in and a
+killed one can be resumed. See [`paper/README.md`](paper/README.md).
+
+## Regenerating
+
+Notebooks are generated; never edit the `.ipynb` directly.
+
+```bash
+python benchmarks/formats/_build.py     # rewrites formats/*.ipynb
+python benchmarks/internals/_build.py   # rewrites internals/*.ipynb
+```
+
+## Shared caveats
+
+- Wall time and on-disk bytes only — no memory profiling.
+- No CI gating in either suite. The only automated performance guard
+  in the project is `tests/test_perf_writes.py` over in
+  `zarr-vectors-py`, which asserts loose (~3×) wall-clock ceilings to
+  catch order-of-magnitude regressions.
+- Synthetic data with `SEED = 0`. Real datasets have different
+  sparsity and chunk-occupancy patterns, and therefore different
+  scaling slopes.
+- Machine-dependent. These are "what to expect on my hardware" sanity
+  plots, not authoritative numbers.