xarray-spatial 0.9.6__tar.gz → 0.9.8__tar.gz

{xarray_spatial-0.9.6 → xarray_spatial-0.9.8}/.claude/commands/bench.md

@@ -1,6 +1,6 @@
 # Bench: Local Performance Comparison
 
-Run ASV benchmarks for the current branch against master and report regressions
+Run ASV benchmarks for the current branch against main and report regressions
 and improvements. The prompt is: $ARGUMENTS
 
 ---
@@ -9,7 +9,7 @@ and improvements. The prompt is: $ARGUMENTS
 
 1. If $ARGUMENTS names specific benchmark classes or functions (e.g. `Slope`,
    `flow_accumulation`), use those directly.
-2. If $ARGUMENTS is empty or says "auto", run `git diff origin/master --name-only`
+2. If $ARGUMENTS is empty or says "auto", run `git diff origin/main --name-only`
    to find changed source files under `xrspatial/`. Map each changed file to the
    corresponding benchmark module in `benchmarks/benchmarks/`. Use the filename
    and imports to match (e.g. changes to `slope.py` map to `benchmarks/benchmarks/slope.py`).
@@ -30,7 +30,7 @@ and improvements. The prompt is: $ARGUMENTS
 Run ASV in continuous-comparison mode from the `benchmarks/` directory:
 
 ```bash
-cd benchmarks && asv continuous origin/master HEAD -b "<regex>" -e
+cd benchmarks && asv continuous origin/main HEAD -b "<regex>" -e
 ```
 
 Where `<regex>` is a pattern matching the benchmark classes identified in Step 1
@@ -64,7 +64,7 @@ Parse the output and classify each result:
 ## Step 5 -- Generate the report
 
 ```
-## Benchmark Report: <branch> vs master
+## Benchmark Report: <branch> vs main
 
 ### Changed files
 - <list of changed source files>
@@ -74,7 +74,7 @@ Parse the output and classify each result:
 
 ### Results
 
-| Benchmark                          | master    | HEAD      | Ratio | Status     |
+| Benchmark                          | main    | HEAD      | Ratio | Status     |
 |------------------------------------|-----------|-----------|-------|------------|
 | slope.Slope.time_numpy             | 3.45 ms   | 3.51 ms   | 1.02x | UNCHANGED  |
 | slope.Slope.time_dask_numpy        | 8.12 ms   | 4.23 ms   | 0.52x | IMPROVED   |
@@ -124,4 +124,4 @@ Do NOT write benchmark files automatically. Report the gap and propose, then wai
   analysis (unless the user explicitly asks for a benchmark to be written in
   response to Step 6).
 - If $ARGUMENTS says "compare <branch1> <branch2>", run
-  `asv continuous <branch1> <branch2>` instead of the default origin/master vs HEAD.
+  `asv continuous <branch1> <branch2>` instead of the default origin/main vs HEAD.

{xarray_spatial-0.9.6 → xarray_spatial-0.9.8}/.claude/commands/efficiency-audit.md

@@ -267,7 +267,7 @@ Thresholds: IMPROVED < 0.8x, REGRESSION > 1.2x, else UNCHANGED.
 - If $ARGUMENTS includes a severity filter (e.g. "high only"), only report
   findings at that severity level.
 - If $ARGUMENTS includes "diff" or "changed", restrict the audit to files
-  changed on the current branch vs origin/master.
+  changed on the current branch vs origin/main.
 - Baseline benchmark scripts are disposable. Clean up `/tmp/` scripts after
   capturing results.
 - The 512x512 array size is a default. If $ARGUMENTS includes a size like

{xarray_spatial-0.9.6 → xarray_spatial-0.9.8}/.claude/commands/release-major.md

@@ -16,7 +16,7 @@ $ARGUMENTS
 ## Step 2 -- Create a release branch
 
 ```bash
-git checkout master && git pull
+git checkout main && git pull
 git checkout -b release/vX.Y.Z
 ```
 
@@ -49,7 +49,7 @@ git push -u origin release/vX.Y.Z
 
 ## Step 5 -- Verify CI
 
-1. Run `gh pr create --title "Release vX.Y.Z" --body "Changelog update for vX.Y.Z major release."` to open a PR against master.
+1. Run `gh pr create --title "Release vX.Y.Z" --body "Changelog update for vX.Y.Z major release."` to open a PR against main.
 2. Wait for CI:
    ```bash
    gh pr checks <PR_NUMBER> --watch
