跳转到主要内容

使用ecCodes按照CF公约将GRIB文件映射到NetCDF公共数据模型的Python接口。

项目描述

cfgrib:使用ecCodes按照CF公约将GRIB文件映射到NetCDF公共数据模型的Python接口。

https://img.shields.io/pypi/v/cfgrib.svg

Python接口将GRIB文件映射到Unidata的公共数据模型v4,遵循CF公约。高级API旨在支持的GRIB引擎,并受到netCDF4-python和h5netcdf的启发。通过ECMWF ecCodes库和eccodes python包进行低级访问和解码。

开发状态为测试版的功能

  • 启用engine='cfgrib'选项以使用 xarray读取GRIB文件,

  • 使用cfgrib.open_datasets读取大多数GRIB 1和2文件,包括异构文件,

  • 支持Python 3.9、3.8、3.7和PyPy3的所有现代版本,

  • 0.9.6.x系列将继续支持Python 2并接收关键错误修复,

  • 在任何 eccodes-python运行的地方工作: Linux MacOS Windows

  • 所有支持平台上的conda-forge软件包,

  • 以内存使用和磁盘访问效率两方面,懒加载且高效地读取数据,

  • 通过 xarraydask 支持大于内存和分布式处理,

  • 支持将坐标转换为不同的数据模型和命名约定,

  • 支持将 GRIB 文件的索引写入磁盘,以在打开时节省完整文件扫描,

  • 接受实现通用 Fieldset 接口的对象,如 ADVANCED_USAGE.rst 中所述。

正在进行中

  • 测试版 安装一个 cfgrib 工具,可以将 GRIB 文件转换为 to_netcdf,可选转换为特定的坐标数据模型,请参阅 #40

  • 预览版/损坏 支持将精心制作的 xarray.Dataset 写入 GRIB1 或 GRIB2 文件,请参阅下面的 高级写入使用 部分,#18#156

限制

  • 依赖于 ecCodes 来获取数据变量的 CF 属性,

  • 依赖于 ecCodes 来处理与坐标系 / gridType 相关的所有内容,请参阅 #28

安装

安装 cfgrib 及其所有二进制依赖项的最简单方法是使用 Conda

$ conda install -c conda-forge cfgrib

另外,如果您自己安装二进制依赖项,可以使用以下命令从 PyPI 安装 Python 包

$ pip install cfgrib

二进制依赖项

cfgrib 依赖于 eccodes python 包 来访问 ECMWF 的 ecCodes 二进制库,当不使用 conda 时,请遵循该处的 系统依赖项 部分。

您可以通过运行简单的自检命令来确保您的系统已正确设置

$ python -m cfgrib selfcheck
Found: ecCodes v2.20.0.
Your system is ready.

使用

首先,您需要一个格式良好的 GRIB 文件,如果您没有,可以下载我们的 ERA5 压力水平样本

$ wget https://get.ecmwf.int/repository/test-data/cfgrib/era5-levels-members.grib

只读 xarray GRIB 引擎

大多数 cfgrib 用户希望将 GRIB 文件打开为 xarray.Dataset,并需要安装 xarray

$ pip install xarray

在 Python 解释器中尝试

>>> import xarray as xr
>>> ds = xr.open_dataset('era5-levels-members.grib', engine='cfgrib')
>>> ds
<xarray.Dataset>
Dimensions:        (number: 10, time: 4, isobaricInhPa: 2, latitude: 61,
                    longitude: 120)
Coordinates:
* number         (number) int64 0 1 2 3 4 5 6 7 8 9
* time           (time) datetime64[ns] 2017-01-01 ... 2017-01-02T12:00:00
    step           timedelta64[ns] ...
* isobaricInhPa  (isobaricInhPa) float64 850.0 500.0
* latitude       (latitude) float64 90.0 87.0 84.0 81.0 ... -84.0 -87.0 -90.0
* longitude      (longitude) float64 0.0 3.0 6.0 9.0 ... 351.0 354.0 357.0
    valid_time     (time) datetime64[ns] ...
Data variables:
    z              (number, time, isobaricInhPa, latitude, longitude) float32 ...
    t              (number, time, isobaricInhPa, latitude, longitude) float32 ...
Attributes:
    GRIB_edition:            1
    GRIB_centre:             ecmf
    GRIB_centreDescription:  European Centre for Medium-Range Weather Forecasts
    GRIB_subCentre:          0
    Conventions:             CF-1.7
    institution:             European Centre for Medium-Range Weather Forecasts
    history:                 ...

cfgrib 引擎支持 xarray 的所有只读功能,如

  • 使用 xarray.open_mfdataset 将多个 GRIB 文件的内容合并到单个数据集中,

  • 使用 dask 处理大于内存的数据集,

  • 使用 dask.distributed 进行分布式处理。

读取任意 GRIB 键

默认情况下,cfgrib 从 GRIB 文件中读取 ecCodes 识别的有限 keys 集合,并将它们作为具有 GRIB_ 前缀的 DatasetDataArray 属性公开。可以通过将 read_keys 字典键添加到 backend_kwargs 并提供所需 GRIB 键的列表,使 cfgrib 读取更多键到属性中。

>>> ds = xr.open_dataset('era5-levels-members.grib', engine='cfgrib',
...                      backend_kwargs={'read_keys': ['experimentVersionNumber']})
>>> ds.t.attrs['GRIB_experimentVersionNumber']
'0001'

转换为自定义数据模型

与 netCDF 不同,GRIB 数据格式不是自描述的,并且将映射到 Unidata Common Data Model 的详细信息由解码格式的软件组件任意设置。名称和单位等细节尤其重要,因为 xarray 的广播和选择规则取决于它们。 cf2cfm 是一个与 cfgrib 一起分发的坐标转换模块,它使将 CF 兼容的坐标(如 cfgrib 提供的)转换为具有设置的 out_nameunitsstored_direction 的用户定义自定义数据模型变得容易。

例如,要将配置为 cfgrib 风格的 xr.Dataset 转换为经典的 ECMWF 坐标命名约定,您可以

