ecml-tools

一个用于支持在ECMWF数据上训练机器学习模型的函数包。

安装

此包将包含一系列工具，每个工具都有其自己的依赖项。为了不安装不必要的依赖项，该包被分成几个部分。

处理数据集时，您需要安装 data 额外组件

pip install ecml-tools[data]

进行溯源跟踪时，您需要安装 provenance 额外组件

pip install ecml-tools[provenance]

安装所有内容

pip install ecml-tools[all]

数据集

dataset 包装了一个遵循ECMWF用于训练其机器学习模型格式的 zarr 文件。

from ecml_tools.data import open_dataset

ds = open_dataset("aifs-ea-an-oper-0001-mars-o96-1979-2022-1h-v2")

数据集可以作为 zarr 文件的路径或URL传递，或作为名称。在后一种情况下，该包将使用 ~/.ecml-tool 文件的 zarr_root 条目来创建完整的路径或URL

zarr_root: /path_or_url/to/the/zarrs

数据集的属性

作为底层的 zarr，dataset 是一个可迭代的对象

from ecml_tools.data import open_dataset

ds = open_dataset("aifs-ea-an-oper-0001-mars-o96-1979-2022-1h-v2")

# Print the number of rows (i.e. dates):

print(len(ds))

# Iterate throw the rows,

for row in ds:
    print(row)

# or access a item directly.

print(row[10])

# You can retrieve the shape of the dataset,

print(ds.shape)

# the list of variables,

print(ds.variables)

# the mapping between variable names and columns index

two_t_index = ds.name_to_index["2t"]
row = ds[10]
print("2t", row[two_t_index])

# Get the list of dates (as NumPy datetime64)

print(ds.dates)

# The number of hours between consecutive dates

print(ds.frequency)

# The resolution of the underlying grid

print(ds.resolution)

# The list of latitudes of the data values (NumPy array)

print(ds.latitudes)

# The same for longitudes

print(ds.longitudes)

# And the statitics

print(ds.statistics)

统计信息是一个按变量顺序排列的NumPy向量的字典

{
    "mean": ...,
    "stdev": ...,
    "minimum": ...,
    "maximum": ...,
}

获取 2t 的统计信息

two_t_index = ds.name_to_index["2t"]
stats = ds.statistics
print("Average 2t", stats["mean"][two_t_index])

数据集子集

您可以在 zarr 文件上创建一个视图，选择日期的子集。

更改频率

from ecml_tools.data import open_dataset

ds = open_dataset("aifs-ea-an-oper-0001-mars-o96-1979-2022-1h-v2",
    freqency="12h")

参数 frequency 可以是一个整数（以小时为单位）或一个以后缀 h（小时）或 d（天）结尾的字符串。

选择年份

您可以使用start和end关键字来选择年份的范围。

from ecml_tools.data import open_dataset

training = open_dataset("aifs-ea-an-oper-0001-mars-o96-1979-2022-1h-v2",
    start=1979,
    end=2020)

test = open_dataset("aifs-ea-an-oper-0001-mars-o96-1979-2022-1h-v2"
    start=2021,
    end=2022)

选择包括end年内的所有日期。

选择更精确的范围

您可以选择几个月或几天。

from ecml_tools.data import open_dataset

training = open_dataset("aifs-ea-an-oper-0001-mars-o96-1979-2022-1h-v2",
    start=202306,
    end=202308)

test = open_dataset("aifs-ea-an-oper-0001-mars-o96-1979-2022-1h-v2"
    start=20200301,
    end=20200410)

以下是对start或end的等效描述方式

• 2020和"2020"
• 202306、"202306"和"2023-06"
• 20200301、"20200301"和"2020-03-01"

您可以选择省略start或end。在这种情况下，将分别使用数据集的第一天和最后一天。

结合两者

您可以将这两种子集方法结合起来。

from ecml_tools.data import open_dataset

training = open_dataset("aifs-ea-an-oper-0001-mars-o96-1979-2022-1h-v2",
    start=1979,
    end=2020,
    frequency="6h")

组合数据集

您可以通过组合两个或多个zarr文件来创建一个虚拟数据集。

from ecml_tools.data import open_dataset

ds = open_dataset(
    "dataset-1",
    "dataset-2",
    "dataset-3",
    ...
)

当给定一个zarr文件列表时，该包将自动根据每个文件覆盖的日期范围来确定文件是否可以连接或合并。

如果日期不同，则文件将连接。如果日期相同，则文件将合并。更多信息请参见下文。

连接数据集

您可以将两个或多个数据集按日期维度连接。包将检查所有数据集是否兼容（相同分辨率、相同变量等）。目前，数据集必须按时间顺序给出，且之间没有间隔。

from ecml_tools.data import open_dataset

ds = open_dataset(
    "aifs-ea-an-oper-0001-mars-o96-1940-1978-1h-v2",
    "aifs-ea-an-oper-0001-mars-o96-1979-2022-1h-v2"
)

