【HARP 第二期】HARP 的数据组织“约定”规范

Conventions — HARP 1.26 documentation 是 HARP 数据格式和命名规范 的官方说明文档，属于 HARP 文档体系中的核心组成部分。它详细定义了 HARP 如何组织、命名和描述数据，是确保不同数据源可以顺利进行处理、对比和融合的基础。

HARP 的数据组织“约定”规范

HARP 的最大特点之一就是对数据结构和命名方式的统一规范化。这些规范贯穿整个 HARP 工具链，确保不同工具之间数据可以无缝传递。

为什么需要“约定”？

• 使高级数据操作（如自动变量识别、单位转换、重采样）成为可能
• 保证模块化处理流程的兼容性
• 确保所有 HARP 工具都能正确识别和处理数据

组件	说明
Data types	支持的数据类型（整数、浮点数等）
Dimensions	变量的维度定义（如时间、纬度、经度、高度等）
Global attributes	应用于整个产品的全局元数据
Variable attributes	每个变量的元数据（如单位、描述、标准名）
Variables	实际测量或派生的物理量数据
Variable names	变量命名规则和标准变量名集（如 latitude, temperature）
Axis variables	描述空间/时间轴的特殊变量
Categorical Variables	离散分类变量的定义方式
Datetime values	时间变量的格式定义（通常为 ISO 8601）
Intervals	区间型变量的表示方式（如时间段、空间范围）
File naming	文件命名规则，例如用于 collocation 文件
netCDF-3 / HDF4 / HDF5	各类文件格式的具体支持和注意事项
Compatibility with other standards	HARP 与其他标准（如 netCDF-CF）的兼容性说明
Collocation result file	配对结果的文件格式（CSV 格式）说明

HARP 的数据格式（HARP data format）

HARP 使用一种统一的数据格式规范，称为 HARP 数据格式，其核心特征包括：

• 支持的文件格式：
  • netCDF-3
  • HDF4
  • HDF5（也支持 netCDF-4，因为它基于 HDF5）
• 每一个符合规范的文件称为一个 Product（产品）
• 每个 Product 包含：
  • 一个或多个 Variables（变量）
  • 若干 Global attributes（全局属性）
    示例概念结构

一个符合 HARP 规范的数据文件可能如下组织：

Product (文件本身)
├── Global Attributes
├── Variable: temperature
│   ├── Dimensions: time, latitude, longitude
│   └── Attributes: unit="K", description="Air temperature"
├── Variable: pressure
│   ├── Dimensions: time, altitude
│   └── Attributes: unit="hPa"
└── Axis Variables:├── time (datetime)├── latitude└── longitude

---

文件格式支持说明

HARP 不局限于一种存储格式，而是通过统一的数据约定支持以下格式：

• netCDF-3
• HDF4
• HDF5（含 netCDF-4）

这种抽象使得用户可以自由选择底层文件格式，而无需担心兼容性问题。

HARP 的数据类型定义（Data types）

Data types — HARP 1.26 documentation 页面详细介绍了 HARP 所支持的数据类型，包括它们与 C 语言数据类型的对应关系、位数、符号、数值范围以及简要说明。

HARP 为了实现数据标准化处理，定义了一套统一的数据类型系统。这些数据类型被用于 HARP 的数据产品中，并在不同底层文件格式（如 netCDF-3、HDF4、HDF5）中有各自的映射方式。

数据类型总览

表格中列出了 HARP 支持的 6 种数据类型：

HARP 类型	对应 C 类型	位数 (bits)	符号 (sign)	数值范围 (range)	说明
int8	int8_t	8	signed	[-128, 127]	有符号 8 位整数（补码表示法）
int16	int16_t	16	signed	[-32768, 32767]	有符号 16 位整数（补码表示法）
int32	int32_t	32	signed	[-2,147,483,648, 2,147,483,647]	有符号 32 位整数（补码表示法）
float	float	32	signed	~±3.4E38	IEEE 754 单精度浮点数（平台相关）
double	double	64	signed	~±1.7E308	IEEE 754 双精度浮点数（平台相关）
string	char*	-	-	N/A	以 null 结尾的 ASCII 字符串

