Deprecations¶

Version 0.15.0¶

The “ens” dimension role has been renamed to “number”¶

The name of the ensemble member dimension role changed to “number” from “ens” in the dim_roles option of to_xarray(). The old name is still available for backward compatibility but will be removed in a future release.

Deprecated code

import earthkit.data as ekd

ds_fl = ekd.from_source("sample", "ens_cf_pf.grib")

ds = ds_fl.to_xarray(
    dim_roles={"ens": "perturbationNumber"},
)

New code

import earthkit.data as ekd

ds_fl = ekd.from_source("sample", "ens_cf_pf.grib")

ds = ds_fl.to_xarray(
    dim_roles={"number": "perturbationNumber"},
)

The “to_grib” method on the earthkit Xarray accessor is deprecated¶

The to_grib() method on the earthkit Xarray accessor is deprecated. Use to_target() instead. The method is still available for backward compatibility but will be removed in a future release. See Xarray engine: writing back to GRIB notebook for details on how to use the new API.

Deprecated code

import earthkit.data as ekd

ds = ekd.from_source("sample", "test.grib")

ds_xr = ds.to_xarray()

ds_xr.earthkit.to_grib("_res_xarray_to_grib_1.grib")

New code

import earthkit.data as ekd

ds = ekd.from_source("sample", "test.grib")

ds_xr = ds.to_xarray()

# option1: writing to GRIB file using the accessor
ds_xr.earthkit.to_target("file", "_res_xarray_to_grib_2.grib")

# option2: writing to GRIB file using the top level function
ekd.to_target("file", "_res_xarray_to_grib_2a.grib", data=ds_xr)

Version 0.13.0¶

The “settings” has been renamed to config ¶

The API did not change with the exception of settings.auto_save_settings, which now is config.autosave. The “settings” object is still available for backward compatibility but will be removed in a future release. Users are encouraged to migrate the code to use config instead.

Deprecated code

from earthkit.data import settings

v = settings.get("number-of-download-threads")

settings.auto_save_settings = False

New code

from earthkit.data import config

v = config.get("number-of-download-threads")

config.autosave = False

`settings.auto_save_settings` is now `config.autosave`¶

See details here.

Data object `save()` is deprecated¶

This functionality is replaced by the targets.

Deprecated code

import earthkit.data as ekd

ds = ekd.from_source("sample", "test.grib")

# case 1
ds.save("res.grib")

# case 2
ds.save("res.grib", append=True)

# case 3
ds.save("res.grib", bits_per_value=12)

# case 4
for field in ds:
    field.save("res1.grib", append=True, bits_per_value=12)

New code

import earthkit.data as ekd

ds = ekd.from_source("sample", "test.grib")

# case 1
ds.to_target("file", "res.grib")

# case 2
ds.to_target("file", "res.grib", append=True)

# case 3
ds.to_target("file", "res.grib", metadata={"bitsPerValue": 12})

# case 4 - equivalent solutions
with ekd.create_target("file", "res1.grib") as t:
    for field in ds:
        t.write(field, metadata={"bitsPerValue": 12})

with ekd.create_target("file", "res1.grib", metadata={"bitsPerValue": 12}) as t:
    for field in ds:
        t.write(field)

with ekd.create_target("file", "res1.grib") as t:
    for field in ds:
        t.write(field, bitsPerValue=12)

Data object `write()` is deprecated¶

This functionality is now replaced by the targets.

Deprecated code

import earthkit.data as ekd

ds = ekd.from_source("sample", "test.grib")

# case 1
with open("res.grib", "wb") as f:
    ds.write(f)

# case 2
with open("res.grib", "wb") as f:
    for field in ds:
        field.write(f)

New code

import earthkit.data as ekd

ds = ekd.from_source("sample", "test.grib")

# case 1 - equivalent solutions
with open("res.grib", "wb") as f:
    ds.to_target("file", f)

with open("res.grib", "wb") as f:
    t = ekd.create_target("file", f)
    t.write(ds)

# case 2 - equivalent solutions
with open("res.grib", "wb") as f:
    for field in ds:
        field.to_target("file", f)

with open("res.grib", "wb") as f:
    t = ekd.create_target("file", f)
    for field in ds:
        t.write(field)

`new_grib_output()` is deprecated¶

new_grib_output() returns a new GribOutput object. Its functionality is replaced by the targets.

Warning

When using new_grib_output(), if the specified metadata does not contain the generatingProcessIdentifier key it is automatically set to 255 for the saved GRIB message. The new API does not have this behavior.

Deprecated code

import earthkit.data as ekd

ds = ekd.from_source("sample", "test.grib")

# case 1
o = ekd.new_grib_output("res.grib", shortName="2t")
for field in ds:
    o.write(None, template=field)
o.close()

# case 2
o = ekd.new_grib_output("res.grib")
for field in ds:
    o.write(None, shortName="2t", template=field)
o.close()

# case 3
with ekd.new_grib_output("res.grib") as o:
    for field in ds:
        o.write(None, shortName="2t", template=field)

# case 4
with ekd.new_grib_output("res.grib") as o:
    for field in ds:
        values = field.values + 1
        o.write(values, shortName="2t", template=field)

New code

import earthkit.data as ekd

ds = ekd.from_source("sample", "test.grib")

# case 1
t = ekd.create_target(
    "file",
    "res.grib",
    metadata={"shortName": "2t", "generatingProcessIdentifier": 255},
)
for field in ds:
    t.write(field)

t.close()

# case 2 - equivalent solutions
t = ekd.create_target("file", "res.grib")
for field in ds:
    t.write(data=field, shortName="2t", generatingProcessIdentifier=255)
t.close()

