Create NDCoord Index + Big Doc improvemntes

AGENTS.md

@@ -20,8 +20,43 @@ Custom xarray Index implementations for keeping multiple coordinates in sync acr
 ```bash
 uv run pytest                        # Run tests
 uv run jupyter execute <notebook>    # Execute a notebook in place
-uv run jupyter-book build docs/      # Build docs
-uv run jupyter-book start docs/      # Preview docs locally
+```
+
+## Documentation
+
+Documentation uses [MyST](https://mystmd.org/) and is located in `docs/`.
+
+### Structure
+
+- `docs/myst.yml` - Configuration file including the Table of Contents (TOC)
+- `docs/index.md` - Main landing page
+- `docs/*.ipynb` - Example notebooks (rendered as documentation pages)
+
+### Adding New Documentation
+
+1. **Add notebooks to `docs/`**, not `examples/` (which is gitignored)
+2. **Update the TOC** in `docs/myst.yml` under `project.toc`
+3. Notebooks are executable documentation - ensure they run without errors
+
+### Building Docs
+
+```bash
+myst start docs/      # Preview docs locally with hot reload
+myst build docs/      # Build static docs
+```
+
+### TOC Format (myst.yml)
+
+```yaml
+project:
+  toc:
+    - file: index.md
+    - file: my_example.ipynb
+      title: My Example Title
+    - title: Section Name
+      children:
+        - file: nested_example.ipynb
+          title: Nested Example
 ```
 
 ## Architecture Notes

docs/index.md

@@ -13,6 +13,26 @@ Custom xarray indexes for keeping multiple coordinates in sync across shared dim
 This library provides custom [xarray Index](https://docs.xarray.dev/en/stable/internals/how-to-create-custom-index.html) implementations that automatically constrain related dimensions when you select on any one of them.
 
 
+### DimensionInterval
+
+The DimensionInterval provides the ability to performantly store arbitrary intervals over a continuous coordinate. Like a multiindex but more generalized. See the [comparison with MultiIndex](alt-multiindex.ipynb) for an understanding of the comparison.
+
+![diagram of possible sel calls for DimensionInterval](images/generic-intervals.png.excalidraw.png)
+
+See the [Multi-Interval Example](multi_interval_example.ipynb) for a detailed walkthrough.
+
+### NDIndex
+
+Provides the ability to select on N-dimensional derived coordinates (like absolute time computed from trial offsets + relative time).
+
+![diagram of two possible abs-rel indexes](images/abs-rel.png.excalidraw.png)
+
+See the [ND Coordinates Example](nd_index_demo.ipynb) for a detailed walkthrough covering trial-based data with both absolute and relative time coordinates.
+
+```{note}
+The time-locking/epoching workflow shown in the diagram is not yet implemented. NDIndex currently supports selection on N-D coordinates but does not yet provide utilities for building multiple time reference frames.
+```
+
 ### Use Cases
 
 - **Speech/audio data** with hierarchical annotations (words, phonemes, time)

docs/multi_interval_example.ipynb

@@ -4,23 +4,7 @@
    "cell_type": "markdown",
    "id": "cell-0",
    "metadata": {},
-   "source": [
-    "# Multi-Interval Index Example\n",
-    "\n",
-    "This notebook demonstrates how `DimensionInterval` enables automatic cross-slicing between multiple interval types over a shared continuous dimension.\n",
-    "\n",
-    "## Use Case: Speech Data\n",
-    "\n",
-    "Imagine you have speech data with:\n",
-    "- A **continuous time dimension** (e.g., audio samples at regular intervals)\n",
-    "- **Word intervals** - each word spans a range of time\n",
-    "- **Phoneme intervals** - each phoneme spans a smaller range of time within words\n",
-    "\n",
-    "TODO: add an explanatory image\n",
-    "\n",
-    "\n",
-    "When you select a specific word, you want the time and phoneme dimensions to automatically constrain to only the overlapping values. This is exactly what `DimensionInterval` provides."
-   ]
+   "source": "# Multi-Interval Index Example\n\nThis notebook demonstrates how `DimensionInterval` enables automatic cross-slicing between multiple interval types over a shared continuous dimension.\n\n![Diagram of possible sel calls for DimensionInterval](images/generic-intervals.png.excalidraw.png)\n\nWhen you select a specific word, you want the time and phoneme dimensions to automatically constrain to only the overlapping values. This is exactly what `DimensionInterval` provides.\n\n::::{note}\nThere are two ways to encode intervals with `DimensionInterval`:\n1. **Pandas IntervalIndex** - Used in this notebook, intervals are encoded directly as `pd.IntervalIndex` objects\n2. **Onset/Duration format** - Intervals are specified as separate onset and duration coordinates, see the [Onset/Duration Example](onset_duration_example.ipynb)\n::::\n\n::::{seealso}\nFor a comparison of `DimensionInterval` with xarray's built-in `MultiIndex`, see the [MultiIndex Comparison](alt-multiindex.ipynb) notebook.\n::::"
   },
   {
    "cell_type": "code",
@@ -43,6 +27,20 @@
     "from linked_indices import DimensionInterval"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "271be299-c765-488f-804d-5322552e41e0",
+   "metadata": {},
+   "source": [
+    "\n",
+    "## Use Case: Speech Data\n",
+    "\n",
+    "Imagine you have speech data with:\n",
+    "- A **continuous time dimension** (e.g., audio samples at regular intervals)\n",
+    "- **Word intervals** - each word spans a range of time\n",
+    "- **Phoneme intervals** - each phoneme spans a smaller range of time within words\n"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "cell-2",
@@ -5444,7 +5442,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -5463,4 +5461,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}

docs/myst.yml

@@ -16,8 +16,14 @@ project:
       title: IntervalIndex Example
     - file: onset_duration_example.ipynb
       title: Onset/Duration Example
+    - file: nd_index_demo.ipynb
+      title: ND Coordinates
+    - file: ndindex_performance.ipynb
+      title: NDIndex Performance
     - title: Gallery
       children:
+        - file: ndindex_slicing_gallery.ipynb
+          title: NDIndex Slicing
         - file: cell_hierarchy_example.ipynb
           title: Cell Hierarchy
     - file: alternatives.md