@@ -65,7 +65,7 @@ gh pr merge <PR_NUMBER> --merge --delete-branch
 ## Step 7 -- Tag the release
 
 ```bash
-git checkout master && git pull
+git checkout main && git pull
 git tag -a vX.Y.Z -m "Version X.Y.Z"
 git push origin vX.Y.Z
 ```

{xarray_spatial-0.9.6 → xarray_spatial-0.9.8}/.claude/commands/release-minor.md

@@ -16,7 +16,7 @@ $ARGUMENTS
 ## Step 2 -- Create a release branch
 
 ```bash
-git checkout master && git pull
+git checkout main && git pull
 git checkout -b release/vX.Y.Z
 ```
 
@@ -49,7 +49,7 @@ git push -u origin release/vX.Y.Z
 
 ## Step 5 -- Verify CI
 
-1. Run `gh pr create --title "Release vX.Y.Z" --body "Changelog update for vX.Y.Z minor release."` to open a PR against master.
+1. Run `gh pr create --title "Release vX.Y.Z" --body "Changelog update for vX.Y.Z minor release."` to open a PR against main.
 2. Wait for CI:
    ```bash
    gh pr checks <PR_NUMBER> --watch
@@ -65,7 +65,7 @@ gh pr merge <PR_NUMBER> --merge --delete-branch
 ## Step 7 -- Tag the release
 
 ```bash
-git checkout master && git pull
+git checkout main && git pull
 git tag -a vX.Y.Z -m "Version X.Y.Z"
 git push origin vX.Y.Z
 ```

{xarray_spatial-0.9.6 → xarray_spatial-0.9.8}/.claude/commands/release-patch.md

@@ -16,7 +16,7 @@ $ARGUMENTS
 ## Step 2 -- Create a release branch
 
 ```bash
-git checkout master && git pull
+git checkout main && git pull
 git checkout -b release/vX.Y.Z
 ```
 
@@ -46,7 +46,7 @@ git push -u origin release/vX.Y.Z
 
 ## Step 5 -- Verify CI
 
-1. Run `gh pr create --title "Release vX.Y.Z" --body "Changelog update for vX.Y.Z patch release."` to open a PR against master.
+1. Run `gh pr create --title "Release vX.Y.Z" --body "Changelog update for vX.Y.Z patch release."` to open a PR against main.
 2. Wait for CI:
    ```bash
    gh pr checks <PR_NUMBER> --watch
@@ -62,7 +62,7 @@ gh pr merge <PR_NUMBER> --merge --delete-branch
 ## Step 7 -- Tag the release
 
 ```bash
-git checkout master && git pull
+git checkout main && git pull
 git tag -a vX.Y.Z -m "Version X.Y.Z"
 git push origin vX.Y.Z
 ```

{xarray_spatial-0.9.6 → xarray_spatial-0.9.8}/.claude/commands/rockout.md

@@ -14,7 +14,8 @@ through all seven steps below. The prompt is: $ARGUMENTS
 2. Pick labels from the repo's existing set. Always include the type label
    (`enhancement`, `bug`, or `proposal`). Add topical labels when they fit
    (e.g. `gpu`, `performance`, `focal tools`, `hydrology`, etc.).
-3. Draft the title and body. Use the repo's issue templates as structure guides:
+3. Draft the title and body. Use the repo's issue templates as structure guides
+   (skip the "Author of Proposal" field -- GitHub already shows the author):
    - Enhancement/proposal: follow `.github/ISSUE_TEMPLATE/feature-proposal.md`
    - Bug: follow `.github/ISSUE_TEMPLATE/bug_report.md`
 4. **Run the body text through the `/humanizer` skill** before creating the issue
@@ -70,20 +71,11 @@ through all seven steps below. The prompt is: $ARGUMENTS
 
 ## Step 6 -- Create a User Guide Notebook
 
-The project has an `examples/user_guide/` directory with numbered notebooks.
-
-1. Determine the next available notebook number by listing the directory.
-2. Create a new `.ipynb` notebook following the established pattern:
-   - Markdown cell with title and explanation of the feature
-   - Import cell
-   - Synthetic data generation with visualization
-   - Demonstrate each mode/option of the feature
-   - Show a practical use case or comparison
-3. Use `matplotlib` for plots, consistent with existing notebooks.
-4. Keep the notebook self-contained (no external data dependencies).
-
 **Skip this step** if the change is a pure bug fix with no new user-facing API.
 