>>> import cf2cdm
>>> ds = xr.open_dataset('era5-levels-members.grib', engine='cfgrib')
>>> cf2cdm.translate_coords(ds, cf2cdm.ECMWF)
<xarray.Dataset>
Dimensions:     (number: 10, time: 4, level: 2, latitude: 61, longitude: 120)
Coordinates:
* number      (number) int64 0 1 2 3 4 5 6 7 8 9
* time        (time) datetime64[ns] 2017-01-01 ... 2017-01-02T12:00:00
    step        timedelta64[ns] ...
* level       (level) float64 850.0 500.0
* latitude    (latitude) float64 90.0 87.0 84.0 81.0 ... -84.0 -87.0 -90.0
* longitude   (longitude) float64 0.0 3.0 6.0 9.0 ... 348.0 351.0 354.0 357.0
    valid_time  (time) datetime64[ns] ...
Data variables:
    z           (number, time, level, latitude, longitude) float32 ...
    t           (number, time, level, latitude, longitude) float32 ...
Attributes:
    GRIB_edition:            1
    GRIB_centre:             ecmf
    GRIB_centreDescription:  European Centre for Medium-Range Weather Forecasts
    GRIB_subCentre:          0
    Conventions:             CF-1.7
    institution:             European Centre for Medium-Range Weather Forecasts
    history:                 ...

要将翻译到气候数据存储的通用数据模型,请使用

>>> import cf2cdm
>>> cf2cdm.translate_coords(ds, cf2cdm.CDS)
<xarray.Dataset>
Dimensions:                  (realization: 10, forecast_reference_time: 4,
                            plev: 2, lat: 61, lon: 120)
Coordinates:
* realization              (realization) int64 0 1 2 3 4 5 6 7 8 9
* forecast_reference_time  (forecast_reference_time) datetime64[ns] 2017-01...
    leadtime                 timedelta64[ns] ...
* plev                     (plev) float64 8.5e+04 5e+04
* lat                      (lat) float64 -90.0 -87.0 -84.0 ... 84.0 87.0 90.0
* lon                      (lon) float64 0.0 3.0 6.0 9.0 ... 351.0 354.0 357.0
    time                     (forecast_reference_time) datetime64[ns] ...
Data variables:
    z                        (realization, forecast_reference_time, plev, lat, lon) float32 ...
    t                        (realization, forecast_reference_time, plev, lat, lon) float32 ...
Attributes:
    GRIB_edition:            1
    GRIB_centre:             ecmf
    GRIB_centreDescription:  European Centre for Medium-Range Weather Forecasts
    GRIB_subCentre:          0
    Conventions:             CF-1.7
    institution:             European Centre for Medium-Range Weather Forecasts
    history:                 ...

过滤异构的 GRIB 文件

xr.open_dataset 只能在所有具有相同 shortName 的消息都可以表示为单个超立方体的情况下打开 GRIB 文件。例如,变量 t 不能同时具有 isobaricInhPahybrid typeOfLevel 类型,因为这会导致同一变量的多个超立方体。打开不符合规范的 GRIB 文件将失败,并显示 ValueError: multiple values for unique key... 错误信息,请参阅 #2

此外,如果不同的变量依赖于相同的坐标,例如 step,则坐标的值必须完全匹配。例如,如果变量 tz 共享相同的 step 坐标,它们必须都具有完全相同的步骤集合。打开不符合规范的 GRIB 文件将失败,并显示 ValueError: key present and new value is different... 错误信息,请参阅 #13

在大多数情况下,您可以通过在 backend_kwargs 中传递 filter_by_keys 键来处理包含异构消息的复杂 GRIB 文件,以选择哪些 GRIB 消息属于一个结构良好的超立方体集。

例如,要打开 美国国家气象服务复杂 GRIB2 文件,您可以

>>> xr.open_dataset('nam.t00z.awp21100.tm00.grib2', engine='cfgrib',
...     backend_kwargs={'filter_by_keys': {'typeOfLevel': 'surface'}})
<xarray.Dataset>
Dimensions:     (y: 65, x: 93)
Coordinates:
    time        datetime64[ns] ...
    step        timedelta64[ns] ...
    surface     float64 ...
    latitude    (y, x) float64 ...
    longitude   (y, x) float64 ...
    valid_time  datetime64[ns] ...
Dimensions without coordinates: y, x
Data variables:
    gust        (y, x) float32 ...
    sp          (y, x) float32 ...
    orog        (y, x) float32 ...
    tp          (y, x) float32 ...
    acpcp       (y, x) float32 ...
    csnow       (y, x) float32 ...
    cicep       (y, x) float32 ...
    cfrzr       (y, x) float32 ...
    crain       (y, x) float32 ...
    cape        (y, x) float32 ...
    cin         (y, x) float32 ...
    unknown     (y, x) float32 ...
Attributes:
    GRIB_edition:            2
    GRIB_centre:             kwbc
    GRIB_centreDescription:  US National Weather Service - NCEP...
    GRIB_subCentre:          0
    Conventions:             CF-1.7
    institution:             US National Weather Service - NCEP...
    history:                 ...
>>> xr.open_dataset('nam.t00z.awp21100.tm00.grib2', engine='cfgrib',
...     backend_kwargs={'filter_by_keys': {'typeOfLevel': 'heightAboveGround', 'level': 2}})
<xarray.Dataset>
Dimensions:            (y: 65, x: 93)
Coordinates:
    time               datetime64[ns] ...
    step               timedelta64[ns] ...
    heightAboveGround  float64 ...
    latitude           (y, x) float64 ...
    longitude          (y, x) float64 ...
    valid_time         datetime64[ns] ...
Dimensions without coordinates: y, x
Data variables:
    t2m                (y, x) float32 ...
    r2                 (y, x) float32 ...
Attributes:
    GRIB_edition:            2
    GRIB_centre:             kwbc
    GRIB_centreDescription:  US National Weather Service - NCEP...
    GRIB_subCentre:          0
    Conventions:             CF-1.7
    institution:             US National Weather Service - NCEP...
    history:                 ...