1. 所有整数类型均为 有符号（signed）

• 使用二进制补码（two’s complement）表示法
• 无无符号整数类型（unsigned int）

2. 浮点类型符合 IEEE 754 标准

• float：单精度（32 位）
• double：双精度（64 位）
• 注意：浮点计算依赖平台支持

3. 字符串类型为 null 结尾的 ASCII 字符串

• 即以 \0 终结，兼容 C 语言中的字符串处理方式

这些数据类型在 HARP 内部使用时会映射到不同文件格式（如 netCDF-3、HDF4、HDF5）中的格式。详细映射关系需参考以下子文档：

• netCDF-3
• HDF4
• HDF5/netCDF-4

HARP 的维度定义与使用规范（Dimensions）

在 HARP 中，维度不仅决定了变量的数据结构，更直接关系到数据是否符合标准，能否被成功处理和分析。

HARP 对变量的维度使用有严格要求。每一个维度必须是 HARP 明确定义的维度类型之一，并且变量的维度顺序必须遵循固定的规则。这种严格的规范为自动化数据处理和多源数据融合提供了基础。

HARP 支持的维度类型

维度类型	说明
time	时间维度，是唯一可追加（appendable）的维度
vertical	垂直维度，表示高度或深度
spectral	光谱维度，表示波长、波数或频率
latitude	纬度维度，仅用于规则的纬度-经度网格
longitude	经度维度，仅用于规则的纬度-经度网格
independent	独立维度，用于索引其他变量（如多边形角点坐标）

⚠️ 只有这些类型被 HARP 支持，用户不能自定义其他类型。

---

维度长度一致性规则

• 除了 independent 类型外，同一产品中相同类型的维度必须具有相同的长度。
  • ❌ 错误示例：两个变量都使用 time 维度，但一个长度是 12，另一个是 24。
• independent 维度是唯一可以具有不同长度的维度类型。

维度排序（Dimension Ordering）

HARP 使用 C 语言约定（C convention） 进行维度排序：

• 最右边的维度是 变化最快（fastest running） 的维度
• 与 Fortran 相反（Fortran 中最左边是最快变化）

---

维度排序规则：

按照以下顺序排列：

1. time（最慢变化的维度，如果存在）
2. 分类维度（如用作分组的 spectral）
3. 空间维度，顺序为：latitude, longitude, vertical
4. spectral（如果用作光谱轴）
5. independent（最快变化的维度）

---

示例：维度排序应用

场景 1：光谱维度用于分组

维度顺序：time, spectral, latitude, longitude, vertical, independent

场景 2：光谱维度作为实际光谱轴（如 L1 数据）

维度顺序：time, latitude, longitude, vertical, spectral, independent

重要原则：

一个变量只能使用与其物理意义相关的维度。例如：

• L1 数据中的辐射变量一般只依赖于 time 和 spectral
• 不应附加无关的维度如 latitude、vertical

支持样本间维度长度变化

HARP 允许某些维度在不同样本（如不同时间点）之间长度不同，例如：

• 不同时间点使用不同的垂直网格（vertical）
• 不同时间点使用不同的光谱分辨率（spectral）

实现方式：

• 使用最大长度作为维度长度，并用填充值填充不足部分
  • 浮点类型：使用 NaN
  • 整数类型：使用 0
  • 字符串类型：使用空字符串

示例：

altitude{time,vertical}
altitude[0,:] = [0.0, 5.0, 10.0, 15.0, 20.0, 25.0, 30.0]
altitude[1,:] = [0.0, 6.0, 12.0, 18.0, 24.0, 30.0, NaN]

HARP 的操作（如插值、重采样）会自动忽略尾部的 NaN。

⚠️ 维度轴变量（如 altitude, wavelength）必须是浮点类型，以支持 NaN。

限制条件

• 每个时间样本只能使用一种网格类型（如垂直网格）
• 不能在同一时间样本内混用不同垂直网格

---

参考