+Run the `/user-guide-notebook` skill to create the notebook. It handles structure,
+plotting conventions, GIS alert boxes, preview images, and humanizer passes.
+
 ## Step 7 -- Update the README Feature Matrix
 
 1. Open `README.md` and find the appropriate category section in the feature matrix.

xarray_spatial-0.9.8/.claude/commands/sweep-accuracy.md

@@ -0,0 +1,296 @@
+# Accuracy Sweep: Dispatch subagents to audit modules for numerical accuracy issues
+
+Audit xrspatial modules for numerical accuracy issues: floating point
+precision loss, incorrect NaN propagation, off-by-one errors in neighborhood
+operations, missing or wrong Earth curvature corrections, and backend
+inconsistencies (numpy vs cupy vs dask results differ). Subagents fix
+findings via /rockout.
+
+Optional arguments: $ARGUMENTS
+(e.g. `--top 3`, `--exclude slope,aspect`, `--only-terrain`, `--reset-state`)
+
+---
+
+## Step 1 -- Gather module metadata via git
+
+Enumerate candidate modules:
+
+**Single-file modules:** Every `.py` file directly under `xrspatial/`, excluding
+`__init__.py`, `_version.py`, `__main__.py`, `utils.py`, `accessor.py`,
+`preview.py`, `dataset_support.py`, `diagnostics.py`, `analytics.py`.
+
+**Subpackage modules:** `geotiff/`, `reproject/`, and `hydro/` directories under
+`xrspatial/`. Treat each as a single audit unit. List all `.py` files within
+each (excluding `__init__.py`).
+
+For every module, collect:
+
+| Field | How |
+|-------|-----|
+| **last_modified** | `git log -1 --format=%aI -- <path>` (for subpackages, most recent file) |
+| **total_commits** | `git log --oneline -- <path> \| wc -l` |
+| **loc** | `wc -l < <path>` (for subpackages, sum all files) |
+| **recent_accuracy_commits** | `git log --oneline --grep='accuracy\|precision\|numerical\|geodesic' -- <path>` |
+
+Store results in memory -- do NOT write intermediate files.
+
+## Step 2 -- Load inspection state
+
+Read `.claude/sweep-accuracy-state.csv`.
+
+If it does not exist, treat every module as never-inspected.
+
+If `$ARGUMENTS` contains `--reset-state`, delete the file and treat
+everything as never-inspected.
+
+State file schema (one row per module):
+
+```
+module,last_inspected,issue,severity_max,categories_found,notes
+slope,2026-03-28,1042,HIGH,1;3,"optional single-line notes"
+```
+
+- `categories_found` is a semicolon-separated integer list (empty when null).
+- `notes` is CSV-quoted; newlines must be flattened to spaces on write so
+  every module stays exactly one line.
+
+The file is registered with `merge=union` in `.gitattributes`, so two
+parallel sweeps touching different modules auto-merge without conflict.
+A transient duplicate-row state can occur after a merge if both branches
+modified the same module; the read-update-write cycle in step 5 keys rows
+by `module` and last-write-wins, so the next write cleans up.
+
+## Step 3 -- Score each module
+
+```
+days_since_inspected = (today - last_inspected).days   # 9999 if never
+days_since_modified  = (today - last_modified).days
+has_recent_accuracy_work = 1 if recent_accuracy_commits is non-empty, else 0
+
+score = (days_since_inspected * 3)
+      + (total_commits * 0.5)
+      - (days_since_modified * 0.2)
+      - (has_recent_accuracy_work * 500)
+      + (loc * 0.05)
+```
+
+Rationale:
+- Modules never inspected dominate (9999 * 3)
+- More commits = more complex = more likely to have accuracy bugs
+- Recently modified modules slightly deprioritized (someone just touched them)
+- Modules with existing accuracy work heavily deprioritized
+- Larger files have more surface area (0.05 per line)
+
+## Step 4 -- Apply filters from $ARGUMENTS
+
+- `--top N` -- only audit the top N modules (default: 3)
+- `--exclude mod1,mod2` -- remove named modules from the list
+- `--only-terrain` -- restrict to: slope, aspect, curvature, terrain,
+  terrain_metrics, hillshade, sky_view_factor
+- `--only-focal` -- restrict to: focal, convolution, morphology, bilateral,
+  edge_detection, glcm
+- `--only-hydro` -- restrict to: flood, cost_distance, geodesic,
+  surface_distance, viewshed, erosion, diffusion, hydro (subpackage)
+- `--only-io` -- restrict to: geotiff, reproject, rasterize, polygonize
+
+## Step 5 -- Print the ranked table and launch subagents
+
+### 5a. Print the ranked table
+
+Print a markdown table showing ALL scored modules (not just selected ones),
+sorted by score descending:
+
+```
+| Rank | Module          | Score  | Last Inspected | Last Modified | Commits | LOC  |
+|------|-----------------|--------|----------------|---------------|---------|------|
+| 1    | viewshed        | 30012  | never          | 45 days ago   | 23      | 800  |
+| 2    | flood           | 29998  | never          | 120 days ago  | 18      | 600  |
+| ...  | ...             | ...    | ...            | ...           | ...     | ...  |
+```
+
+### 5b. Launch subagents for the top N modules
+
+For each of the top N modules (default 3), launch an Agent in parallel using
+`isolation: "worktree"` and `mode: "auto"`. All N agents must be dispatched
+in a single message so they run concurrently.
+
+Each agent's prompt must be self-contained and follow this template (adapt
+the module name, paths, and metadata):
+
+```
+You are auditing the xrspatial module "{module}" for numerical accuracy issues.
+
+This module has {commits} commits and {loc} lines of code.
+
+Read these files: {module_files}
+
+Also read xrspatial/utils.py to understand _validate_raster() behavior and
+xrspatial/tests/general_checks.py for the cross-backend comparison helpers.
+
+**Your task:**
+
+1. Read all listed files thoroughly, including the matching test file(s)
+   under xrspatial/tests/ so you understand expected behavior.
+
+2. Audit for these 5 accuracy categories. For each, look for the specific
+   patterns described. Only flag issues ACTUALLY present in the code.
+
+   **Cat 1 — Floating Point Precision Loss**
+   - Accumulation loops that sum many small values into a large running
+     total without Kahan summation or compensated accumulation
+   - float32 used where float64 is required for stable intermediate results
+     (e.g. large grids, long gradients, iterative solvers)
+   - Subtraction of nearly-equal large quantities (catastrophic cancellation)
+   - Division by small numbers without a stability floor
+   Severity: HIGH if the result is visibly wrong on realistic inputs;
+   MEDIUM if only observable on adversarial inputs
+
+   **Cat 2 — NaN / Inf Propagation Errors**
+   - NaN input silently produces a finite output (masked, skipped, or
+     treated as zero without being documented)
+   - NaN check using `==` instead of `!= x` for NaN detection in numba
+   - Neighborhood operations that ignore NaN pixels but do not update the
+     normalization denominator, biasing the result
+   - Inf / -Inf inputs treated as numbers in comparisons without guards
+   - Divide-by-zero producing Inf that then corrupts downstream accumulation
+   Severity: HIGH if NaN input yields a wrong but finite output;
+   MEDIUM if the behavior is documented but still surprising
+
+   **Cat 3 — Off-by-One Errors in Neighborhood Operations**
+   - Loop bounds that exclude the last row/column (e.g. `range(H-1)` where
+     `range(H)` is intended)
+   - `map_overlap` depth that is smaller than the actual stencil radius
+   - Boundary handling that duplicates or skips edge pixels
+   - Asymmetric kernel indexing (one-sided rather than centered)
+   - CUDA kernel bounds guard that is `i > H` instead of `i >= H`
+   Severity: HIGH if it causes a silent wrong result at all chunk boundaries;
+   MEDIUM if it only affects a single-pixel edge
+
+   **Cat 4 — Missing or Wrong Earth Curvature / Projection Corrections**
+   - Geodesic calculations that assume a flat projection without curvature
+     correction (see slope.py, aspect.py, geodesic.py for the reference
+     pattern: `u += (e² + n²) / (2R)`)
+   - Haversine / great-circle distance using the wrong Earth radius
+     constant, or using a spherical approximation where WGS84 is needed
+   - Mixing projected and geographic coordinates in the same calculation
+     without a transform
+   - Using cell size in degrees as if it were meters
+   Severity: HIGH if the correction is missing entirely on a public API;
+   MEDIUM if the correction is present but uses a questionable constant
+
+   **Cat 5 — Backend Inconsistency (numpy vs cupy vs dask)**
+   - numpy and cupy paths use different algorithms that can diverge on
+     identical inputs (e.g. different boundary handling, different NaN
+     semantics, different numerical precision)
+   - dask path silently falls back to materializing the full array
+   - dask `map_overlap` chunk function returns a different shape than the
+     input, corrupting the reassembled array
+   - A backend raises on valid input that another backend accepts
+   - Result dtype differs across backends without documentation
+   Severity: HIGH if numerically different results on the same input;
+   MEDIUM if only metadata (dtype, coords) differs
+
+3. For each real issue found, assign a severity (CRITICAL/HIGH/MEDIUM/LOW)
+   and note the exact file and line number.
+
+4. If any CRITICAL or HIGH issue is found, run /rockout to fix it end-to-end
+   (GitHub issue, worktree branch, fix, tests, and PR).
+   For MEDIUM/LOW issues, document them but do not fix.
+
+5. After finishing (whether you found issues or not), update the inspection
+   state file .claude/sweep-accuracy-state.csv. The file is row-per-module
+   CSV with header:
+
+   `module,last_inspected,issue,severity_max,categories_found,notes`
+
+   Use this Python pattern to read, update, and write it (do NOT hand-edit
+   the file -- always go through csv.DictReader / csv.DictWriter so quoting
+   stays consistent):
+
+   ```python
+   import csv
+   from pathlib import Path
+
+   path = Path(".claude/sweep-accuracy-state.csv")
+   header = ["module", "last_inspected", "issue", "severity_max",
+             "categories_found", "notes"]
+
+   rows = {}
+   if path.exists():
+       with path.open() as f:
+           for r in csv.DictReader(f):
+               rows[r["module"]] = r  # last write wins on dupes
+
+   rows["{module}"] = {
+       "module": "{module}",
+       "last_inspected": "<today's ISO date, e.g. 2026-04-27>",
+       "issue": "<issue number from rockout, or empty string>",
+       "severity_max": "<HIGH|MEDIUM|LOW, or empty>",
+       "categories_found": "<semicolon-joined ints, e.g. 1;3, or empty>",
+       "notes": "<single-line notes (replace any newlines with spaces), or empty>",
+   }
+
+   with path.open("w", newline="") as f:
+       w = csv.DictWriter(f, fieldnames=header, quoting=csv.QUOTE_MINIMAL)
+       w.writeheader()
+       for m in sorted(rows):
+           w.writerow(rows[m])
+   ```
+
+   Use empty strings (not `null`) for missing values. Set `issue` to the
+   issue number when one was filed, otherwise leave it empty.
+
+   Then `git add .claude/sweep-accuracy-state.csv` and commit it to the
+   worktree branch so the state update is included in the PR.
+
+Important:
+- Only flag real accuracy issues. False positives waste time.
+- Read the tests for this module to understand expected behavior before
+  flagging a result as wrong -- the test may codify the current behavior.
+- For backend comparisons, check that the cross-backend tests in
+  xrspatial/tests/general_checks.py actually exercise the code path you
+  are suspicious of; missing test coverage is itself a finding.
+- Do NOT flag the use of numba @jit itself as an accuracy issue. Focus on
+  what the JIT code does, not that it uses JIT.
+- For the hydro subpackage: focus on one representative variant (d8) in
+  detail, then note which dinf/mfd files share the same pattern. Do not
+  read all 29 files line by line.
+- This repo uses ArrayTypeFunctionMapping to dispatch across numpy/cupy/dask
+  backends. Check all backend paths, not just numpy.
+```
+
+### 5c. Print a status line
+
+After dispatching, print:
+
+```
+Launched {N} accuracy audit agents: {module1}, {module2}, {module3}
+```
+
+## Step 6 -- State updates
+
+State is updated by the subagents themselves (see agent prompt step 5).
+After completion, verify state with:
+
+```
+column -t -s, .claude/sweep-accuracy-state.csv | less
+```
+
+To reset all tracking: `/sweep-accuracy --reset-state`
+
+---
+
+## General Rules
+
+- Do NOT modify any source files directly. Subagents handle fixes via /rockout.
+- Keep the output concise -- the table and agent dispatch are the deliverables.
+- If $ARGUMENTS is empty, use defaults: top 3, no category filter, no exclusions.
+- State file (`.claude/sweep-accuracy-state.csv`) is tracked in git, with
+  `merge=union` set in `.gitattributes` so parallel sweeps touching
+  different modules auto-merge. Subagents must `git add` and commit it so
+  the state update lands in the PR.
+- For subpackage modules (geotiff, reproject, hydro), the subagent should read
+  ALL `.py` files in the subpackage directory, not just `__init__.py`.
+- Only flag patterns that are ACTUALLY present in the code. Do not report
+  hypothetical issues or patterns that "could" occur with imaginary inputs.
+- False positives are worse than missed issues. When in doubt, skip.