geoskill-地下水补给潜力

原始内容

---
name: groundwater-recharge-potential
description: >
  Multi-criteria screening of groundwater recharge potential using terrain, soil, geology,
  land cover, drainage density, and rainfall. Supports AHP, weighted overlay, and fuzzy
  aggregation with sensitivity analysis and spatial validation. Use when the user wants to
  identify zones with higher recharge potential, compare weight scenarios, or generate
  candidate recharge area maps for planning purposes.
---

## Prerequisites / 先准备 X 文件

> ⚠️ **必读** — 本 skill 不属于即用型，需要先准备特定文件才能跑。

本 skill 需要 **6 个栅格**（坡度/土壤/地质/土地覆盖/排水密度/降雨）。其中 4 个可自动下载（DEM→slope / SoilGrids / WorldCover / CHIRPS），**地质必须用户准备**。

👉 完整教程见仓库根目录 `PREREQUISITES.md` 1.4 节。

**先准备 X 文件**：1:50万 地质图（矢量化栅格）→ 其余自动下载。

快速试跑命令：

```bash
python groundwater_recharge_potential.py --bbox 116.0 39.5 116.5 40.0 --geology my_geology.tif --output-dir ./grp
```


# Groundwater Recharge Potential

Multi-criteria screening analysis for groundwater recharge potential.

## Purpose

Identify zones with higher groundwater recharge potential by combining:
- **Slope** — flatter terrain favors infiltration
- **Soil permeability** — higher permeability favors recharge
- **Geology** — formation type ranked by permeability
- **Land cover** — surface type ranked by infiltration favorability
- **Drainage density** — lower density favors infiltration over runoff
- **Rainfall** — more rain provides more recharge source

## Positioning

**This is a screening-level tool.** It does NOT:
- Promise specific groundwater volumes
- Guarantee well success rates
- Replace hydrogeological field investigation

Results are for planning reference only. Engineering safety, administrative
determination, and legal compliance require human review.

## Exit Codes

| Code | Meaning |
|---|---|
| 0 | Success |
| 2 | Argument error |
| 3 | Missing dependency |
| 6 | Data validation failure |
| 7 | Processing failure |

## Usage

```bash
python scripts/groundwater_recharge_potential.py \
  --bbox 116.0 39.5 116.5 40.0 \
  --slope slope.tif \
  --soil-permeability soil.tif \
  --geology geology.tif \
  --land-cover landcover.tif \
  --drainage-density drainage.tif \
  --rainfall rainfall.tif \
  --method weighted \
  --sensitivity-runs 100 \
  --min-area 1.0 \
  --output-dir grp-output
```

## Parameters

### Spatial extent (provide one)
- `--place` — Named place to geocode
- `--bbox` — Bounding box (xmin ymin xmax ymax) in EPSG:4326
- `--aoi-file` — Path to AOI vector file

### Analysis
- `--factor-config` — Custom factor configuration JSON
- `--weights` — Weights JSON, `equal`, or `ahp`
- `--method` — `ahp` | `weighted` | `fuzzy` (default: weighted)
- `--constraints` — Hard constraints JSON
- `--sensitivity-runs` — Monte Carlo runs (default: 100)
- `--min-area` — Minimum zone area in hectares (default: 1.0)

### Input rasters
- `--slope` — Slope in degrees
- `--soil-permeability` — Soil permeability proxy
- `--geology` — Geology class (categorical)
- `--land-cover` — Land cover class (categorical)
- `--drainage-density` — Drainage density
- `--rainfall` — Annual rainfall in mm

### Validation
- `--well-points` — Well locations GeoJSON for validation
- `--validation-blocks` — Spatial blocks for cross-validation (default: 5)

### Output
- `--output-dir` / `-o` — Output directory
- `--overwrite` — Allow overwriting
- `--dry-run` — Estimate only
- `--log-level` — Logging level

## Outputs

