Skip to content

Commit 65d1afb

Browse files
d-v-bclaude
andcommitted
docs(indexing): state that a key's type picks relative or absolute indexing
Make the one rule about indexing a LazyArray prominent: NumPy keys are positions relative to the view, an `IndexDomain` key names absolute coordinates of the view's domain, an `IndexTransform` key composes onto it, no key type has two readings, and every view keeps its absolute domain whichever key produced it. A guide section with a runnable snippet carries the table and the pandas `ix` / TensorStore comparison; the module docstring, README, and API page point at it. Assisted-by: ClaudeCode:claude-fable-5-1 Co-Authored-By: Claude Fable 5.1 <[email protected]>
1 parent bc63d97 commit 65d1afb

5 files changed

Lines changed: 74 additions & 4 deletions

File tree

‎packages/zarr-indexing/README.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,10 @@ materializes them on request; the transform algebra itself performs no source I/
1212
Key types:
1313

1414
- `LazyArray` — wraps a system-memory/basic-indexing source with lazy indexing:
15-
`LazyArray.from_numpy(numpy_array)[10:50, ::2].oindex[[3, 1, 1], :]`
15+
`LazyArray.from_numpy(numpy_array)[10:50, ::2].oindex[[3, 1, 1], :]`.
16+
The key's type picks the frame: NumPy keys are positions relative to the
17+
view, while an `IndexDomain` or `IndexTransform` key addresses the view's
18+
absolute domain, which every view keeps.
1619
composes a transform and returns a new view without reading data, and
1720
`result()` materializes it into owned system memory. `LazyArray(source)` uses
1821
the basic reader; `from_numpy` selects `numpy_reader`, which currently uses

‎packages/zarr-indexing/docs/api/lazy_array.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,10 @@ conversion needs a custom reader that transfers into the output buffer. Derived
1616
reader and part views may be materialized concurrently, so stateful readers
1717
must synchronize their own mutable state.
1818

19+
The key's type picks the frame: NumPy keys are relative positions, `IndexDomain`
20+
and `IndexTransform` keys are absolute, and every view keeps its absolute
21+
domain. See [the guide](../guide/index.md#the-keys-type-picks-the-frame).
22+
1923
Every public `Partition.view.transform` directly maps that view's own domain
2024
coordinates into its raw `Partition.view.array`, including for non-first
2125
partitions; a box part's domain is a sub-domain of the parent view's literal

‎packages/zarr-indexing/docs/guide/index.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,32 @@ literal domain, as a TensorStore view does: `source[10:20]` has domain
114114
`[10, 20)`, and a further `[2:5]` on it has domain `[12, 15)`. A domain or
115115
transform key addresses those literal coordinates directly.
116116

117+
### The key's type picks the frame {#the-keys-type-picks-the-frame}
118+
119+
**The type of a key decides whether it is relative or absolute.** This is the
120+
one rule to remember about indexing a `LazyArray`:
121+
122+
| Key type | Read as | Example |
123+
| --- | --- | --- |
124+
| slice, integer, `...`, `None`, index array, mask | **Relative**: positions in the current view, NumPy-style | `view[2:5]`, `view[-1]`, `view.oindex[[3, 1]]` |
125+
| `IndexDomain` | **Absolute**: coordinates of the view's domain, restricted to a box | `view[IndexDomain((12,), (15,))]` |
126+
| `IndexTransform` | **Absolute**: composed onto the view; the key's domain becomes the new view's domain | `view[IndexTransform.identity(view.transform.domain)[12:15]]` |
127+
128+
No key type is valid in both readings, so a key never has two meanings. That is
129+
the property pandas lost with value-based `ix` dispatch and removed in favor of
130+
`loc` and `iloc`; TensorStore keeps it by giving each key type one fixed
131+
reading, and so does this wrapper. The only difference from TensorStore is
132+
which reading the NumPy key gets: absolute there, relative here.
133+
134+
Whichever key produced a view, **its domain is always absolute**:
135+
`view.transform.domain` reports literal coordinates after `view[2:5]` exactly as
136+
it does after `view[IndexDomain(...)]`. The relative reading exists only at the
137+
moment a NumPy key is interpreted, so relative and absolute steps compose freely.
138+
139+
```python
140+
--8<-- "snippets/key_types.py:key-types"
141+
```
142+
117143
### A transform points from the request to the source
118144

119145
An `IndexTransform` records how every coordinate in a request finds its source
Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
"""The type of a key decides whether it is read relative to the view or as absolute coordinates."""
2+
3+
import numpy as np
4+
5+
from zarr_indexing import IndexDomain, IndexTransform, LazyArray
6+
7+
source = np.arange(30)
8+
9+
# --8<-- [start:key-types]
10+
view = LazyArray(source)[10:20]
11+
assert view.transform.domain == IndexDomain((10,), (20,))
12+
13+
# NumPy keys are positions relative to the view: 0 is its first element.
14+
relative = view[2:5]
15+
assert relative.result().tolist() == [12, 13, 14]
16+
assert view[-1].result() == 19
17+
18+
# An IndexDomain key names absolute coordinates of the view's domain.
19+
absolute = view[IndexDomain((12,), (15,))]
20+
assert absolute.result().tolist() == [12, 13, 14]
21+
22+
# An IndexTransform key composes onto the view; index the identity over the
23+
# view's domain to spell any selection in absolute coordinates.
24+
literal = IndexTransform.identity(view.transform.domain)
25+
assert view[literal[12:15]].result().tolist() == [12, 13, 14]
26+
assert view[literal[::-1]].result().tolist()[:2] == [19, 18]
27+
28+
# Whichever key produced a view, its domain is absolute.
29+
assert relative.transform.domain == absolute.transform.domain == IndexDomain((12,), (15,))
30+
# --8<-- [end:key-types]

‎packages/zarr-indexing/src/zarr_indexing/lazy_array.py‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -85,9 +85,16 @@
8585
traversal order. A query can fill its hull, and a singleton box can fill its hull
8686
even when its recorded stride exceeds one.
8787
88-
The positional dialect
89-
----------------------
90-
Selections on `LazyArray` are **positional, NumPy-style**: index 0 is the first
88+
Relative keys, absolute domain
89+
------------------------------
90+
**The type of a key decides whether it is relative or absolute.** NumPy keys
91+
(slices, integers, `...`, `None`, index arrays, masks) are positions relative to
92+
the current view. An `IndexDomain` key names absolute coordinates of the view's
93+
domain, and an `IndexTransform` key composes onto the view. No key type has two
94+
readings, and whichever key produced a view, `view.transform.domain` is
95+
absolute. See the guide section "The key's type picks the frame".
96+
97+
Selections with NumPy keys are **positional, NumPy-style**: index 0 is the first
9198
element of the current view, `-1` is the last, boolean masks must match the
9299
view's shape, integer coordinates are bounds-checked, and slices are clipped
93100
to the view's extent.

0 commit comments

Comments
 (0)