Merge pull request #1920 from OceanParcels/1844-timestamps

Remove timestamps keyword from Field and FieldSet

Author: VeckoTheGecko

docs/documentation/index.rst

@@ -25,7 +25,6 @@ Parcels has several documentation and tutorial Jupyter notebooks and scripts whi
    ../examples/tutorial_periodic_boundaries.ipynb
    ../examples/tutorial_interpolation.ipynb
    ../examples/tutorial_unitconverters.ipynb
-   ../examples/tutorial_timestamps.ipynb
 
 
 .. nbgallery::

docs/examples/example_globcurrent.py

@@ -1,3 +1,4 @@
+from collections.abc import Callable
 from datetime import timedelta
 from glob import glob
 
@@ -8,11 +9,21 @@
 import parcels
 
 
+def Unit_to_units(d: dict) -> dict:
+    if "Unit" in d:
+        d["units"] = d.pop("Unit")
+    return d
+
+
+def xarray_patch_metadata(ds: xr.Dataset, f: Callable[[dict], dict]) -> xr.Dataset:
+    """Convert attrs"""
+    for var in ds.variables:
+        ds[var].attrs = f(ds[var].attrs)
+    return ds
+
+
 def set_globcurrent_fieldset(
     filename=None,
-    indices=None,
-    use_xarray=False,
-    timestamps=None,
 ):
     if filename is None:
         data_folder = parcels.download_example_dataset("GlobCurrent_example_data")
@@ -23,25 +34,18 @@ def set_globcurrent_fieldset(
         "U": "eastward_eulerian_current_velocity",
         "V": "northward_eulerian_current_velocity",
     }
