shihua-meoteofence 0.1
Meoteofence is a preprocessing program for numerical weather forecasting, which is mainly used to segment the original meteorological data according to the five dimensions of starting time, prediction time, spatial hierarchy, meteorological physical quantities and station coordinate grid. The main technology uses HDF5 to organize the matrix data after analysis, uses hook technology to organize the code, and adds parallel processing at the prediction time level.
License: MIT
Requires Python: >=3.9.12



# Meoteofence-数值天气预报数据预处理工具

![shields_version](/static/shields_version.svg)    ![shields_license](/static/shields_license.svg)    ![shields_author](/static/shields_author.svg)    ![shiedls_python](/static/shields_python.svg)

![meoteofencesymbol](/static/meoteofencesymbol.JPG)

## 介绍
+ meoteofence是数值天气预报的预处理程序，主要用于根据起始时间、预报时间、空间层次、气象物理量和台站坐标网格五个维度对原始气象数据进行分割。主要技术使用HDF5组织分析后的矩阵数据（以加速磁盘IO），使用hook技术组织代码（方便扩展，动态挂载），并在预测时间级别添加并行处理（使用multiprocessing以异步非阻塞方式实现）。


## 安装
meoteofence采用Python开发，得益于Python良好的社区环境，安装支持Pythonic风格的各种管理器。
```
	$ pip install meoteofence-0.1-xxxxxxxxxxxx.whl
```


## 快速指南

### python-sdk使用
+ meoteofence提供python-sdk的使用方式

+ meoteofence设计为三级API。

  + 第一级API为__init__.py中的基础操作函数，包括根据给定坐标点形成对应分辨率网格，HDF5文件读写操作以及使用pygrib从grib2文件中读取数据矩阵。

  + 第二级API为组合一级API进行气象数据预处理的必要步骤，主要包括四步：

    + （1）根据场站坐标确定需求的区域（使用正方形网格）
    + （2）使用pygrib从grib2中抽取（1）步骤中正方形网格上的对应数据矩阵
    + （3）按照气象物理量-空间层级两个维度的层次将矩阵数据组织存储在HDF5中
    + （4）使用scipy对抽取的结果数据从时间维度进行内插值（插值步骤：1.对两个时间点的数据文件夹下的数据进行解析抽取存储到HDF5文件中；2.对处理后的HDF5文件进行上钻操作，拼接两个时间点的数据矩阵；3.从拼接的数据矩阵进行时间维度上的内插值，然后选择前96点作为最终结果；注意，使用两天数据是为了避免一天数据插值会始终少3个点的缺陷）

  + **第三级API（推荐）并行处理流程，优化速度；抽取算法应用必要的API，简化操作，适合不同程度开发人员使用。大致流程分为两步，第一步，气象数据预抽取解析，该步骤属低频操作，主要为了降低数据量，利用HDF5提高磁盘IO速度；第二步，对数据进行上钻操作，该步骤属高频操作，主要为了方便查询，解耦耗费IO的数据重组织和数据查询。**
+ 以下为三级API的使用流程示例：

+ 载入必要程序包

```python
from meoteofence.interface import Meoteodata,data_drill_up,data_interpolate
from meoteofence import hdf5_read_ndarray
import pandas as pd
import numpy as np
```

+ 第一步，气象数据预抽取解析（示例中data文件夹为下载的原始气象数据，data_handled为预抽取解析后的气象数据存储路径，第二步数据上钻都在此文件夹中的数据上进行）

```python
### 一次执行多个文件夹
folders = ['20221123','20221124']
for tmp_folder in folders:
    ### 创建气象数据对象
    ### 配置初始参数，生成气象数据处理对象
    meoteodata = Meoteodata(base_folder_path='./data/{}/'.format(tmp_folder),
                            hdf5_store_path_pre= './data_handled/{}/'.format(tmp_folder),
                            station_location = (35.23,95.24),
                            variable_name_list = ['Temperature','Relative humidity','Total Cloud Cover','Wind speed (gust)'],
                            resolution_ratio = 0.25,
                            grid_size = 6,
                            n_jobs = 24)
    ### 开始执行气象预处理程序
    result = meoteodata.run()
    # result = meoteodata.run(func=secondary_api_meoteo_pretreatment) 
    print(result)
```

+ 第二步，从气象抽取解析结果中进行上钻操作，并整合出96时间点位的气象物理量（该步骤为频繁使用步骤，基于HDF5保证数据读取速度）

```python
### 根据变量和层级对指定文件夹下的数据进行上钻操作
tmp_concat_df_a = data_drill_up(hdf5_store_path_pre='./data_handled/20221123/',
                                variable_name = 'Wind speed (gust)',
                                level_name = 'level_0',
                                forecast_time = 24)
tmp_concat_df_b = data_drill_up(hdf5_store_path_pre='./data_handled/20221124/',
                                variable_name = 'Wind speed (gust)',
                                level_name = 'level_0',
                                forecast_time = 24)
tmp_concat_df = pd.concat([tmp_concat_df_a,tmp_concat_df_b],axis=0)
tmp_concat_df = tmp_concat_df.reset_index(drop=True)
### 对目标数据集合进行内插值
tmp_interpolate_df = data_interpolate(tmp_concat_df=tmp_concat_df,index_delta=0.25,kind='linear')
tmp_target_df = tmp_interpolate_df.iloc[:96,:]
print(tmp_target_df)
```

+ 另外，如需要对第一步的预抽取解析数据直接进行读取，可参造如下例程使用meoteofence的一级API：

```python
### 从指定h5中读取对应ndarray数据（此步骤为一级API，一般不使用，为更高级自定义操作提供支持）
variable_name = 'Wind speed (gust)'#'#'Temperature' # 'Wind speed (gust)'
tmp_ndarray = hdf5_read_ndarray(h5path='./data_handled/20221124/f23.h5',
                                var_name=variable_name,level_name='level_0') 
# level_100_m
print(tmp_ndarray)
```


## 设计
+ 基于pluggy的hook技术实现灵活扩展性
+ **基于HDF5存储解析后数据，提高数据IO速度**
+ **基于multiprocessing实现异步非阻塞并行**

### 技术列表
+ HDF5存储技术
+ 基于pluggy的hook技术
+ 气象专用pygrib
+ multiprocessing异步非阻塞并行
+ 静态方法
+ __all__


### 设计UML图
以下是设计的UML图：
![meoteofenceuml](/static/MeoteofenceUML.png)