geoxarray.accessor module

XArray extensions via accessor objects.

The functionality in this module can be accessed via the .geo accessor on any xarray DataArray or Dataset object.

Geolocation cases that these accessors are supposed to be able to handle:

  1. CF compliant Dataset: A Dataset object with one or more data variables and one CRS specification variable. By default a ‘grid_mapping’ attribute is used to specify the name of the variable.

    https://cfconventions.org/Data/cf-conventions/cf-conventions-1.7/build/ch05s06.html

  2. Geotiff DataArrays: A DataArray object returned by either the rioxarray library or by xarray.open_rasterio`().

  3. Raw lon/lat coordinate arrays: A DataArray or Dataset object that contains 1D or 2D longitude and latitude arrays defining the coordinates of the data.

These accessors attempt to provide standard interfaces to the following information from these different data cases:

  1. Standard dimensions: X (columns), Y (rows), Vertical, and Time.

  2. Coordinate Reference System (CRS)

Lastly, these accessor provide basic wrappers around other tools that are typically used with geospatial data (resampling, plotting, etc) or converting to other formats (CF compatible NetCDF file).

class geoxarray.accessor.GeoDataArrayAccessor(data_arr_obj)[source]

Provide DataArray geolocation helper functions from a .geo accessor.

property dim_map

Map current data dimension to geoxarray preferred dim name.

property dims

Get preferred dimension names in order.

property gcps: dict | None

Get GeoJSON-formatted GCPs, if any, from the grid mapping coordinate variable.

get_lonlats(chunks=None)[source]

Return longitude and latitude arrays.

Parameters:

chunks (None or int) – Specify chunk size for dask arrays.

Returns:

  • Longitude and latitude dask arrays. If chunks is None then a

  • numpy array is returned.

property grid_mapping: str | None

Name of a grid mapping variable associated with this DataArray.

Note

Much of this code is copied from the rioxarray project and is under the Apache 2.0 license. A copy of this license is available in the source file LICENSE_rioxarray.

Returns:

  • Grid mapping variable name defined in the xarray object. If not found,

  • None is returned.

plot()[source]

Plot data on a map.

set_dims(x=None, y=None, vertical=None, time=None, inplace=True)[source]

Set preferred dimension names inside the Geoxarray accessor.

Geoxarray will use this information for future operations. If any of the dimensions are not provided they will be found by best guess.

This information does not rename or modify the data of the Xarray object itself. To easily rename the dimensions in a Geoxarray-friendly manner, follow a call of this method with write_dims().

Parameters:

  • x (None | str) – Name of the X dimension. This dimension usually exists with a corresponding coordinate variable in meters for gridded/projected data.

  • y (None | str) – Name of the Y dimension. Similar to the X dimension but on the Y axis.

  • vertical (None | str) – Name of the vertical or Z dimension. This dimension usually exists with a corresponding coordinate variable in meters for altitude or pressure level (ex. hPa, millibar, etc).

  • time (None | str) – Name of the time dimension. This dimension usually exists with a corresponding coordinate variable with time objects.

  • inplace (bool) – If True, changes are made to the current xarray object. Otherwise, a copy of the object is made first. Default is False.

Return type:

DataArray

See also

GeoDataArrayAccessor.dims

Show the current dimensions as Geoxarray knows them

GeoDataArrayAccessor.write_dims

Rename dimensions to match Geoxarray preferred dimension names

property sizes

Get size map with preferred dimension names.

write_crs(new_crs_info=None, grid_mapping_name=None, inplace=False)

Write the CRS to the xarray object in a CF compliant manner.

Note

Much of this code is copied from the rioxarray project and is under the Apache 2.0 license. A copy of this license is available in the source file LICENSE_rioxarray.

Parameters:

  • new_crs_info (Any | None) – Coordinate Reference System (CRS) information to write to the Xarray object. Can be a pyproj.CRS object or anything understood by the pyproj.CRS.from_user_input() method. If not provided, the .crs property will be used. If .crs returns None a RuntimeError is raised.

  • grid_mapping_name (str | None) – Name to use for the coordinate variable created and written by this method. The coordinate variable, also known as the grid mapping variable, will have this name when written to a NetCDF file. Defaults to “spatial_ref”.

  • inplace (bool) – Whether to modify the current Xarray object inplace or to create a copy first. Default (False) is to make a copy.

Return type:

TypeVar(XarrayObject, DataArray, Dataset)

write_dims()

Rename object’s dimensions to match geoxarray’s preferred dimension names.

This is a simple wrapper around Xarray’s xarray.DataArray.rename() or xarray.Dataset.rename() methods along with .geo.dim_map to rename the dimension names. These methods always produce copies of the original object. It is not possible to do this operation “inplace”.

Return type:

TypeVar(XarrayObject, DataArray, Dataset)

write_gcps(gcps, grid_mapping_name=None, inplace=False)

Write GeoJSON-formatted GCPs to the spatial ref.

GCPs can be retrieved later from the obj.geo.gcps property. The GeoJSON will also be available from the grid mapping coordinate variable as an attribute named “gcps”.

More information on the GeoJSON format and examples can be found here: https://geojson.org/. GCP GeoJSON is almost always constructed from a series of “Point” features in a FeatureCollection. A basic example:

{'type': 'FeatureCollection', 'features': [
    {'type': 'Feature', 'properties': {'id': '1', 'info': '', 'row': 0.0, 'col': 0.0},
     'geometry': {'type': 'Point', 'coordinates': [33.03, 61.80, 126.43]}},
    {'type': 'Feature', 'properties': {'id': '2', 'info': '', 'row': 0.0, 'col': 530.0},
     'geometry': {'type': 'Point', 'coordinates': [32.64, 61.85, 126.43]}},
    {'type': 'Feature', 'properties': {'id': '3', 'info': '', 'row': 0.0, 'col': 1060.0},
     'geometry': {'type': 'Point', 'coordinates': [32.25, 61.90, 126.43]}},
    {'type': 'Feature', 'properties': {'id': '4', 'info': '', 'row': 0.0, 'col': 1590.0},
     'geometry': {'type': 'Point', 'coordinates': [31.86, 61.95, 126.43]}},
    {'type': 'Feature', 'properties': {'id': '5', 'info': '', 'row': 0.0, 'col': 2120.0},
     'geometry': {'type': 'Point', 'coordinates': [31.47, 62.00, 126.43]}},
    {'type': 'Feature', 'properties': {'id': '6', 'info': '', 'row': 0.0, 'col': 2650.0},
     'geometry': {'type': 'Point', 'coordinates': [31.08, 62.04, 126.43]}},
    {'type': 'Feature', 'properties': {'id': '7', 'info': '', 'row': 0.0, 'col': 3180.0},
     'geometry': {'type': 'Point', 'coordinates': [30.68, 62.09, 126.43]}}]}
Parameters:

  • gcps (str) – GeoJSON-formatted Ground Control Points (GCPs).

  • grid_mapping_name (str | None) – Name to use for the coordinate variable created and written by this method. The coordinate variable, also known as the grid mapping variable, will have this name when written to a NetCDF file. Defaults to “spatial_ref”.

  • inplace (bool) – Whether to modify the current Xarray object inplace or to create a copy first. Default (False) is to make a copy.

Return type:

None

write_spatial_coords()

Write ‘y’ and ‘x’ coordinate arrays to .coords.

This operation always produces a new copy of the xarray object. See xarray.DataArray.assign_coords() and xarray.Dataset.assign_coords().

See geoxarray.coords.spatial_coords() for supported metadata structures.

Coordinate arrays are currently always a single point per data pixel representing the center of the pixel.

Return type:

DataArray

class geoxarray.accessor.GeoDatasetAccessor(xarray_obj)[source]

Provide Dataset geolocation helper functions from a .geo accessor.

property dim_map

Map current data dimension to geoxarray preferred dim name.

property dims

Get preferred dimension names in order.

property gcps: dict | None

Get GeoJSON-formatted GCPs, if any, from the grid mapping coordinate variable.

property grid_mapping: str | None

Name of a grid mapping variable associated with this DataArray.

Note

Much of this code is copied from the rioxarray project and is under the Apache 2.0 license. A copy of this license is available in the source file LICENSE_rioxarray.

Returns:

  • Grid mapping variable name defined in the xarray object. If not found,

  • None is returned.

set_dims(x=None, y=None, vertical=None, time=None, inplace=False)[source]

Tell geoxarray the names of the provided dimensions in this Dataset.

Parameters:

  • x (str | None) – Name of the X dimension. This dimension usually exists with a corresponding coordinate variable in meters for gridded/projected data.

  • y (str | None) – Name of the Y dimension. Similar to the X dimension but on the Y axis.

  • vertical (str | None) – Name of the vertical or Z dimension. This dimension usually exists with a corresponding coordinate variable in meters for altitude or pressure level (ex. hPa, millibar, etc).

  • time (str | None) – Name of the time dimension. This dimension usually exists with a corresponding coordinate variable with time objects.

  • inplace (bool) – If True, changes are made to the current xarray object. Otherwise, a copy of the object is made first. Default is False.

property sizes

Get size map with preferred dimension names.

write_crs(new_crs_info=None, grid_mapping_name=None, inplace=False)

Write the CRS to the xarray object in a CF compliant manner.

Note

Much of this code is copied from the rioxarray project and is under the Apache 2.0 license. A copy of this license is available in the source file LICENSE_rioxarray.

Parameters:

  • new_crs_info (Any | None) – Coordinate Reference System (CRS) information to write to the Xarray object. Can be a pyproj.CRS object or anything understood by the pyproj.CRS.from_user_input() method. If not provided, the .crs property will be used. If .crs returns None a RuntimeError is raised.

  • grid_mapping_name (str | None) – Name to use for the coordinate variable created and written by this method. The coordinate variable, also known as the grid mapping variable, will have this name when written to a NetCDF file. Defaults to “spatial_ref”.

  • inplace (bool) – Whether to modify the current Xarray object inplace or to create a copy first. Default (False) is to make a copy.

Return type:

TypeVar(XarrayObject, DataArray, Dataset)

write_dims()

Rename object’s dimensions to match geoxarray’s preferred dimension names.

This is a simple wrapper around Xarray’s xarray.DataArray.rename() or xarray.Dataset.rename() methods along with .geo.dim_map to rename the dimension names. These methods always produce copies of the original object. It is not possible to do this operation “inplace”.

Return type:

TypeVar(XarrayObject, DataArray, Dataset)

write_gcps(gcps, grid_mapping_name=None, inplace=False)

Write GeoJSON-formatted GCPs to the spatial ref.

GCPs can be retrieved later from the obj.geo.gcps property. The GeoJSON will also be available from the grid mapping coordinate variable as an attribute named “gcps”.

More information on the GeoJSON format and examples can be found here: https://geojson.org/. GCP GeoJSON is almost always constructed from a series of “Point” features in a FeatureCollection. A basic example:

{'type': 'FeatureCollection', 'features': [
    {'type': 'Feature', 'properties': {'id': '1', 'info': '', 'row': 0.0, 'col': 0.0},
     'geometry': {'type': 'Point', 'coordinates': [33.03, 61.80, 126.43]}},
    {'type': 'Feature', 'properties': {'id': '2', 'info': '', 'row': 0.0, 'col': 530.0},
     'geometry': {'type': 'Point', 'coordinates': [32.64, 61.85, 126.43]}},
    {'type': 'Feature', 'properties': {'id': '3', 'info': '', 'row': 0.0, 'col': 1060.0},
     'geometry': {'type': 'Point', 'coordinates': [32.25, 61.90, 126.43]}},
    {'type': 'Feature', 'properties': {'id': '4', 'info': '', 'row': 0.0, 'col': 1590.0},
     'geometry': {'type': 'Point', 'coordinates': [31.86, 61.95, 126.43]}},
    {'type': 'Feature', 'properties': {'id': '5', 'info': '', 'row': 0.0, 'col': 2120.0},
     'geometry': {'type': 'Point', 'coordinates': [31.47, 62.00, 126.43]}},
    {'type': 'Feature', 'properties': {'id': '6', 'info': '', 'row': 0.0, 'col': 2650.0},
     'geometry': {'type': 'Point', 'coordinates': [31.08, 62.04, 126.43]}},
    {'type': 'Feature', 'properties': {'id': '7', 'info': '', 'row': 0.0, 'col': 3180.0},
     'geometry': {'type': 'Point', 'coordinates': [30.68, 62.09, 126.43]}}]}
Parameters:

  • gcps (str) – GeoJSON-formatted Ground Control Points (GCPs).

  • grid_mapping_name (str | None) – Name to use for the coordinate variable created and written by this method. The coordinate variable, also known as the grid mapping variable, will have this name when written to a NetCDF file. Defaults to “spatial_ref”.

  • inplace (bool) – Whether to modify the current Xarray object inplace or to create a copy first. Default (False) is to make a copy.

Return type:

None

write_spatial_coords()

Write ‘y’ and ‘x’ coordinate arrays to .coords.

This operation always produces a new copy of the xarray object. See xarray.DataArray.assign_coords() and xarray.Dataset.assign_coords().

See geoxarray.coords.spatial_coords() for supported metadata structures.

Coordinate arrays are currently always a single point per data pixel representing the center of the pixel.

Return type:

DataArray