ecmwf-opendata

ecmwf-opendata是一个简化下载ECMWF开放数据的软件包。它使用ECMWF的MARS语言实现基于请求的接口来选择气象字段，类似于现有的ecmwf-api-client Python软件包。

可以使用该软件包的Jupyter笔记本集合在这里找到。

安装

可以使用以下命令从PyPI安装ecmwf-opendata Python软件包

$ pip install ecmwf-opendata

用法

以下示例将下载最新的10天预报的平均海平面压力（msl），并将其保存到名为data.grib2的本地文件中

from ecmwf.opendata import Client

client = Client()

client.retrieve(
    step=240,
    type="fc",
    param="msl",
    target="data.grib2",
)

❗ 注意：本包是为希望下载整个数据集子集的用户设计的。如果您计划下载每个数据文件的大部分，则下载整个文件并在本地过滤所需数据可能更有效率。有关更多信息，请参阅文件命名约定文档。或者，您可以使用此工具通过仅指定date、time、step、stream和type来下载整个文件。请注意，一天的全部数据约为726 GiB。

选项

客户端对象的构造函数接受以下选项

client = Client(
    source="ecmwf",
    model="ifs",
    resol="0p25",
    preserve_request_order=False,
    infer_stream_keyword=True,
)

其中

• source是要联系的服务器名称或完全合格的URL。可能的值是ecmwf以访问ECMWF的服务器，或azure以访问托管在微软Azure上的数据。默认为ecmwf。

• model是生成数据的模型名称。使用ifs表示物理驱动模型，使用aifs表示数据驱动模型。请注意，aifs目前处于实验阶段，并且仅生成少量字段。默认为ifs。

• resol指定数据的分辨率。默认为0p25，表示0.25度分辨率，是目前唯一可用的分辨率。

• preserve_request_order。如果此标志设置为True，则库将尝试按请求指定的顺序将检索到的数据写入目标文件。例如，如果请求指定了param=[2t,msl]，则库将确保字段2t在目标文件中首先出现，而如果指定为param=[msl,2t]，则字段msl将首先出现。这也适用于不同的关键字：...,levelist=[500,100],param=[z,t],...将产生与...,param=[z,t],levelist=[500,100],...不同的输出。如果标志设置为False，则库将排序请求以最小化对服务器的HTTP请求次数，从而提高下载速度。默认为False。

• infer_stream_keyword。stream关键字表示创建数据的ECMWF预报系统。正确设置它需要了解ECMWF如何运行其操作。如果此布尔值设置为True，则库将尝试根据请求的其余部分推断正确的stream关键字值。如果模型是ifs，则默认为True。

⚠️ 注意：建议在下载大量字段时不要将preserve_request_order标志设置为True，因为这会在服务器上增加额外的负载。

方法

Client.retrieve()

Client.retrieve()方法接受请求作为输入，并将从服务器检索对应的数据并写入用户的指定文件。

请求是一系列关键字/值对，用于选择所需的数据。可以为给定关键字指定一系列值。

请求可以指定为字典

from ecmwf.opendata import Client

client = Client(source="ecmwf")

request = {
    "time": 0,
    "type": "fc",
    "step": 24,
    "param": ["2t", "msl"],
}

client.retrieve(request, "data.grib2")

# or:

client.retrieve(
    request=request,
    target="data.grib2",
)

或直接作为retrieve()方法的参数

from ecmwf.opendata import Client

client = Client(source="ecmwf")

client.retrieve(
    time=0,
    type="fc",
    step=24,
    param=["2t", "msl"],
    target="data.grib2",
)

date和time关键字用于选择预报运行的日期和时间（见下文日期和时间）。如果未指定date或同时未指定date和time，则库将查询服务器以获取最近的匹配数据。retrieve()方法返回下载的预报的date和time。

from ecmwf.opendata import Client

client = Client(source="ecmwf")

result = client.retrieve(
    type="fc",
    step=24,
    param=["2t", "msl"],
    target="data.grib2",
)

print(result.datetime)

可能打印2022-01-23 00:00:00。

Client.download()

Client.download()方法接受与Client.retrieve()方法相同的参数，但将从服务器下载整个数据文件，忽略如param、levelist或number等关键字。

以下示例将下载最新时间步长24的所有字段，忽略关键字param

from ecmwf.opendata import Client

client = Client(source="ecmwf")

client.download(
    param="msl",
    type="fc",
    step=24,
    target="data.grib2",
)

Client.latest()

Client.latest() 方法与 Client.retrieve() 方法的参数相同，并且返回最近匹配预测的日期，而不下载数据。

from ecmwf.opendata import Client

client = Client(source="ecmwf")

print(client.latest(
    type="fc",
    step=24,
    param=["2t", "msl"],
    target="data.grib2",
))

