rioxarray package

rioxarray.open_rasterio

rioxarray.open_rasterio(filename, parse_coordinates=None, chunks=None, cache=None, lock=None, masked=False, mask_and_scale=False, variable=None, group=None, default_name=None, **open_kwargs)[source]

Open a file with rasterio (experimental).

This should work with any file that rasterio can open (most often: geoTIFF). The x and y coordinates are generated automatically from the file’s geoinformation, shifted to the center of each pixel (see “PixelIsArea” Raster Space for more information).

You can generate 2D coordinates from the file’s attributes with:

from affine import Affine
da = xr.open_rasterio('path_to_file.tif')
transform = Affine.from_gdal(*da.attrs['transform'])
nx, ny = da.sizes['x'], da.sizes['y']
x, y = np.meshgrid(np.arange(nx)+0.5, np.arange(ny)+0.5) * transform
Parameters:
  • filename (str, rasterio.DatasetReader, or rasterio.WarpedVRT) – Path to the file to open. Or already open rasterio dataset.
  • parse_coordinates (bool, optional) – Whether to parse the x and y coordinates out of the file’s transform attribute or not. The default is to automatically parse the coordinates only if they are rectilinear (1D). It can be useful to set parse_coordinates=False if your files are very large or if you don’t need the coordinates.
  • chunks (int, tuple or dict, optional) – Chunk sizes along each dimension, e.g., 5, (5, 5) or {'x': 5, 'y': 5}. If chunks is provided, it used to load the new DataArray into a dask array. Chunks can also be set to True or "auto" to choose sensible chunk sizes according to ``dask.config.get(“array.chunk-size”).
  • cache (bool, optional) – If True, cache data loaded from the underlying datastore in memory as NumPy arrays when accessed to avoid reading from the underlying data- store multiple times. Defaults to True unless you specify the chunks argument to use dask, in which case it defaults to False.
  • lock (False, True or threading.Lock, optional) – If chunks is provided, this argument is passed on to dask.array.from_array(). By default, a global lock is used to avoid issues with concurrent access to the same file when using dask’s multithreaded backend.
  • masked (bool, optional) – If True, read the mask and to set values to NaN. Defaults to False.
  • mask_and_scale (bool, optional) – Lazily scale (using scale_factor and add_offset) and mask (using _FillValue). If the _Unsigned attribute is present treat integer arrays as unsigned.
  • variable (str or list or tuple, optional) – Variable name or names to use to filter loading.
  • group (str or list or tuple, optional) – Group name or names to use to filter loading.
  • default_name (str, optional) – The name of the data array if none exists. Default is None.
  • **open_kwargs (kwargs, optional) – Optional keyword arguments to pass into rasterio.open().
Returns:

data – The newly created DataArray.

Return type:

DataArray

rioxarray.merge module

rioxarray.merge.merge_arrays()[source]

Merge data arrays geospatially.

Uses rasterio.merge.merge:
https://rasterio.readthedocs.io/en/stable/api/rasterio.merge.html#rasterio.merge.merge
Parameters:
  • dataarrays (list) – List of xarray.DataArray’s with all geo attributes. The first one is assumed to have the same CRS, dtype, and dimensions as the others in the array.
  • bounds (tuple, optional) – Bounds of the output image (left, bottom, right, top). If not set, bounds are determined from bounds of input DataArrays.
  • res (tuple, optional) – Output resolution in units of coordinate reference system. If not set, the resolution of the first DataArray is used. If a single value is passed, output pixels will be square.
  • nodata (float, optional) – nodata value to use in output file. If not set, uses the nodata value in the first input DataArray.
  • precision (float, optional) – Number of decimal points of precision when computing inverse transform.
  • method (str or callable, optional) – See rasterio docs.
  • parse_coordinates (bool, optional) – If False, it will disable loading spatial coordinates.
Returns:

DataArray

Return type:

The geospatially merged data.

rioxarray.merge.merge_datasets()[source]

Merge datasets geospatially.

