Field

A Field represents a single horizontal slice of a geophysical quantity at a particular time and vertical level. It is the fundamental data structure in EarthKit Data and bundles together:

  • the data values — a 2-D (or 1-D unstructured) array of floating-point numbers;

  • a set of metadata components that fully describe the field (see below).

Fields are created automatically when reading data through from_source() and are normally accessed as members of a FieldList. See fieldlist for how to work with collections of fields.

Component-based metadata

The Field class is not polymorphic. Instead it is composed of a set of replaceable, polymorphic components, each responsible for a distinct aspect of the metadata:

Attribute

Component class

What it describes

field.parameter

ParameterBase

Physical quantity: variable name, units, CF names, chemical or optical properties.

field.time

TimeBase

Temporal coordinate: base datetime, forecast step, valid datetime.

field.vertical

VerticalBase

Vertical coordinate: level value, level type, layer bounds.

field.geography

GeographyBase

Horizontal grid: lat/lon arrays, bounding box, projection, grid type.

field.ensemble

EnsembleBase

Ensemble member identifier.

field.proc

ProcBase

Post-processing operations applied to produce the field (e.g. accumulation).

Each component exposes its metadata through named methods (e.g. field.vertical.level()) and through the generic get() method using a "component.key" prefix:

>>> import earthkit.data as ekd
>>> field = ekd.from_source("sample", "test.grib").to_fieldlist()[0]
>>> field.parameter.variable()
'2t'
>>> field.get("parameter.variable")
'2t'
>>> field.vertical.level()
0
>>> field.get("time.base_datetime")
datetime.datetime(2020, 1, 1, 0, 0)

For a full description of each component’s available keys see the dedicated pages: Parameter component, Time component, Vertical component, Geography component, Ensemble component, and Processing (proc) component.

Immutability of field values

Field values are immutable: values() always returns a copy of the underlying array. Modifications to that copy do not affect the stored data. This guarantees that the original data remains consistent no matter how many downstream operations consume it.

Modifying a field

Because both values and metadata are immutable, changes are expressed by creating a new field via 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 while leaving all other attributes unchanged:

>>> new_field = field.set({"vertical.level": 500, "time.step": 6})
>>> new_field.vertical.level()
500
>>> new_field.time.step()
datetime.timedelta(seconds=21600)

Arithmetic operations

Fields support element-wise arithmetic directly (+, -, *, /). Each operation returns a new field whose data is the result of the operation. The metadata (parameter, time, vertical, geography, ensemble, proc) of the left-hand operand is retained in the result without modification:

>>> fl = ekd.from_source("sample", "tuv_pl.grib").to_fieldlist()
>>> result = fl[0] + fl[1]
>>> result.parameter.variable() == fl[0].parameter.variable()
True

How-tos