自动过滤

cfgrib 还提供了一个函数,可以自动选择适当的 filter_by_keys,并返回 GRIB 文件中所有有效的 xarray.Dataset 列表。

>>> import cfgrib
>>> cfgrib.open_datasets('nam.t00z.awp21100.tm00.grib2')
[<xarray.Dataset>
Dimensions:                (y: 65, x: 93)
Coordinates:
    time                   datetime64[ns] 2018-09-17
    step                   timedelta64[ns] 00:00:00
    atmosphereSingleLayer  float64 0.0
    latitude               (y, x) float64 ...
    longitude              (y, x) float64 ...
    valid_time             datetime64[ns] ...
Dimensions without coordinates: y, x
Data variables:
    pwat                   (y, x) float32 ...
Attributes:
    GRIB_edition:            2
    GRIB_centre:             kwbc
    GRIB_centreDescription:  US National Weather Service - NCEP...
    GRIB_subCentre:          0
    Conventions:             CF-1.7
    institution:             US National Weather Service - NCEP, <xarray.Dataset>
Dimensions:     (y: 65, x: 93)
Coordinates:
    time        datetime64[ns] 2018-09-17
    step        timedelta64[ns] 00:00:00
    cloudBase   float64 0.0
    latitude    (y, x) float64 12.19 12.39 12.58 12.77 ... 57.68 57.49 57.29
    longitude   (y, x) float64 226.5 227.2 227.9 228.7 ... 308.5 309.6 310.6
    valid_time  datetime64[ns] 2018-09-17
Dimensions without coordinates: y, x
Data variables:
    pres        (y, x) float32 ...
    gh          (y, x) float32 ...
Attributes:
    GRIB_edition:            2
    GRIB_centre:             kwbc
    GRIB_centreDescription:  US National Weather Service - NCEP...
    GRIB_subCentre:          0
    Conventions:             CF-1.7
    institution:             US National Weather Service - NCEP, <xarray.Dataset>
Dimensions:     (y: 65, x: 93)
Coordinates:
    time        datetime64[ns] 2018-09-17
    step        timedelta64[ns] 00:00:00
    cloudTop    float64 0.0
    latitude    (y, x) float64 12.19 12.39 12.58 12.77 ... 57.68 57.49 57.29
    longitude   (y, x) float64 226.5 227.2 227.9 228.7 ... 308.5 309.6 310.6
    valid_time  datetime64[ns] 2018-09-17
Dimensions without coordinates: y, x
Data variables:
    pres        (y, x) float32 ...
    t           (y, x) float32 ...
    gh          (y, x) float32 ...
Attributes:
    GRIB_edition:            2
    GRIB_centre:             kwbc
    GRIB_centreDescription:  US National Weather Service - NCEP...
    GRIB_subCentre:          0
    Conventions:             CF-1.7
    institution:             US National Weather Service - NCEP, <xarray.Dataset>
Dimensions:            (y: 65, x: 93)
Coordinates:
    time               datetime64[ns] 2018-09-17
    step               timedelta64[ns] 00:00:00
    heightAboveGround  float64 10.0
    latitude           (y, x) float64 ...
    longitude          (y, x) float64 ...
    valid_time         datetime64[ns] ...
Dimensions without coordinates: y, x
Data variables:
    u10                (y, x) float32 ...
    v10                (y, x) float32 ...
Attributes:
    GRIB_edition:            2
    GRIB_centre:             kwbc
    GRIB_centreDescription:  US National Weather Service - NCEP...
    GRIB_subCentre:          0
    Conventions:             CF-1.7
    institution:             US National Weather Service - NCEP, <xarray.Dataset>
Dimensions:            (y: 65, x: 93)
Coordinates:
    time               datetime64[ns] 2018-09-17
    step               timedelta64[ns] 00:00:00
    heightAboveGround  float64 2.0
    latitude           (y, x) float64 12.19 12.39 12.58 ... 57.68 57.49 57.29
    longitude          (y, x) float64 226.5 227.2 227.9 ... 308.5 309.6 310.6
    valid_time         datetime64[ns] 2018-09-17
Dimensions without coordinates: y, x
Data variables:
    t2m                (y, x) float32 ...
    r2                 (y, x) float32 ...
Attributes:
    GRIB_edition:            2
    GRIB_centre:             kwbc
    GRIB_centreDescription:  US National Weather Service - NCEP...
    GRIB_subCentre:          0
    Conventions:             CF-1.7
    institution:             US National Weather Service - NCEP, <xarray.Dataset>
Dimensions:                 (heightAboveGroundLayer: 2, y: 65, x: 93)
Coordinates:
    time                    datetime64[ns] 2018-09-17
    step                    timedelta64[ns] 00:00:00
* heightAboveGroundLayer  (heightAboveGroundLayer) float64 1e+03 3e+03
    latitude                (y, x) float64 ...
    longitude               (y, x) float64 ...
    valid_time              datetime64[ns] ...
Dimensions without coordinates: y, x
Data variables:
    hlcy                    (heightAboveGroundLayer, y, x) float32 ...
Attributes:
    GRIB_edition:            2
    GRIB_centre:             kwbc
    GRIB_centreDescription:  US National Weather Service - NCEP...
    GRIB_subCentre:          0
    Conventions:             CF-1.7
    institution:             US National Weather Service - NCEP, <xarray.Dataset>
Dimensions:        (isobaricInhPa: 19, y: 65, x: 93)
Coordinates:
    time           datetime64[ns] 2018-09-17
    step           timedelta64[ns] 00:00:00
* isobaricInhPa  (isobaricInhPa) float64 1e+03 950.0 900.0 ... 150.0 100.0
    latitude       (y, x) float64 12.19 12.39 12.58 12.77 ... 57.68 57.49 57.29
    longitude      (y, x) float64 226.5 227.2 227.9 228.7 ... 308.5 309.6 310.6
    valid_time     datetime64[ns] 2018-09-17
Dimensions without coordinates: y, x
Data variables:
    t              (isobaricInhPa, y, x) float32 ...
    u              (isobaricInhPa, y, x) float32 ...
    v              (isobaricInhPa, y, x) float32 ...
    w              (isobaricInhPa, y, x) float32 ...
    gh             (isobaricInhPa, y, x) float32 ...
    r              (isobaricInhPa, y, x) float32 ...
Attributes:
    GRIB_edition:            2
    GRIB_centre:             kwbc
    GRIB_centreDescription:  US National Weather Service - NCEP...
    GRIB_subCentre:          0
    Conventions:             CF-1.7
    institution:             US National Weather Service - NCEP, <xarray.Dataset>
Dimensions:        (isobaricInhPa: 5, y: 65, x: 93)
Coordinates:
    time           datetime64[ns] 2018-09-17
    step           timedelta64[ns] 00:00:00
* isobaricInhPa  (isobaricInhPa) float64 1e+03 850.0 700.0 500.0 250.0
    latitude       (y, x) float64 ...
    longitude      (y, x) float64 ...
    valid_time     datetime64[ns] ...
Dimensions without coordinates: y, x
Data variables:
    absv           (isobaricInhPa, y, x) float32 ...
Attributes:
    GRIB_edition:            2
    GRIB_centre:             kwbc
    GRIB_centreDescription:  US National Weather Service - NCEP...
    GRIB_subCentre:          0
    Conventions:             CF-1.7
    institution:             US National Weather Service - NCEP, <xarray.Dataset>
Dimensions:       (y: 65, x: 93)
Coordinates:
    time          datetime64[ns] 2018-09-17
    step          timedelta64[ns] 00:00:00
    isothermZero  float64 0.0
    latitude      (y, x) float64 12.19 12.39 12.58 12.77 ... 57.68 57.49 57.29
    longitude     (y, x) float64 226.5 227.2 227.9 228.7 ... 308.5 309.6 310.6
    valid_time    datetime64[ns] 2018-09-17
Dimensions without coordinates: y, x
Data variables:
    gh            (y, x) float32 ...
    r             (y, x) float32 ...
Attributes:
    GRIB_edition:            2
    GRIB_centre:             kwbc
    GRIB_centreDescription:  US National Weather Service - NCEP...
    GRIB_subCentre:          0
    Conventions:             CF-1.7
    institution:             US National Weather Service - NCEP, <xarray.Dataset>
Dimensions:     (y: 65, x: 93)
Coordinates:
    time        datetime64[ns] 2018-09-17
    step        timedelta64[ns] 00:00:00
    maxWind     float64 0.0
    latitude    (y, x) float64 12.19 12.39 12.58 12.77 ... 57.68 57.49 57.29
    longitude   (y, x) float64 226.5 227.2 227.9 228.7 ... 308.5 309.6 310.6
    valid_time  datetime64[ns] 2018-09-17
Dimensions without coordinates: y, x
Data variables:
    pres        (y, x) float32 ...
    u           (y, x) float32 ...
    v           (y, x) float32 ...
    gh          (y, x) float32 ...
Attributes:
    GRIB_edition:            2
    GRIB_centre:             kwbc
    GRIB_centreDescription:  US National Weather Service - NCEP...
    GRIB_subCentre:          0
    Conventions:             CF-1.7
    institution:             US National Weather Service - NCEP, <xarray.Dataset>
Dimensions:     (y: 65, x: 93)
Coordinates:
    time        datetime64[ns] 2018-09-17
    step        timedelta64[ns] 00:00:00
    meanSea     float64 0.0
    latitude    (y, x) float64 12.19 12.39 12.58 12.77 ... 57.68 57.49 57.29
    longitude   (y, x) float64 226.5 227.2 227.9 228.7 ... 308.5 309.6 310.6
    valid_time  datetime64[ns] 2018-09-17
Dimensions without coordinates: y, x
Data variables:
    prmsl       (y, x) float32 ...
    mslet       (y, x) float32 ...
Attributes:
    GRIB_edition:            2
    GRIB_centre:             kwbc
    GRIB_centreDescription:  US National Weather Service - NCEP...
    GRIB_subCentre:          0
    Conventions:             CF-1.7
    institution:             US National Weather Service - NCEP, <xarray.Dataset>
Dimensions:                  (pressureFromGroundLayer: 2, y: 65, x: 93)
Coordinates:
    time                     datetime64[ns] 2018-09-17
    step                     timedelta64[ns] 00:00:00
* pressureFromGroundLayer  (pressureFromGroundLayer) float64 9e+03 1.8e+04
    latitude                 (y, x) float64 12.19 12.39 12.58 ... 57.49 57.29
    longitude                (y, x) float64 226.5 227.2 227.9 ... 309.6 310.6
    valid_time               datetime64[ns] 2018-09-17
Dimensions without coordinates: y, x
Data variables:
    cape                     (pressureFromGroundLayer, y, x) float32 ...
    cin                      (pressureFromGroundLayer, y, x) float32 ...
Attributes:
    GRIB_edition:            2
    GRIB_centre:             kwbc
    GRIB_centreDescription:  US National Weather Service - NCEP...
    GRIB_subCentre:          0
    Conventions:             CF-1.7
    institution:             US National Weather Service - NCEP, <xarray.Dataset>
Dimensions:                  (pressureFromGroundLayer: 5, y: 65, x: 93)
Coordinates:
    time                     datetime64[ns] 2018-09-17
    step                     timedelta64[ns] 00:00:00
* pressureFromGroundLayer  (pressureFromGroundLayer) float64 3e+03 ... 1.5e+04
    latitude                 (y, x) float64 12.19 12.39 12.58 ... 57.49 57.29
    longitude                (y, x) float64 226.5 227.2 227.9 ... 309.6 310.6
    valid_time               datetime64[ns] 2018-09-17
Dimensions without coordinates: y, x
Data variables:
    t                        (pressureFromGroundLayer, y, x) float32 ...
    u                        (pressureFromGroundLayer, y, x) float32 ...
    v                        (pressureFromGroundLayer, y, x) float32 ...
    r                        (pressureFromGroundLayer, y, x) float32 ...
Attributes:
    GRIB_edition:            2
    GRIB_centre:             kwbc
    GRIB_centreDescription:  US National Weather Service - NCEP...
    GRIB_subCentre:          0
    Conventions:             CF-1.7
    institution:             US National Weather Service - NCEP, <xarray.Dataset>
Dimensions:                  (y: 65, x: 93)
Coordinates:
    time                     datetime64[ns] 2018-09-17
    step                     timedelta64[ns] 00:00:00
    pressureFromGroundLayer  float64 3e+03
    latitude                 (y, x) float64 ...
    longitude                (y, x) float64 ...
    valid_time               datetime64[ns] ...
Dimensions without coordinates: y, x
Data variables:
    pli                      (y, x) float32 ...
Attributes:
    GRIB_edition:            2
    GRIB_centre:             kwbc
    GRIB_centreDescription:  US National Weather Service - NCEP...
    GRIB_subCentre:          0
    Conventions:             CF-1.7
    institution:             US National Weather Service - NCEP, <xarray.Dataset>
Dimensions:                  (y: 65, x: 93)
Coordinates:
    time                     datetime64[ns] 2018-09-17
    step                     timedelta64[ns] 00:00:00
    pressureFromGroundLayer  float64 1.8e+04
    latitude                 (y, x) float64 ...
    longitude                (y, x) float64 ...
    valid_time               datetime64[ns] ...
Dimensions without coordinates: y, x
Data variables:
    4lftx                    (y, x) float32 ...
Attributes:
    GRIB_edition:            2
    GRIB_centre:             kwbc
    GRIB_centreDescription:  US National Weather Service - NCEP...
    GRIB_subCentre:          0
    Conventions:             CF-1.7
    institution:             US National Weather Service - NCEP, <xarray.Dataset>
Dimensions:     (y: 65, x: 93)
Coordinates:
    time        datetime64[ns] 2018-09-17
    step        timedelta64[ns] 00:00:00
    surface     float64 0.0
    latitude    (y, x) float64 12.19 12.39 12.58 12.77 ... 57.68 57.49 57.29
    longitude   (y, x) float64 226.5 227.2 227.9 228.7 ... 308.5 309.6 310.6
    valid_time  datetime64[ns] 2018-09-17
Dimensions without coordinates: y, x
Data variables:
    unknown     (y, x) float32 ...
    cape        (y, x) float32 ...
    sp          (y, x) float32 ...
    acpcp       (y, x) float32 ...
    cin         (y, x) float32 ...
    orog        (y, x) float32 ...
    tp          (y, x) float32 ...
    crain       (y, x) float32 ...
    cfrzr       (y, x) float32 ...
    cicep       (y, x) float32 ...
    csnow       (y, x) float32 ...
    gust        (y, x) float32 ...
Attributes:
    GRIB_edition:            2
    GRIB_centre:             kwbc
    GRIB_centreDescription:  US National Weather Service - NCEP...
    GRIB_subCentre:          0
    Conventions:             CF-1.7
    institution:             US National Weather Service - NCEP, <xarray.Dataset>
Dimensions:     (y: 65, x: 93)
Coordinates:
    time        datetime64[ns] 2018-09-17
    step        timedelta64[ns] 00:00:00
    tropopause  float64 0.0
    latitude    (y, x) float64 12.19 12.39 12.58 12.77 ... 57.68 57.49 57.29
    longitude   (y, x) float64 226.5 227.2 227.9 228.7 ... 308.5 309.6 310.6
    valid_time  datetime64[ns] 2018-09-17
Dimensions without coordinates: y, x
Data variables:
    t           (y, x) float32 ...
    u           (y, x) float32 ...
    v           (y, x) float32 ...
    trpp        (y, x) float32 ...
Attributes:
    GRIB_edition:            2
    GRIB_centre:             kwbc
    GRIB_centreDescription:  US National Weather Service - NCEP...
    GRIB_subCentre:          0
    Conventions:             CF-1.7
    institution:             US National Weather Service - NCEP]