Uses rasterio.merge.merge:
https://rasterio.readthedocs.io/en/stable/api/rasterio.merge.html#rasterio.merge.merge
Parameters:
  • datasets (list) – List of xarray.Dataset’s with all geo attributes. The first one is assumed to have the same CRS, dtype, dimensions, and data_vars as the others in the array.
  • bounds (tuple, optional) – Bounds of the output image (left, bottom, right, top). If not set, bounds are determined from bounds of input Dataset.
  • res (tuple, optional) – Output resolution in units of coordinate reference system. If not set, the resolution of the first Dataset is used. If a single value is passed, output pixels will be square.
  • nodata (float, optional) – nodata value to use in output file. If not set, uses the nodata value in the first input Dataset.
  • precision (float, optional) – Number of decimal points of precision when computing inverse transform.
  • method (str or callable, optional) – See rasterio docs.
Returns:

Dataset

Return type:

The geospatially merged data.

rioxarray.rioxarray module

This module is an extension for xarray to provide rasterio capabilities to xarray datasets/dataarrays.

Credits: The reproject functionality was adopted from https://github.com/opendatacube/datacube-core # noqa Source file: - https://github.com/opendatacube/datacube-core/blob/084c84d78cb6e1326c7fbbe79c5b5d0bef37c078/datacube/api/geo_xarray.py # noqa datacube is licensed under the Apache License, Version 2.0: - https://github.com/opendatacube/datacube-core/blob/1d345f08a10a13c316f81100936b0ad8b1a374eb/LICENSE # noqa

class rioxarray.rioxarray.RasterArray(xarray_obj)[source]

Bases: rioxarray.rioxarray.XRasterBase

This is the GIS extension for xarray.DataArray

bounds(recalc=False)[source]

Determine the bounds of the xarray.DataArray

Parameters:recalc (bool, optional) – Will force the bounds to be recalculated instead of using the transform attribute.
Returns:left, bottom, right, top – Outermost coordinates.
Return type:float
clip(geometries, crs, all_touched=False, drop=True, invert=False)[source]

Crops a xarray.DataArray by geojson like geometry dicts.

Powered by rasterio.features.geometry_mask.

Parameters:
  • geometries (list) – A list of geojson geometry dicts.
  • crs (rasterio.crs.CRS) – The CRS of the input geometries.
  • all_touched (bool, optional) – If True, all pixels touched by geometries will be burned in. If false, only pixels whose center is within the polygon or that are selected by Bresenham’s line algorithm will be burned in.
  • drop (bool, optional) – If True, drop the data outside of the extent of the mask geoemtries Otherwise, it will return the same raster with the data masked. Default is True.
  • invert (boolean, optional) – If False, pixels that do not overlap shapes will be set as nodata. Otherwise, pixels that overlap the shapes will be set as nodata. False by default.
Returns:

DataArray

Return type:

A clipped xarray.DataArray object.

Examples

>>> geometry = ''' {"type": "Polygon",
...                 "coordinates": [
...                 [[-94.07955380199459, 41.69085871273774],
...                 [-94.06082436942204, 41.69103313774798],
...                 [-94.06063203899649, 41.67932439500822],
...                 [-94.07935807746362, 41.679150041277325],
...                 [-94.07955380199459, 41.69085871273774]]]}'''
>>> cropping_geometries = [geojson.loads(geometry)]
>>> xds = xarray.open_rasterio('cool_raster.tif')
>>> cropped = xds.rio.clip(geometries=cropping_geometries, crs=4326)
clip_box(minx, miny, maxx, maxy, auto_expand=False, auto_expand_limit=3)[source]

Clip the xarray.DataArray by a bounding box.

Parameters:
  • minx (float) – Minimum bound for x coordinate.
  • miny (float) – Minimum bound for y coordinate.
  • maxx (float) – Maximum bound for x coordinate.
  • maxy (float) – Maximum bound for y coordinate.
  • auto_expand (bool) – If True, it will expand clip search if only 1D raster found with clip.
  • auto_expand_limit (int) – maximum number of times the clip will be retried before raising an exception.
Returns:

DataArray

Return type:

