UAV-CO2/GASFLUX_CONFIG_DOCUMENTATION.md

# GasFlux 配置清单完整说明文档

## 概述

GasFlux 是一个用于处理无人机气体通量数据的完整管道系统。本文档详细说明了所有配置文件参数及其使用方法。

## 配置文件结构

GasFlux 使用 YAML 格式的配置文件，主要包含以下几个部分：

1. **输出设置** (`output_dir`)
2. **必需列定义** (`required_cols`)
3. **气体配置** (`gases`)
4. **处理策略** (`strategies`)
5. **背景校正设置** (`algorithmic_baseline_settings`)
6. **半变异函数设置** (`semivariogram_settings`)
7. **普通克里金设置** (`ordinary_kriging_settings`)
8. **可选过滤器** (`filters`) - 高级配置

## 详细参数说明

### 1. 输出设置

```yaml
output_dir: ./output  # 输出目录路径
```

- **类型**: 字符串
- **描述**: 指定处理结果的输出目录
- **默认值**: `./output`
- **注意**: 可以使用相对路径或绝对路径

### 2. 必需列定义

```yaml
required_cols:
  latitude: [-90, 90]        # 纬度范围
  longitude: [-180, 180]     # 经度范围
  height_ato: [0, 200]       # 相对起飞高度（米）
  windspeed: [0, 20]         # 风速（m/s）
  winddir: [0, 360]          # 风向（度）
  temperature: [-50, 60]     # 温度（°C）
  pressure: [900, 1100]      # 气压（hPa）
```

- **格式**: 字典，键为列名，值为 `[最小值, 最大值]` 数组
- **作用**: 数据验证和范围检查
- **注意**:
  - 所有值必须是 float64 类型
  - 不允许 NaN 值
  - 超出范围的值会报错

### 3. 气体配置

```yaml
gases:
  co2: [300, 500]    # 二氧化碳浓度范围（ppm）
  ch4: [1.5, 10.0]   # 甲烷浓度范围（ppm）
```

- **格式**: 字典，键为气体名称，值为 `[最小值, 最大值]` 数组
- **作用**: 指定要处理的 gases 及其合理浓度范围
- **注意**:
  - 气体名称必须与数据中的列名完全匹配
  - 范围用于数据验证

### 4. 处理策略

```yaml
strategies:
  background: "algorithm"    # 背景校正方法
  sensor: "insitu"          # 传感器类型
  spatial: "curtain"        # 空间处理模式: "curtain" 或 "spiral"
  interpolation: "kriging"  # 插值方法
```

- **background**: 目前只支持 `"algorithm"`
- **sensor**: 目前只支持 `"insitu"`
- **spatial**: `"curtain"` (平面模式) 或 `"spiral"` (螺旋模式)
- **interpolation**: 目前只支持 `"kriging"`

## 背景校正算法设置

### 算法总览

```yaml
algorithmic_baseline_settings:
  algorithm: fastchrom  # 选择使用的算法
  # 以下是各算法的具体参数
```

### 支持的算法

#### 1. FastChrom 算法 (推荐用于大多数情况)

```yaml
algorithmic_baseline_settings:
  algorithm: fastchrom
  fastchrom:
    half_window: 6              # 半窗口大小，用于基线拟合
    threshold: "custom"         # 阈值方法，推荐使用 "custom"
    min_fwhm: ~                 # 最小峰宽，~ 表示 null
    interp_half_window: 3       # 插值半窗口
    smooth_half_window: 3       # 平滑半窗口
    weights: ~                  # 权重，~ 表示 null
    max_iter: 100               # 最大迭代次数
    min_length: 2               # 最小段长度
```

#### 2. Dietrich 算法

```yaml
algorithmic_baseline_settings:
  algorithm: dietrich
  dietrich:
    poly_order: 5               # 多项式阶数
    smooth_half_window: 5       # 平滑半窗口
```

#### 3. FABC (Fully Automatic Baseline Correction) 算法

```yaml
algorithmic_baseline_settings:
  algorithm: fabc
  fabc:
    lam: 10000                  # 平滑参数，值越大基线越平滑
    scale: 10                   # 小波变换尺度
    diff_order: 2               # 微分矩阵阶数
```

#### 4. Golotvin 算法

```yaml
algorithmic_baseline_settings:
  algorithm: golotvin
  golotvin:
    half_window: 2              # 半窗口大小
    sections: 10                # 分段数量
```

## 克里金插值设置

### 半变异函数设置

