earthkit.data.field.xarray.geography

Classes

XArrayGeography

Geography component representing the geographical information of a field.

XArrayGeographyHandler

Geography component of a field.

Module Contents

class earthkit.data.field.xarray.geography.XArrayGeography(owner, selection)

Bases: earthkit.data.field.component.geography.GeographyBase

Geography component representing the geographical information of a field.

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

The geographical information can be accessed by methods like latitudes(), longitudes(), and shape(). 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:

  • “latitudes”

  • “longitudes”

  • “distinct_latitudes”

  • “distinct_longitudes”

  • “x”

  • “y”

  • “shape”

  • “projection”

  • “bounding_box”

  • “unique_grid_id”

  • “grid_spec”

  • “grid_type”

  • “grid”

  • “area”

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

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

The following example demonstrates how to access the geographical 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.geography.area()
(70, -20, 35, 40)
>>> field.geography.get("area")
(70, -20, 35, 40)
>>> field.get("geography.area")
(70, -20, 35, 40)

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

>>> new_geography = field.geography.set(grid_spec= [10,10])
>>> new_geography.area()
(90.0, 0, -90.0, 360.0)

We can also call the Field’s set() method to create a new field with an updated time component. This is typically done by also passing a new data array to match the new geography. For example, the following code creates a new field with an updated geography component and data array:

>>> values = np.random.rand(19, 36)  # new values matching the new geography shape
>>> new_field = field.set({"geography.grid_spec": [10,10], "values": values})
>>> new_field.geography.area()
(90.0, 0, -90.0, 360.0)
aliases()

Return the aliases in the component.

area()

Return the area of the grid.

bounding_box()

Return the bounding box.

Returns:

The bounding box or None if not available.

Return type:

BoundingBox, None

distinct_latitudes(dtype=None)

Return the distinct latitudes.

distinct_longitudes(dtype=None)

Return the distinct longitudes.

classmethod from_dict(data, shape_hint=None)

Create a Geography object from a dictionary.

Parameters:

  • data (dict) – Dictionary containing geography data.

  • shape_hint (tuple, optional) – A hint for the shape of the geography. This is typically used when the geography is created from a dictionary that does not contain explicit shape information, and the shape needs to be inferred from the data array shape.

Returns:

The created Geography instance.

Return type:

Geography

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.

grid()

Return the area of the grid.

grid_spec()

Return the grid specification.

grid_type()

Return the grid specification.

keys()

Return the available keys in the component.

latitudes(dtype=None)

Return the latitudes.

Parameters:

dtype (str, array.dtype or None) – Typecode or data-type of the array. When it is None None the default type used by the underlying data accessor is used. For GRIB it is float64.

Returns:

The latitudes or None if not available.

Return type:

array-like, None

latlons(flatten=False, dtype=None)

Return the latitudes/longitudes of all the gridpoints in the field.

Parameters:

  • flatten (bool) – When it is True 1D arrays are returned. Otherwise arrays with the field’s shape are returned.

  • dtype (str, array.dtype or None) – Typecode or data-type of the arrays. When it is None the default type used by the underlying data accessor is used. For GRIB it is float64.

Returns:

Tuple of latitudes and longitudes.

Return type:

array-like, array-like

See also

to_points

longitudes(dtype=None)

Return the longitudes.

Parameters:

dtype (str, array.dtype or None) – Typecode or data-type of the array. When it is None the default type used by the underlying data accessor is used. For GRIB it is float64.

Returns:

The longitudes or None if not available.

Return type:

array-like, None

owner
points(flatten=False, dtype=None)

Return the x/y coordinates of all the points.

This is an alias for xys() and is provided for convenience when the geographical coordinates are desired as points rather than separate x and y arrays.

See also

xys

projection()

Return the projection.

Returns:

The projection or None if not available.

Return type:

Projection, None

selection
set(*args, shape_hint=None, **kwargs)

Return a new GeographyBase object with updated values.

