earthkit.data.field.component.vertical¶

Classes¶

`EmptyVertical`	Empty vertical component, representing the absence of vertical information.
`Vertical`	Vertical component of a field, representing the vertical coordinate information.
`VerticalBase`	Base class for vertical coordinate component of a field.

Functions¶

create_vertical(d)

Create a Vertical object from a dictionary.

Module Contents¶

class earthkit.data.field.component.vertical.EmptyVertical¶

Bases: VerticalBase

Empty vertical component, representing the absence of vertical information.

abbreviation()¶

Return the abbreviation of level type.

The abbreviation is not available for this vertical type, and this method returns None.

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

cf()¶

Return the CF metadata for the level type.

The CF metadata is not available for this vertical type, and this method returns None.

classmethod from_dict(d)¶

Create a Vertical object from a dictionary.

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

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.

layer()¶

Return the layer.

The layer information is not available for this vertical type, and this method returns None.

level()¶

Return the level.

The level information is not available for this vertical type, and this method returns None.

level_type()¶

Return the level type.

Returns an UnknownLevelType, indicating the absence of vertical information.

positive()¶

Return the positive direction of the vertical coordinate.

The positive direction is not available for this vertical type, and this method returns None.

set(*args, **kwargs)¶

Create a new instance with updated data.

An EmptyVertical object cannot be updated, and this method raises a ValueError if any data is provided.

to_dict()¶: Convert the object to a dictionary.

units()¶

Return the units of the level type.

The units are not available for this vertical type, and this method returns None.

class earthkit.data.field.component.vertical.Vertical(level=None, layer=None, level_type=None)¶

Bases: VerticalBase

Vertical component of a field, representing the vertical coordinate information.

Parameters:

level (int or float, optional) – The level value. The meaning of the level value depends on the level_type.
layer (tuple of two floats, optional) – The layer information, represented as a tuple of two values (bottom, top). The layer information is only applicable for certain vertical types, and may be None for other types.
level_type (LevelType or str, optional) – The level type, which defines the type of vertical coordinate (e.g. “pressure”, “height”, “isotherm”, etc.). It can be specified as a LevelType object or as a string. If specified as a string, it will be converted to a LevelType object using the get_level_type() function. The level type is used to interpret the level and layer information, and to provide additional metadata such as units and CF attributes.

abbreviation()¶: Return the abbreviation of level type.

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

cf()¶

Return the CF metadata for the vertical coordinate.

The CF metadata is a dictionary containing the following keys: - “standard_name”: the CF standard name for the vertical coordinate - “long_name”: the CF long name for the vertical coordinate - “positive”: the positive direction of the vertical coordinate (e.g. “up” or “down”) - “units”: the units as str for the vertical coordinate

classmethod from_dict(d, allow_unused=False)¶

Create a Vertical object from a dictionary.

Parameters:

d (dict) –
Dictionary containing vertical coordinate data.

The dictionary can contain the following keys:
- ”level”: The level value.
- ”layer”: The layer information.
- ”level_type”: The level type.
If (The "level_type" key can be specified as a LevelType object or as a string.)
string (specified as a)
using (it will be converted to a LevelType object)

:param the get_level_type() function.:

Returns:: The created Vertical instance.
Return type:: Vertical

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.

layer()¶

Return the layer.

The layer is represented as a tuple of two values (bottom, top). The layer information is only available for certain vertical types, and will return None for other types.

level()¶: Return the level.

level_type()¶

Return the level type.

Returns:: The level type is returned as a string.
Return type:: str

positive()¶

Return the positive direction of the vertical coordinate.

The positive direction is typically “up” or “down”. It may return None if the positive direction is not defined for the vertical type.

set(*args, **kwargs)¶

Create a new instance with updated data.

Parameters:

args (tuple) – Positional arguments containing time data. Only dictionaries are allowed.
kwargs (dict) – Keyword arguments containing time data.

Returns:

The created Vertical instance.

Return type:

Vertical

The allowed keys in the dictionaries and keyword arguments are:

“level”
“layer”
“level_type”

The “level_type” key can be specified as a LevelType object or as a string. If specified as a string, it will be converted to a LevelType object using the get_level_type() function.

to_dict()¶: Convert the object to a dictionary.

units()¶

Return the units of the level type.

The units are returned an earthkit.utils.units.Units object.

class earthkit.data.field.component.vertical.VerticalBase¶

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

Base class for vertical coordinate component of a field.

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

The vertical information can be accessed by methods like level(), and level_type(). 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:

“level”
“level_type”
“layer”
“cf”
“abbreviation”
“units”
“positive”

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

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

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

>>> import earthkit.data as ekd
>>> field = ekd.from_source("sample", "tuv_pl.grib").to_fieldlist()[0]
>>> field.vertical.level()
1000
>>> field.vertical.get("level")
1000
>>> field.get("vertical.level")
1000
>>> field.vertical.level_type()
'pressure'
>>> field.vertical.get("level_type")
'pressure'
>>> field.get("vertical.level_type")
'pressure'

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

>>> new_vertical = field.vertical.set(level=500)
>>> new_vertical.level()
500

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

>>> new_field = field.set({"vertical.level": 500})
>>> new_field.vertical.level()
500

abstractmethod abbreviation()¶: Return the abbreviation of level type.

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

abstractmethod cf()¶

Return the CF metadata for the vertical coordinate.

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 layer()¶

Return the layer.

The layer is represented as a tuple of two values (bottom, top). The layer information is only available for certain vertical types, and will return None for other types.

abstractmethod level()¶: Return the level.

abstractmethod level_type()¶

Return the level type.

Returns:: The level type is returned as a string.
Return type:: str

abstractmethod positive()¶

Return the positive direction of the vertical coordinate.

The positive direction is typically “up” or “down”. It may return None if the positive direction is not defined for the vertical type.

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 to_dict()¶

Convert the object to a dictionary.

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

abstractmethod units()¶

Return the units of the level type.

The units are returned an earthkit.utils.units.Units object.

earthkit.data.field.component.vertical.create_vertical(d)¶

Create a Vertical object from a dictionary.

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