earthkit.data.field.component.parameter¶

Classes¶

`EmptyParameter`	Empty parameter component, representing the absence of parameter information.
`Parameter`	Parameter component representing parameter information.
`ParameterBase`	Base class for the parameter component of a field.

Functions¶

create_parameter(d)

Create a ParameterBase object from a dictionary.

Module Contents¶

class earthkit.data.field.component.parameter.EmptyParameter¶

Bases: ParameterBase

Empty parameter component, representing the absence of parameter information.

aliases()¶: Return the aliases in the component.

chem_variable()¶

Return the parameter chemical variable.

An EmptyParameter does not contain any parameter information, and this method returns None.

classmethod from_dict(d)¶: Create an EmptyParameter object from a dictionary.

get(key, default=None, *, astype=None, raise_on_missing=False)¶

Return the value for the specified key.

Parameters:

key (str) – The key to retrieve.
default (Any, optional) – The default value to return if the key is not found. Default is None.
astype (type, optional) – The type to which the value should be cast. Default is None.
raise_on_missing (bool, optional) – If True, raise a KeyError if the key is not found. Default is False.

Returns:

The value for the specified key.

Return type:

Any

Raises:

KeyError – If raise_on_missing is True and the key is not found.

keys()¶: Return the available keys in the component.

long_name()¶

Return the long name of the parameter variable.

An EmptyParameter does not contain any parameter information, and this method returns None.

param()¶

set(*args, **kwargs)¶

Create a new instance with updated data.

An EmptyParameter object cannot be updated, and this method raises a ValueError.

standard_name()¶

Return the standard name of the parameter variable.

An EmptyParameter does not contain any parameter information, and this method returns None.

to_dict()¶: Return a dictionary representation of the EmptyParameter.

units()¶

Return the parameter units.

An EmptyParameter does not contain any parameter information, and this method returns None.

variable()¶

Return the parameter variable.

An EmptyParameter does not contain any parameter information, and this method returns None.

class earthkit.data.field.component.parameter.Parameter(variable=None, standard_name=None, long_name=None, units=None, chem_variable=None)¶

Bases: ParameterBase

Parameter component representing parameter information.

Parameters:

variable (str, optional) – The parameter variable, by default None.
units (str or Units, optional) – The parameter units, by default None. Can be provided as a string or a Units object.
chem_variable (str, optional) – The parameter chemical variable, by default None.

aliases()¶: Return the aliases in the component.

chem_variable()¶: Return the parameter chemical variable.

classmethod from_dict(d)¶

Create a Parameter object from a dictionary.

Parameters:

d (dict) –

Dictionary containing parameter data.

The dictionary can contain the following keys:

”variable”: The parameter variable.
”units”: The parameter units, as a string or a Units object.

Returns:

The created Parameter instance.

Return type:

Parameter

get(key, default=None, *, astype=None, raise_on_missing=False)¶

Return the value for the specified key.

Parameters:

key (str) – The key to retrieve.
default (Any, optional) – The default value to return if the key is not found. Default is None.
astype (type, optional) – The type to which the value should be cast. Default is None.
raise_on_missing (bool, optional) – If True, raise a KeyError if the key is not found. Default is False.

Returns:

The value for the specified key.

Return type:

Any

Raises:

KeyError – If raise_on_missing is True and the key is not found.

keys()¶: Return the available keys in the component.

long_name()¶

Return the long name of the parameter variable.

The long name is a string representing the long name of the parameter variable

param()¶

set(*args, **kwargs)¶

Create a new instance with updated data.

Parameters:

args (tuple) – Positional arguments containing parameter data. Only dictionaries are allowed.
kwargs (dict) – Keyword arguments containing parameter data.
information (The following keys can be provided to update the parameter) –
- “variable”: The parameter variable.
- ”units”: The parameter units, as a string or a Units object.
- ”standard_name”: The standard name of the parameter variable.
- ”long_name”: The long name of the parameter variable.
- ”chem_variable”: The chemical variable of the parameter.

standard_name()¶

Return the standard name of the parameter variable.

The standard name is a string representing the standard name of the parameter variable. It is based on the CF standard name.

to_dict()¶

Convert the object to a dictionary.

Returns:: Dictionary representation of the object.
Return type:: dict

units()¶

Return the parameter units.

