xarray-contrib/xarray-spatial

Spatial analysis algorithms for xarray implemented in numba

Structural Verdict

How Data Flows Through the System

Raster data flows through spatial analysis pipelines, typically starting with elevation or satellite imagery, applying transformations via numba-accelerated kernels, and outputting processed xarray DataArrays.

1. Data Input — Load raster data as xarray DataArrays from GeoTIFF or other formats
2. Backend Selection — Detect and select optimal computation backend (NumPy/Dask/CuPy/RTX) based on data size and hardware
3. Algorithm Execution — Apply spatial analysis functions using numba-compiled kernels for performance
4. Result Generation — Return processed xarray DataArrays with preserved coordinate systems and metadata

System Behavior

How the system actually operates at runtime — where data accumulates, what loops, what waits, and what controls what.

Data Pools

Feedback Loops

• Backend Performance Adaptation (auto-scale, balancing) — Trigger: Function call with data size detection. Action: Select optimal backend based on array size and hardware availability. Exit: Backend selected for current operation.

Delays & Async Processing

• Numba JIT Compilation (async-processing, ~First call compilation time) — Initial function calls are slower due to compilation overhead
• Dask Graph Construction (batch-window, ~Variable based on chunk size) — Lazy evaluation delays computation until .compute() is called

Control Points

• Backend Selection Override (env-var) — Controls: Forces specific backend regardless of automatic detection
• Numba JIT Toggle (runtime-toggle) — Controls: Enables/disables JIT compilation for debugging. Default: True

Technology Stack

Key Components

• convolution (module) — Provides kernel-based convolution operations with custom kernel support xrspatial/convolution.py
• focal (module) — Implements focal statistics operations like mean, sum, and hotspot detection xrspatial/focal.py
• flow_direction (function) — Computes D8 flow direction from elevation data for hydrological modeling xrspatial/flow_direction.py
• flow_accumulation (function) — Calculates accumulated flow based on flow direction grids xrspatial/flow_accumulation.py
• polygonize (function) — Converts raster regions to vector polygons with multiple output format support xrspatial/polygonize.py
• multispectral (module) — Implements vegetation indices like NDVI, EVI, ARVI for satellite imagery analysis xrspatial/multispectral.py
• proximity (module) — Calculates proximity, allocation, and direction analysis with multiple distance metrics xrspatial/proximity.py
• rasterize (function) — Converts vector geometries to raster format with burn-in value support xrspatial/rasterize.py
• classify (module) — Provides data classification methods including natural breaks and quantiles xrspatial/classify.py
• utils (module) — Contains backend detection, array conversion, and common utility functions xrspatial/utils.py
• geotiff (module) — Handles GeoTIFF file I/O with coordinate system and metadata support xrspatial/geotiff/__init__.py
• hillshade (function) — Generates terrain shading visualization from elevation data xrspatial/hillshade.py

Configuration

codecov.yml (yaml)

• coverage.status.patch (string, unknown) — default: off
• coverage.status.project.default.target (string, unknown) — default: auto
• coverage.status.project.default.threshold (string, unknown) — default: 0.5%
• comment.require_changes (string, unknown) — default: yes
• ignore (array, unknown) — default: ./setup.py,xrspatial/tests/*,xrspatial/experimental/*,xrspatial/gpu_rtx/*,xrspatial/datasets/*,xrspatial/__init__.py,xrspatial/__main__.py

xrspatial/diagnostics.py (python-dataclass)

• code (str, unknown)
• message (str, unknown)
• suggestion (str, unknown)

xrspatial/diagnostics.py (python-dataclass)

• issues (List[DiagnosticIssue], unknown) — default: field(default_factory=list)
• horizontal_unit_type (Optional[str], unknown) — default: None
• vertical_unit_type (Optional[str], unknown) — default: None
• resolution (Optional[tuple], unknown) — default: None

xrspatial/geotiff/_geotags.py (python-dataclass)

• transform (GeoTransform, unknown) — default: field(default_factory=GeoTransform)
• model_type (int, unknown) — default: 0
• raster_type (int, unknown) — default: RASTER_PIXEL_IS_AREA

Science Pipeline

1. Load elevation data — xarray.open_dataarray or from_array conversion [(ny, nx) or chunked equivalent → (ny, nx)] xrspatial/flow_direction.py
2. Compute flow direction — Apply D8 algorithm with numba kernel on elevation grid [(ny, nx) → (ny, nx)] xrspatial/flow_direction.py
3. Calculate flow accumulation — Trace upstream contributions using flow direction matrix [(ny, nx) → (ny, nx)] xrspatial/flow_accumulation.py
4. Generate derived products — Apply focal statistics, hillshading, or classification algorithms [(ny, nx) → (ny, nx) or vector geometries] xrspatial/focal.py

Assumptions & Constraints

• [warning] Assumes 2D elevation grid but no explicit shape validation before applying D8 algorithm (shape)
• [info] Expects NIR and red band values to be in reflectance range [0,1] or DN values but no bounds checking (value-range)
• [warning] Assumes elevation data is numeric but may fail silently with non-numeric dtypes (dtype)
• [critical] CuPy backend assumes data fits in GPU memory without explicit memory checks (device)
• [warning] Assumes kernel has odd dimensions for proper centering but doesn't validate (format)

Related Library Repositories

Frequently Asked Questions

Analyzed on March 31, 2026 by CodeSea. Written by Karolina Sarna.