Version 1.0 Updates

Note

This release contains breaking changes. Please refer to the migration guide for a full description of what has changed and how to update your code.

Version 1.0.0

New features

Data object returned by from_source

from_source() now returns a lightweight data object instead of a format-specific fieldlist. The data object defers actual loading until it is converted to a concrete representation via one of the to_* methods (e.g. to_fieldlist(), to_xarray(), to_numpy()). The available conversions for a given source can be inspected via available_types.

See Migration guide for 1.0 for migration details.

Notebook examples:

• The object returned by from_source

Component-based Field metadata

Field has been redesigned around a set of format-independent, polymorphic components, each responsible for a distinct aspect of the field’s metadata:

• Parameter component — physical quantity, units, CF names; extended with chemical, optical, and wave-spectra sub-types.

• Time component — base datetime, forecast step, valid datetime.

• Vertical component — level value, level type, layer bounds, parametric (hybrid) level coefficients.

• Geography component — lat/lon arrays, bounding box, projection, grid type.

• Ensemble component — ensemble member identifier.

• Processing (proc) component — post-processing operations (e.g. accumulation type and time span).

Components are accessed via field attributes (e.g. field.time) or through the generic get() method using "component.key" strings. Raw source-native keys (e.g. GRIB shortName) remain accessible via metadata() or with the "metadata." prefix in get().

See the Field page for full details.

Notebook examples:

• Field overview

• Using GRIB data

• Xarray engine: chemical and optical dimensions

• Xarray engine: 2D wave spectra dimensions

Field modification via set()

Fields can now be modified in a non-destructive way using set(). The method accepts a dictionary of "component.key": value pairs (and/or a "values" entry) and returns a new field with the requested changes applied, leaving the original unchanged.

See the how-to notebooks:

• GRIB: modifying metadata

• GRIB: modifying values

Field and FieldList arithmetic

Element-wise arithmetic operators (+, -, *, /) are now supported directly on both Field and FieldList objects. Each operation returns a new object with the computed values; the metadata of the left-hand operand is preserved in the result.

Note

The + operator no longer concatenates fieldlists. Use concat() for concatenation instead.

Notebook examples:

• Field overview

• Field arithmetic

• Assigning a constant value

• Using GRIB data

Xarray engine

The Xarray engine has been refactored and a new default profile earthkit has been added. This profile uses the format-independent component metadata keys to build dataset dimensions and coordinates, making it consistent across GRIB, NetCDF, and other sources. The legacy mars and grib profiles are retained.

Other notable Xarray engine changes:

• Four new built-in dimensions were added to support the extended parameter component metadata (#1008):

  • chem_variable — chemical constituent or aerosol type

  • wavelength — central wavelength for optical parameters

  • wave_direction — wave propagation direction for 2-D wave spectra

  • wave_frequency — wave frequency for 2-D wave spectra

  CF-compliant attributes are set on the corresponding coordinate variables automatically.

• The "number" dimension role has been renamed to "member".

• The time_dim_mode kwarg has been replaced by time_dims.

• The _earthkit dataset attribute is now serialised as a JSON string, enabling round-trip NetCDF serialisation without removing it (#1021).

• Added the aux_coords keyword argument to specify 1- or multi-dimensional auxiliary coordinate variables whose values are derived from any metadata key (#969).

• Added the reference_field property to the Xarray earthkit accessor to allow getting the reference field of the dataarray. Also added the set method to allow setting the reference field of the dataarray using a Field or any args/kwargs accepted by set() (#990).

• Allowed using null values in datetime related objects (#999).

See Xarray engine: overview for full documentation.

Notebook examples:

• Xarray engine: overview

• Xarray engine: temporal dimensions

• Xarray engine: ensemble data

• Xarray engine: chemical and optical dimensions

• Xarray engine: 2D wave spectra dimensions

Dependencies

Geography support for GRIB data — including access to latitudes, longitudes, grid specification, and other grid properties via the GeographyBase component — requires the eccodes binaries built with eckit geo support. Without it, geography keys will return None or raise an error.