The parameter units are Units objects. The units are are based on Pint (when possible) and are normalised to a standard form. They can be used for unit conversions and comparisons.

variable()¶

Return the parameter variable.

The parameter variable is a string representing the parameter variable. At the moment it not normalised, but takes the value as it is in the source data. For example, for GRIB data, it will be the value of the “shortName” key in the GRIB message.

class earthkit.data.field.component.parameter.ParameterBase¶

Bases: earthkit.data.field.component.component.SimpleFieldComponent

Base class for the parameter component of a field.

This class defines the interface for parameter components, which can represent different types of parameter information. Some of the methods may not be applicable to all parameter types (e.g. chem_variable()), and may return None.

The parameter information can be accessed by methods like variable(), units(), and chem_variable(). Each of these methods has an associated key that can be used in the get() method to retrieve the corresponding information. The list of supported keys are as follows:

“variable”: string representing the parameter variable
“standard_name”: string representing the standard name of the parameter variable, based
on the CF standard name
“long_name”: string representing the long name of the parameter variable
“units”: as a string or a Units object representing the parameter units
“chem_variable”: string representing the parameter chemical variable
“param”: alias of “variable”

Depending on the type of parameter information available, some of these keys may not be supported and will return None in the subclasses. For example, the “chem_variable” key is only supported for chemical parameters, and will return None for other parameter types.

Typically, this object is used as a component of a field, and can be accessed via the parameter attribute of a field. The keys above can also be accessed via the get() method of the field, using the “parameter.” prefix.

The following example demonstrates how to access the parameter information from a field using various methods and keys:

>>> import earthkit.data as ekd
>>> field = ekd.from_source("sample", "test.grib").to_fieldlist()[0]
>>> field.parameter.variable()
'2t'
>>> field.parameter.get("variable")
'2t'
>>> field.get("parameter.variable")
'2t'

The parameter component is immutable. The set() method to create a new instance with updated values. For example, the following code creates a new parameter component with an updated variable:

>>> new_parameter = field.parameter.set(variable="msl", units="Pa")
>>> new_parameter.variable()
'msl'

We can also call the Field’s set() method to create a new field with an updated parameter component:

>>> new_field = field.set({"parameter.variable": "msl", "parameter.units": "Pa"})
>>> new_field.parameter.variable()
'msl'

aliases()¶: Return the aliases in the component.

abstractmethod chem_variable()¶: Return the parameter chemical variable.

classmethod from_dict(d)¶

Abstractmethod:

Create a FieldComponent instance from a dictionary.

Parameters:: d (dict) – Dictionary containing specification data.
Returns:: The created FieldComponent instance.
Return type:: FieldComponent

get(key, default=None, *, astype=None, raise_on_missing=False)¶

Return the value for the specified key.

Parameters:

key (str) – The key to retrieve.
default (Any, optional) – The default value to return if the key is not found. Default is None.
astype (type, optional) – The type to which the value should be cast. Default is None.
raise_on_missing (bool, optional) – If True, raise a KeyError if the key is not found. Default is False.

Returns:

The value for the specified key.

Return type:

Any

Raises:

KeyError – If raise_on_missing is True and the key is not found.

keys()¶: Return the available keys in the component.

abstractmethod long_name()¶

Return the long name of the parameter variable.

The long name is a string representing the long name of the parameter variable

param()¶

abstractmethod set(*args, **kwargs)¶

Create a new instance with updated data.

Parameters:

*args – Positional arguments.
**kwargs – Keyword arguments.

Returns:

The created FieldComponent instance.

Return type:

FieldComponent

Raises:

KeyError – If any of the keys to be set are not supported.

abstractmethod standard_name()¶

Return the standard name of the parameter variable.

The standard name is a string representing the standard name of the parameter variable. It is based on the CF standard name.

abstractmethod to_dict()¶

Convert the object to a dictionary.

Returns:: Dictionary representation of the object.
Return type:: dict

abstractmethod units()¶

Return the parameter units.

The parameter units are Units objects. The units are are based on Pint (when possible) and are normalised to a standard form. They can be used for unit conversions and comparisons.

abstractmethod variable()¶

Return the parameter variable.

earthkit.data.field.component.parameter.create_parameter(d)¶

Create a ParameterBase object from a dictionary.

Parameters:: d (dict) – Dictionary containing parameter data.
Returns:: The created ParameterBase instance.
Return type:: ParameterBase