A clipped xarray.DataArray object.

count
encoded_nodata

Return the encoded nodata value for the dataset if encoded.

interpolate_na(method='nearest')[source]

This method uses scipy.interpolate.griddata to interpolate missing data.

Parameters:method ({‘linear’, ‘nearest’, ‘cubic’}, optional) – The method to use for interpolation in scipy.interpolate.griddata.
Returns::class:`xarray.DataArray`
Return type:An interpolated xarray.DataArray object.
nodata

Get the nodata value for the dataset.

reproject(dst_crs, resolution=None, dst_affine_width_height=None, resampling=<Resampling.nearest: 0>)[source]

Reproject xarray.DataArray objects

Powered by rasterio.warp.reproject

Note

Only 2D/3D arrays with dimensions ‘x’/’y’ are currently supported. Requires either a grid mapping variable with ‘spatial_ref’ or a ‘crs’ attribute to be set containing a valid CRS. If using a WKT (e.g. from spatiareference.org), make sure it is an OGC WKT.

Parameters:
  • dst_crs (str) – OGC WKT string or Proj.4 string.
  • resolution (float or tuple(float, float), optional) – Size of a destination pixel in destination projection units (e.g. degrees or metres).
  • dst_affine_width_height (tuple(dst_affine, dst_width, dst_height), optional) – Tuple with the destination affine, width, and height.
  • resampling (Resampling method, optional) – See rasterio.warp.reproject for more details.
Returns:

:class:`xarray.DataArray`

Return type:

A reprojected DataArray.

reproject_match(match_data_array, resampling=<Resampling.nearest: 0>)[source]

Reproject a DataArray object to match the resolution, projection, and region of another DataArray.

Powered by rasterio.warp.reproject

Note

Only 2D/3D arrays with dimensions ‘x’/’y’ are currently supported. Requires either a grid mapping variable with ‘spatial_ref’ or a ‘crs’ attribute to be set containing a valid CRS. If using a WKT (e.g. from spatiareference.org), make sure it is an OGC WKT.

Parameters:
  • match_data_array (xarray.DataArray) – DataArray of the target resolution and projection.
  • resampling (Resampling method, optional) – See rasterio.warp.reproject for more details.
Returns:

Contains the data from the src_data_array, reprojected to match match_data_array.

Return type:

xarray.DataArray

resolution(recalc=False)[source]

Determine the resolution of the xarray.DataArray

Parameters:recalc (bool, optional) – Will force the resolution to be recalculated instead of using the transform attribute.
set_nodata(input_nodata, inplace=True)[source]

Set the nodata value for the DataArray without modifying the data array.

Parameters:
  • input_nodata (object) – Valid nodata for dtype.
  • inplace (bool, optional) – If True, it will write to the existing dataset. Default is False.
Returns:

xarray.DataArray

Return type:

Dataset with nodata attribute set.

slice_xy(minx, miny, maxx, maxy)[source]

Slice the array by x,y bounds.

Parameters:
  • minx (float) – Minimum bound for x coordinate.
  • miny (float) – Minimum bound for y coordinate.
  • maxx (float) – Maximum bound for x coordinate.
  • maxy (float) – Maximum bound for y coordinate.
Returns:

DataArray

Return type:

A sliced xarray.DataArray object.

to_raster(raster_path, driver='GTiff', dtype=None, tags=None, windowed=False, recalc_transform=True, **profile_kwargs)[source]

Export the DataArray to a raster file.

Parameters:
  • raster_path (str) – The path to output the raster to.
  • driver (str, optional) – The name of the GDAL/rasterio driver to use to export the raster. Default is “GTiff”.
  • dtype (str, optional) – The data type to write the raster to. Default is the datasets dtype.
  • tags (dict, optional) – A dictionary of tags to write to the raster.
  • windowed (bool, optional) – If True, it will write using the windows of the output raster. This only works if the output raster is tiled. As such, if you set this to True, the output raster will be tiled. Default is False.
  • **profile_kwargs – Additional keyword arguments to pass into writing the raster. The nodata, transform, crs, count, width, and height attributes are ignored.
