Getting Started

Welcome! This page aims to help you gain a foundational understanding of rioxarray.

rio accessor

rioxarray extends xarray with the rio accessor. The rio accessor is activated by importing rioxarray like so:

import rioxarray

You can learn how to clip, merge, and reproject rasters in the Usage Examples section of the documentation. Need to export to a raster (GeoTiff)? There is an example for that as well.

Reading Files

xarray

Since rioxarray is an extension of xarray, you can load in files using the standard xarray open methods. If you use one of xarray’s open methods such as xarray.open_dataset to load netCDF files with the default engine, it is recommended to use decode_coords=”all”. This will load the grid mapping variable into coordinates for compatibility with rioxarray.

import xarray

xds = xarray.open_dataset("file.nc", decode_coords="all")

rioxarray

rioxarray 0.4+ enables passing engine=”rasterio” to xarray.open_dataset and xarray.open_mfdataset for xarray 0.18+. This uses rioxarray.open_rasterio() as the backend and always returns an xarray.Dataset.

import xarray

xds = xarray.open_dataset("my.tif", engine="rasterio")

You can also use rioxarray.open_rasterio(). This objects returned depend on your input file type.

import rioxarray

xds = rioxarray.open_rasterio("my.tif")

Why use rioxarray.open_rasterio() instead of xarray.open_rasterio?

  1. It supports multidimensional datasets such as netCDF.

  2. It stores the CRS as a WKT, which is the recommended format (PROJ FAQ).

  3. It loads in the CRS, transform, and nodata metadata in standard CF & GDAL locations.

  4. It supports masking and scaling data with the masked and mask_and_scale kwargs.

  5. It adds the coordinate axis CF metadata.

  6. It loads raster metadata into the attributes.

  7. xarray.open_rasterio is deprecated (since v0.20.0)

Introductory Information