1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84
|
.. _getting_started:
Getting Started
================
Welcome! This page aims to help you gain a foundational understanding of rioxarray.
rio accessor
-------------
rioxarray `extends xarray <https://docs.xarray.dev/en/stable/internals/extending-xarray.html>`__
with the `rio` accessor. The `rio` accessor is activated by importing rioxarray like so:
.. code-block:: python
import rioxarray
You can learn how to `clip`, `merge`, and `reproject` rasters in the :ref:`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.
.. code-block:: python
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
:func:`rioxarray.open_rasterio` as the backend and always returns an ``xarray.Dataset``.
.. code-block:: python
import xarray
xds = xarray.open_dataset("my.tif", engine="rasterio")
You can also use :func:`rioxarray.open_rasterio`. This objects returned depend on
your input file type.
.. code-block:: python
import rioxarray
xds = rioxarray.open_rasterio("my.tif")
Why use :func:`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 <https://proj.org/faq.html#what-is-the-best-format-for-describing-coordinate-reference-systems>`__).
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
--------------------------
.. toctree::
:maxdepth: 1
crs_management.ipynb
nodata_management.ipynb
manage_information_loss.ipynb
|