FEAT: Update FieldSet.describe() to print output and update docs (#2738)

* FEAT: Update FieldSet.describe() to print output

* Update docstring

* Adding fieldset.describe() calls to tutorials

* Don't hide output in tutorial_quickstart

* Update fieldset printing in interp-notebook

---------

Co-authored-by: Erik van Sebille <erikvansebille@gmail.com>

Author: VeckoTheGecko

docs/getting_started/tutorial_quickstart.md

@@ -52,11 +52,10 @@ ds_fset = parcels.convert.copernicusmarine_to_sgrid(fields=fields)
 fieldset = parcels.FieldSet.from_sgrid_conventions(ds_fset)
 ```
 
-You can inspect the `fieldset` by simply printing it:
+You can inspect the `parcels.FieldSet` object with the `describe` method in order to see which `parcels.Field`s are included, and which grid and interpolation method is used for each field. This also gives information on the type of mesh and the time interval of the `parcels.FieldSet`:
 
 ```{code-cell}
-:tags: [hide-output]
-print(fieldset)
+fieldset.describe()
 ```
 
 The subset contains a region of the Agulhas current along the southeastern coast of Africa:

docs/user_guide/examples/tutorial_fesom.ipynb

@@ -148,11 +148,7 @@
    "source": [
     "fieldset = parcels.FieldSet.from_ugrid_conventions(ds, mesh=\"spherical\")\n",
     "\n",
-    "for name, field in fieldset.fields.items():\n",
-    "    # TODO clean this up when #2683 is implemented\n",
-    "    print(\n",
-    "        f\"{name:>4s}  ->  {type(field).__name__:<11s}  interp={field.interp_method.__class__.__name__}\"\n",
-    "    )"
+    "fieldset.describe()"
    ]
   },
   {

docs/user_guide/examples/tutorial_interpolation.ipynb

@@ -129,8 +129,8 @@
     "    fieldset.P.interp_method = (\n",
     "        p_interp  # setting the interpolation method for fieldset.P\n",
     "    )\n",
+    "    fieldset.describe()\n",
     "\n",
-    "    print(fieldset.P.interp_method.__class__.__name__)\n",
     "    xv, yv = np.meshgrid(np.linspace(0, 1, 8), np.linspace(0, 1, 8))\n",
     "    pset[p_interp.__class__.__name__] = parcels.ParticleSet(\n",
     "        fieldset, pclass=SampleParticle, x=xv.flatten(), y=yv.flatten()\n",

docs/user_guide/examples/tutorial_schism.ipynb

@@ -215,12 +215,7 @@
    "source": [
     "fieldset = parcels.FieldSet.from_ugrid_conventions(uxds, mesh=\"flat\")\n",
     "\n",
-    "for name, field in fieldset.fields.items():\n",
-    "    # TODO clean this up when #2683 is implemented\n",
-    "    print(\n",
-    "        f\"{name:>4s} -> {type(field).__name__:<11s} interp={field.interp_method.__class__.__name__}\"\n",
-    "    )\n",
-    "print(\"time interval:\", fieldset.time_interval)"
+    "fieldset.describe()"
    ]
   },
   {

src/parcels/_core/fieldset.py

@@ -1,8 +1,9 @@
 from __future__ import annotations
 
 import functools
+import sys
 from collections.abc import Iterable
-from typing import TYPE_CHECKING
+from typing import IO, TYPE_CHECKING
 
 import cf_xarray  # noqa: F401
 import numpy as np
@@ -285,9 +286,21 @@ def from_sgrid_conventions(
         model = StructuredModelData.from_sgrid_conventions(ds, mesh, vector_fields)
         return cls([model])
 
-    def describe(self):
-        """Return a table description of a FieldSet, which fields it has and their interpolation methods."""
-        return fieldset_describe(self)
+    def describe(self, buf: IO | None = None) -> None:
+        """
+        Summary of a FieldSet including available Fields, associated
+        interpolators, and context values.
+
+        Parameters
+        ----------
+        buf : file-like, default: sys.stdout
+            writable buffer
+        """
+        if buf is None:
+            buf = sys.stdout
+        assert buf is not None
+
+        buf.write(fieldset_describe(self))
 
 
 def assert_compatible_fieldsets(left: FieldSet, right: FieldSet) -> None:

src/parcels/_reprs.py

@@ -252,7 +252,8 @@ def fieldset_describe(fieldset: FieldSet) -> str:
 
 
 mesh: {fieldset.models[0].grid._mesh}
-time interval: {_print_time_interval(fieldset.time_interval)}"""
+time interval: {_print_time_interval(fieldset.time_interval)}
+"""
     )
 
 

tests/test_fieldset.py

@@ -1,4 +1,5 @@
 from datetime import timedelta
+from io import StringIO
 
 import cf_xarray  # noqa: F401
 import cftime
@@ -395,6 +396,7 @@ def test_fieldset_add_context_values():
 )
 def test_fieldset_describe(fieldset_two_models: FieldSet):
     fieldset = fieldset_two_models
+    io = StringIO()
     expected = """\
 | Name           | Type        | Grid number   | Interp method / value   |
 |:---------------|:------------|:--------------|:------------------------|
@@ -409,6 +411,8 @@ def test_fieldset_describe(fieldset_two_models: FieldSet):
 | constant_field | Field       | 2             | XConstantField(...)     |
 
 mesh: flat
-time interval: (np.datetime64('2000-01-01T00:00:00.000000000'), np.datetime64('2001-01-01T00:00:00.000000000'))"""
-    actual = fieldset.describe()
+time interval: (np.datetime64('2000-01-01T00:00:00.000000000'), np.datetime64('2001-01-01T00:00:00.000000000'))
+"""
+    fieldset.describe(io)
+    actual = io.getvalue()
     assert actual == expected