Add read_netcdf() to the io-docs

docs/api/io.rst

@@ -6,10 +6,10 @@ Input/output file formats
 DataFrames and xlsx/csv files
 -----------------------------
 
-A :class:`pandas.DataFrame` or a path to an :code:`xlsx` or :code:`csv`
-with data in the required structure (i.e., index/columns) can be imported
-directly by initializing an :class:`IamDataFrame` - see
-`this tutorial <../tutorials/data_table_formats.html>`_ for more information.
+A :class:`pandas.DataFrame` or a path to an *xlsx* or *csv* with data in the required
+structure (i.e., index/columns) can be imported directly by initializing an
+:class:`IamDataFrame` - see `this tutorial <../tutorials/data_table_formats.html>`_ for
+more information.
 
 Exporting to these formats is implemented via the following functions:
 
@@ -22,6 +22,38 @@ Exporting to these formats is implemented via the following functions:
 .. automethod:: IamDataFrame.to_csv
    :noindex:
 
+Integration with netcdf files
+-----------------------------
+
+`NetCDF <https://www.unidata.ucar.edu/software/netcdf/>`_ is a powerful file format that
+can efficiently store multiple scientific variables sharing the same dimensions.
+In climate science, data such as temperature, precipitation and radiation can be stored
+in four dimensions: a time dimension and three spatial dimensions (latitude, longitude,
+altitude).
+
+The |pyam| package supports reading and writing to netcdf files that have the following
+structure:
+
+- **Timeseries data** are stored such that each *variable* (in the sense of the IAMC
+  format) is a separate netcdf-data-variable with the dimensions *time*, *model*,
+  *scenario* and *region*. The *unit* is given as an attribute of the data variable.
+  The *long_name* attribute is used as the *variable* in the :class:`IamDataFrame`.
+  The *time* dimension can be either a datetime format or given as years (integer).
+
+- **Meta indicators** are stored as netcdf-data-variables with the dimensions *model*
+  and *scenario*.
+
+Read more about :ref:`pyam_data_model`. The :attr:`exclude <pyam.IamDataFrame.exclude>`
+attribute is not written to netcdf files.
+
+.. autofunction:: read_netcdf
+
+.. automethod:: IamDataFrame.to_netcdf
+   :noindex:
+
+.. automethod:: IamDataFrame.to_xarray
+   :noindex:
+
 The frictionless Data Package
 -----------------------------
 

docs/conf.py

@@ -330,6 +330,7 @@
     "nomenclature": ("https://nomenclature-iamc.readthedocs.io/en/stable", None),
     "ixmp4": ("https://docs.ece.iiasa.ac.at/projects/ixmp4/en/stable", None),
     "wbdata": ("https://wbdata.readthedocs.io/en/stable/", None),
+    "xarray": ("https://docs.xarray.dev/en/stable/", None),
 }
 
 # Set up the plotting gallery with plotly scraper

docs/data.rst

@@ -41,6 +41,8 @@ using the IAMC data format.
 
 .. _`CD-LINKS`: https://www.cd-links.org
 
+.. _pyam_data_model:
+
 The pyam data model
 -------------------
 

docs/index.rst

@@ -24,7 +24,7 @@ Release v\ |version|.
 .. |ruff| image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json
    :target: https://github.com/astral-sh/ruff
 
-.. |python| image:: https://img.shields.io/badge/python-≥3.10,<3.13-blue?logo=python&logoColor=white
+.. |python| image:: https://img.shields.io/badge/python-≥3.10,<3.14-blue?logo=python&logoColor=white
    :target: https://github.com/IAMconsortium/pyam
 
 .. |pytest| image:: https://img.shields.io/github/actions/workflow/status/iamconsortium/pyam/pytest.yml?logo=GitHub&label=pytest