高级用法

写入支持

请注意,写入支持处于 Alpha 版本。 目前只能保存 canonical 形式的 xarray.Dataset,即坐标名称与 cfgrib 坐标完全匹配的坐标

>>> from cfgrib.xarray_to_grib import to_grib
>>> ds = xr.open_dataset('era5-levels-members.grib', engine='cfgrib').sel(number=0)
>>> ds
<xarray.Dataset>
Dimensions:        (time: 4, isobaricInhPa: 2, latitude: 61, longitude: 120)
Coordinates:
    number         int64 0
* time           (time) datetime64[ns] 2017-01-01 ... 2017-01-02T12:00:00
    step           timedelta64[ns] ...
* isobaricInhPa  (isobaricInhPa) float64 850.0 500.0
* latitude       (latitude) float64 90.0 87.0 84.0 81.0 ... -84.0 -87.0 -90.0
* longitude      (longitude) float64 0.0 3.0 6.0 9.0 ... 351.0 354.0 357.0
    valid_time     (time) datetime64[ns] ...
Data variables:
    z              (time, isobaricInhPa, latitude, longitude) float32 ...
    t              (time, isobaricInhPa, latitude, longitude) float32 ...
Attributes:
    GRIB_edition:            1
    GRIB_centre:             ecmf
    GRIB_centreDescription:  European Centre for Medium-Range Weather Forecasts
    GRIB_subCentre:          0
    Conventions:             CF-1.7
    institution:             European Centre for Medium-Range Weather Forecasts
    history:                 ...
