earthkit.data.field.grib.geography¶

Attributes¶

COLLECTOR

Classes¶

`GribGeography`	Geography component representing the geographical information of a field.
`GribGeographyBuilder`
`GribGeographyContextCollector`
`GribGeographyHandler`

Functions¶

missing_is_none(x)

Module Contents¶

earthkit.data.field.grib.geography.COLLECTOR¶

class earthkit.data.field.grib.geography.GribGeography(handle)¶

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 as a tuple of (north, west, south, east).

Returns:: The area as a tuple of (north, west, south, east).
Return type:: tuple

bounding_box()¶

Return the bounding box of the field.

Return type:: BoundingBox

distinct_latitudes(dtype=None)¶

Return the distinct latitudes.

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 distinct latitudes or None if not available.
Return type:: array-like, None

distinct_longitudes(dtype=None)¶

Return the distinct 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 distinct longitudes or None if not available.
Return type:: array-like, None

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 Grid object.

This feature is not yet implemented in earthkit-data, and this method currently returns None.

grid_spec()¶

Return the grid spec.

Returns:: The grid spec or None if not available.
Return type:: dict, None

grid_type()¶: Return the grid type.

handle¶

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

xys

projection()¶

Return information about the projection.

Returns:

Projection
Examplesa
--------
>>> import earthkit.data
>>> ds = earthkit.data.from_source(``”file”, ``"docs/how-tos/test.grib")
>>> ds.projection()
<Projected CRS (+proj=eqc +ellps=WGS84 +a=6378137.0 +lon_0=0.0 +to ...>)
Name (unknown)
Axis Info [cartesian]
- E[east] (Easting (unknown))
- N[north] (Northing (unknown))
- h[up] (Ellipsoidal height (metre))
Area of Use
- undefined
Coordinate Operation
- name (unknown)
- method (Equidistant Cylindrical)
Datum (Unknown based on WGS 84 ellipsoid)
- Ellipsoid (WGS 84)
- Prime Meridian (Greenwich)
>>> ds.projection().to_proj_string()
'+proj=eqc +ellps=WGS84 +a=6378137.0 +lon_0=0.0 +to_meter=111319.4907932736 +no_defs +type=crs'

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

Get the shape of the field.

For structured grids the shape is a tuple in the form of (Nj, Ni) where:

ni: the number of gridpoints in i direction (longitude for a regular latitude-longitude grid)
nj: the number of gridpoints in j direction (latitude for a regular latitude-longitude grid)

For other grid types the number of gridpoints is returned as (num,)

Return type:: tuple

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

unique_grid_id()¶: Return a unique id of the grid of a field.

x(dtype=None)¶

Return the x coordinates in the original CRS.

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 x coordinates or None if not available.
Return type:: array-like, None

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