transform(recalc=False)[source]

Determine the affine of the xarray.DataArray

transform_bounds(dst_crs, densify_pts=21, recalc=False)[source]

Transform bounds from src_crs to dst_crs.

Optionally densifying the edges (to account for nonlinear transformations along these edges) and extracting the outermost bounds.

Note: this does not account for the antimeridian.

Parameters:
  • dst_crs (str, rasterio.crs.CRS, or dict) – Target coordinate reference system.
  • densify_pts (uint, optional) – Number of points to add to each edge to account for nonlinear edges produced by the transform process. Large numbers will produce worse performance. Default: 21 (gdal default).
  • recalc (bool, optional) – Will force the bounds to be recalculated instead of using the transform attribute.
Returns:

left, bottom, right, top – Outermost coordinates in target coordinate reference system.

Return type:

float

write_nodata(input_nodata, inplace=False)[source]

Write the nodata to the DataArray in a CF compliant manner.

Parameters:
  • input_nodata (object) – Nodata value for the DataArray. If input_nodata is None, it will remove the _FillValue attribute.
  • inplace (bool, optional) – If True, it will write to the existing DataArray. Default is False.
Returns:

xarray.DataArray

Return type:

Modified DataArray with CF compliant nodata information.

class rioxarray.rioxarray.RasterDataset(xarray_obj)[source]

Bases: rioxarray.rioxarray.XRasterBase

This is the GIS extension for xarray.Dataset

clip(geometries, crs, all_touched=False, drop=True, invert=False)[source]

Crops a xarray.Dataset by geojson like geometry dicts.

Warning

Only works if all variables in the dataset have the same coordinates.

Powered by rasterio.features.geometry_mask.

Parameters:
  • geometries (list) – A list of geojson geometry dicts.
  • crs (rasterio.crs.CRS) – The CRS of the input geometries.
  • all_touched (boolean, optional) – If True, all pixels touched by geometries will be burned in. If false, only pixels whose center is within the polygon or that are selected by Bresenham’s line algorithm will be burned in.
  • drop (bool, optional) – If True, drop the data outside of the extent of the mask geoemtries Otherwise, it will return the same raster with the data masked. Default is True.
  • invert (boolean, optional) – If False, pixels that do not overlap shapes will be set as nodata. Otherwise, pixels that overlap the shapes will be set as nodata. False by default.
Returns:

Dataset

Return type:

A clipped xarray.Dataset object.

Examples

>>> geometry = ''' {"type": "Polygon",
...                 "coordinates": [
...                 [[-94.07955380199459, 41.69085871273774],
...                 [-94.06082436942204, 41.69103313774798],
...                 [-94.06063203899649, 41.67932439500822],
...                 [-94.07935807746362, 41.679150041277325],
...                 [-94.07955380199459, 41.69085871273774]]]}'''
>>> cropping_geometries = [geojson.loads(geometry)]
>>> xds = xarray.open_rasterio('cool_raster.tif')
>>> cropped = xds.rio.clip(geometries=cropping_geometries, crs=4326)
clip_box(minx, miny, maxx, maxy, auto_expand=False, auto_expand_limit=3)[source]

Clip the xarray.Dataset by a bounding box.

Warning

Only works if all variables in the dataset have the same coordinates.

Parameters:
  • minx (float) – Minimum bound for x coordinate.
  • miny (float) – Minimum bound for y coordinate.
  • maxx (float) – Maximum bound for x coordinate.
  • maxy (float) – Maximum bound for y coordinate.
  • auto_expand (bool) – If True, it will expand clip search if only 1D raster found with clip.
  • auto_expand_limit (int) – maximum number of times the clip will be retried before raising an exception.
Returns:

DataArray

Return type:

A clipped xarray.Dataset object.

crs

Retrieve projection from xarray.Dataset

Type:rasterio.crs.CRS
interpolate_na(method='nearest')[source]

This method uses scipy.interpolate.griddata to interpolate missing data.