```yaml
semivariogram_settings:
  model: spherical        # 变异函数模型: spherical, gaussian, exponential
  estimator: cressie      # 估计器: cressie, matheron, dowd
  n_lags: 20             # 滞后期数
  bin_func: even         # 分箱函数: even, uniform
  fit_method: lm         # 拟合方法: lm, manual
  maxlag: 100            # 最大滞后距离（米）
  tolerance: 10          # 方向容差（度）
  azimuth: 0             # 方位角（度，0为水平向右）
  bandwidth: 20          # 带宽（米）
```

### 普通克里金设置

```yaml
ordinary_kriging_settings:
  min_points: 3          # 最小邻点数
  max_points: 100        # 最大邻点数
  grid_resolution: 500   # 网格分辨率
  min_nodes: 10          # 最小网格节点数
  y_min: ~               # 最小y值覆盖，手动覆盖，~表示使用默认
  cut_ground: True       # 是否切割地面以下的值
```

## 空间处理模式详解

### 平面模式 (Curtain Mode)

**适用场景**: 直线飞行路径，沿着固定方向的多个平行航线

```yaml
strategies:
  spatial: "curtain"

# 推荐的半变异函数设置（平面模式）
semivariogram_settings:
  model: spherical
  estimator: cressie
  n_lags: 15
  bin_func: even
  fit_method: lm
  maxlag: 80          # 根据飞行距离调整
  tolerance: 15        # 较大的容差适应直线路径
  azimuth: 0           # 沿着飞行方向
  bandwidth: 25        # 较大的带宽适应航线间距

ordinary_kriging_settings:
  min_points: 5
  max_points: 80
  grid_resolution: 200  # 较高的分辨率
  min_nodes: 10
  y_min: 20           # 设置最小高度
  cut_ground: True
```

**特点**:
- 应用风偏移校正
- 沿着最大单调序列提取航线
- 适合规则的栅格飞行模式

### 螺旋模式 (Spiral Mode)

**适用场景**: 螺旋或圆形飞行路径

```yaml
strategies:
  spatial: "spiral"

# 推荐的半变异函数设置（螺旋模式）
semivariogram_settings:
  model: spherical
  estimator: cressie
  n_lags: 20
  bin_func: even
  fit_method: lm
  maxlag: 100         # 较大的最大距离适应螺旋半径
  tolerance: 30        # 更大的容差适应圆形路径
  azimuth: 0           # 径向方向
  bandwidth: 20        # 适应螺旋间距

ordinary_kriging_settings:
  min_points: 3
  max_points: 100
  grid_resolution: 500  # 较低的分辨率适应圆形区域
  min_nodes: 10
  y_min: ~            # 自动确定最小高度
  cut_ground: True
```

**特点**:
- 不应用风偏移校正（假设风垂直于螺旋）
- 计算圆偏差和中心
- 重新居中方位角
- 使用周长距离作为x坐标

## 可选过滤器（高级配置）

```yaml
filters:
  course_filter:
    azimuth_filter: 15      # 方位角过滤容差（度）
    azimuth_window: 8       # 滚动中位数窗口大小
    elevation_filter: 8     # 海拔过滤容差（度）
```

## 完整配置示例

### 平面模式完整配置

```yaml
output_dir: ./curtain_output

required_cols:
  latitude: [-90, 90]
  longitude: [-180, 180]
  height_ato: [0, 200]
  windspeed: [0, 20]
  winddir: [0, 360]
  temperature: [-50, 60]
  pressure: [900, 1100]

gases:
  co2: [300, 500]
  ch4: [1.5, 10.0]

strategies:
  background: "algorithm"
  sensor: "insitu"
  spatial: "curtain"
  interpolation: "kriging"

algorithmic_baseline_settings:
  algorithm: fastchrom
  fastchrom:
    half_window: 6
    threshold: "custom"
    min_fwhm: ~
    interp_half_window: 3
    smooth_half_window: 3
    weights: ~
    max_iter: 100
    min_length: 2

semivariogram_settings:
  model: spherical
  estimator: cressie
  n_lags: 15
  bin_func: even
  fit_method: lm
  maxlag: 80
  tolerance: 15
  azimuth: 0
  bandwidth: 25

ordinary_kriging_settings:
  min_points: 5
  max_points: 80
  grid_resolution: 200
  min_nodes: 10
  y_min: 20
  cut_ground: True
```

### 螺旋模式完整配置

