# PRV 操作文档

本文档介绍 `yhrpyTools` 中 `PRV` 模块（Precipitation Variability，降水变率）的使用方法。

## 1. 模块说明

`PRV` 用于计算降水变异系数（CV, coefficient of variation = std / mean），支持以下时间尺度：

1. 全年逐日：`CV_daily`
2. 月尺度（6/7/8 月）：`CV_June`、`CV_July`、`CV_August`
3. 季节尺度（夏季 6-8 月）：`CV_Summer`

## 2. 安装

```bash
pip install yhrpyTools
```

## 3. 输入数据要求

输入必须是 `xarray.DataArray`，并建议满足：

1. 包含 `time` 维度
2. 变量名属于以下之一：`pr`、`pre`、`precipitation`、`rain`、`prec`、`tp`
3. 一般为三维网格：`(time, lat, lon)`
4. 时间应为逐日数据（模块会自动尝试转换时间格式）

## 4. 核心参数

所有公开函数都包含：

1. `pr`：降水 `DataArray`
2. `include_zeros=False`：是否把 0 降水日纳入统计

参数建议：

1. 若要研究湿日内部波动，通常用 `include_zeros=False`
2. 若要包含干湿共同波动，使用 `include_zeros=True`

## 5. 主要函数

### 5.1 全年逐日

```python
CV_daily(pr, include_zeros=False)
```

说明：

1. 按年计算每个格点的日降水 CV
2. 每年少于 5 天数据时，该年对应格点返回 `NaN`

### 5.2 月尺度

```python
CV_June(pr, include_zeros=False)
CV_July(pr, include_zeros=False)
CV_August(pr, include_zeros=False)
```

说明：

1. 分别计算每年 6 月、7 月、8 月的 CV
2. 每年对应月份少于 5 天数据时返回 `NaN`

### 5.3 夏季尺度

```python
CV_Summer(pr, include_zeros=False)
```

说明：

1. 计算每年夏季（6-8 月）CV
2. 夏季有效天数少于 15 天时返回 `NaN`

## 6. 快速开始

```python
import xarray as xr
from yu_pytools.PRV import CV_daily, CV_Summer

pr = xr.open_dataset("pr_daily.nc")["pr"]

# 逐年日尺度 CV（仅湿日）
cv_daily = CV_daily(pr, include_zeros=False)

# 逐年夏季 CV（包含干日）
cv_summer = CV_Summer(pr, include_zeros=True)

cv_daily.to_netcdf("CV_daily.nc")
cv_summer.to_netcdf("CV_summer.nc")
```

## 7. 完整示例

```python
import xarray as xr
from yu_pytools.PRV import (
    CV_daily, CV_June, CV_July, CV_August, CV_Summer
)

pr = xr.open_dataset("pr_daily.nc")["pr"]

cv_daily = CV_daily(pr, include_zeros=False)
cv_june = CV_June(pr, include_zeros=False)
cv_july = CV_July(pr, include_zeros=False)
cv_aug = CV_August(pr, include_zeros=False)
cv_summer = CV_Summer(pr, include_zeros=False)

cv_daily.to_netcdf("CV_daily.nc")
cv_june.to_netcdf("CV_june.nc")
cv_july.to_netcdf("CV_july.nc")
cv_aug.to_netcdf("CV_august.nc")
cv_summer.to_netcdf("CV_summer.nc")
```

## 8. 输出说明

所有公开函数返回 `xarray.DataArray`，通常特征为：

1. 维度为 `year, lat, lon`
2. 变量值为各格点 CV（无量纲）
3. 包含 `attrs` 元数据，如 `calculation_type`、`include_zeros`、`time_period`、`month` 或 `months`（按函数不同）

## 9. 常见问题

### 9.1 报错：输入数据必须包含 `time` 维度

请检查输入是否为 `DataArray`，且含 `time`。

### 9.2 报错：无效的降水变量名

请将变量重命名为支持名称之一，例如：

```python
pr = ds["your_var"].rename("pr")
```

### 9.3 结果出现大量 `NaN`

常见原因：

1. 某些年份有效天数不足（<5 天，夏季 <15 天）
2. 输入含大量缺测
3. `include_zeros=False` 且某些格点湿日极少

### 9.4 为什么 `include_zeros=True` 时结果会变化明显

因为 0 降水日会显著影响均值和标准差，从而改变 CV；这通常反映干湿变化共同作用。
