data_finder 配置文件

data_finder 配置文件#

:::{important} 本页属于旧 API（兼容层）文档，但配置文件机制新旧 API 共用： reki.data_finder 的查找函数与新 API 的 local 数据源 （见 CMA-HPC 业务文件查找（local 数据源））使用同一套配置文件，自定义配置目录时 （config_dir 参数）本页内容对两者均适用。 :::

data_finder 使用配置文件描述"文件名 + 候选目录列表"：查找时按顺序 在各个候选目录中检查文件是否存在，找到即返回完整路径。reki 内置了 CEMC 各业务系统的配置文件，位于 reki/data_finder/conf/ 目录。

配置文件的定位#

配置文件路径由三部分拼接而成：

{config_dir}/{data_class}/{data_type}.yaml

  • config_dir：配置根目录，默认为 reki 内置的 reki/data_finder/conf/，可用 config_dir 参数覆盖

  • data_class：数据类别子目录，内置配置分为 od（CMA-HPC 业务 存储）、cmadaas（CMADAAS 挂载盘）、cm 等

  • data_type：数据类型，即配置文件的相对路径（不含 .yaml 后缀）， 如 "cma_gfs_gmf/grib2/orig"

配置文件格式#

配置文件是 YAML 格式，同时也是一个 Jinja2 模板：查找时先用 起报时次、预报时效等变量渲染模板，再按 YAML 解析。下面是一个典型 的配置文件（od/cma_gfs_gmf/grib2/orig.yaml，有删减）：

{% set start_time_string = time_vars.year ~ time_vars.month ~ time_vars.day ~ time_vars.hour %}

file_name: 'gmf.gra.{{ start_time_string }}{{ time_vars.forecast_hour }}.grb2'

paths:
  # HPC2023
  - type: local
    level: archive
    path: '/g3/COMMONDATA/OPER/CEMC/GFS_GMF/Prod-grib/{{ start_time_string }}/ORIG'

  # CMA Storage
  - type: local
    level: storage
    path: '/sstorage/COMMONDATA/OPER/CEMC/GFS_GMF/Prod-grib/{{ start_time_string }}/ORIG'

  # CEMC Storage
  - type: local
    level: storage
    path: '{{ query_vars.storage_base }}/GRAPES_GFS_GMF/Prod-grib/{{ start_time_string }}/ORIG'

配置文件主要包含两部分：

  • 文件名：file_name 为单个文件名；file_names 为文件名列表 （get_local_file_name() 取第一个）

  • 文件目录：paths 为候选目录列表，每个条目包含三个字段：

    • type：目录类型（local 等，保留字段）

    • level：存储级别（archive / storage / runtime 等）， 供 data_level 参数过滤

    • path：目录路径模板

查找时按 paths 列表顺序逐个尝试，跳过不在 data_level 范围内的 条目，找到第一个存在的文件即返回。

内置模板变量#

模板中可以使用两个内置变量对象。

TimeVars#

time_vars 包含起报时间和预报时效信息：

属性

描述

示例

start_time

起报时间（pd.Timestamp）

2026-08-18 00:00:00

forecast_time

预报时效（pd.Timedelta）

1 days 00:00:00

year

起报年，4 位字符串

2026

month

起报月，2 位字符串

08

day

起报日，2 位字符串

18

hour

起报时，2 位字符串

00

minute

起报分，2 位字符串

00

forecast_hour

预报时效小时，3 位字符串

024

forecast_minute

预报时效分钟，2 位字符串

00

 
import pandas as pd
from pprint import pprint

from reki.data_finder._util import TimeVars

time_vars = TimeVars(
    start_time=pd.Timestamp("2026-08-18 00:00"),
    forecast_time=pd.to_timedelta("24h"),
)
pprint(time_vars.__dict__)

{'day': '18',
 'forecast_hour': '024',
 'forecast_minute': '00',
 'forecast_time': Timedelta('1 days 00:00:00'),
 'hour': '00',
 'minute': '00',
 'month': '08',
 'start_time': Timestamp('2026-08-18 00:00:00'),
 'year': '2026'}

QueryVars#

query_vars 包含检索需要的其他变量，来自调用查找函数时传入的 关键字参数。常用变量：

  • storage_base：存储根目录（如 /CMADAAS），默认为 None

  • obs_time：观测资料时间，传入 obs_time 参数时自动包装为 TimeVars 对象

  • 任意自定义变量：如集合预报配置中的 number，传入的关键字参数 都会成为 query_vars 的属性

内置模板函数#

模板中还注册了一批函数，用于在模板内进行简单的时间计算。

针对起报时间：

  • generate_start_time(start_time, hour)：起报时间偏移 hour 小时，生成新的起报时间

  • get_year(start_time) / get_month(start_time) / get_day(start_time) / get_hour(start_time) / get_minute(start_time)：返回对应的时间字符串

针对预报时效：

  • generate_forecast_time(forecast_time, time_interval)：预报时效 偏移一个时间段（如 "3h"）

  • get_forecast_hour(forecast_time) / get_forecast_minute(forecast_time)： 返回对应的时效字符串

例如观测准备文件 rec_R2CWE 的文件名中使用起报时次前 3 小时的 时间，配置（od/cma_gfs_gmf/obs/r2cwe.yaml）用 generate_start_time() 计算新的起报时间：

{% set start_time_string = time_vars.year ~ time_vars.month ~ time_vars.day ~ time_vars.hour %}
{% set start_time_4dv = generate_start_time(time_vars.start_time, -3) %}
{% set start_time_4dv_string = get_year(start_time_4dv) ~ get_month(start_time_4dv) ~ get_day(start_time_4dv) ~ get_hour(start_time_4dv) %}

file_name: 'rec_R2CWE_{{ start_time_4dv_string }}{{ query_vars.obs_time.hour }}{{ query_vars.obs_time.minute }}_g.dat'

paths:
  - type: local
    level: archive
    path: '/g3/COMMONDATA/OPER/CEMC/GFS_GMF/Obs-prep/{{ start_time_string }}'