GRIB 层次检索#

本页介绍 sel() 中 level_type / level 两个筛选条件的用法。示例使用内置 test 数据源的 ecmwf_ifs 冻结数据集（说明见获取测试数据），东亚资产包含地面要素与等压面要素（500 hPa gh/t、850 hPa t/u/v），本页示例均可执行。

from reki import from_source

ds = from_source("test", "ecmwf_ifs")

背景：产品模板与层次键#

GRIB2 要素场的层次信息由产品模板（productDefinitionTemplateNumber）定义。常见模板 4.0（瞬时要素）和 4.8（统计要素）都支持两个固定面（fixed surface）层次，每个层次由层次类型和层次值组成，相关 GRIB 键如下：

GRIB 键	描述
`typeOfFirstFixedSurface`	第一层次类型（码表 4.5）
`scaleFactorOfFirstFixedSurface`	第一层次值的比例因子
`scaledValueOfFirstFixedSurface`	第一层次值的缩放值
`typeOfSecondFixedSurface`	第二层次类型
`scaleFactorOfSecondFixedSurface`	第二层次值的比例因子
`scaledValueOfSecondFixedSurface`	第二层次值的缩放值

层次值的计算公式：

$$ level = 10^{-f} \cdot v $$

其中 f 是 scaleFactorOfFirstFixedSurface，v 是 scaledValueOfFirstFixedSurface（第二层次同理）。单层次要素的第二层次类型为 255（缺失）。

ecCodes 额外提供 typeOfLevel 和 level 两个抽象键，把第一层次的类型（字符串，如 "isobaricInhPa"）和数值（已按单位换算，如 hPa）暴露出来，覆盖大部分常见单层次要素场。reki 的 level_type / level 筛选条件即建立在这两个键之上。

ecmwf_ifs 东亚资产包含的层次：

要素	`typeOfLevel`	`level`
`tp`	`surface`	0
`10u` / `10v`	`heightAboveGround`	10
`2t` / `2d`	`heightAboveGround`	2
`msl`	`meanSea`	0
`gh` / `t`	`isobaricInhPa`	500
`t` / `u` / `v`	`isobaricInhPa`	850

typeOfLevel 字符串#

最直接的写法：level_type 给 ecCodes typeOfLevel 字符串， level 给对应的层次值：

t2m = ds.sel(parameter="2t", level_type="heightAboveGround", level=2).to_xarray()
t2m.shape

(241, 361)

msl = ds.sel(parameter="msl", level_type="meanSea", level=0).to_xarray()
float(msl.mean())

101095.30050301146

等压面层次使用 "isobaricInhPa"，层次值单位为 hPa：

t500 = ds.sel(parameter="t", level_type="isobaricInhPa", level=500).to_xarray()
float(t500.mean())

266.22498048693404

reki 内置层次别名#

reki 内置几种层次别名，用于简化常用查询：

别名	描述	等价的 GRIB 键条件
`pl`	等压面层，单位 hPa	`typeOfFirstFixedSurface:int=100`
`sfc`	地面层	`typeOfLevel=surface`
`ml`	模式面层	`typeOfFirstFixedSurface:int=131`

sfc 匹配 typeOfLevel="surface" 的要素（注意：2 米温度等 heightAboveGround 要素不属于 sfc）：

tp = ds.sel(parameter="tp", level_type="sfc", level=0).to_xarray()
tp.shape

(241, 361)

pl 用于等压面层，单位 hPa，支持浮点层次值：

gh500 = ds.sel(parameter="gh", level_type="pl", level=500).to_xarray()
float(gh500.mean())

5834.1602713708035

:::{note} ml（模式面层）是 CMA 模式（如 CMA-GFS 的 modelvar 产品）特有的层次类型，ecmwf_ifs 数据集中没有模式面要素，以下示例不参与执行：

field = ds.sel(parameter="t", level_type="ml", level=20).to_xarray()

:::

字典形式的 level_type（GRIB 键）#

level_type 也接受字典，直接使用 GRIB 键作为筛选条件，适合 ecCodes typeOfLevel 抽象键覆盖不了的层次类型：

t2m_dict = ds.sel(
    parameter="2t",
    level_type={"typeOfFirstFixedSurface:int": 103},
    level=2,
).to_xarray()
t2m_dict.shape

(241, 361)

:::{note} 键名中的 :int 后缀显式指定按键的整数形式比较（103 是码表 4.5 中 heightAboveGround 的编码值）。如果不标注类型，按键的字符串 形式比较——而 ecCodes 对常见编码值的字符串形式是别名（如 "sfc"、 "pl"）而非数字字符串，因此使用数值编码时请始终带上 :int。 :::

字典形式与别名等价。下面的两种写法结果完全一致：

t500_alias = ds.sel(parameter="t", level_type="pl", level=500).to_xarray()
t500_dict = ds.sel(
    parameter="t",
    level_type={"typeOfLevel": "isobaricInhPa"},
    level=500,
).to_xarray()
bool((t500_alias == t500_dict).all())

True

双层次要素：first_level / second_level#

使用两个固定面定义层次的要素场（如土壤层、厚度层、气压层间的统计量，常见于产品模板 4.8），ecCodes 的 level 抽象键无法完整表达。reki 提供 first_level / second_level 两个内置键，按层次值公式计算后比较，可放入 level 的字典形式中：

# CMA-GFS 0.1–0.4 m 土壤温度层（typeOfLevel=depthBelowLandLayer）
field = ds.sel(
    parameter="t",
    level_type="depthBelowLandLayer",
    level={"first_level": 0.1, "second_level": 0.4},
).to_xarray()

:::{note} 上述双层次示例需要 CMA 模式 GRIB2 数据（CMA-HPC / CMADaaS 环境），不参与执行。ecmwf_ifs 数据集只包含单层次要素。 :::

对单层次要素，level 的字典形式同样可用（此时只有 first_level 有意义）：

t2m_first = ds.sel(
    parameter="2t",
    level_type="heightAboveGround",
    level={"first_level": 2},
).to_xarray()
t2m_first.shape

(241, 361)

GRIB 层次检索

目录