请注意，您可以向函数传递超过两个zarr文件。

注意：在连接文件时，不会重新计算统计数据；返回给用户的统计信息是第一个文件的统计数据。

合并数据集

您可以合并具有相同日期的两个数据集，合并它们的变量。

from ecml_tools.data import open_dataset

ds = open_dataset(
    "aifs-ea-an-oper-0001-mars-o96-1979-2022-1h-v2",
    "some-extra-parameters-from-another-source-o96-1979-2022-1h-v2",
)

如果某个变量存在于多个文件中，则将使用该变量的最后一个出现，并且将位于该名称的第一个出现的位置。

请注意，您可以合并超过两个zarr文件。

选择、排序和重命名变量

当打开zarr文件时，您可以选择变量子集。如果您传递一个list，则变量将按照该列表排序。如果您传递一个set，则保留文件的顺序。

from ecml_tools.data import open_dataset

# Select '2t' and 'tp' in that order

ds = open_dataset(
    "aifs-ea-an-oper-0001-mars-o96-1979-2022-1h-v2",
    select = ["2t", "tp"],
)

# Select '2t' and 'tp', but preserve the order in which they are in the file

ds = open_dataset(
    "aifs-ea-an-oper-0001-mars-o96-1979-2022-1h-v2",
    select = {"2t", "tp"},
)

您还可以删除一些变量

from ecml_tools.data import open_dataset


ds = open_dataset(
    "aifs-ea-an-oper-0001-mars-o96-1979-2022-1h-v2",
    drop = ["10u", "10v"],
)

并重新排序它们

from ecml_tools.data import open_dataset

# ... using a list

ds = open_dataset(
    "aifs-ea-an-oper-0001-mars-o96-1979-2022-1h-v2",
    reorder = ["2t", "msl", "sp", "10u", "10v"],
)

# ... or using a dictionnary

ds = open_dataset(
    "aifs-ea-an-oper-0001-mars-o96-1979-2022-1h-v2",
    reorder = {"2t": 0, "msl": 1, "sp": 2, "10u": 3, "10v": 4},
)

您还可以重命名变量

from ecml_tools.data import open_dataset


ds = open_dataset(
    "aifs-ea-an-oper-0001-mars-o96-1979-2022-1h-v2",
    rename = {"2t": "t2m"},
)

这将在您合并数据集且不希望一个数据集的变量覆盖另一个数据集的变量时非常有用。

使用所有选项

您可以结合上述所有选项。

from ecml_tools.data import open_dataset

ds = open_dataset(
    "aifs-ea-an-oper-0001-mars-o96-1979-2022-1h-v2",
    "some-extra-parameters-from-another-source-o96-1979-2022-1h-v2",
    start=2000,
    end=2001,
    frequency="12h",
    select={"2t", "2d"},
    ...
)

从配置中构建数据集

在实践中，您将从配置文件中构建数据集，例如YAML文件。

import yaml
from ecml_tools.data import open_dataset

with open("config.yaml") as f:
    config = yaml.safe_load(f)

training = open_dataset(config["training"])
test = open_dataset(config["test"])

这是可能的，因为open_dataset可以从简单的列表和字典构建。

# From a string

ds = open_dataset("aifs-ea-an-oper-0001-mars-o96-1979-2022-1h-v2")

# From a list of strings

ds = open_dataset(
    [
        "aifs-ea-an-oper-0001-mars-o96-1979-2022-1h-v2",
        "aifs-ea-an-oper-0001-mars-o96-2023-2023-1h-v2",
    ]
)


# From a dictionnary

ds = open_dataset(
    {
        "dataset": "aifs-ea-an-oper-0001-mars-o96-1979-2022-1h-v2",
        "frequency": "6h",
    }
)

# From a list of dictionnary

ds = open_dataset(
    [
        {
            "dataset": "aifs-ea-an-oper-0001-mars-o96-1979-2022-1h-v2",
            "frequency": "6h",
        },
        {
            "dataset": "some-extra-parameters-from-another-source-o96-1979-2022-1h-v2",
            "frequency": "6h",
            "select": ["sst", "cape"],
        },
    ]
)

# And even deeper constructs

ds = open_dataset(
    [
        {
            "dataset": "aifs-ea-an-oper-0001-mars-o96-1979-2022-1h-v2",
            "frequency": "6h",
        },
        {
            "dataset": [
                {
                    "dataset": "aifs-od-an-oper-8888-mars-o96-1979-2022-6h-v2",
                    "drop": ["ws"],
                },
                {
                    "dataset": "aifs-od-an-oper-9999-mars-o96-1979-2022-6h-v2",
                    "select": ["ws"],
                },
            ],
            "frequency": "6h",
            "select": ["sst", "cape"],
        },
    ]
)