Additional documentation for imas.util.to_xarray

Author: maarten-ic

docs/source/courses/advanced/xarray.rst

@@ -8,6 +8,8 @@ Create ``xarray.DataArray`` from an IDS
     recommend to use :py:func:`imas.util.to_xarray` instead of manually creating
     xarray ``DataArray``\ s.
 
+    See also: :ref:`Convert IMAS-Python IDSs directly to Xarray Datasets`.
+
 Let's start with an introduction of Xarray. According to `their website
 <https://docs.xarray.dev/en/stable/getting-started-guide/why-xarray.html>`_ (where you
 can also find an excellent summary of why that is useful):

docs/source/netcdf.rst

@@ -1,7 +1,7 @@
 .. _`IMAS netCDF files`:
 
-IMAS netCDF files
-=================
+IMAS netCDF files \& Xarray
+===========================
 
 .. toctree::
     :hidden:
@@ -69,6 +69,7 @@ features that are supported by DBEntries using ``imas_core`` respectively
       - Yes (requires ``imas_core >= 5.4.0``)
       - Not implemented
 
+.. _`Using IMAS netCDF files with 3rd-party tools`:
 
 Using IMAS netCDF files with 3rd-party tools
 --------------------------------------------
@@ -138,3 +139,47 @@ Validating an IMAS netCDF file
 IMAS netCDF files can be validated with IMAS-Python through the command line ``imas
 validate_nc <filename>``. See also :ref:`IMAS-Python Command Line tool` or type
 ``imas validate_nc --help`` in a command line.
+
+
+.. _`Convert IMAS-Python IDSs directly to Xarray Datasets`:
+
+Convert IMAS-Python IDSs directly to Xarray Datasets
+----------------------------------------------------
+
+In the section :ref:`Using IMAS netCDF files with 3rd-party tools`, we showed
+how to open an IMAS netCDF file with Xarray. However, IMAS-Python IDSs can also
+be converted directly to Xarray ``Dataset``\ s with
+:py:func:`imas.util.to_xarray`.
+
+This method can be used to convert a full IDS to an Xarray ``Dataset``, or only
+specific paths inside the IDS. The latter variant can also be combined with
+:ref:`lazy loading`. We'll show a small example below:
+
+.. code-block:: python
+    :caption: Converting a lazy loaded IDS to Xarray
+
+    import imas.training
+
+    # Open the training entry
+    with imas.training.get_training_db_entry() as training_entry:
+        # Lazy load the core_profiles IDS
+        core_profiles = training_entry.get("core_profiles", lazy=True)
+        # Load the average ion temperature and all coordinate data
+        xrds = imas.util.to_xarray(core_profiles, "profiles_1d.t_i_average")
+        # All relevant data is now loaded from the data entry into the xarray
+        # Dataset. We close the data entry by exiting the with-statement.
+
+    # Inspect what's inside the dataset
+    print(xrds.data_vars)
+    # Data variables:
+    #   profiles_1d.t_i_average
+
+    # Included coordinates depends on the used Data Dictionary version
+    print(xrds.coords)
+    # Coordinates:  (with DD 4.0.0)
+    # * time
+    #   profiles_1d.grid.area
+    #   profiles_1d.grid.volume
+    #   profiles_1d.grid.rho_tor
+    #   profiles_1d.grid.rho_tor_norm
+    #   profiles_1d.grid.psi