DOC: Contributing instructions, BytesIO, switch from rasterio, GDAL config, & external courses

CONTRIBUTING.rst

@@ -126,6 +126,32 @@ This assumes you have cloned the rioxarray repository and are in the base folder
         'source /venv/bin/activate && python -m pytest'
 
 
+Build documentation
+-------------------
+
+This assumes you have cloned the rioxarray repository, installed rioxarray conda environment and are in the base folder.
+
+1. Install documentation libraries
+
+.. code-block:: bash
+
+    conda activate rioxarray
+    conda install -c conda-forge pandoc
+    pip install -e . --group doc
+
+2. Build the documentation
+
+.. code-block:: bash
+
+    make docs
+
+If you are on Windows or don't have ``make`` installed:
+
+.. code-block:: bash
+
+    sphinx-build -b html docs/ docs/_build/
+
+
 Pull Request Guidelines
 -----------------------
 

docs/conf.py

@@ -60,7 +60,7 @@
 
 # General information about the project.
 project = "rioxarray"
-copyright = "2019-2025, Corteva Agriscience™"
+copyright = "2019-2026, Corteva Agriscience™"
 author = "rioxarray Contributors"
 
 # The version info for the project you're documenting, acts as replacement

docs/examples/convert_to_raster.ipynb

@@ -632,7 +632,7 @@
     "    \"planet_scope_tiled.tif\",\n",
     "    tiled=True,  # GDAL: By default striped TIFF files are created. This option can be used to force creation of tiled TIFF files.\n",
     "    windowed=True,  # rioxarray: read & write one window at a time\n",
