earthkit.data.field.geotiff.geography¶

Classes¶

GeoTIFFGeography

Geography component representing the geographical information of a field.

Module Contents¶

class earthkit.data.field.geotiff.geography.GeoTIFFGeography(ds)¶

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.

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

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

xys

projection()¶

Return the projection.

Returns:: The projection or None if not available.
Return type:: Projection, None

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.

x_dim¶

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