Rioxarray

Warnings

• gotcha Many `.rio` operations (e.g., `reproject`, `bounds`, `resolution`) explicitly require a Coordinate Reference System (CRS) to be set on the DataArray. If the CRS is missing, these operations will raise an error.
  Fix: Always ensure your DataArray has a CRS set. When opening files, use `xr.open_dataarray(..., engine='rasterio')` to infer it. For in-memory arrays or when modifying, use `da.rio.write_crs(crs_string_or_object)`.
• breaking The `rasterio.crs.CRS` object, which `rioxarray` uses, became immutable in `rasterio` version 1.2.x (a dependency for `rioxarray >= 0.20.0`). This means direct in-place modification of CRS attributes (e.g., `da.rio.crs['init'] = 'epsg:4326'`) will now raise an error.
  Fix: Instead of modifying, create a new `CRS` object or use `da.rio.write_crs()` to completely replace the CRS. For example, `new_crs = rasterio.crs.CRS.from_epsg(4326)` then `da.rio.write_crs(new_crs)`.
• gotcha There can be nuances in handling `_FillValue` from NetCDF/HDF and `nodata` from GeoTIFFs. `rioxarray` attempts to unify these under `da.rio.nodata`, but inconsistencies or unexpected behavior can arise, especially when merging datasets or after reprojection where new `NaN` values might be introduced.
  Fix: Explicitly set and manage nodata values using `da.rio.write_nodata()` or `da.rio.update_attrs(nodata=...)` for consistency. Be mindful of `NaN` values introduced by transformations and handle them appropriately.
• deprecated The `da.rio.set_crs()` method is deprecated. While it may still function in current versions, it is recommended to use `da.rio.write_crs()` for better clarity and future compatibility.
  Fix: Replace `da.rio.set_crs(...)` with `da.rio.write_crs(...)`.
• gotcha When opening non-geospatial-specific file formats (e.g., generic NetCDF, HDF files without explicit geospatial metadata), you must explicitly specify `engine='rasterio'` with `xr.open_dataarray` or `xr.open_dataset` for `rioxarray` to process them. Otherwise, `xarray`'s default engine will be used, and the `.rio` accessor might not be available or fully functional.
  Fix: Always specify `engine='rasterio'` (e.g., `xr.open_dataarray('file.nc', engine='rasterio')`) when you intend `rioxarray` to handle the geospatial interpretation of a file.

Install

• pip install rioxarray Default Install
• pip install 'rioxarray[tools]' # For CLI tools, requires GDAL With CLI Tools

Imports

• rioxarray

  import rioxarray

  Importing `rioxarray` activates the `.rio` accessor on `xarray.DataArray` and `xarray.Dataset` objects. You don't typically import specific classes or functions directly from `rioxarray` for most common use cases.

Quickstart

Demonstrates how to create a simple xarray DataArray, assign geospatial metadata using the `.rio` accessor, and retrieve basic spatial properties like CRS, bounds, and resolution. It also includes a commented-out example of reprojection, a common geospatial operation.

import xarray as xr
import rioxarray # Enables the .rio accessor
import numpy as np

# Create a dummy DataArray for demonstration
# In a real scenario, you'd typically open a GeoTIFF like this:
# da = xr.open_dataarray("path/to/your/file.tif", engine="rasterio")

# Dummy data: a 2x2 grid representing a small geographic area
data = np.array([[10.1, 20.2], [30.3, 40.4]], dtype=np.float32)
coords = {
    "y": [45.5, 45.0],  # Example latitude (y-coordinate, usually decreasing)
    "x": [-120.0, -119.5], # Example longitude (x-coordinate, usually increasing)
}
da = xr.DataArray(data, coords=coords, dims=("y", "x"), name="temperature")

# Assign geospatial metadata using the .rio accessor
# These properties are typically inferred automatically when opening a geospatial file.
da = da.rio.write_crs("EPSG:4326") # WGS84 Geographic CRS
da = da.rio.set_spatial_dims(x_dim="x", y_dim="y") # Explicitly set spatial dimensions

print(f"Original CRS: {da.rio.crs}")
print(f"Original Bounds: {da.rio.bounds()}")
print(f"Original Resolution: {da.rio.resolution()}")
print(f"Original Width: {da.rio.width}")
print(f"Original Height: {da.rio.height}")

# Example of a common operation: Reproject to a different CRS
# Note: This operation requires 'pyproj' to be installed. Some systems 
# might also need GDAL for full functionality and performance.
# try:
#     # Reproject to Web Mercator (EPSG:3857)
#     reprojected_da = da.rio.reproject("EPSG:3857")
#     print(f"\nReprojected CRS: {reprojected_da.rio.crs}")
#     print(f"Reprojected Bounds: {reprojected_da.rio.bounds()}")
#     print(f"Reprojected Resolution: {reprojected_da.rio.resolution()}")
# except ImportError:
#     print("\nSkipping reprojection: 'pyproj' not installed. Install with 'pip install pyproj'.")
# except Exception as e:
#     print(f"\nCould not reproject: {e}")