# MRGID

**Repository Path**: lilidream/mrgid

## Basic Information

- **Project Name**: MRGID
- **Description**: 类MRG波信号传播识别的 Python 实现与识别结果数据集。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-04-21
- **Last Updated**: 2025-04-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Mixed-Rossby Gravity Wave Identification

此仓库包含识别 MRG 波信号的 Python 脚本。识别方法基于 Au-Yeung 和 Tam (2018) [^1]，事件连接方法由 Lilidream 设计。

This repository contains a Python script for identifying mixed Rossby gravity like waves in gridded data.
The method is based on Au-Yeung and Tam (2018) [^1], and the event connection method is designed by Lilidream.


## 定义

 - **MRGWL**: MRG wave-like signal, or MRG-like wave. 指经向风分布类似 MRG 波的波动信号，我们将一个 MRG 波的经向风正/负相位称为一个 MRGWL，是时间和空间的函数，会随时间向西运动。
 - **MRGWL 事件**: MRGWL event. 指一个 MRGWL 的某一个时刻。一个 MRGWL 又多个时间上连续的 MRGWL 事件组成。


## 数据集
使用此脚本并基于 1979-2022 年的 ERA5 再分析资料（每日4次，0.5°），制作了 MRGWL 的数据集。 根据识别方法，在连接 MRGWL 事件时选择不同的误差限会得到不同的结果，因此数据集提供多个误差的版本。

此数据集与热带气旋数据集类似，仅包含 MRGWL 的位置、赤道经向风等个体信息，并不包含空间风场等，变量为：
 
 - `eq_v`: 赤道上的经向风，单位为 m/s。
 - `y0`: MRGWL 的经向尺度，单位为纬度。
 - `err`: 经向风误差
 - `time`: MRGWL 的时间
 - `longitude`: MRGWL 的经度
 - `wavenumber`: MRGWL 的纬向波数(zonal wavenumber)，单位为 个/赤道长度。
 - `phase_speed`: MRGWL 的相速度，单位为 m/s。
 - `uid`: MRGWL 的唯一ID，为一个 14 位整数，为时间+经度。

以下为 2000 年 01 月的识别结果，误差限为 0.1。黑色实线与点为 MRGWL，填色为 5°N~5°S 平均滤波后的经向风。

![识别结果](doc/chech.png)


### NetCDF

NetCDF 格式数据集预览如下，其中 `id` 为 MRGWL 的 ID，从 0 开始，`tick` 为 MRGWL 的时刻，各个变量对应这每个 MRGWL 每个时刻的值。

```bash
<xarray.Dataset>
Dimensions:      (id: 32119, tick: 65)
Coordinates:
  * id           (id) int32 0 1 2 3 4 5 ... 32113 32114 32115 32116 32117 32118
  * tick         (tick) int32 0 1 2 3 4 5 6 7 8 9 ... 56 57 58 59 60 61 62 63 64
Data variables:
    eq_v         (id, tick) float32 ...
    y0           (id, tick) float32 ...
    err          (id, tick) float32 ...
    time         (id, tick) datetime64[ns] ...
    longitude    (id, tick) float32 ...
    phase_speed  (id, tick) float32 ...
    wavenumber   (id, tick) float32 ...
    uid          (id) int64 ...
Attributes:
    Conventions:           CF-1.12
    identification_level:  850 hPa
    title:                 Identification of MRG wave like signal
    source:                ERA5 reanalysis data
    comment:               Identified MRG wave like events from 4xdaily 0.5 d...
    history:               Created on 2025-04-22 16:26:48.380856 by Lilidream
    param_lat_range:       10
    param_y0_threshold:    20
    param_err_threshold:   0.1
    param_max_speed:       1.6666666666666667
    param_min_exist_hour:  24
```

### JSON

JSON 格式以 MRGWL 为对象保存数据。
```
{
    "info": {
        "数据集信息": "xxx",
        ...
    },
    "params: {
        "参数信息": "xxx",
        ...
    },
    "data": [
        {
            "id": 0,
            "uid": 20220101001000,
            "eq_v": [-2.3, -3, ...],
            "y0": [5, 6, ...],
            "err": [0.05, 0.06, ...],
            "time": ["2022-01-01 00:00:00", "2022-01-01 00:10:00", ...],
            "longitude": [100.0, 99.0, ...],
            "phase_speed": [-2, -1, ...],
            "wavenumber": [18, 15, ...],
        },
        ...
    ]
}

```

## 计算流程

主要的流程可参考 `src/main.py`，计算过程的一些参数在 `src/config.py` 中定义，分为以下几步：

1. 对原始的再分析资料滤波，3-8日带通滤波与西传波动滤波，与论文中的相同。滤波的实现可参考 `src/dataProcess.py`。
2. 使用 `src/identification.py` 中的 `identify_mrgwl_event()` 方法识别出滤波数据每一个时次存在的 MRGWL 事件，此方法返回一个识别结果的列表对象 `MrgwLikeEvents`。
3. （非必要）`MrgwLikeEvents` 包含保存与加载的函数，可以保存识别后的结果。
4. 使用 `src/identification.py` 中的 `mrgwl_case_identification()` 方法连接 MRGWL 事件，组合为一个个 MRGWL，返回 MRGWL 的列表 `list[MrgwLike]`。
5. 保存识别结果，在 `src/mrgLike.py` 中提供了两个保存方法：
    1. `mrgw_like_list_to_nc()` 保存为 NetCDF 格式。
    2. `mrgw_like_list_to_json()` 保存为 JSON 格式。



[^1]: AU-YEUNG A Y M, TAM C Y, 2018. Dispersion Characteristics and Circulation Associated with Boreal Summer Westward-Traveling Mixed Rossby–Gravity Wave–Like Disturbances[J/OL]. Journal of the Atmospheric Sciences, 75(2): 513-533. DOI:10.1175/JAS-D-16-0245.1.