tidy3a 0.1.0__tar.gz

tidy3a-0.1.0/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+## 0.1.0 — 2026-10-24
+
+First release.
+
+- `read_array` reads raw numeric files, `.npy` files, and in-memory NumPy
+  arrays, with `infer`, labels, `field_axis=`, `variables_from=`, byte
+  order, storage order, header offsets, and memory-mapping.
+- `read_binary` reads packed or explicitly padded mixed records into
+  separate typed variables. `fixed_text` declares strict UTF-8/ASCII text
+  decoding and padding; numeric fields retain their widths and kinds.
+- `tidy()` wraps xarray objects; `TidyArray` reports its axes, labels, axis
+  roles, and anything the reader inferred.
+- Tidy-layer verbs: `select` with tidy3's selection helpers, `filter`,
+  `slice`/`slice_head`/`slice_tail`, `mutate` with write-back and vector
+  assignment, `group_by` by axis, value, or `bins()`, `summarise`,
+  `ungroup`, `pull`, `bind_cols`, and `left_join`/`inner_join`/`full_join`.
+- Expressions: `col`, `variable`, `label`, `env`, `fields`, `[x, y, z]`
+  vectors, `if_else`, and reductions `mean`, `sum`, `min`, `max`, `median`,
+  `std`, `var` (variance, as in tidy3 and dplyr), `any`, and `all` with
+  `over=` and `na_rm=`, plus `n()` for observation counts.
+- Exact label alignment, with reordering by label and explicit joins.
+- Metadata: wrapping keeps attributes and encodings; new and computed
+  results clear stale serialization encoding and inherited attributes,
+  direct aliases keep theirs, and joins report dropped conflicting
+  attributes.
+- Lazy input: NetCDF and Dask-backed data stay lazy through inspection,
+  selection, regular positional slicing, arithmetic, and reductions until
+  `collect()`; grouping, filtering, and field write-back read the values
+  they need, as documented.
+- Array layer: `dot` with `over=`, elementwise numeric functions, `conj`,
+  `real`, `imag`, `angle`, `arctan2`, `rename_axes`, and `pack`.
+- `formula()`: plain mathematical text and a strict LaTeX dialect with
+  plot3's conventions, subscripts as axis indices, labels, and positions,
+  `\sum` with optional checked bounds, `bind=` for index letters and
+  values, and show-back of how each formula was read.
+- Notebook layer (`%load_ext tidy3a.jupyter`): bare names in tidy3A verbs,
+  settled when the verb runs, with an error when a name is both data and a
+  notebook variable; `[x, y, z] = …` inside `mutate`; only tidy3A's own
+  calls are rewritten, so tidy3 and tidy3A share a notebook.
+- `n()` counts observations on the axes every non-scalar variable shares.
+- Inspection output shows time labels to the second (or as dates) and
+  floats to 10 significant digits, with a gap before each axis role.
+- Examples on real data: a nuScenes Mini LiDAR sweep, and three public
+  sample datasets (air temperature, ERA-Interim wind, a Landsat scene),
+  each checked against plain NumPy or xarray.
+- Source distributions include documentation, examples, and prototype
+  tests. Packaging checks build a wheel from the source archive and
+  validate both distributions' metadata. The build requires setuptools
+  77.0.3 or newer for the license metadata.
+- Requires Python 3.11+, NumPy 2.0+, pandas 2.2.2+ (now declared, as
+  tidy3A imports it directly), and xarray 2024.6+.
+- Publishing a GitHub Release runs the version check and reusable CI gate,
+  then uploads the validated distributions to PyPI through trusted publishing.

tidy3a-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rleyvasal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tidy3a-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include CHANGELOG.md
+include scripts/check.sh
+recursive-include docs *.md
+recursive-include examples *.py
+recursive-include prototypes *.py

