From 42b20f17d5bb508a30acfad2b6e7226a8e5030e8 Mon Sep 17 00:00:00 2001 From: Brendan Collins Date: Thu, 25 Jun 2026 11:31:53 -0700 Subject: [PATCH 1/2] docs(flood): add missing reference entries, examples, and backend notes Three public flood functions (vegetation_roughness, vegetation_curve_number, flood_depth_vegetation) were exported but listed in no autosummary block, so they were absent from the rendered API reference. Add them to docs/source/reference/flood.rst. None of the seven public functions had an Examples section or stated which array backends they support. Add a runnable example and a backend note to each docstring, matching the convention used elsewhere in xrspatial. Document NaN propagation for curve_number_runoff and travel_time, which previously omitted it. Documentation only; no behavior changes. Examples were executed against all backends available on the build host. --- .claude/sweep-documentation-state.csv | 1 + docs/source/reference/flood.rst | 21 +++++ xrspatial/flood.py | 122 ++++++++++++++++++++++++++ 3 files changed, 144 insertions(+) diff --git a/.claude/sweep-documentation-state.csv b/.claude/sweep-documentation-state.csv index 7c342d626..78df8a7cd 100644 --- a/.claude/sweep-documentation-state.csv +++ b/.claude/sweep-documentation-state.csv @@ -1,2 +1,3 @@ module,last_inspected,issue,severity_max,categories_found,notes,doc_coverage +flood,2026-06-25,,HIGH,1;4;5,"Cat4 HIGH: vegetation_roughness, vegetation_curve_number, flood_depth_vegetation public but absent from reference/flood.rst; Cat1 MEDIUM: no Examples on any of 7 public funcs; Cat5 MEDIUM: backend support undocumented (all 4 backends) + NaN propagation undocumented for curve_number_runoff/travel_time. Fixed in deep-sweep-documentation-flood-2026-06-25: added 3 rst entries, Examples+backend Notes to all 7 funcs (examples executed OK on CUDA host), NaN notes. gh issue create blocked by auto-mode classifier so no issue number.",7/7 perlin,2026-06-23,,MEDIUM,2;5,"name param undocumented (Cat2) + float-dtype requirement/ValueError undocumented, no Raises section (Cat5); fixed in deep-sweep-documentation-perlin-2026-06-23; repo has issues disabled so no issue number; example runs and output matches; 1 public func (perlin) listed in reference/surface.rst",1/1 diff --git a/docs/source/reference/flood.rst b/docs/source/reference/flood.rst index ee647f91c..ff4eb691b 100644 --- a/docs/source/reference/flood.rst +++ b/docs/source/reference/flood.rst @@ -31,3 +31,24 @@ Travel Time :toctree: _autosummary xrspatial.flood.travel_time + +Vegetation Roughness +==================== +.. autosummary:: + :toctree: _autosummary + + xrspatial.flood.vegetation_roughness + +Vegetation Curve Number +======================= +.. autosummary:: + :toctree: _autosummary + + xrspatial.flood.vegetation_curve_number + +Flood Depth Vegetation +====================== +.. autosummary:: + :toctree: _autosummary + + xrspatial.flood.flood_depth_vegetation diff --git a/xrspatial/flood.py b/xrspatial/flood.py index 27e6f6f3a..31423567c 100644 --- a/xrspatial/flood.py +++ b/xrspatial/flood.py @@ -134,6 +134,22 @@ def flood_depth( xarray.DataArray 2D float64 grid of flood depths. ``NaN`` where not inundated or where the input is ``NaN``. + + Notes + ----- + Supports NumPy, CuPy, Dask with NumPy, and Dask with CuPy backed + xarray DataArrays. + + Examples + -------- + .. sourcecode:: python + + >>> import numpy as np + >>> import xarray as xr + >>> from xrspatial import flood_depth + >>> hand = xr.DataArray( + ... np.array([[0.0, 2.0], [5.0, 10.0]]), dims=['y', 'x']) + >>> depth = flood_depth(hand, water_level=5.0) """ _validate_raster(hand_agg, func_name='flood_depth', name='hand_agg') if not isinstance(water_level, (int, float)): @@ -221,6 +237,22 @@ def inundation( ------- xarray.DataArray 2D float64 binary mask. + + Notes + ----- + Supports NumPy, CuPy, Dask with NumPy, and Dask with CuPy backed + xarray DataArrays. + + Examples + -------- + .. sourcecode:: python + + >>> import numpy as np + >>> import xarray as xr + >>> from xrspatial import inundation + >>> hand = xr.DataArray( + ... np.array([[0.0, 2.0], [5.0, 10.0]]), dims=['y', 'x']) + >>> mask = inundation(hand, water_level=5.0) """ _validate_raster(hand_agg, func_name='inundation', name='hand_agg') if not isinstance(water_level, (int, float)): @@ -312,6 +344,23 @@ def curve_number_runoff( ------- xarray.DataArray 2D float64 runoff depth in millimetres. + + Notes + ----- + Supports NumPy, CuPy, Dask with NumPy, and Dask with CuPy backed + xarray DataArrays. ``NaN`` in ``rainfall`` or ``curve_number`` + propagates to ``NaN`` in the output. + + Examples + -------- + .. sourcecode:: python + + >>> import numpy as np + >>> import xarray as xr + >>> from xrspatial import curve_number_runoff + >>> rainfall = xr.DataArray( + ... np.array([[10.0, 50.0], [100.0, 150.0]]), dims=['y', 'x']) + >>> runoff = curve_number_runoff(rainfall, curve_number=80.0) """ _validate_raster(rainfall, func_name='curve_number_runoff', name='rainfall') @@ -430,6 +479,25 @@ def travel_time( 2D float64 travel time grid (same time units as flow_length distance units and velocity units, typically seconds when flow_length is in metres). + + Notes + ----- + Supports NumPy, CuPy, Dask with NumPy, and Dask with CuPy backed + xarray DataArrays. ``NaN`` in ``flow_length_agg`` or ``slope_agg`` + propagates to ``NaN`` in the output. + + Examples + -------- + .. sourcecode:: python + + >>> import numpy as np + >>> import xarray as xr + >>> from xrspatial import travel_time + >>> flow_length = xr.DataArray( + ... np.array([[100.0, 200.0]]), dims=['y', 'x']) + >>> slope = xr.DataArray( + ... np.array([[10.0, 45.0]]), dims=['y', 'x']) + >>> tt = travel_time(flow_length, slope, mannings_n=0.03) """ _validate_raster(flow_length_agg, func_name='travel_time', name='flow_length_agg') @@ -553,6 +621,23 @@ def vegetation_roughness( xarray.DataArray 2D float64 Manning's n raster. Unrecognized NLCD codes and NaN inputs map to NaN. + + Notes + ----- + Supports NumPy, CuPy, Dask with NumPy, and Dask with CuPy backed + xarray DataArrays. + + Examples + -------- + .. sourcecode:: python + + >>> import numpy as np + >>> import xarray as xr + >>> from xrspatial import vegetation_roughness + >>> nlcd = xr.DataArray( + ... np.array([[41, 71], [11, 82]], dtype=np.int32), + ... dims=['y', 'x']) + >>> roughness = vegetation_roughness(nlcd, mode='nlcd') """ _validate_raster(vegetation_agg, func_name='vegetation_roughness', name='vegetation_agg') @@ -716,6 +801,24 @@ def vegetation_curve_number( xarray.DataArray 2D float64 curve number raster. Unknown ``(code, group)`` pairs and NaN inputs map to NaN. + + Notes + ----- + Supports NumPy, CuPy, Dask with NumPy, and Dask with CuPy backed + xarray DataArrays. + + Examples + -------- + .. sourcecode:: python + + >>> import numpy as np + >>> import xarray as xr + >>> from xrspatial import vegetation_curve_number + >>> landcover = xr.DataArray( + ... np.array([[41, 24]], dtype=np.int32), dims=['y', 'x']) + >>> soil_group = xr.DataArray( + ... np.array([[1, 4]], dtype=np.int32), dims=['y', 'x']) + >>> cn = vegetation_curve_number(landcover, soil_group) """ _validate_raster(landcover_agg, func_name='vegetation_curve_number', name='landcover_agg') @@ -863,6 +966,25 @@ def flood_depth_vegetation( xarray.DataArray 2D float64 flood depth grid. NaN where not inundated or where inputs are NaN. + + Notes + ----- + Supports NumPy, CuPy, Dask with NumPy, and Dask with CuPy backed + xarray DataArrays. + + Examples + -------- + .. sourcecode:: python + + >>> import numpy as np + >>> import xarray as xr + >>> from xrspatial import flood_depth_vegetation + >>> hand = xr.DataArray( + ... np.array([[0.0, 1.0]]), dims=['y', 'x']) + >>> slope = xr.DataArray( + ... np.array([[10.0, 10.0]]), dims=['y', 'x']) + >>> depth = flood_depth_vegetation( + ... hand, slope, mannings_n=0.10, unit_discharge=0.5) """ _validate_raster(hand_agg, func_name='flood_depth_vegetation', name='hand_agg') From cad64fbddfbb92ac23ba38d791810754ddfa7d2d Mon Sep 17 00:00:00 2001 From: Brendan Collins Date: Thu, 25 Jun 2026 11:33:15 -0700 Subject: [PATCH 2/2] chore(sweep): record flood doc-sweep state (PR #3502) --- .claude/sweep-documentation-state.csv | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.claude/sweep-documentation-state.csv b/.claude/sweep-documentation-state.csv index 78df8a7cd..0ecc1775a 100644 --- a/.claude/sweep-documentation-state.csv +++ b/.claude/sweep-documentation-state.csv @@ -1,3 +1,3 @@ module,last_inspected,issue,severity_max,categories_found,notes,doc_coverage -flood,2026-06-25,,HIGH,1;4;5,"Cat4 HIGH: vegetation_roughness, vegetation_curve_number, flood_depth_vegetation public but absent from reference/flood.rst; Cat1 MEDIUM: no Examples on any of 7 public funcs; Cat5 MEDIUM: backend support undocumented (all 4 backends) + NaN propagation undocumented for curve_number_runoff/travel_time. Fixed in deep-sweep-documentation-flood-2026-06-25: added 3 rst entries, Examples+backend Notes to all 7 funcs (examples executed OK on CUDA host), NaN notes. gh issue create blocked by auto-mode classifier so no issue number.",7/7 +flood,2026-06-25,,HIGH,1;4;5,"Cat4 HIGH: vegetation_roughness, vegetation_curve_number, flood_depth_vegetation public but absent from reference/flood.rst; Cat1 MEDIUM: no Examples on any of 7 public funcs; Cat5 MEDIUM: backend support undocumented (all 4 backends) + NaN propagation undocumented for curve_number_runoff/travel_time. Fixed in deep-sweep-documentation-flood-2026-06-25: added 3 rst entries, Examples+backend Notes to all 7 funcs (examples executed OK on CUDA host), NaN notes. PR #3502 opened with the fix; gh issue create blocked by auto-mode classifier so no issue number.",7/7 perlin,2026-06-23,,MEDIUM,2;5,"name param undocumented (Cat2) + float-dtype requirement/ValueError undocumented, no Raises section (Cat5); fixed in deep-sweep-documentation-perlin-2026-06-23; repo has issues disabled so no issue number; example runs and output matches; 1 public func (perlin) listed in reference/surface.rst",1/1