Parameters:method ({‘linear’, ‘nearest’, ‘cubic’}, optional) – The method to use for interpolation in scipy.interpolate.griddata.
Returns::class:`xarray.DataArray`
Return type:An interpolated xarray.DataArray object.
reproject(dst_crs, resolution=None, dst_affine_width_height=None, resampling=<Resampling.nearest: 0>)[source]

Reproject xarray.Dataset objects

Note

Only 2D/3D arrays with dimensions ‘x’/’y’ are currently supported. Requires either a grid mapping variable with ‘spatial_ref’ or a ‘crs’ attribute to be set containing a valid CRS. If using a WKT (e.g. from spatiareference.org), make sure it is an OGC WKT.

Parameters:
  • dst_crs (str) – OGC WKT string or Proj.4 string.
  • resolution (float or tuple(float, float), optional) – Size of a destination pixel in destination projection units (e.g. degrees or metres).
  • dst_affine_width_height (tuple(dst_affine, dst_width, dst_height), optional) – Tuple with the destination affine, width, and height.
  • resampling (Resampling method, optional) – See rasterio.warp.reproject for more details.
Returns:

:class:`xarray.Dataset`

Return type:

A reprojected Dataset.

reproject_match(match_data_array, resampling=<Resampling.nearest: 0>)[source]

Reproject a Dataset object to match the resolution, projection, and region of another DataArray.

Note

Only 2D/3D arrays with dimensions ‘x’/’y’ are currently supported. Requires either a grid mapping variable with ‘spatial_ref’ or a ‘crs’ attribute to be set containing a valid CRS. If using a WKT (e.g. from spatiareference.org), make sure it is an OGC WKT.

Parameters:
  • match_data_array (xarray.DataArray) – DataArray of the target resolution and projection.
  • resampling (Resampling method, optional) – See rasterio.warp.reproject for more details.
Returns:

Contains the data from the src_data_array, reprojected to match match_data_array.

Return type:

xarray.Dataset

to_raster(raster_path, driver='GTiff', dtype=None, tags=None, windowed=False, recalc_transform=True, **profile_kwargs)[source]

Export the Dataset to a raster file. Only works with 2D data.

Parameters:
  • raster_path (str) – The path to output the raster to.
  • driver (str, optional) – The name of the GDAL/rasterio driver to use to export the raster. Default is “GTiff”.
  • dtype (str, optional) – The data type to write the raster to. Default is the datasets dtype.
  • tags (dict, optional) – A dictionary of tags to write to the raster.
  • windowed (bool, optional) – If True, it will write using the windows of the output raster. This only works if the output raster is tiled. As such, if you set this to True, the output raster will be tiled. Default is False.
  • **profile_kwargs – Additional keyword arguments to pass into writing the raster. The nodata, transform, crs, count, width, and height attributes are ignored.
vars

Returns non-coordinate varibles

Type:list
class rioxarray.rioxarray.XRasterBase(xarray_obj)[source]

Bases: object

This is the base class for the GIS extensions for xarray

crs

Retrieve projection from xarray.DataArray or xarray.Dataset

Type:rasterio.crs.CRS
height

Returns the height of the dataset (y dimension size)

Type:int
isel_window(window)[source]

Use a rasterio.window.Window to select a subset of the data.

Parameters:window (rasterio.window.Window) – The window of the dataset to read.
Returns::obj:`xarray.Dataset` | :obj:`xarray.DataArray`
Return type:The data in the window.
set_attrs(new_attrs, inplace=False)[source]

Set the attributes of the dataset/dataarray and reset rioxarray properties to re-search for them.

Parameters:
  • new_attrs (dict) – A dictionary of new attributes.
  • inplace (bool, optional) – If True, it will write to the existing dataset. Default is False.
Returns:

  • xarray.Dataset or xarray.DataArray
  • Modified dataset with new attributes.

set_crs(input_crs, inplace=True)[source]

Set the CRS value for the Dataset/DataArray without modifying the dataset/data array.

Parameters:
  • input_crs (object) – Anything accepted by rasterio.crs.CRS.from_user_input.
  • inplace (bool, optional) – If True, it will write to the existing dataset. Default is False.