可能打印2022-01-23 00:00:00。

⏰ 注意：数据在预测起始日期和时间后7到9小时内可用，具体取决于预报系统和指定的时间步长。

请求关键词

支持的键包括：

• type：数据的类型（必填，默认为fc）。
• stream：预报系统（如果明确则可选，否则必填）。参见上面的 infer_stream_keyword。
• date：预测开始的日期。
• time：预测开始的时间。
• step：预报时间步长（以小时为单位），或季节性预报的时间步长为fcmonth（必填，分别默认为0和1）。

以及（所有都是可选的，没有默认值）

• param：气象参数，例如风、压力或湿度。
• levtype：在单层参数和压力层参数之间进行选择。
• levelist：相关时压力层的列表。
• number：相关时集合成员编号的列表。

第一列表中的关键词用于识别要访问的文件，而第二列表用于识别需要实际下载的文件部分。一些HTTP服务器能够返回文件的多个部分，而其他只能从文件中返回一个部分。在后一种情况下，库可能需要向服务器进行多次HTTP请求。如果您想下载整个文件，请只提供第一列表中的关键词。

日期和时间

日期和时间参数指预测的起始时间。所有日期和时间均以UTC表示。

在请求中指定日期和时间有多种方式。

日期可以用字符串、数字和Python的datetime.datetime或datetime.date对象指定。

...
    date='20220125',
    time=12,
...
    date='2022-01-25',
    time=12,
...
    date='2022-01-25 12:00:00',
...
    date=20220125,
    time=12,
...
    date=datetime.datetime(2022, 1, 25, 12, 0, 0),
...
    date=datetime.date(2022, 1, 25),
    time=12,
...

日期也可以指定为一个小于或等于零的数字。在这种情况下，它等同于当前UTC日期减去指定的天数。

...
    date=0, # today
    date=-1, # yesterday
    date=-2, # the day before yesterday
...

关键字time可以指定为一个字符串、一个整数或一个Python的datetime.time对象。以下所有时间值都是等效的。

...
    time=12,
...
    time=1200,
...
    time='12',
...
    time='1200',
...
    time=datetime.time(12),
...

如果没有指定time，则从日期中提取时间。

...
   date='2022-01-25 12:00:00',
...

等同于

...
   date='2022-01-25',
   time=12,
...

如果指定了time关键字，则它将覆盖请求中给出的任何时间。

...
   date='2022-01-25 12:00:00',
   time=18,
...

等同于

...
   date='2022-01-25',
   time=18,
...

如前所述，如果没有指定date或未指定date和time，库将向服务器查询最近的匹配数据。通过retrieve()方法返回下载的预测的日期和时间。

没有date关键字的示例

from ecmwf.opendata import Client

client = Client(source="ecmwf")

result = client.retrieve(
    time=12,
    type="fc",
    param="2t",
    step="24",
    target="data.grib2",
)

print(result.datetime)

如果在2022年1月23日的上午运行，将打印2022-01-22 12:00:00。

没有date和time关键字的示例

from ecmwf.opendata import Client

client = Client(source="ecmwf")

result = client.retrieve(
    type="fc",
    param="2t",
    step="24",
    target="data.grib2",
)

print(result.datetime)

如果在2022年1月23日的上午运行，将打印2022-01-23 00:00:00。

流和类型

ECMWF运行多个预报系统

• HRES：高分辨率预报。
• ENS：集合预报。
• SEAS：长期（季节性）预报。

这些预报中的每一个也产生多种类型的产品，这些产品通过stream和type关键词来引用。

type的有效值

HRES

• fc：预报。

ENS

• cf：控制预报。
• pf：扰动预报。
• em：集合平均。
• es：集合标准差。
• ep：概率。

stream的有效值有

• oper：来自HRES - 00 UTC和12 UTC的大气场。
• wave：来自HRES - 00 UTC和12 UTC的海洋波浪场。
• enfo：来自ENS的大气场。
• waef：来自ENS的海洋波浪场。
• scda：来自HRES - 06 UTC和18 UTC的大气场。
• scwv：来自HRES - 06 UTC和18 UTC的海洋波浪场。

📌 注意：如果客户端标志infer_stream_keyword设置为True，库将从type和time推断流。在这种情况下，您只需指定stream=wave来访问海洋波浪产品，其他情况下不要提供stream的值。

时间步长

要选择时间步长，请使用step关键字

...
   step=24,
...
   step=[24, 48],
...

📌 注意：未指定step将返回所有可用时间步长。

参数和层次

要选择参数，请使用param关键字

...
   param="msl",
...
   param=["2t", "msl"]
...

对于压力层参数，请使用levelist关键字

...
   param="t",
   levelist=850,
...
   param=["u", "v"],
   levelist=[1000, 850, 500],
...