| File | Description |
|---|---|
| `recharge_potential.tif` | Composite suitability raster (0–1) |
| `candidate_zones.geojson` | Connected high-potential zones |
| `factor_weights.json` | Factor weights and metadata |
| `sensitivity.json` | Sensitivity analysis summary |
| `report.pdf` | HTML report with maps and stats |
| `request.json` | Input request manifest |
| `dataset-manifest.json` | Input data manifest |
| `output-manifest.json` | Output file manifest |
| `qa.json` | Quality assurance record |
| `run.log` | Execution log |

## Method Details

### AHP (Analytic Hierarchy Process)
- Pairwise comparison matrix → eigenvector weights
- Consistency ratio CR < 0.1 required
- Weights derived from expert judgment

### Weighted Overlay
- Linear normalization of continuous factors
- Categorical lookup for geology/land cover
- Weighted arithmetic mean

### Fuzzy Aggregation
- Sigmoid membership functions
- Gamma operator for combining factors
- Smooth transitions between classes

## Sensitivity Analysis
Monte Carlo perturbation of weights (±50%) to assess:
- Spatial stability of high-potential zones
- Mean standard deviation across runs
- Pixel-level consistency

## Validation
When well point data is provided:
- Spatial block cross-validation
- Compare mean suitability at well vs. non-well locations
- Report difference as evidence level indicator

## Constraints
Hard constraints can exclude:
- Slopes above a threshold
- Specific land cover classes (e.g., urban, water)
- Buffered areas around features

## References
- `references/recharge_factors.json` — Default factor scoring tables
- Saaty, T.L. (1980) — AHP methodology
- Bonham-Carter, G.F. (1994) — GIS-based multi-criteria analysis


## 数据下载

本 skill 可自动从 Microsoft Planetary Computer 下载数据 (无需 API key):

```bash
python groundwater_recharge_potential.py --bbox 116,39,117,40 --date-range 2024-06-01,2024-06-30 --output-dir <tmp>
```

- `--bbox W,S,E,N`: WGS-84 边界框 (西, 南, 东, 北)
- `--date-range START,END`: 日期范围 (YYYY-MM-DD,YYYY-MM-DD)
- `--aoi-file <path.geojson>`: 替代 --bbox 的 GeoJSON 多边形
- `--cache-dir <path>`: 缓存目录 (默认 ~/.geoskill_cache)

当用户只给 `--bbox + --date-range` (没有 `--dem`) 时，skill 自动下载数据。
当用户给 `--dem` 时，走原文件路径 (向后兼容)。

name: groundwater-recharge-potential description: > Multi-criteria screening of groundwater recharge potential using terrain, soil, geology, land cover, drainage density, and rainfall. Supports AHP, weighted overlay, and fuzzy aggregation with sensitivity analysis and spatial validation. Use when the user wants to identify zones with higher recharge potential, compare weight scenarios, or generate candidate recharge area maps for planning purposes.

Prerequisites / 先准备 X 文件

⚠️ 必读 — 本 skill 不属于即用型，需要先准备特定文件才能跑。

本 skill 需要 6 个栅格（坡度/土壤/地质/土地覆盖/排水密度/降雨）。其中 4 个可自动下载（DEM→slope / SoilGrids / WorldCover / CHIRPS），地质必须用户准备。

👉 完整教程见仓库根目录 PREREQUISITES.md 1.4 节。

先准备 X 文件：1:50万地质图（矢量化栅格）→ 其余自动下载。

快速试跑命令：

python groundwater_recharge_potential.py --bbox 116.0 39.5 116.5 40.0 --geology my_geology.tif --output-dir ./grp

Groundwater Recharge Potential

Multi-criteria screening analysis for groundwater recharge potential.

Purpose

Identify zones with higher groundwater recharge potential by combining:

Slope — flatter terrain favors infiltration
Soil permeability — higher permeability favors recharge
Geology — formation type ranked by permeability
Land cover — surface type ranked by infiltration favorability
Drainage density — lower density favors infiltration over runoff
Rainfall — more rain provides more recharge source

Positioning

This is a screening-level tool. It does NOT:

Promise specific groundwater volumes
Guarantee well success rates
Replace hydrogeological field investigation