>>> to_grib(ds, 'out1.grib', grib_keys={'edition': 2})
>>> xr.open_dataset('out1.grib', engine='cfgrib')
<xarray.Dataset>
Dimensions:        (time: 4, isobaricInhPa: 2, latitude: 61, longitude: 120)
Coordinates:
    number         ...
* time           (time) datetime64[ns] 2017-01-01 ... 2017-01-02T12:00:00
    step           timedelta64[ns] ...
* isobaricInhPa  (isobaricInhPa) float64 850.0 500.0
* latitude       (latitude) float64 90.0 87.0 84.0 81.0 ... -84.0 -87.0 -90.0
* longitude      (longitude) float64 0.0 3.0 6.0 9.0 ... 351.0 354.0 357.0
    valid_time     (time) datetime64[ns] ...
Data variables:
    z              (time, isobaricInhPa, latitude, longitude) float32 ...
    t              (time, isobaricInhPa, latitude, longitude) float32 ...
Attributes:
    GRIB_edition:            2
    GRIB_centre:             ecmf
    GRIB_centreDescription:  European Centre for Medium-Range Weather Forecasts
    GRIB_subCentre:          0
    Conventions:             CF-1.7
    institution:             European Centre for Medium-Range Weather Forecasts
    history:                 ...

可以通过设置带有以 GRIB_ 为前缀的键的 attrs 变量来设置按变量设置的 GRIB 键,例如