-    if timestamps is None:
-        dimensions = {"lat": "lat", "lon": "lon", "time": "time"}
-    else:
-        dimensions = {"lat": "lat", "lon": "lon"}
-    if use_xarray:
-        ds = xr.open_mfdataset(filename, combine="by_coords")
-        return parcels.FieldSet.from_xarray_dataset(
-            ds,
-            variables,
-            dimensions,
-        )
-    else:
-        return parcels.FieldSet.from_netcdf(
-            filename,
-            variables,
-            dimensions,
-            indices,
-            timestamps=timestamps,
-        )
+    dimensions = {"lat": "lat", "lon": "lon", "time": "time"}
+    ds = (
+        xr.open_mfdataset(filename, combine="by_coords")
+        .pipe(xarray_patch_metadata, Unit_to_units)
+        .pipe(xr.decode_cf)
+    )
+
+    return parcels.FieldSet.from_xarray_dataset(
+        ds,
+        variables,
+        dimensions,
+    )
 
 
 @pytest.mark.v4remove(
@@ -51,15 +55,15 @@ def set_globcurrent_fieldset(
     "use_xarray", [True, pytest.param(False, marks=pytest.mark.xfail)]
 )
 def test_globcurrent_fieldset(use_xarray):
-    fieldset = set_globcurrent_fieldset(use_xarray=use_xarray)
+    fieldset = set_globcurrent_fieldset()
     assert fieldset.U.lon.size == 81
     assert fieldset.U.lat.size == 41
     assert fieldset.V.lon.size == 81
     assert fieldset.V.lat.size == 41
 
     if not use_xarray:
         indices = {"lon": [5], "lat": range(20, 30)}
-        fieldsetsub = set_globcurrent_fieldset(indices=indices, use_xarray=use_xarray)
+        fieldsetsub = set_globcurrent_fieldset(indices=indices)
         assert np.allclose(fieldsetsub.U.lon, fieldset.U.lon[indices["lon"]])
         assert np.allclose(fieldsetsub.U.lat, fieldset.U.lat[indices["lat"]])
         assert np.allclose(fieldsetsub.V.lon, fieldset.V.lon[indices["lon"]])
@@ -69,21 +73,20 @@ def test_globcurrent_fieldset(use_xarray):
 @pytest.mark.parametrize(
     "dt, lonstart, latstart", [(3600.0, 25, -35), (-3600.0, 20, -39)]
 )
-@pytest.mark.parametrize("use_xarray", [True, False])
-def test_globcurrent_fieldset_advancetime(dt, lonstart, latstart, use_xarray):
+def test_globcurrent_fieldset_advancetime(dt, lonstart, latstart):
     data_folder = parcels.download_example_dataset("GlobCurrent_example_data")
     basepath = str(data_folder / "20*-GLOBCURRENT-L4-CUReul_hs-ALT_SUM-v02.0-fv01.0.nc")
     files = sorted(glob(str(basepath)))
 
-    fieldsetsub = set_globcurrent_fieldset(files[0:10], use_xarray=use_xarray)
+    fieldsetsub = set_globcurrent_fieldset(files[0:10])
     psetsub = parcels.ParticleSet.from_list(
         fieldset=fieldsetsub,
         pclass=parcels.Particle,
         lon=[lonstart],
         lat=[latstart],
     )
 
-    fieldsetall = set_globcurrent_fieldset(files[0:10], use_xarray=use_xarray)
+    fieldsetall = set_globcurrent_fieldset(files[0:10])
     psetall = parcels.ParticleSet.from_list(
         fieldset=fieldsetall,
         pclass=parcels.Particle,
@@ -100,9 +103,8 @@ def test_globcurrent_fieldset_advancetime(dt, lonstart, latstart, use_xarray):
     assert abs(psetsub[0].lon - psetall[0].lon) < 1e-4
 
 
-@pytest.mark.parametrize("use_xarray", [True, False])
-def test_globcurrent_particles(use_xarray):
-    fieldset = set_globcurrent_fieldset(use_xarray=use_xarray)
+def test_globcurrent_particles():
+    fieldset = set_globcurrent_fieldset()
 
     lonstart = [25]
     latstart = [-35]
@@ -119,6 +121,10 @@ def test_globcurrent_particles(use_xarray):
     assert abs(pset[0].lat - -35.3) < 1
 
 
+@pytest.mark.v4remove
+@pytest.mark.xfail(
+    reason="Can't patch metadata without using xarray. v4 will natively use xarray anyway. GH1919."
+)
 @pytest.mark.parametrize("dt", [-300, 300])
 def test_globcurrent_xarray_vs_netcdf(dt):
     fieldsetNetcdf = set_globcurrent_fieldset(use_xarray=False)
@@ -139,6 +145,10 @@ def test_globcurrent_xarray_vs_netcdf(dt):
     assert np.allclose(psetN[0].lat, psetX[0].lat)
 
 
+@pytest.mark.v4remove
+@pytest.mark.xfail(
+    reason="Timeslices will be removed in v4, as users will be able to use xarray directly."
+)
 @pytest.mark.parametrize("dt", [-300, 300])
 def test_globcurrent_netcdf_timestamps(dt):
     fieldsetNetcdf = set_globcurrent_fieldset()
@@ -200,9 +210,8 @@ def test__particles_init_time():
     assert pset[0].time - pset4[0].time == 0
 
 
-@pytest.mark.parametrize("use_xarray", [True, False])
-def test_globcurrent_time_extrapolation_error(use_xarray):
-    fieldset = set_globcurrent_fieldset(use_xarray=use_xarray)
+def test_globcurrent_time_extrapolation_error():
+    fieldset = set_globcurrent_fieldset()
     pset = parcels.ParticleSet(
         fieldset,
         pclass=parcels.Particle,

docs/examples/tutorial_timestamps.ipynb

@@ -5,5 +5,7 @@ List of tasks that are important to do before the release of version 4 (but can'
 - [ ] Make migration guide for v3 to v4
 - [ ] Just prior to release: Update conda feedstock recipe dependencies (remove cgen and compiler dependencies). Make sure that recipe is up-to-date.
 - [ ] Revamp the oceanparcels.org landing page, and perhaps also consider new logo/branding?
-- [ ] Look into xarray and whether users can create periodic datasets without increasing the size of the original dataset (i.e., no compromise alternative to `time_periodic` param in v3). Update docs accordingly.
 - [ ] Rerun all the tutorials so that their output is in line with new v4 print statements etc
+- Documentation
+  - [ ] Look into xarray and whether users can create periodic datasets without increasing the size of the original dataset (i.e., no compromise alternative to `time_periodic` param in v3). Update docs accordingly.
+  - [ ] Look into xarray and whether users can create datasets from snapshots assigning different time dimensions without increasing the size of the original dataset (i.e., no compromise alternative to `timestamps` param in v3). Update docs accordingly.