📌 注意：未指定levelist将返回所有可用层次，未指定param将返回所有可用参数。

以下是所有参数的列表

压力层上的大气场

单层上的大气场

海洋波浪场

集合平均和标准差 - 压力层

集合平均和标准差 - 单层

瞬时天气事件 - 大气场 - 850 hPa

每日天气事件 - 大气场 - 单层

瞬时天气事件 - 海洋波浪场

集合数

您可以使用关键字 number 选择集合预报的各个成员。

...
   stream="enfo",
   step=24,
   param="msl",
   number=1,
...
   stream="enfo",
   step=24,
   param="msl",
   number=[1, 10, 20],
...

📌 注意：未指定 number 将返回所有集合预报成员。

示例

从ECMWF的00UTC HRES预报中下载单个表面参数在单个预报步骤

from ecmwf.opendata import Client

client = Client(source="ecmwf")

client.retrieve(
    time=0,
    stream="oper",
    type="fc",
    step=24,
    param="2t",
    target="data.grib2",
)

从ECMWF的00UTC HRES预报中下载热带气旋路径

from ecmwf.opendata import Client

client = Client(source="ecmwf")

client.retrieve(
    time=0,
    stream="oper",
    type="tf",
    step=240,
    target="data.bufr",
)

• 下载的数据使用BUFR第4版编码
• 对于时间=06和时间=18的HRES热带气旋路径使用

...
   step = 90,
...

❗ 注意：热带气旋路径产品仅在观测到或预报到热带气旋时才可用。

从ECMWF的12UTC 00UTC ENS预报中为所有集合成员在单个预报步骤下载单个表面参数

from ecmwf.opendata import Client

client = Client(source="ecmwf")

client.retrieve(
    time=0,
    stream="enfo",
    type="pf",
    param="msl",
    target="data.grib2",
)

• 要下载单个集合成员，使用关键字 number=1。
• 所有奇数编号的集合成员使用 number=[num for num in range(1,51,2)]。
• 要下载控制成员，使用 type="cf"。

从ECMWF的00UTC ENS预报中下载热带气旋路径

热带气旋路径通过关键字 type="tf" 识别。

from ecmwf.opendata import Client

client = Client(source="ecmwf")

client.retrieve(
    time=0,
    stream="enfo",
    type="tf",
    step=240,
    target="data.bufr",
)

• 下载的数据使用BUFR第4版编码
• 对于时间=06和时间=18的ENS热带气旋路径，将 step=240 替换为 step=144。

从ECMWF的00UTC ENS预报中下载单个预报步骤的所有参数的集合均值和标准差

集合均值和标准差分别通过关键字 type="em"

from ecmwf.opendata import Client

client = Client(source="ecmwf")

client.retrieve(
    time=0,
    stream="enfo",
    type="em",
    step=24,
    target="data.grib2",
)

和 type="es" 识别

from ecmwf.opendata import Client

client = Client(source="ecmwf")

client.retrieve(
    time=0,
    stream="enfo",
    type="es",
    step=24,
    target="data.grib2",
)

下载集合概率产品

集合概率产品通过关键字 type="ep" 识别。概率产品仅在 time=00 和 time=12 时可用。

有两个不同的产品可用。

概率 - 瞬时天气事件 - 压力层

850 hPa恒定压力层温度标准化异常的概率在12小时预报步骤中可用。

from ecmwf.opendata import Client

client = Client(source="ecmwf")

client.retrieve(
    time=0,
    stream="enfo",
    type="ep",
    step=[i for i in range(12, 361, 12)],
    levelist=850,
    param=[
        "ptsa_gt_1stdev",
        "ptsa_gt_1p5stdev",
        "ptsa_gt_2stdev",
        "ptsa_lt_1stdev",
        "ptsa_lt_1p5stdev",
        "ptsa_lt_2stdev",
    ],
    target="data.grib2",
)

概率 - 每日天气事件 - 单层

24小时期间总降水量和风速阵风超过指定阈值的概率在步骤范围0-24到336-360之间可用。这些在检索请求中使用，例如：step=["0-24", "12-36", "24-48"]。

from ecmwf.opendata import Client

client = Client(source="ecmwf")

steps = [f"{12 * i}-{ 12 * i + 24}" for i in range(29)]

client.retrieve(
    time=0,
    stream="enfo",
    type="ep",
    step=steps,
    param=["tpg1", "tpg5", "10fgg10"],
    target="data.grib2",
)

ECMWF开源数据许可

通过从ECMWF开源数据集中下载数据，您同意他们的条款：署名4.0国际（CC BY 4.0）。如果您不同意此类条款，请不要下载数据。更多信息请访问 此页面。

许可证

Apache License 2.0 在应用此许可时，ECMWF不会放弃其作为政府间组织所享有的特权或豁免权，也不会服从任何司法管辖权。