t = ekd.create_target("file", "res.grib")
for field in ds:
    t.write(shortName="2t", template=field, generatingProcessIdentifier=255)
t.close()

# case 3
with ekd.create_target("file", "res.grib") as t:
    for field in ds:
        t.write(field, shortName="2t", generatingProcessIdentifier=255)

# case 4
with ekd.create_target("file", "res.grib") as t:
    for field in ds:
        values = field.values + 1
        t.write(data=field, values=values, shortName="2t")

The split_output=True option of new_grib_output() is not supported by the file target but implemented by the file-pattern target.

Deprecated code

import earthkit.data as ekd

ds = ekd.from_source("sample", "test.grib")

# case 1
o = ekd.new_grib_output("res_{shortName}.grib", split_output=True)
for field in ds:
    o.write(None, template=field)
o.close()

New code

import earthkit.data as ekd

ds = ekd.from_source("sample", "test.grib")

# case 1 - equivalent solutions
t = ekd.create_target("file-pattern", "res_{shortName}.grib")
for field in ds:
    t.write(field)

t.close()

ds.to_target("file-pattern", "res_{shortName}.grib")

Warning

When using new_grib_output() the {param} pattern substitutes the value of the "param" ecCodes key from the GRIB header. However, with the targets the {param} pattern substitutes the value of the "shortName" key. This is to match the behaviour of Field.metadata("param"), which always returns the value of the "shortName". If you still want to use the value of the "param" ecCodes key you need to use the {mars.param} pattern instead.

# Deprecated code
new_grib_output("file", "output_{param}.grib", split_output=True)
...

# New code
to_target("file-pattern", "output_{mars.param}.grib")

`GribOutput` is deprecated¶

Its functionality is replaced by the targets instead. For details see migrating new_grib_output().

`new_grib_coder()` is deprecated¶

new_grib_coder() returns a new GribCoder object. Its functionality is replaced by the targets.

Warning

When using new_grib_coder(), if the specified metadata does not contain the generatingProcessIdentifier key it is automatically set to 255 in the generated GRIB message. The new API does not have this behavior.

Deprecated code

from earthkit.data.readers.grib.output import new_grib_coder

import earthkit.data as ekd

ds = ekd.from_source("sample", "test.grib")

values = ds[1].values + 1

# case 1
c = new_grib_coder()
# c is a GribCodesHandle
d = c.encode(values, shortName="2t", template=ds[1])

# case 2
c = new_grib_coder(template=ds[1])
# c is a GribCodesHandle
d = c.encode(values, shortName="2t")

New code

import earthkit.data as ekd

ds = ekd.from_source("sample", "test.grib")

values = ds[1].values + 1

# case 1 - equivalent solutions
c = ekd.create_encoder("grib")
d = c.encode(
    values=values,
    template=ds[1],
    shortName="2t",
    generatingProcessIdentifier=255,
)
# d is a GribEncodedData

c = ekd.create_encoder("grib")
d = c.encode(ds[1], values=values, shortName="2t", generatingProcessIdentifier=255)

# case 2
c = ekd.create_encoder("grib", template=ds[1], generatingProcessIdentifier=255)
d = c.encode(
    values=values,
    shortName="2t",
)

`GribCoder` is deprecated¶

Its functionality is replaced by the encoders. For details see migrating new_grib_coder().

Version 0.19.0¶

The `array_backend` kwarg is deprecated¶

The array_backend kwarg is now deprecated and array_namespace should be used instead. This affects the following methods: Field.to_array(), Field.copy(), Field.clone(), FieldList.to_array(), FieldList.to_fieldlist(), to_xarray(). The old kwarg is still available for backward compatibility but will be removed in a future release.

Deprecated code

import earthkit.data as ekd

ds_fl = ekd.from_source("sample", "test.grib")

vals1 = ds_fl.to_array(array_backend="torch")
vals2 = ds_fl[0].to_array(array_backend="torch")

New code

import earthkit.data as ekd

ds_fl = ekd.from_source("sample", "test.grib")

vals1 = ds_fl.to_array(array_namespace="torch")
vals2 = ds_fl[0].to_array(array_namespace="torch")

The `Field.array_backend` attribute is deprecated¶

The Field.array_backend attribute is now deprecated and Field.array_namespace should be used instead. The old attribute is still available for backward compatibility but will be removed in a future release.

Deprecated code

import earthkit.data as ekd

ds_fl = ekd.from_source("sample", "test.grib")

b = ds_fl[0].array_backend

New code

import earthkit.data as ekd

ds_fl = ekd.from_source("sample", "test.grib")

b = ds_fl[0].array_namespace

Deprecations¶

Version 0.15.0¶

The “ens” dimension role has been renamed to “number”¶

The “to_grib” method on the earthkit Xarray accessor is deprecated¶

Version 0.13.0¶

The “settings” has been renamed to config¶

settings.auto_save_settings is now config.autosave¶

Data object save() is deprecated¶

Data object write() is deprecated¶

new_grib_output() is deprecated¶

GribOutput is deprecated¶

new_grib_coder() is deprecated¶

GribCoder is deprecated¶

Version 0.19.0¶

The array_backend kwarg is deprecated¶

The Field.array_backend attribute is deprecated¶

The “settings” has been renamed to config ¶

`settings.auto_save_settings` is now `config.autosave`¶

Data object `save()` is deprecated¶

Data object `write()` is deprecated¶

`new_grib_output()` is deprecated¶

`GribOutput` is deprecated¶

`new_grib_coder()` is deprecated¶

`GribCoder` is deprecated¶

The `array_backend` kwarg is deprecated¶

The `Field.array_backend` attribute is deprecated¶