Returns:

  • xarray.Dataset or xarray.DataArray
  • Dataset with crs attribute.

set_spatial_dims(x_dim, y_dim, inplace=True)[source]

This sets the spatial dimensions of the dataset.

Parameters:
  • x_dim (str) – The name of the x dimension.
  • y_dim (str) – The name of the y dimension.
  • inplace (bool, optional) – If True, it will modify the dataframe in place. Otherwise it will return a modified copy.
Returns:

Dataset with spatial dimensions set.

Return type:

xarray.Dataset or xarray.DataArray

shape

Returns the shape (width, height)

Type:tuple
update_attrs(new_attrs, inplace=False)[source]

Update the attributes of the dataset/dataarray and reset rioxarray properties to re-search for them.

Parameters:
  • new_attrs (dict) – A dictionary of new attributes to update with.
  • inplace (bool, optional) – If True, it will write to the existing dataset. Default is False.
Returns:

  • xarray.Dataset or xarray.DataArray
  • Modified dataset with updated attributes.

width

Returns the width of the dataset (x dimension size)

Type:int
write_crs(input_crs=None, grid_mapping_name='spatial_ref', inplace=False)[source]

Write the CRS to the dataset in a CF compliant manner.

Parameters:
  • input_crs (object) – Anything accepted by rasterio.crs.CRS.from_user_input.
  • grid_mapping_name (str, optional) – Name of the coordinate to store the CRS information in.
  • inplace (bool, optional) – If True, it will write to the existing dataset. Default is False.
Returns:

  • xarray.Dataset or xarray.DataArray
  • Modified dataset with CF compliant CRS information.

x_dim
y_dim
rioxarray.rioxarray.add_spatial_ref(in_ds, dst_crs, grid_map_name)[source]
rioxarray.rioxarray.add_xy_grid_meta(coords)[source]

Add x,y metadata to coordinates

rioxarray.rioxarray.affine_to_coords(affine, width, height, x_dim='x', y_dim='y')[source]

Generate 1d pixel centered coordinates from affine.

Based on code from the xarray rasterio backend.

Parameters:
  • affine (affine.Affine) – The affine of the grid.
  • width (int) – The width of the grid.
  • height (int) – The height of the grid.
  • x_dim (str, optional) – The name of the X dimension. Default is ‘x’.
  • y_dim (str, optional) – The name of the Y dimension. Default is ‘y’.
Returns:

dict

Return type:

x and y coordinate arrays.

rioxarray.exceptions module

This contains exceptions for rioxarray.

exception rioxarray.exceptions.DimensionError[source]

Bases: rioxarray.exceptions.RioXarrayError

This is raised when there are more dimensions than is supported by the method

exception rioxarray.exceptions.DimensionMissingCoordinateError[source]

Bases: rioxarray.exceptions.RioXarrayError

This is raised when the dimension does not have the supporting coordinate.

exception rioxarray.exceptions.InvalidDimensionOrder[source]

Bases: rioxarray.exceptions.DimensionError

This is raised when there the dimensions are not ordered correctly.

exception rioxarray.exceptions.MissingCRS[source]

Bases: rioxarray.exceptions.RioXarrayError

Missing the CRS in the dataset.

exception rioxarray.exceptions.NoDataInBounds[source]

Bases: rioxarray.exceptions.RioXarrayError

This is for when there are no data in the bounds for clipping a raster.

exception rioxarray.exceptions.OneDimensionalRaster[source]

Bases: rioxarray.exceptions.DimensionError

This is an error when you have a 1 dimensional raster.

exception rioxarray.exceptions.RioXarrayError[source]

Bases: RuntimeError

This is the base exception for errors in the rioxarray extension.

exception rioxarray.exceptions.SingleVariableDataset[source]

Bases: rioxarray.exceptions.RioXarrayError

This is for when you have a dataset with a single variable.

exception rioxarray.exceptions.TooManyDimensions[source]

Bases: rioxarray.exceptions.DimensionError

This is raised when there are more dimensions than is supported by the method