tidy3a-0.1.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: tidy3a
+Version: 0.1.0
+Summary: Tidy-style verbs for named multidimensional arrays, built on xarray
+Author: Rigoberto Leyva Salmeron
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/rleyvasal/tidy3a
+Keywords: xarray,arrays,tidyverse,dplyr,point-cloud,raster
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.0
+Requires-Dist: pandas>=2.2.2
+Requires-Dist: xarray>=2024.6
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: flox>=0.9; extra == "dev"
+Requires-Dist: ipython>=8.0; extra == "dev"
+Requires-Dist: dask[array]; extra == "dev"
+Dynamic: license-file
+
+# tidy3A
+
+Tidy-style verbs for named multidimensional arrays: point clouds, images,
+sensor measurements, scientific and complex-valued arrays. Built on xarray
+and NumPy, in the spirit of [tidy3](https://github.com/rleyvasal/tidy3).
+
+**Status:** version `0.1.0` is prepared for the first release, not yet published.
+The design decisions are in [docs/plan.md](docs/plan.md); the rules fit on one page in
+[docs/decisions.md](docs/decisions.md).
+
+Requires Python 3.11 or newer. From a checkout, install the package:
+
+```bash
+python -m pip install -e .
+```
+
+## Quick start
+
+```python
+import numpy as np
+from tidy3a import fields, filter, formula, infer, mutate, read_array
+
+points = np.array([[3, 4, 0], [0, 0, 50], [60, 0, 0]], dtype="float32")
+cloud = read_array(
+    points,
+    dims={"point": infer, "feature": 3},
+    labels={"feature": ["x", "y", "z"]},
+    field_axis="feature",
+)
+x, y, z, distance = fields("x", "y", "z", "distance")
+
+nearby = (
+    cloud
+    >> mutate(distance = formula(r"\sqrt{x^2 + y^2 + z^2}"))
+    >> filter(distance <= 50)
+)
+print(nearby.collect()["distance"].values)  # [ 5. 50.]
+```
+
+The implemented API includes `read_array`, `read_binary`, `fixed_text`,
+`infer`, `tidy()`, tidy-layer
+verbs (`select`, `filter`, `slice`, `mutate`, `group_by`, `summarise`, joins,
+`pull`, `bind_cols`), array helpers (`dot`, numeric functions, `conj`,
+`rename_axes`, `pack`), and `formula()` for plain mathematical text and a
+strict LaTeX dialect. Scripts declare names with
+`fields()` or write `col("x")`. `collect()` returns a computed xarray
+Dataset; `to_xarray()` returns a shallow copy sharing the underlying values.
+
+## Notebooks
+
+Install IPython separately to use the notebook extension. In a notebook cell:
+
+```ipython
+%load_ext tidy3a.jupyter
+from tidy3a import *
+```
+
+The extension enables bare field names inside verbs, so the quick-start
+example can omit the `fields()` declaration. Multi-line pipes need
+parentheses. Sharing a notebook with tidy3 requires its ownership-aware
+transformer; the prerequisite is recorded in [the plan](docs/plan.md#56-notebook-layer).
+
+## Execution and first-release scope
+
+The first release runs eagerly on NumPy. `read_array` accepts homogeneous
+raw numeric files, `.npy` files, and NumPy arrays. `read_binary` reads mixed
+fixed-width records into separate variables, preserving numeric types and
+strictly decoding UTF-8/ASCII text declared with `fixed_text`. Records can
+be packed or have explicit field offsets and padding; see the
+[reader contract](docs/m6-read-binary.md) for supported options. `tidy()` wraps xarray
+DataArrays and Datasets; optional file readers stay in xarray's ecosystem.
+
+`read_array(..., lazy=True)` memory-maps raw and `.npy` files. It does not
+make the verb pipeline lazy: arithmetic can allocate results, filtering evaluates its
+mask, and updating a field label copies its containing array into memory.
+`tidy()` preserves a lazy xarray input initially; `collect()` computes it.
+Dask execution guarantees remain planned.
+
+Integer arithmetic follows NumPy, including unsigned subtraction wrapping
+around. Convert before subtracting when negative results are needed, for
+example `nir * 1.0 - red` for uint8 image bands. See
+[first-release limitations](docs/first-release.md) for the supported subset.
+
+## Examples and development
+
+The point-cloud example runs on real nuScenes Mini data and checks itself
+against plain NumPy:
+
+```bash
+python examples/nuscenes_sweep.py /path/to/nuscenes-mini
+```
+
+Three public sample datasets (gridded air temperature, ERA-Interim wind, and
+stars' Landsat scene) run against plain xarray; see
+[examples/sample_data.py](examples/sample_data.py) for the files, optional
+reader dependencies, and checks.
+
+To run the local tests:
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest -q
+```
+
+Before pushing, run the CI checks in fresh environments with only declared
+dependencies (requires [uv](https://docs.astral.sh/uv/)):
+
+```bash
+scripts/check.sh
+```
+
+The [release procedure](docs/releasing.md) describes the GitHub Release
+workflow and the one-time GitHub/PyPI setup.
+
+## License
+
+MIT

tidy3a-0.1.0/README.md

@@ -0,0 +1,117 @@
+# tidy3A
+
+Tidy-style verbs for named multidimensional arrays: point clouds, images,
+sensor measurements, scientific and complex-valued arrays. Built on xarray
+and NumPy, in the spirit of [tidy3](https://github.com/rleyvasal/tidy3).
+
+**Status:** version `0.1.0` is prepared for the first release, not yet published.
+The design decisions are in [docs/plan.md](docs/plan.md); the rules fit on one page in
+[docs/decisions.md](docs/decisions.md).
+
+Requires Python 3.11 or newer. From a checkout, install the package:
+
+```bash
+python -m pip install -e .
+```
+
+## Quick start
+
+```python
+import numpy as np
+from tidy3a import fields, filter, formula, infer, mutate, read_array
+
+points = np.array([[3, 4, 0], [0, 0, 50], [60, 0, 0]], dtype="float32")
+cloud = read_array(
+    points,
+    dims={"point": infer, "feature": 3},
+    labels={"feature": ["x", "y", "z"]},
+    field_axis="feature",
+)
+x, y, z, distance = fields("x", "y", "z", "distance")
+
+nearby = (
+    cloud
+    >> mutate(distance = formula(r"\sqrt{x^2 + y^2 + z^2}"))
+    >> filter(distance <= 50)
+)
+print(nearby.collect()["distance"].values)  # [ 5. 50.]
+```
+
+The implemented API includes `read_array`, `read_binary`, `fixed_text`,
+`infer`, `tidy()`, tidy-layer
+verbs (`select`, `filter`, `slice`, `mutate`, `group_by`, `summarise`, joins,
+`pull`, `bind_cols`), array helpers (`dot`, numeric functions, `conj`,
+`rename_axes`, `pack`), and `formula()` for plain mathematical text and a
+strict LaTeX dialect. Scripts declare names with
+`fields()` or write `col("x")`. `collect()` returns a computed xarray
+Dataset; `to_xarray()` returns a shallow copy sharing the underlying values.
+
+## Notebooks
+
+Install IPython separately to use the notebook extension. In a notebook cell:
+
+```ipython
+%load_ext tidy3a.jupyter
+from tidy3a import *
+```
+
+The extension enables bare field names inside verbs, so the quick-start
+example can omit the `fields()` declaration. Multi-line pipes need
+parentheses. Sharing a notebook with tidy3 requires its ownership-aware
+transformer; the prerequisite is recorded in [the plan](docs/plan.md#56-notebook-layer).
+
+## Execution and first-release scope
+
+The first release runs eagerly on NumPy. `read_array` accepts homogeneous
+raw numeric files, `.npy` files, and NumPy arrays. `read_binary` reads mixed
+fixed-width records into separate variables, preserving numeric types and
+strictly decoding UTF-8/ASCII text declared with `fixed_text`. Records can
+be packed or have explicit field offsets and padding; see the
+[reader contract](docs/m6-read-binary.md) for supported options. `tidy()` wraps xarray
+DataArrays and Datasets; optional file readers stay in xarray's ecosystem.
+
+`read_array(..., lazy=True)` memory-maps raw and `.npy` files. It does not
+make the verb pipeline lazy: arithmetic can allocate results, filtering evaluates its
+mask, and updating a field label copies its containing array into memory.
+`tidy()` preserves a lazy xarray input initially; `collect()` computes it.
+Dask execution guarantees remain planned.
+
+Integer arithmetic follows NumPy, including unsigned subtraction wrapping
+around. Convert before subtracting when negative results are needed, for
+example `nir * 1.0 - red` for uint8 image bands. See
+[first-release limitations](docs/first-release.md) for the supported subset.
+
+## Examples and development
+
+The point-cloud example runs on real nuScenes Mini data and checks itself
+against plain NumPy:
+
+```bash
+python examples/nuscenes_sweep.py /path/to/nuscenes-mini
+```
+
+Three public sample datasets (gridded air temperature, ERA-Interim wind, and
+stars' Landsat scene) run against plain xarray; see
+[examples/sample_data.py](examples/sample_data.py) for the files, optional
+reader dependencies, and checks.
+
+To run the local tests:
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest -q
+```
+
+Before pushing, run the CI checks in fresh environments with only declared
+dependencies (requires [uv](https://docs.astral.sh/uv/)):
+
+```bash
+scripts/check.sh
+```
+
+The [release procedure](docs/releasing.md) describes the GitHub Release
+workflow and the one-time GitHub/PyPI setup.
+
+## License
+
+MIT

tidy3a-0.1.0/docs/decisions.md

@@ -0,0 +1,19 @@
+# tidy3A tidy-layer rules
+
+The one-page rule set from plan §1.1: if the tidy layer's rules stop fitting on this page, simplify the layer rather than adding rules. Details, reasons, and precedents are in `docs/plan.md`, with section references below.
+
+**Data.** A dataset holds variables (named arrays). Each axis is either the one **field axis**, declared with `field_axis=`, whose labels act as column names, or an **observation axis**, whose labels are values. Without `field_axis=` there are only variables. `variables_from=` turns a labeled axis into one variable per label instead. (§3, §4.1)
+
+**Names.** In verbs and expressions, a name means, in order: a variable, then a field-axis label. A field label alone, `x`, is that field with the field axis dropped; a list `[x, y, z]` keeps the field axis, narrowed, and also rebuilds variables made by the same `variables_from=` import into their recorded axis. Other variables are packed with `pack([...], along=...)`. A name on an observation axis means that axis's labels (`filter(time > t0)`). A name that is both data and a notebook value is an error: write `col("x")` or `env("x")`. A name that is both a variable and a field label is an error: write `variable("x")` or `label("x")`. Scripts use strings or `fields("x", …)`. (§5.1, §5.2)
+
+**Verbs never reshape on their own.** `select` keeps variables and field labels (columns), with tidy3's selection helpers. `filter` keeps positions on observation axes (rows); every predicate must vary along one axis, and predicates on different axes combine with AND into a rectangle. `slice` keeps positions by 1-based position and keeps the axis unless `drop=True`. Filtering keeps original positions as labels. Empty results are returned. (§5.1, §5.3)
+
+**Mutate.** Assignments run in order. Writing to a field label writes into the shared array, promoting its type if needed. Vectors are written in one assignment, `[x, y, z] = …`. Masking is `if_else`. (§5.4)
+
+**Grouping.** `group_by` on an axis keeps it; on a value field, or `bins(...)` of one, it groups that field's one axis into a new axis of sorted values or intervals. `summarise` reduces every other observation axis and never the field axis. A summary using a variable without the grouping axis is an error. Grouped summaries inside `mutate` broadcast back. Missing values propagate unless `na_rm=True`. After `summarise`, the last grouping level is dropped (`groups=`). (§5.4)
+
+**Alignment.** Labels on a shared axis must match exactly; the same labels in another order are reordered and reported. Different labels need a join verb (`left_join`, `inner_join`, `full_join`, with `_x`/`_y` suffixes; `tolerance=` is currently supported only on `left_join`). A labeled axis never pairs with an unlabeled one by length; attach outside arrays with `bind_cols(…, along=)`, and read labels with `pull(axis)`. (§5.5)
+
+**Array layer.** Maths helpers name their axes: `dot(…, over=)`, `sum(…, over=)`, `rename_axes(…)`; `dot` never conjugates. `formula()` reads a strict LaTeX dialect into the same expressions, binds index letters to axes by name or `bind=`, and always shows how it was read. (§6)
+
+**Results.** `read_array` and `tidy()` return the wrapper. `collect()` returns a computed xarray Dataset; `to_xarray()` returns the underlying xarray object. (§3, §4.1)

tidy3a-0.1.0/docs/first-release.md

@@ -0,0 +1,69 @@
+# First-release scope and limitations
+
+Version `0.1.0` is the first release.
+The release notes are in [the changelog](../CHANGELOG.md). Progress and verification
+are recorded in [milestone 7](plan.md#milestone-7--independent-first-release).
+
+## Supported scope
+
+- Python 3.11 or newer, NumPy 2.0 or newer, pandas 2.2.2 or newer, and
+  xarray 2024.6 or newer.
+- Homogeneous raw numeric files, `.npy` files, and in-memory NumPy arrays
+  through `read_array`; xarray objects through `tidy()`.
+- Mixed fixed-width numeric/text records through `read_binary`, with
+  explicit padding layouts and strict UTF-8/ASCII `fixed_text` decoding.
+  The supported reader options are listed in [the contract](m6-read-binary.md).
+- Tidy verbs, exact label alignment, explicit joins, named-axis mathematics,
+  complex values, and the implemented plain-text and LaTeX formula dialect.
+- Script expressions with `fields()` or `col()`, and optional IPython
+  shorthand through `%load_ext tidy3a.jupyter`.
+
+## Memory and execution
+
+NumPy-backed operations run eagerly. `lazy=True` on `read_array` creates a
+read-only memory map; it does not defer the whole pipeline. Arithmetic can
+allocate arrays, filtering evaluates its predicate mask, and field-label
+updates copy the whole containing array, even when changing one field.
+`pull()` returns NumPy values and materializes the requested data.
+
+`tidy()` does not itself compute a lazy xarray input. Selection, regular
+positional slicing, arithmetic, and reductions on Dask-backed or file-backed
+xarray data stay lazy and are checked in the test suite
+([metadata and lazy input](m6-metadata-lazy.md)). Grouping by field values
+or bins reads the grouping values, filtering reads the mask, and field-label
+write-back reads and copies the containing array. `median(..., na_rm=True)`
+over every axis of a chunked array is an error that asks you to collect
+first. `collect()` computes the resulting Dataset. `to_xarray()` makes a
+shallow copy without computing it. Dask-backed grouping and performance
+guarantees are not part of this release; memory-mapping alone does not
+promise bounded memory use.
+
+## Known limitations
+
+- Grouping supports multiple axis keys but only one value-field or bin key.
+  Grouped `slice` and its head/tail helpers require `ungroup()` first.
+- Reductions with `over=` cannot be combined with grouping by a value field.
+  A summary cannot reference an earlier result in the same `summarise`;
+  derive from summary results in a following `mutate`.
+- `tolerance=` is implemented only for `left_join`. Other joins use exact
+  labels. `case_when` is not implemented; use `if_else` for binary choices.
+- xarray on the left of an arithmetic operator does not defer to a tidy3A
+  expression. Write `x * R` rather than `R * x`, or use `dot()`.
+- Integer arithmetic follows NumPy. For unsigned data, promote before a
+  subtraction that may be negative: `nir * 1.0 - red`.
+- Formulas support the dialect documented in [plan §6.3](plan.md#63-formula), with
+  errors for unsupported syntax. Product reductions, integrals, sums over
+  more than one index letter at once, and implicit multiplication in plain
+  text are not supported. Write `2*x` rather than `2x` in plain text.
+- Notebook pipes spanning lines need parentheses; tidy3-style backtick
+  names are not supported. Use `col("field name")` for such names.
+- Coexistence with tidy3's notebook extension requires tidy3's ownership
+  check (`_owned_by_tidy3`); the prerequisite change is recorded in the
+  implementation plan. The coexistence tests skip when it is unavailable.
+
+Mixed-record reading, metadata handling, and the lazy-input checks were
+brought forward from milestone 6 before publication. Dedicated NetCDF/Zarr
+readers, Dask-backed grouping, text encodings beyond UTF-8/ASCII, and
+variable-length records remain planned. Existing
+xarray readers can already be used with `tidy()`; their optional dependencies
+are installed separately.

tidy3a-0.1.0/docs/m0-examples.md

@@ -0,0 +1,127 @@
+# Milestone 0: acceptance examples in two styles
+
+Status: prototype comparison for review. None of the tidy3A code below is implemented. Each example's plain-xarray equivalent runs in `prototypes/test_examples.py` on small synthetic data with hand-checked answers, and `prototypes/test_xarray_assumptions.py` checks the xarray and NumPy behavior the plan relies on. Both pass (39 tests, xarray 2026.9.0, NumPy 2.5.4).
+
+The question this answers (plan §5.1, milestone 0): does `select` with a declared **field axis** read better than the **stars style**, where fields become separate variables (stars' `split`, tidy3A's `variables_from=`) and `select` picks only variables?
+
+- **Style A, field axis:** `read_array(..., field_axis="feature")`. One array; field labels act as columns.
+- **Style B, stars style:** `read_array(..., variables_from="feature")`. One variable per field, as after stars' `split(x, "feature")`. This comparison was written with a re-packing helper, `merge(x, y, z, along="feature")` after stars' `merge()`; since decided: `[x, y, z]` rebuilds the recorded axis (plan §5.2), so Style B's vector line now matches Style A.
+- **Style C, strict without splitting:** no field axis and no split. Field labels are reached only through `filter` and xarray. Shown once, for comparison.
+
+## Example 1: point cloud
+
+Synthetic data: four points that, after a 90° rotation about z and a 1 m offset, lie 49 m, 50 m, 51 m, and 3 m from the origin; `intensity` 10, 20, 30, 40; `ring` 1, 2, 1, 2.
+
+**Style A**
+
+```python
+cloud = read_array(
+    path,
+    value_type="float32",
+    dims={"point": infer, "feature": 5},
+    labels={"feature": ["x", "y", "z", "intensity", "ring"]},
+    field_axis="feature",
+)
+
+nearby = (
+    cloud
+    >> mutate(p = dot(R, [x, y, z], over="feature") + offset)
+    >> mutate(distance = formula(r"\sqrt{\sum_i p_i^2}"))
+    >> filter(distance <= 50)
+)
+
+nearby >> group_by(ring) >> summarise(mean_intensity = mean(intensity))
+```
+
+**Style B**
+
+```python
+cloud = read_array(
+    path,
+    value_type="float32",
+    dims={"point": infer, "feature": 5},
+    labels={"feature": ["x", "y", "z", "intensity", "ring"]},
+    variables_from="feature",
+)
+
+nearby = (
+    cloud
+    >> mutate(p = dot(R, [x, y, z], over="feature") + offset)   # rebuilds the recorded feature axis
+    >> mutate(distance = formula(r"\sqrt{\sum_i p_i^2}"))
+    >> filter(distance <= 50)
+)
+
+nearby >> group_by(ring) >> summarise(mean_intensity = mean(intensity))
+```
+
+**Style C**
+
+```python
+xyz = cloud >> filter(feature.is_in(["x", "y", "z"]))
+# Bare x, intensity, and ring do not exist; expressions need xarray:
+#   cloud.to_xarray()["values"].sel(feature="ring")
+```
+
+Expected (checked): kept points 1, 2, 4 with original positions as labels, since 50 m is inside the boundary; intensities 10, 20, 40; mean intensity per ring: ring 1 → 10, ring 2 → 30.
+
+## Example 2: sensor time series
+
+Synthetic data: `values (time: 4, sensor: front rear, feature: x y z)`.
+
+| Operation | Style A | Style B |
+|---|---|---|
+| Mean x per sensor | `group_by(sensor) >> summarise(mean_x = mean(x))` | same |
+| All fields per sensor | `group_by(sensor) >> summarise(m = mean(values))` → `m (sensor, feature)` | one summary per field, e.g. `summarise(mx = mean(x), my = mean(y), mz = mean(z))` |
+| Front sensor after time 2 | `filter(sensor == "front", time > 2)` | same |
+| Times where any sensor has x > 20 | `filter(any(x > 20, over="sensor"))` | same |
+
+Expected (checked): mean x is 4 (front) and 40 (rear); the front sensor's field means are x 4, y 3, z 0.5; the two-axis filter keeps `time: 2, sensor: 1`; the `any` filter keeps times 2, 3, 4.
+
+## Example 3: geospatial raster
+
+Synthetic data in the shape stars handles: a 3 × 2 pixel scene, bands `blue green red nir`, two dates, with `x`/`y` map coordinates. Near-infrared halves at the second date.
+
+**Style A** (`field_axis="band"`)
+
+```python
+scene >> mutate(ndvi = (nir - red) / (nir + red))
+scene >> filter(x > 500010, y > 4100010)                     # crop, as stars' filter
+scene >> mutate(ndvi = (nir - red) / (nir + red)) >> group_by(x, y) >> summarise(mean_ndvi = mean(ndvi))
+scene >> summarise(m = mean(values))                         # one mean per band; stars: st_apply(x, "band", mean)
+scene >> mutate(ndvi = …) >> group_by(bins(ndvi, [-1, 0.25, 1])) >> summarise(pixels = n())
+```
+
+**Style B** (`variables_from="band"`)
+
+```python
+scene >> mutate(ndvi = (nir - red) / (nir + red))            # same
+scene >> filter(x > 500010, y > 4100010)                     # same
+# per-pixel mean NDVI and bins: same
+scene >> summarise(blue = mean(blue), green = mean(green),   # one summary per band
+                   red = mean(red), nir = mean(nir))
+```
+
+Expected (checked): NDVI at the first date is 0.5, 0, 0, 0.75, 0.5, 0 by pixel; the crop keeps `x: 2, y: 1`; the first pixel's mean NDVI over time is (0.5 + 0.2) / 2; the per-band mean of blue is 0.05; the NDVI bins hold 3 and 3 pixels.
+
+## Comparison
+
+| Aspect | Style A, field axis | Style B, stars style | Style C, strict |
+|---|---|---|---|
+| Scalar expressions (`distance <= 50`, NDVI, `mean(x)`) | Bare names | Bare names, identical text | Not available without xarray |
+| Vector operations (rotation) | `[x, y, z]` directly | `[x, y, z]` rebuilds the recorded axis (decided after this comparison; it first needed a `merge` helper) | xarray |
+| One summary for every field | `mean(values)` keeps the field axis | One expression per field, or an `across()`-style helper | xarray |
+| Fields with different types (`ring` as integer) | Not possible: one array, one type | Natural | Not possible |
+| Concepts a user must learn | Field axis, observation axis | Separate variables only | Separate variables only |
+| Rules in the tidy layer | More: field-axis select, `var()`/`label()` collisions, write-back, type promotion | Fewer | Fewest |
+
+Findings:
+
+1. **Style C is clearly worst.** Without either a field axis or splitting, the most common point-cloud and raster operations leave the pipeline. It is not a real option.
+2. **Styles A and B read the same for scalar work.** Filters, NDVI, grouping, and bins are character-for-character identical. The choice of style changes nothing for most expressions.
+3. **Style A wins where fields form a vector or a spectrum:** rotation (`[x, y, z]` versus `merge(...)`), and one summary for every band or component (`mean(values)` versus one line per field).
+4. **Style B wins where fields are heterogeneous:** different types and units, such as nuScenes' `ring`, and it needs fewer rules.
+5. Both styles are already in the plan, as `field_axis=` and `variables_from=`. The comparison supports keeping both, with documented guidance: use `field_axis=` when fields are components of one quantity (`x y z`, spectral bands, RGB), and `variables_from=` when they are different quantities.
+
+Decided (2026-10-24): keep the field axis, with `variables_from=` equally first-class (plan §5.1). The recommendation as reviewed: keep the field axis. Its advantage is real but narrow (vectors and spectra), so the documentation should present `variables_from=` as equally first-class, and milestone 2 should check the tidy layer's one-page complexity budget (`docs/decisions.md`) before adding more field-axis rules.
+
+Re-packing, found while writing Style B and since decided (plan §5.2): `[x, y, z]` rebuilds a vector from variables of the same recorded `variables_from` axis, and `pack([...], along=...)` re-packs other variables, with the axis always named. `merge` was avoided because `xr.merge` implements joins.