Results are for planning reference only. Engineering safety, administrative determination, and legal compliance require human review.

Exit Codes

Code	Meaning
0	Success
2	Argument error
3	Missing dependency
6	Data validation failure
7	Processing failure

Usage

python scripts/groundwater_recharge_potential.py \
  --bbox 116.0 39.5 116.5 40.0 \
  --slope slope.tif \
  --soil-permeability soil.tif \
  --geology geology.tif \
  --land-cover landcover.tif \
  --drainage-density drainage.tif \
  --rainfall rainfall.tif \
  --method weighted \
  --sensitivity-runs 100 \
  --min-area 1.0 \
  --output-dir grp-output

Parameters

Spatial extent (provide one)

--place — Named place to geocode
--bbox — Bounding box (xmin ymin xmax ymax) in EPSG:4326
--aoi-file — Path to AOI vector file

Analysis

--factor-config — Custom factor configuration JSON
--weights — Weights JSON, equal, or ahp
--method — ahp | weighted | fuzzy (default: weighted)
--constraints — Hard constraints JSON
--sensitivity-runs — Monte Carlo runs (default: 100)
--min-area — Minimum zone area in hectares (default: 1.0)

Input rasters

--slope — Slope in degrees
--soil-permeability — Soil permeability proxy
--geology — Geology class (categorical)
--land-cover — Land cover class (categorical)
--drainage-density — Drainage density
--rainfall — Annual rainfall in mm

Validation

--well-points — Well locations GeoJSON for validation
--validation-blocks — Spatial blocks for cross-validation (default: 5)

Output

--output-dir / -o — Output directory
--overwrite — Allow overwriting
--dry-run — Estimate only
--log-level — Logging level

Outputs

File	Description
`recharge_potential.tif`	Composite suitability raster (0–1)
`candidate_zones.geojson`	Connected high-potential zones
`factor_weights.json`	Factor weights and metadata
`sensitivity.json`	Sensitivity analysis summary
`report.pdf`	HTML report with maps and stats
`request.json`	Input request manifest
`dataset-manifest.json`	Input data manifest
`output-manifest.json`	Output file manifest
`qa.json`	Quality assurance record
`run.log`	Execution log

Method Details

AHP (Analytic Hierarchy Process)

Pairwise comparison matrix → eigenvector weights
Consistency ratio CR < 0.1 required
Weights derived from expert judgment

Weighted Overlay

Linear normalization of continuous factors
Categorical lookup for geology/land cover
Weighted arithmetic mean

Fuzzy Aggregation

Sigmoid membership functions
Gamma operator for combining factors
Smooth transitions between classes

Sensitivity Analysis

Monte Carlo perturbation of weights (±50%) to assess:

Spatial stability of high-potential zones
Mean standard deviation across runs
Pixel-level consistency

Validation

When well point data is provided:

Spatial block cross-validation
Compare mean suitability at well vs. non-well locations
Report difference as evidence level indicator

Constraints

Hard constraints can exclude:

Slopes above a threshold
Specific land cover classes (e.g., urban, water)
Buffered areas around features

References

references/recharge_factors.json — Default factor scoring tables
Saaty, T.L. (1980) — AHP methodology
Bonham-Carter, G.F. (1994) — GIS-based multi-criteria analysis

数据下载

本 skill 可自动从 Microsoft Planetary Computer 下载数据 (无需 API key):

python groundwater_recharge_potential.py --bbox 116,39,117,40 --date-range 2024-06-01,2024-06-30 --output-dir <tmp>

--bbox W,S,E,N: WGS-84 边界框 (西, 南, 东, 北)
--date-range START,END: 日期范围 (YYYY-MM-DD,YYYY-MM-DD)
--aoi-file <path.geojson>: 替代 --bbox 的 GeoJSON 多边形
--cache-dir <path>: 缓存目录 (默认 ~/.geoskill_cache)

当用户只给 --bbox + --date-range (没有 --dem) 时，skill 自动下载数据。当用户给 --dem 时，走原文件路径 (向后兼容)。