-    ") "
+    ")"
    ]
   },
   {
@@ -651,6 +651,28 @@
    "source": [
     "!rio info planet_scope_tiled.tif"
    ]
+  },
+  {
+   "metadata": {},
+   "cell_type": "markdown",
+   "source": [
+    "## Write your raster in `BytesIO` object\n",
+    "\n",
+    "As recommended in the [planetary computer documentation](https://planetarycomputer.microsoft.com/docs/quickstarts/storage/#Write-to-Azure-Blob-Storage), your raster can be directly written into a `BytesIO` object. Then, it can be uploaded into your favorite cloud storage."
+   ]
+  },
+  {
+   "metadata": {},
+   "cell_type": "code",
+   "source": [
+    "import io\n",
+    "\n",
+    "with io.BytesIO() as buffer:\n",
+    "    rds.rio.to_raster(buffer, driver=\"COG\")\n",
+    "    buffer.seek(0)"
+   ],
+   "outputs": [],
+   "execution_count": null
   }
  ],
  "metadata": {

docs/examples/examples.rst

@@ -36,3 +36,11 @@ This page contains links to a collection of examples of how to use rioxarray.
    How to mask NetCDF time series data from a shapefile in Python? <https://gis.stackexchange.com/a/354798/144357>
    Extract data from raster at a point <https://gis.stackexchange.com/a/358058/144357>
    Convert raster to CSV with lat, lon, and value columns <https://gis.stackexchange.com/a/358057/144357>
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: External courses:
+
+   Geospatial Python courses by The Carpentries <https://carpentries-incubator.github.io/geospatial-python/06-raster-intro.html>
+   Geospatial Python courses by Earth Lab at University of Colorado, Boulder <https://earthdatascience.org/courses/use-data-open-source-python/intro-raster-data-python/>

docs/getting_started/gdal_env.rst

@@ -0,0 +1,43 @@
+.. _gdal_env:
+
+Configure GDAL environment
+==========================
+
+``rioxarray`` relies on ``rasterio`` so setting up GDAL environment stays the same. See ``rasterio``'s `documentation <https://rasterio.readthedocs.io/en/latest/topics/configuration.html#rasterio>`__ for more insights.
+
+Setting up GDAL environment is very useful when working with cloud-stored data.
+You can find Development Seed's TiTiler environment proposition `here <https://developmentseed.org/titiler/advanced/performance_tuning/#recommended-configuration-for-dynamic-tiling>`__.
+
+With Dask clusters
+~~~~~~~~~~~~~~~~~~
+
+When setting up a Dask cluster, be sure to pass the GDAL environment (and AWS session) to every workers.
+First create a function setting up the env and then submit it to every worker.
+
+.. code-block:: python
+
+    import os
+    from dask.distributed import Client
+
+
+    def set_env():
+        # Set that to dask workers to make process=True work on cloud
+        os.environ["AWS_S3_ENDPOINT"] = os.getenv("AWS_S3_ENDPOINT")
+        os.environ["AWS_S3_AWS_ACCESS_KEY_ID"] = os.getenv("AWS_S3_AWS_ACCESS_KEY_ID")
+        os.environ["AWS_S3_AWS_SECRET_ACCESS_KEY"] = os.getenv(
+            "AWS_S3_AWS_SECRET_ACCESS_KEY"
+        )
+        os.environ["CPL_VSIL_CURL_ALLOWED_EXTENSIONS"] = ".vrt"
+
+
+    # Run the client
+    with Client(processes=True) as client:
+
+        # Propagate the env variables
+        client.run(set_env)
+        ...
+
+
+.. note::
+
+  There are gotchas with the environment and dask workers, see this `discussion <https://github.com/corteva/rioxarray/discussions/630>`__ for more insights.

docs/getting_started/getting_started.rst

@@ -79,6 +79,8 @@ Introductory Information
 .. toctree::
    :maxdepth: 1
 
+   switching_from_rasterio
    crs_management.ipynb
    nodata_management.ipynb
    manage_information_loss.ipynb
+   gdal_env

docs/getting_started/switching_from_rasterio.rst

@@ -0,0 +1,119 @@
+.. _switching_from_rasterio:
+
+Switching from ``rasterio``
+===========================
+
+Reasons to switch from ``rasterio`` to ``rioxarray``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Usually, switching from ``rasterio`` to ``rioxarray`` means you are working with rasters and you have to adapt your code to ``xarray``.
+
+``xarray`` is a powerful abstraction of both the raster dataset and the raster array. There is a lot of advantages to unite these two notions under the same object, as it simplifies the use of the functions, using attributes stored in the object rather than passing arguments to the functions.
+
+``xarray`` comes also with a lot of very interesting built-in functions and can leverage several backends to replace ``numpy`` in cases where it is limiting (out-of-memory computation, running the code on clusters, on GPU...). Dask is one of the most well-knwown. ``rioxarray`` handles some basic ``dask`` features in I/O (see `Dask I/O example <https://corteva.github.io/rioxarray/html/examples/dask_read_write.html>`__) but is not designed to support ``dask`` in more evolved functions such as reproject.
+
+Beware, ``xarray`` comes also with gotchas! You can see some of them in `the dedicated section <https://corteva.github.io/rioxarray/html/getting_started/manage_information_loss.html>`__.
+
+
+  .. note::
+
+    ``rasterio`` Dataset and xarray Dataset are two completely different things! Please be careful with these overlapping names.
+
+Equivalences between ``rasterio`` and ``rioxarray``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To ease the switch from ``rasterio`` and ``rioxarray``, here is a table of the usual parameters or functions used.
+
+``ds`` stands for ``rasterio`` Dataset
+
+Profile
+-------
+
+Here is the parameters that you can derive from ``rasterio``'s Dataset profile:
+
++----------------------------------+-----------------------------------------------------------------------------------------------------------------------+
+| ``rasterio`` from ``ds.profile`` | ``rioxarray`` from DataArray                                                                                          |
++==================================+=======================================================================================================================+
+| :attr:`blockxsize`               | :attr:`.encoding["preferred_chunks"]["x"]`                                                                            |
++----------------------------------+-----------------------------------------------------------------------------------------------------------------------+
+| :attr:`blockysize`               | :attr:`.encoding["preferred_chunks"]["y"]`                                                                            |
++----------------------------------+-----------------------------------------------------------------------------------------------------------------------+
+| :attr:`compress`                 | *Unused in rioxarray*                                                                                                 |
++----------------------------------+-----------------------------------------------------------------------------------------------------------------------+
+| :attr:`~rasterio.io.DatasetReader.count` | :attr:`rio.count <rioxarray.rioxarray.XRasterBase.count>`                                                             |
++----------------------------------+-----------------------------------------------------------------------------------------------------------------------+
+| :attr:`~rasterio.io.DatasetReader.crs` | :attr:`rio.crs <rioxarray.rioxarray.XRasterBase.crs>`                                                                 |
++----------------------------------+-----------------------------------------------------------------------------------------------------------------------+
+| :attr:`~rasterio.io.DatasetReader.driver` | Unused in rioxarray                                                                                                   |
++----------------------------------+-----------------------------------------------------------------------------------------------------------------------+
+| :attr:`~rasterio.io.DatasetReader.dtype` | :attr:`.encoding["rasterio_dtype"]`                                                                                   |
++----------------------------------+-----------------------------------------------------------------------------------------------------------------------+
+| :attr:`~rasterio.io.DatasetReader.height` | :attr:`rio.height <rioxarray.rioxarray.XRasterBase.height>`                                                           |
++----------------------------------+-----------------------------------------------------------------------------------------------------------------------+
+| :attr:`interleave`               | Unused in rioxarray                                                                                                   |
++----------------------------------+-----------------------------------------------------------------------------------------------------------------------+
+| :attr:`~rasterio.io.DatasetReader.nodata` | :attr:`rio.nodata <rioxarray.raster_array.RasterArray.nodata>` (or `encoded_nodata <nodata_management.html>`_ )       |
++----------------------------------+-----------------------------------------------------------------------------------------------------------------------+
+| :attr:`tiled`                    | Unused in rioxarray                                                                                                   |
++----------------------------------+-----------------------------------------------------------------------------------------------------------------------+
+| :attr:~rasterio.io.DatasetReader.transform` | :func:`rio.transform() <rioxarray.rioxarray.XRasterBase.transform>`                                                   |
++----------------------------------+-----------------------------------------------------------------------------------------------------------------------+
+| :attr:`~rasterio.io.DatasetReader.width` | :attr:`rio.width <rioxarray.rioxarray.XRasterBase.width>`                                                             |
++----------------------------------+-----------------------------------------------------------------------------------------------------------------------+
+
+The values not used in ``rioxarray`` comes from the abstraction of the dataset in ``xarray``: a dataset no longer belongs to a file on disk even if read from it. The driver and other file-related notions are meaningless in this context.
+
+Other dataset parameters
+------------------------
+
++----------------------------------+-------------------------------------------------------------------+
+| ``rasterio`` from ``ds``         | ``rioxarray`` from DataArray                                      |
++==================================+===================================================================+
+| :attr:`~rasterio.io.DatasetReader.gcps` or  :func:`~rasterio.io.DatasetReader.get_gcps` | :func:`rio.get_gcps() <rioxarray.rioxarray.XRasterBase.get_gcps>`  |
++----------------------------------+-------------------------------------------------------------------+
+| :attr:`~rasterio.io.DatasetReader.rpcs`  | :func:`rio.get_rpcs() <rioxarray.rioxarray.XRasterBase.get_rpcs>` |
++----------------------------------+-------------------------------------------------------------------+
+| :attr:`~rasterio.io.DatasetReader.bounds` | :func:`rio.bounds() <rioxarray.rioxarray.XRasterBase.bounds>`     |
++----------------------------------+-------------------------------------------------------------------+
+
+Functions
+---------
+
++------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
+| ``rasterio``                       | ``rioxarray``                                                                                                                     |
++====================================+===================================================================================================================================+
+| :func:`rasterio.open`            | :func:`rioxarray.open_rasterio` or :attr:`xarray.open_dataset(..., engine="rasterio", decode_coords="all") <xarray.open_dataset>` |
++------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
+| :func:`~rasterio.io.DatasetReader.read`                  | :func:`compute() <xarray.DataArray.compute>` (load data into memory)                                                              |
++------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
+| :func:`ds.read(... window=)  <rasterio.io.DatasetReader.read>` | :func:`rio.isel_window() <rioxarray.rioxarray.XRasterBase.isel_window>`                                                           |
++------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
+| :func:`~rasterio.io.DatasetWriter.write` | :func:`rio.to_raster() <rioxarray.raster_array.RasterArray.to_raster>`                                                            |
++------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
+| :func:`mask(..., crop=False) <rasterio.mask.mask>` | :func:`rio.clip(..., drop=False) <rioxarray.raster_array.RasterArray.clip>`                                                       |
++------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
+| :func:`mask(..., crop=True) <rasterio.mask.mask>`  | :func:`rio clip(..., drop=True) <rioxarray.raster_array.RasterArray.clip>`                                                        |
++------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
+| :func:`~rasterio.warp.reproject`           | :func:`rio.reproject() <rioxarray.raster_array.RasterArray.reproject>`                                                            |
++------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
+| :func:`~rasterio.merge.merge`              | :func:`rioxarray.merge.merge_arrays`                                                                                              |
++------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
+| :func:`~rasterio.fill.fillnodata`          | :func:`rio.interpolate_na() <rioxarray.raster_array.RasterArray.interpolate_na>`                                                  |
++------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
+
+
+
+By default, ``xarray`` is lazy and therefore not loaded into memory, hence the ``compute`` equivalent to ``read``.
+
+
+Going back to ``rasterio``
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``rioxarray`` 0.21+ enables recreating a ``rasterio`` Dataset from ``rioxarray``.
+This is useful when translating your code from ``rasterio`` to ``rioxarray``, even if it is sub-optimal, because the array will be loaded and written in memory behind the hood.
+It is always better to look for ``rioxarray``'s native functions.
+
+.. code-block:: python
+
+    with dataarray.rio.to_rasterio_dataset() as rio_ds:
+        ...