>>> import numpy as np
>>> import xarray as xr
>>> ds2 = xr.DataArray(
...     np.zeros((5, 6)) + 300.,
...     coords=[
...         np.linspace(90., -90., 5),
...         np.linspace(0., 360., 6, endpoint=False),
...     ],
...     dims=['latitude', 'longitude'],
... ).to_dataset(name='skin_temperature')
>>> ds2.skin_temperature.attrs['GRIB_shortName'] = 'skt'
>>> to_grib(ds2, 'out2.grib')
>>> xr.open_dataset('out2.grib', engine='cfgrib')
<xarray.Dataset>
Dimensions:     (latitude: 5, longitude: 6)
Coordinates:
    time        datetime64[ns] ...
    step        timedelta64[ns] ...
    surface     float64 ...
* latitude    (latitude) float64 90.0 45.0 0.0 -45.0 -90.0
* longitude   (longitude) float64 0.0 60.0 120.0 180.0 240.0 300.0
    valid_time  datetime64[ns] ...
Data variables:
    skt         (latitude, longitude) float32 ...
Attributes:
    GRIB_edition:            2
    GRIB_centre:             consensus
    GRIB_centreDescription:  Consensus
    GRIB_subCentre:          0
    Conventions:             CF-1.7
    institution:             Consensus
    history:                 ...

数据集 / 变量 API

使用 xarray 不是强制的,您可以使用 Python 解释器中的高级 API 将 GRIB 文件的内容访问为超立方体

>>> ds = cfgrib.open_file('era5-levels-members.grib')
>>> ds.attributes['GRIB_edition']
1
>>> sorted(ds.dimensions.items())
[('isobaricInhPa', 2), ('latitude', 61), ('longitude', 120), ('number', 10), ('time', 4)]
>>> sorted(ds.variables)
['isobaricInhPa', 'latitude', 'longitude', 'number', 'step', 't', 'time', 'valid_time', 'z']
>>> var = ds.variables['t']
>>> var.dimensions
('number', 'time', 'isobaricInhPa', 'latitude', 'longitude')
>>> var.data[:, :, :, :, :].mean()
262.92133
>>> ds = cfgrib.open_file('era5-levels-members.grib')
>>> ds.attributes['GRIB_edition']
1
>>> sorted(ds.dimensions.items())
[('isobaricInhPa', 2), ('latitude', 61), ('longitude', 120), ('number', 10), ('time', 4)]
>>> sorted(ds.variables)
['isobaricInhPa', 'latitude', 'longitude', 'number', 'step', 't', 'time', 'valid_time', 'z']
>>> var = ds.variables['t']
>>> var.dimensions
('number', 'time', 'isobaricInhPa', 'latitude', 'longitude')
>>> var.data[:, :, :, :, :].mean()
262.92133

GRIB 索引文件

默认情况下,cfgrib 将 GRIB 文件的索引保存到磁盘,将 .idx 添加到 GRIB 文件名。索引文件是一个 实验性 且完全可选的功能,如果出现问题,您可以随意删除它们并再次尝试。可以通过将 indexpath='' 添加到 backend_kwargs 关键字参数来禁用索引文件的保存。

地理坐标缓存

默认情况下,当打开数据集时,cfgrib 将为 GRIB 文件中的每个记录缓存计算出的地理坐标,这可以显著加快数据集创建的速度。理论上,在长时间运行的应用程序中,如果读取许多不同的网格类型,此缓存可能会无限制地增长。如果需要,可以通过将 backend_kwargs=dict(cache_geo_coords=False) 传递给 xarray.open_dataset()cfgrib.open_dataset()cfgrib.open_datasets() 来禁用缓存。

项目资源

开发

https://github.com/ecmwf/cfgrib

下载

https://pypi.ac.cn/project/cfgrib

用户支持

https://stackoverflow.com/search?q=cfgrib

代码质量

Coverage status on Codecov

贡献

主仓库托管在GitHub上,欢迎测试、提交错误报告和贡献。

https://github.com/ecmwf/cfgrib

请参阅CONTRIBUTING.rst文档,了解最佳帮助方式。

主要开发者

主要贡献者

还可以查看参与此项目的贡献者列表

许可协议

版权所有 2017-2021 欧洲中期天气预报中心(ECMWF)。