```yaml
# GasFlux configuration file for basic usage example

output_dir: ./10m

# Required columns and their maximum valid ranges
required_cols:
  latitude: [-90, 90]
  longitude: [-180, 180]
  height_ato: [0, 50] # meters above takeoff
  windspeed: [0, 50] # m/s
  winddir: [0, 360] # degrees
  temperature: [-50, 60] # degrees Celsius
  pressure: [900, 1100] # hPa/mb

# Optional gas columns and their maximum ppm concentration ranges.
# Relative concentrations are used, so absolute offset can be incorrect as long as gain and linearity are correct.
gases:
  ch4: [2, 2.5]
  co2: [2, 2.5]

strategies:
  background: "algorithm"    # Currently only algorithmic baseline correction (via pybaselines) is supported
  sensor: "insitu"          # Currently only in-situ sensor data is supported
  spatial: "spiral"         # Spatial processing mode: "curtain" and "spiral" are supported
  interpolation: "kriging"  # Currently only kriging interpolation is supported

# Baseline correction algorithm settings 
algorithmic_baseline_settings:
  algorithm: fastchrom
  fastchrom: {
    "half_window": 6, 
    "threshold": "custom", #
    "min_fwhm": ~,
    "interp_half_window": 3, 
    "smooth_half_window": 3, 
    "weights": ~, 
    "max_iter": 100, 
    "min_length": 2}
  fabc : {
    "lam": 10000,  # The smoothing parameter. Larger values will create smoother baselines. Default is 1e6.
    "scale": 10,  # The scale at which to calculate the continuous wavelet transform. Should be approximately equal to the index-based full-width-at-half-maximum of the peaks or features in the data.  Default is None, which will use half of the value from optimize_window(), which is not always a good value, but at least scales with the number of data points and gives a starting point for tuning the parameter.
    "diff_order": 2}  # The order of the differential matrix. Must be greater than 0. Default is 2 (second order differential matrix). Typical values are 2 or 1.
  dietrich : {
    "poly_order": 5,
    "smooth_half_window": 5,}
  golotvin : {
    "half_window": 2, 
    "sections": 10}

# Kriging settings - aggressively optimized for Spiral mode
semivariogram_settings:
  model: exponential       # Changed to exponential model for better circular data fitting
  estimator: cressie        # Robust estimator for variogram calculation
  n_lags: 50               # Further increased to 50 for better variogram resolution
  bin_func: even           # Even binning function
  fit_method: lm           # Least squares fitting method
  ### Aggressively increased search ranges for circular/spiral data distribution
  maxlag: 5000             # Dramatically increased to 5000m for comprehensive coverage
  tolerance: 180           # Increased to 180° to allow full circular search
  azimuth: 0               # Horizontal direction maintained
  bandwidth: 300           # Further increased to 300m for maximum search bandwidth
   # fit_sigma: linear # this should allow for a spatial uncertainty but currently producing bugs
ordinary_kriging_settings:
  min_points: 1            # Reduced to 1 to allow interpolation even with sparse data
  max_points: 20           # Further reduced to 20 to minimize computational load
  grid_resolution: 100     # Increased density to 100 for finer interpolation grid
  min_nodes: 20            # Increased to 20 to ensure sufficient grid nodes
  y_min: ~                 # Automatically determine minimum y value
  cut_ground: False   
```

## 参数调优指南

### 空间模式选择

1. **平面模式 (curtain)**:
   - 飞行路径呈直线或平行航线
   - 数据点分布在规则的栅格中
   - 适合大型区域的系统采样

2. **螺旋模式 (spiral)**:
   - 飞行路径呈螺旋或圆形
   - 数据点围绕中心点分布
   - 适合点源排放的详细采样

### 半变异函数调优

1. **maxlag**: 设置为数据空间范围的 80-100%
2. **tolerance**: 平面模式 10-20°，螺旋模式 20-40°
3. **bandwidth**: 根据飞行间距调整，过大会影响精度
4. **n_lags**: 通常 10-25，根据数据量调整

### 克里金插值调优

1. **grid_resolution**: 影响输出网格密度
2. **min_points/max_points**: 平衡计算速度和精度
3. **cut_ground**: 根据是否有地面高程数据决定

## 故障排除

### 常见错误

1. **"autodetected range of [nan, nan] is not finite"**
   - 检查气体列是否有NaN值
   - 确认气体名称与数据列名匹配

2. **"`ydata` must not be empty!"**
   - 检查半变异函数参数是否过于严格
   - 减少 maxlag 或增加 tolerance

3. **Missing columns**
   - 确认数据列名与配置中的 gases 键匹配
   - 检查必需列是否存在

### 性能优化

1. **减少计算时间**: 降低 grid_resolution，减少 max_points
2. **提高精度**: 增加 n_lags，调整半变异函数参数
3. **内存优化**: 适当减少 max_points 和 grid_resolution

## 版本信息

- **GasFlux 版本**: 开发版
- **最后更新**: 2025年2月
- **文档版本**: 1.0

---

*本配置文档基于 GasFlux 系统的实际代码实现编写。如有疑问，请参考源码注释或提交 Issue。*