Parameters:

  • *args (tuple) – Positional arguments to update the geography. Positional arguments containing time data. Only dictionaries are allowed.

  • shape_hint (tuple, optional) – A hint for the shape of the geography. This is typically used when the geography is created from a dictionary that does not contain explicit shape information, and the shape needs to be inferred from the data array shape.

  • **kwargs (dict) – Keyword arguments to update the geography. The allowed keys are:

  • are (The allowed keys in the dictionaries and keyword arguments) –

    • “grid_spec”, str or dict

    • ”latitudes” and “longitudes”, array-like

  • updating (The following cases are supported for)

  • "grid_spec" (- the only key provided is) – is created from the provided grid specification. In this case nothing is taken from the existing geography, and no other keys should be provided to avoid ambiguity. The “grid_spec” can be str or dict.

  • geography (in which case the new) – is created from the provided grid specification. In this case nothing is taken from the existing geography, and no other keys should be provided to avoid ambiguity. The “grid_spec” can be str or dict.

  • "longitudes" (- the only keys provided are "latitudes" and) – the new geography is created from the provided latitude and longitude arrays. In this case, the shape_hint is used to determine the shape of the new geography if the provided latitudes and longitudes are 1D arrays. If the latitudes and longitudes are already 2D arrays matching the shape_hint, then the shape_hint is ignored. No other keys should be provided to avoid ambiguity.

  • case (in which) – the new geography is created from the provided latitude and longitude arrays. In this case, the shape_hint is used to determine the shape of the new geography if the provided latitudes and longitudes are 1D arrays. If the latitudes and longitudes are already 2D arrays matching the shape_hint, then the shape_hint is ignored. No other keys should be provided to avoid ambiguity.

Returns:

The new GeographyBase object with updated values.

Return type:

GeographyBase

Raises:

ValueError – If the provided keys do not match any of the supported update cases, or if there is ambiguity in the provided keys.

Example

>>> new_geography = field.geography.set(grid_spec= [10,10])
>>> new_geography.area()
(90.0, 0, -90.0, 360.0)

>>> values = np.random.rand(19, 36)  # new values matching the new geography shape
>>> new_field = field.set({"geography.grid_spec": [10,10], "values": values})
>>> new_field.geography.area()
(90.0, 0, -90.0, 360.0)
shape()

Return the shape of the geography.

Returns:

The shape of the geography.

Return type:

tuple

to_dict()

Return a dictionary representation of the Geography.

unique_grid_id()

str: Return the unique id of the grid.

x(dtype=None)

array-like: Return the x coordinates in the original CRS.

xys(flatten=False, dtype=None)

Return the x/y coordinates of all the points.

Parameters:

  • flatten (bool) – When it is True 1D arrays are returned. Otherwise arrays with the field’s shape are returned.

  • dtype (str, array.dtype or None) – Typecode or data-type of the arrays. When it is None the default type used by the underlying data accessor is used. For GRIB it is float64.

Returns:

Tuple of x and y coordinates.

Return type:

array-like, array-like

See also

to_points

y(dtype=None)

array-like: Return the y coordinates in the original CRS.

class earthkit.data.field.xarray.geography.XArrayGeographyHandler(owner, selection)

Bases: earthkit.data.field.handler.geography.GeographyFieldComponentHandler

Geography component of a field.

COMPONENT_CLS
COMPONENT_MAKER
KEYS = ()
NAME = 'geography'
check(owner)

Default check implementation.

property component: Any

Return the component object.

classmethod create_empty()
dump(owner, name, result, prefix_keys=False)

Populate the namespace dictionary for this SpecFieldComponent.

classmethod from_any(data, dict_kwargs=None)

Create a SimpleFieldComponent object from any input.

Parameters:

  • data (Any) – The input data from which to create the SimpleFieldComponent instance.

  • dict_kwargs (dict, optional) – Additional keyword arguments to be passed when creating the instance from a dictionary.

Returns:

An instance of SimpleFieldComponentHandler. If the input is already an instance of SimpleFieldComponentHandler, it is returned as is. Otherwise, it is assumed to be a component object and a new SimpleFieldComponentHandler instance is created from it.

Return type:

SimpleFieldComponentHandler

classmethod from_component(component)

Create a SimpleFieldComponent object from a component object.

classmethod from_dict(d, **kwargs)

Create a SimpleFieldComponent object from a dictionary.

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

Return the value for key.

Parameters:

  • key (str) – Key

  • default (value) – Specify the default value for key. Returned when key is not found or its value is a missing value and raise_on_missing is False.

  • astype (type as str, int or float) – Return/access type for key. When it is supported astype is passed to the underlying accessor as an option. Otherwise the value is cast to astype after it is taken from the accessor.

  • raise_on_missing (bool) – When it is True raises an exception if key is not found or it has a missing value.

Returns:

Returns the key value. Returns default if key is not found or it has a missing value and raise_on_missing is False.

Return type:

value

Raises:

KeyError – If raise_on_missing is True and key is not found or it has a missing value.

get_grib_context(context)

Populate the GRIB context dictionary for this FieldComponent.

set(*args, **kwargs)

Create a new SimpleFieldComponentHandler instance with updated component data.