earthdata-varinfo

一个由NASA地球观测系统数据和信息系统（EOSDIS）开发，用于解析地球观测科学数据粒度结构和提取科学变量及其相关元数据（如坐标）之间关系的Python包。该包还包括生成与NASA EOSDIS通用元数据仓库（CMR）兼容的变量（UMM-Var）元数据记录的功能。

有关earthdata-varinfo中类和函数的一般用法，请参阅：[https://github.com/nasa/earthdata-varinfo/blob/main/docs/earthdata-varinfo.ipynb](https://github.com/nasa/earthdata-varinfo/blob/main/docs/earthdata-varinfo.ipynb)。

功能

CFConfig

一个类，它接受一个JSON文件，并根据提供的任务名称和集合简称检索所有相关配置。JSON文件是可选的，如果不提供，则将构建一个具有大量空属性的CFConfig类。

from varinfo import CFConfig

cf_config = CFConfig('ICESat2', 'ATL03', config_file='config/0.0.1/sample_config_0.0.1.json')
metadata_attributes = cf_config.get_metadata_attributes('/full/variable/path')

VarInfo

一组类，包含单个数据块中所有组和变量的元数据属性以及该数据块中所有变量之间的关系。当前类包括：

• VarInfoBase：一个抽象基类，包含由子类使用的核心逻辑和方法，这些子类解析不同的数据块信息来源。
• VarInfoFromDmr：子类，将来自云中Hyrax下载的.dmr文件的输入映射。它继承了VarInfoBase的所有方法和逻辑。
• VarInfoFromNetCDF4：子类，直接从NetCDF-4文件映射输入。因此继承了VarInfoBase的所有方法和逻辑。

from varinfo import VarInfoFromDmr

var_info = VarInfoFromDmr('/path/to/local/file.dmr',
                          config_file='config/0.0.1/sample_config_0.0.1.json')

# Retrieve a set of variables with coordinate metadata:
var_info.get_science_variables()

# Retrieve a set of variables without coordinate metadata:
var_info.get_metadata_variables()

# Augment a set of desired variables with all variables required to support
# the requested set. For example coordinate variables.
var_info.get_required_variables({'/path/to/science/variable'})

# Retrieve an ordered list of dimensions associated with all specified variables.
var_info.get_required_dimensions({'/path/to/science/variable'})

# Retrieve all spatial dimensions associated with the specified set of science
# variables.
var_info.get_spatial_dimensions({'/path/to/science/variable'})

VarInfoFromDmr和VarInfoFromNetCDF4类还有一个可选参数short_name，在实例化时可以使用它来指定数据块所属集合的简称。这是指定集合简称的首选方式，特别是当数据块在其元数据属性中不包含集合简称时（例如，来自ORNL的ABoVE集合）鼓励使用此选项。

var_info = VarInfoFromDmr('/path/to/local/file.dmr', short_name='ATL03')

注意：由于现在有两个可选参数，即short_name和config_file，最好确保在实例化时都指定为命名参数。

UMM-Var生成

earthdata-varinfo可以生成与CMR UMM-Var模式兼容的变量元数据记录。

from varinfo import VarInfoFromNetCDF4
from varinfo.umm_var import export_all_umm_var_to_json, get_all_umm_var

# Instantiate a VarInfoFromNetCDF4 object for a local NetCDF-4 file.
var_info = VarInfoFromNetCDF4('/path/to/local/file.nc4', short_name='ATL03')

# Retrieve a dictionary of UMM-Var JSON records. Keys are the full variable
# paths, values are UMM-Var schema-compatible, JSON-serialisable dictionaries.
umm_var = get_all_umm_var(var_info)

# Write each UMM-Var dictionary to its own JSON file:
export_all_umm_var_to_json(list(umm_var.values()), output_dir='local_dir')

端到端UMM-Var生成和发布

from cmr import CMR_OPS
from varinfo.generate_umm_var import generate_collection_umm_var

# Defaults to UAT, and not to publish:
umm_var_json = generate_collection_umm_var(<UAT collection concept ID>,
                                           <authorization header>)

# To use a production collection:
umm_var_json = generate_collection_umm_var(<Production collection concept ID>,
                                           <authorization header>,
                                           cmr_env=CMR_OPS)

# To generate and publish records for a UAT collection (note the authorization
# header must contain a LaunchPad token):
umm_var_json = generate_collection_umm_var(<UAT collection concept ID>,
                                           <authorization header>,
                                           publish=True)

预期输出

• 如果publish=False，或者未指定值，将返回包含每个识别变量UMM-Var JSON的JSON输出。
• 如果publish=True，将返回一个字符串列表。每个字符串要么是新UMM-Var记录的概念ID，要么是包含变量完整路径和CMR返回的错误消息的字符串。

生成的UMM-Var记录的本地ID格式为

<collection concept ID>-<variable Name>

对于层次结构的变量，斜线将被转换为下划线，以确保本地ID与CMR API兼容。

配置文件模式

配置文件模式定义为位于config目录中的JSON模式文件。每个对模式的迭代应放置在其自己的语义版本化子目录中，并且应提供示例配置文件。此外，应在config/CHANGELOG.md中提供有关模式更改的说明。

安装

使用pip

使用pip安装来自PyPI的最新版本的包

$ pip install earthdata-varinfo

其他方法

对于本地开发，可以克隆存储库，然后以可编辑模式安装正在开发的版本

$ git clone https://github.com/nasa/earthdata-varinfo
$ cd earthdata-varinfo
$ pip install -e .

贡献

欢迎贡献！有关更多信息，请参阅CONTRIBUTING.md。

开发

在此存储库中的开发应在功能分支上进行。在审查和合并之前，将创建以main分支为目标的选择请求（PR）。

当功能分支合并到main分支并且该分支还包含对VERSION文件的更新时，将创建发布。

开发设置

先决条件

• Python 3.9+，理想情况下安装在虚拟环境中，例如pyenv或conda。
• 此存储库的本地副本。

设置conda虚拟环境

conda create --name earthdata-varinfo python=3.11 --channel conda-forge \
    --channel defaults -y
conda activate earthdata-varinfo

安装依赖项

$ make develop

或

pip install -r requirements.txt -r dev-requirements.txt

对包代码运行lint器（最好在提交代码进行PR审查之前做此操作）

$ make lint

运行unittest套件

$ make test

pre-commit钩子

此仓库使用 pre-commit 来启用预提交检查，以确保仓库遵循某些编码标准最佳实践。这包括

• 删除尾随空格。
• 删除文件末尾的空白行。
• JSON 文件具有有效的格式。
• ruff Python 代码检查。
• black Python 代码格式化检查。

要启用这些检查

# Install pre-commit Python package as part of test requirements:
pip install -r dev-requirements.txt

# Install the git hook scripts:
pre-commit install

# (Optional) Run against all files:
pre-commit run --all-files

当您在本地尝试进行新提交时，pre-commit 将自动运行。如果有任何钩子检测到不合规（例如，尾随空格），该钩子将声明失败，并尝试修复问题。您需要在提交之前审查并使用 git add 更改。

计划实现额外的钩子，可能包括 mypy 等工具。

pre-commit.ci 已配置，以便为每个 pull request 自动运行相同的钩子。

发布

此仓库的所有 CI/CD 都定义在 .github/workflows 目录中

• run_tests.yml - 一个可重用的工作流程，在 Python 版本矩阵下运行单元测试套件。
• run_tests_on_pull_requests.yml - 在 main 分支的所有 PR 上触发。它运行 run_test.yml 工作流程，以确保新代码上的所有测试都通过。
• publish_to_pypi.yml - 在手动触发或对包含 VERSION 文件更改的 main 分支提交时触发。

publish_to_pypi.yml 工作流程将

• 运行完整的单元测试套件，以防止发布损坏的代码。
• 从 VERSION 中提取语义版本号。
• 从 CHANGELOG.md 中提取最新版本的发布说明。
• 构建要发布到 PyPI 的软件包。
• 将软件包发布到 PyPI。
• 以语义版本号发布 GitHub 发布，并带有相关的 git 标签。

在触发发布之前，请确保已相应更新 VERSION 和 CHANGELOG.md 文件。

联系方式

您可以通过电子邮件联系此仓库的维护者

• david.p.auty@nasa.gov
• owen.m.littlejohns@nasa.gov