本文件遵循Apache License,版本2.0(“许可证”);除非遵守许可证,否则不得使用此文件。您可以在以下位置获得许可证副本:[https://apache.ac.cn/licenses/LICENSE-2.0](https://apache.ac.cn/licenses/LICENSE-2.0)。除非适用法律要求或书面同意,否则在许可证下分发的软件按“原样”基础分发,不提供任何形式的明示或暗示保证。有关许可证的具体语言、权限和限制,请参阅许可证。

cfgrib的变更日志

0.9.14.1 (2024-09-12)

  • 修复了与xarray 2024.09.0的兼容性。见#401

0.9.14.0 (2024-07-19)

  • 为open_dataset()添加了coords_as_attributes参数,允许选定的维度存储为属性而不是维度,从而允许将更多异构数据编码为xarray数据集。见#394

  • 如果提供了monthlyVerificationDate和validityTime,则添加了valid_month维度。见#393

  • 将uvRelativeToGrid添加到默认读取的GRIB键列表中。见#379

0.9.13.0 (2024-06-27)

  • 允许用户传递一个值列表来通过键进行过滤。见#384

  • 读取GRIB文件时忽略键的功能。见#382

  • 在cfgrib.open_datasets中保留坐标编码。见#381

0.9.12.0 (2024-05-26)

  • 修复了GRIB消息中非每小时步长无法读取的问题。见#370

0.9.11.0 (2024-04-05)

  • 添加了对地理坐标的自动缓存以提高性能。见#341

  • 修复了当给定的数据集具有单值维度时,to_grib()可能崩溃的问题。见#347

  • 修复了当alternativeRowScanning=1且网格不是2D表示时无法提取值的问题。见#358

  • 修复了无法正确处理grib_errors参数的问题。此参数现已更名为errors。见#349

  • 停止支持Python 3.6。见#363

0.9.10.4 (2023-05-19)

  • 将to_netcdf工具添加了–var-encoding-json(或-v)选项,例如:cfgrib to_netcdf -v '{"dtype": "float", "scale_factor": 0.1}' -o $OUTFILE $INFILE。见#334

  • 修复了从高斯网格派生的xarrays在作为GRIB写回时没有正确几何形状的问题。见#330

  • 修复了open_datasets()可能合并具有相同数据值的不同的GRIB字段的问题。见#336

0.9.10.3 (2022-11-24)

  • 大幅减少内存泄漏。见#320

  • 将distutils.version替换为packaging.version,并添加了xarray插件的描述和url。见#318

0.9.10.2 (2022-10-04)

  • 添加了‘cfgrib to_netcdf’的–netcdf_kwargs_json选项。详见:#294

  • 修复了对GRIB文件中alternativeRowScanning=1的支持。详见:#296

  • 修复了对缺失值的支持。详见:#313

0.9.10.1 (2022-03-16)

  • 修复了读取索引文件失败的问题。详见:#292

  • 允许在to_netcdf可执行文件中提供后端kwargs,可以通过json格式字符串或通过-b参数提供json文件的路径。详见:#288

  • 修复了使用relpath()可能导致的Windows上的问题。详见:#284

  • 修复了传递pathlib.Path的问题。详见:#282

  • 修复了将集合号写入GRIB文件时产生的错误。详见:#278

0.9.10.0 (2022-01-31)

  • 进行了重大内部重构,以添加类似于Metview的通用Fieldset支持。详见:#243

0.9.9.1 (2021-09-29)

  • 修复了插件接口中缺少extra_coords的问题。详见:#231

  • 修复了当extra_coords返回标量时的崩溃问题。详见:#238

  • 改进了类型提示。这是由#243所必需的。

0.9.9.0 (2021-04-09)

  • 依赖于ECMWF的eccodes python包来访问低级别的ecCodes C库,放弃所有其他GRIB解码选项。详见:#95#14#204#147#141

  • 在生成索引和访问数据期间进行了许多性能改进。详见:#142#197

  • filter_by_keys现在可以在不显式将非默认键添加到read_keys的情况下,选择所有已知于ecCodes的键。详见:#187

  • 使用xarray 0.18+的新后端API支持engine="cfgrib"。详见:#216

  • 修复了无法加载只有一个网格点的GRIB消息的问题。详见:#199

  • 在所有情况下将level坐标解码为浮点数,修复了非整数级别的问题。详见:#195

0.9.8.5 (2020-11-11)

  • 在发生错误时提供更简单、更清晰的提示信息。

  • 如果存在,使用环境变量ECCODES_DIR。由xavierabellan从eccodes-python移植。详见:#162

  • 当设置CFGRIB_USE_EXTERNAL_ECCODES_BINDINGS=1时,修复使用当前的ecCodes绑定。

0.9.8.4 (2020-08-03)

  • 如果存在,使用ecmwflibs来查找ecCodes的安装。

0.9.8.3 (2020-06-25)

  • 添加了对indexingDateindexingTime时间坐标的支持。

  • lambert_azimuthal_equal_area网格现在作为二维数组返回。详见:#119

0.9.8.2 (2020-05-22)

  • 添加了对在GRIB产品中使用以存储风(例如GFS,NAM等)的uv组件的MULTI-FIELD消息的支持。这是在cfgrib中最常报告的单一错误,已经尝试了两次修复,现在让我们看看第三次是否成功。请进行测试!详见:#45#76#111

0.9.8.1 (2020-03-13)

  • 始终以二进制模式打开GRIB文件,由@b8raoult完成。

0.9.8.0 (2020-03-12)

  • 添加了对实验性的pyeccodes低级驱动程序的支持,由@b8raoult完成。

0.9.7.7 (2020-01-24)

  • cf2cdm.translate_coords中添加了对forecastMonth的支持。

0.9.7.6 (2019-12-05)

  • 修复了README。

0.9.7.5 (2019-12-05)

  • 弃用 ensure_valid_time 和配置选项 preferred_time_dimension,现在它们可以通过 time_dims 更好地处理。

0.9.7.4 (2019-11-22)

  • time_dims 添加更多选项,预报产品可以表示为 ('time', 'verifying_time')('time', 'forecastMonth')。参见: #97

0.9.7.3 (2019-11-04)

  • 通过 time_dims 支持选择作为维度的时坐标。预报产品可以表示为 ('time', 'step')(默认值)、('time', 'valid_time')('valid_time', 'step')。参见: #97

  • 减少 FieldIndex 的内存占用和 .idx 文件的大小。

0.9.7.2 (2019-09-24)

  • 通过 read_keys 支持从 GRIB 文件中读取额外的键,它们出现在变量 attrs 中,并且可以对它们进行 filter_by_keys 过滤。这是针对所有用户已知他们感兴趣的额外键名称的问题的通用解决方案。参见: #89#101

0.9.7.1 (2019-07-08)

  • 修复了在 Windows 上尝试写入 GRIB 时字节代替字符串的错误。参见: #91

  • open_datasets 中尊重 indexpath 设置,参见: #93

0.9.7 (2019-05-27)

  • 大幅改进了 cfgrib.open_datasets 的启发式算法,现在可以读取更多异构的 GRIB 文件。该函数现在是受支持的 API。参见: #63#66#73#75

  • 修复了对仅包含 Python 2 的包的 conda 依赖项,参见: #78

0.9.7rc1(2019-05-14)

  • 停止支持 Python 2,与 xarray 0.12.0 保持一致。0.9.6.x 系列将长期支持 Python 2 用户。参见: #69

  • 将内部 ecCodes 绑定 API 与 eccodes-python 中的 API 同步。参见: #81

  • 使用 black -S -l 99 格式化源代码。

  • 添加了对光谱坐标的初始支持。

0.9.6.2 (2019-04-15)

  • 改进了将变量合并到数据集中的过程。参见: #63

0.9.6.1.post1(2019-03-17)

  • 修复了 README 格式中的问题。

0.9.6.1 (2019-03-17)

  • 修复了真正的 MULTI-FIELD 消息问题,参见: #45

  • 在索引文件中添加了协议版本。必须删除旧的 *.idx 文件。

0.9.6.post1(2019-03-07)

  • 修复了 README 中的重要拼写错误。参见: #64

0.9.6 (2019-02-26)

  • 通过安装 ecCodes 通过 conda 来支持 Windows。参见: #7

  • 添加了 conda-forge 软件包。参见: #5

0.9.5.7 (2019-02-24)

  • 修复了在计算非立方 GRIB 文件的 filter_by_keys 时出现的严重错误。结果,cfgrib.xarray_store.open_datasets 未找到文件中的所有变量。参见: #54

  • 修复了可能导致变量值丢失或混淆的变量命名严重错误。再次参见: #54

  • 重新打开 #45,因为修复返回了错误的数据。现在我们回到除了第一个变量以外的所有变量在 MULTI-FIELD 中被删除。

0.9.5.6 (2019-02-04)

  • units 中不要设置显式的时区,以避免某些版本的 xarray 崩溃。参见: #44

0.9.5.5 (2019-02-02)

  • 默认启用ecCodes隐式MULTI-FIELD支持,这是NCEP NAM产品所需的。参见:#45

  • 添加了对depthBelowLand坐标的支持。

0.9.5.4 (2019-01-25)

  • 添加了对从坏的时间步长超立方体构建valid_time的支持。

0.9.5.3 (2019-01-25)

  • 同时将valid_time转换为可以在translate_coords中索引所有时间和步骤。

0.9.5.2 (2019-01-24)

  • valid_time设置为CDS数据模型的推荐时间维度。

  • 当没有更好的选项时,回退到使用通用的GRIB2 ecCodes模板。参见:#39

0.9.5.1 (2018-12-27)

  • 修复了在具有非维度坐标的数据集上使用cf2cdm.translate_coords时的崩溃问题。参见:#41

  • 添加了一个可以将GRIB转换为netCDF的cfgrib脚本。参见:#40

0.9.5 (2018-12-20)

  • 为了降低复杂性,放弃对xarray版本低于v0.11的支持。(这实际上只有v0.10.9)。参见:#32

  • 通过Conventions全局属性将数据声明为符合CF-1.7。参见:#36

  • 通过daskdask.distributed测试了大于内存和分布式处理。参见:#33

  • 通过cfgrib.to_grib提升写入支持到Alpha。参见:#18

  • 提供cf2cdm.translate_coords实用函数,用于在CF兼容数据模型之间转换坐标,由out_nameunitsstore_direction定义。参见:#24

  • 提供cfgrib.__version__。参见:#31

  • 当用户尝试打开不是GRIB的文件时,给出更好的错误信息。参见:#34

  • rotated_llrotated_gggridType创建二维网格。参见:#35

0.9.4.1 (2018-11-08)

  • 修复了PyPI页面的格式。

0.9.4 (2018-11-08)

  • 以更稳健的方式为每套index_keys保存一个索引文件。

  • 重构CF编码,并在backend_kwargs中添加了新的encode_cf选项。参见:#23

  • 重构错误处理和忽略错误(尚未很好地记录)的选项。参见:#13

  • ecCodes未完全支持安装的gridType时,不会崩溃。参见:#27

  • 一些小的错误修复和性能改进。

0.9.3.1 (2018-10-28)

  • 各种README修复,特别是推广索引文件支持为Alpha。

0.9.3 (2018-10-28)

  • 大幅性能改进:添加Alpha支持以保存到磁盘和从磁盘读取由首次打开时的完整文件扫描产生的GRIB索引。参见:#20

0.9.2 (2018-10-22)

  • 将坐标名air_pressure重命名为isobaricInhPa,以与所有其他垂直level坐标保持一致性。参见:#25

0.9.1.post1 (2018-10-19)

  • 修复PyPI描述。

0.9.1 (2018-10-19)

  • cfgrib.open_dataset 的使用方式改为与 xarray.open_dataset 保持一致,特别是必须将 filter_by_key 添加到 backend_kwargs 字典中。请参阅:[链接](https://github.com/ecmwf/cfgrib/issues/21)。

0.9.0 (2018-10-14)

  • 带有读取支持的Beta版本。

项目详情


发布历史 发布通知 | RSS源

下载文件

下载适用于您的平台文件。如果您不确定要选择哪个,请了解有关安装包的更多信息。

源分布

cfgrib-0.9.14.1.tar.gz (6.5 MB 查看哈希值)

上传时间:

构建分布

cfgrib-0.9.14.1-py3-none-any.whl (48.7 kB 查看哈希值)

上传时间: Python 3

由以下支持

AWS AWS 云计算和安全赞助商 Datadog Datadog 监控 Fastly Fastly CDN Google Google 下载分析 Microsoft Microsoft PSF 赞助商 Pingdom Pingdom 监控 Sentry Sentry 错误记录 StatusPage StatusPage 状态页面