eo-tides 0.6.3.dev1__tar.gz → 0.6.3.dev3__tar.gz

{eo_tides-0.6.3.dev1 → eo_tides-0.6.3.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: eo-tides
-Version: 0.6.3.dev1
+Version: 0.6.3.dev3
 Summary: Tide modelling tools for large-scale satellite earth observation analysis
 Project-URL: Homepage, https://GeoscienceAustralia.github.io/eo-tides/
 Project-URL: Repository, https://github.com/GeoscienceAustralia/eo-tides

{eo_tides-0.6.3.dev1 → eo_tides-0.6.3.dev3}/docs/setup.md

@@ -2,20 +2,30 @@
 
 !!! important
 
-    `eo-tides` provides tools for modelling tides using global ocean tide models but does not host or maintain the models themselves. **Users are responsible for accessing, using, and citing ocean tide models in compliance with each model's licensing terms.**
+    `eo-tides` provides tools for modelling tides using global ocean tide models but does not host or maintain the model data itself. **Users are responsible for accessing, using, and citing ocean tide model data in compliance with each model's licensing terms.**
 
-Once you [have installed `eo-tides`](install.md), we need to download and set up the external global ocean tide models required for `eo-tides` to work.
+Once you [have installed `eo-tides`](install.md), we need to download and set up the external global ocean tide model data required for `eo-tides` to work.
 The following documentation provides instructions for getting started with several common global ocean tide models.
 
 !!! tip
 
     Please refer to the [`pyTMD` documentation](https://pytmd.readthedocs.io/en/latest/getting_started/Getting-Started.html#directories) for additional instructions covering all other supported tide models.
 
+## Tide model files and harmonic tidal constituents
+
+Tides are driven by complex gravitational interactions between the Earth, moon, and sun, which create periodic and predictable variations in sea level. These variations can be decomposed into a set of **harmonic tidal constituents** (also known as "tidal constants") with unique amplitudes and phases that correspond to different celestial influences.
+
+**When downloading tide model data, you are retrieving these tidal constituents rather than direct modelled or measured tidal height outputs.** Global ocean tide models use amplitudes and phases from these tidal constituents to precisely reconstruct tidal variations, allowing them to predict tide heights for any location on the planet and any moment in time — even into the future.
+
+!!! tip
+
+    For a deep dive into the science of tide modelling and how harmonic tidal constituents are used by global ocean tide models, refer to [`pyTMD` Ocean and Load Tides documentation.](https://pytmd.readthedocs.io/en/latest/background/Tides.html)
+
 ## Setting up a tide model directory
 
 As a first step, we need to create a directory that will contain our tide model data.
 This directory will be accessed by all `eo-tides` functions.
-For example, we might want to store our tide models in a directory called `tide_models/`:
+For example, we might want to store our tide model data in a directory called `tide_models/`:
 
 ```
 tide_models/

{eo_tides-0.6.3.dev1 → eo_tides-0.6.3.dev3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "eo-tides"
-version = "0.6.3.dev1"
+version = "0.6.3.dev3"
 description = "Tide modelling tools for large-scale satellite earth observation analysis"
 authors = [
     { name = "Robbi Bishop-Taylor" },

{eo_tides-0.6.3.dev1 → eo_tides-0.6.3.dev3}/tests/conftest.py

@@ -105,7 +105,7 @@ def satellite_ds(satellite_ds_load):
 # Run once per session to generate symethic HAMTIDE11 files; autouse=True
 # allows this to run without being specifically called in tests
 @pytest.fixture(scope="session", autouse=True)
-def create_synthetic_model(base_dir="tests/data/tide_models_synthetic"):
+def create_synthetic_hamtide11(base_dir="tests/data/tide_models_synthetic"):
     """
     Generates and exports synthetic HAMTIDE11 model data
     to test clipping functionality.
@@ -116,16 +116,16 @@ def create_synthetic_model(base_dir="tests/data/tide_models_synthetic"):
     lon = np.arange(0, 360.125, 0.125)  # 2881 points
     lat = np.arange(-90, 90.125, 0.125)  # 1441 points
 
-    # List of hamtide tidal constituents
+    # List of HAMTIDE11 tidal constituents
     constituents = ["2n", "k1", "k2", "m2", "n2", "o1", "p1", "q1", "s2"]
 
-    # Create hamtide output directory
+    # Create HAMTIDE11 output directory
     hamtide_dir = base_dir / "hamtide"
     hamtide_dir.mkdir(parents=True, exist_ok=True)
 
     # Create and save a NetCDF for each constituent
     for constituent in constituents:
-        # Create synthetic hamtide dataset with random data
+        # Create synthetic HAMTIDE11 dataset with random data
         shape = (len(lat), len(lon))  # 1441, 2881
         data = np.random.random(shape).astype(np.float32)
         ds = xr.Dataset(
@@ -142,3 +142,69 @@ def create_synthetic_model(base_dir="tests/data/tide_models_synthetic"):
         # Export
         filename = hamtide_dir / f"{constituent}.hamtide11a.nc"
         ds.to_netcdf(filename)
+
+
+# Run once per session to generate symethic EOT20 files; autouse=True
+# allows this to run without being specifically called in tests
+@pytest.fixture(scope="session", autouse=True)
+def create_synthetic_eot20(base_dir="tests/data/tide_models_synthetic"):
+    """
+    Generates and exports synthetic EOT20 model data
+    to test clipping functionality.
+    """
+    base_dir = Path(base_dir)  # Ensure base_dir is a Path object
+
+    # Create coordinate arrays
+    lon = np.arange(0, 360.125, 0.125)  # 2881 points
+    lat = np.arange(-90, 90.125, 0.125)  # 1441 points
+
+    # List of EOT20 tidal constituents
+    constituents = [
+        "2N2",
+        "J1",
+        "K1",
+        "K2",
+        "M2",
+        "M4",
+        "MF",
+        "MM",
+        "N2",
+        "O1",
+        "P1",
+        "Q1",
+        "S1",
+        "S2",
+        "SA",
+        "SSA",
+        "T2",
+    ]
+
+    # Create EOT20 output directory
+    eot20_dir = base_dir / "EOT20/ocean_tides"
+    eot20_dir.mkdir(parents=True, exist_ok=True)
+
+    # Create and save a NetCDF for each constituent
+    for constituent in constituents:
+        # Create synthetic EOT20 dataset with random data
+        shape = (len(lat), len(lon))  # 1441, 2881
+        data = np.random.random(shape).astype(np.float64)
+
+        # Add NaN values to match original
+        mask = np.random.random(shape) < 0.2
+        data[mask] = np.nan
+
+        # Create the dataset
+        ds = xr.Dataset(
+            {
+                "amplitude": (("lat", "lon"), data),
+                "phase": (("lat", "lon"), data),
+                "imag": (("lat", "lon"), data),
+                "real": (("lat", "lon"), data),
+            },
+            coords={"lat": lat, "lon": lon},
+            attrs={"title": f"DGFI-TUM global empirical ocean tide model"},
+        )
+
+        # Export
+        filename = eot20_dir / f"{constituent}_ocean_eot20.nc"
+        ds.to_netcdf(filename)

{eo_tides-0.6.3.dev1 → eo_tides-0.6.3.dev3}/tests/test_utils.py

@@ -95,17 +95,21 @@ def test_clip_models():
     assert np.allclose(df_unclipped.tide_height, df_clipped.tide_height)
 
 
-# Test clipping across multiple global locations using synthetic HAMTIDE11 data
+# Test clipping across multiple global locations using synthetic tide data
 @pytest.mark.parametrize(
-    "bbox, point, name",
+    "model, bbox, point, name",
     [
-        ((-166, 14, -151, 29), (19.60, -155.46), "hawaii"),  # entirely W of prime meridian
-        ((-13, 49, 6, 60), (51.47, 0.84), "uk"),  # crossing prime meridian
-        ((105, -48, 160, -5), (-25.59, 153.03), "aus"),  # entirely E of prime meridian
-        ((-257, 7, -120, 63), (19.59, -155.45), "pacific"),  # crossing antimeridian
+        ("EOT20", (-166, 14, -151, 29), (19.60, -155.46), "hawaii"),  # entirely W of prime meridian
+        ("EOT20", (-13, 49, 6, 60), (51.47, 0.84), "uk"),  # crossing prime meridian
+        ("EOT20", (105, -48, 160, -5), (-25.59, 153.03), "aus"),  # entirely E of prime meridian
+        ("EOT20", (-257, 7, -120, 63), (19.59, -155.45), "pacific"),  # crossing antimeridian
+        ("HAMTIDE11", (-166, 14, -151, 29), (19.60, -155.46), "hawaii"),  # entirely W of prime meridian
+        ("HAMTIDE11", (-13, 49, 6, 60), (51.47, 0.84), "uk"),  # crossing prime meridian
+        ("HAMTIDE11", (105, -48, 160, -5), (-25.59, 153.03), "aus"),  # entirely E of prime meridian
+        ("HAMTIDE11", (-257, 7, -120, 63), (19.59, -155.45), "pacific"),  # crossing antimeridian
     ],
 )
-def test_clip_models_bbox(bbox, point, name):
+def test_clip_models_bbox(model, bbox, point, name):
     # Set input and output paths
     in_dir = "tests/data/tide_models_synthetic/"
     out_dir = f"tests/data/tide_models_synthetic_{name}/"
@@ -115,7 +119,7 @@ def test_clip_models_bbox(bbox, point, name):
         input_directory=in_dir,
         output_directory=out_dir,
         bbox=bbox,
-        model="HAMTIDE11",
+        model=model,
         overwrite=True,
     )
 
@@ -128,14 +132,14 @@ def test_clip_models_bbox(bbox, point, name):
         x=x,
         y=y,
         time=time,
-        model="HAMTIDE11",
+        model=model,
         directory=in_dir,
     )
     df_clipped = model_tides(
         x=x,
         y=y,
         time=time,
-        model="HAMTIDE11",
+        model=model,
         directory=out_dir,
     )
 

{eo_tides-0.6.3.dev1 → eo_tides-0.6.3.dev3}/tests/testing.ipynb

@@ -125,52 +125,99 @@
     "    return measured_tides_df.to_xarray()\n",
     "\n",
     "\n",
-    "def create_synthetic_model(base_dir=\"data/tide_models_synthetic\"):\n",
+    "def create_synthetic_hamtide11(base_dir=\"tests/data/tide_models_synthetic\"):\n",
     "    \"\"\"\n",
     "    Generates and exports synthetic HAMTIDE11 model data\n",
     "    to test clipping functionality.\n",
     "    \"\"\"\n",
     "    base_dir = Path(base_dir)  # Ensure base_dir is a Path object\n",
-    "    \n",
+    "\n",
     "    # Create coordinate arrays\n",
     "    lon = np.arange(0, 360.125, 0.125)  # 2881 points\n",
     "    lat = np.arange(-90, 90.125, 0.125)  # 1441 points\n",
-    "    \n",
-    "    # List of hamtide tidal constituents\n",
-    "    constituents = ['2n', 'k1', 'k2', 'm2', 'n2', 'o1', 'p1', 'q1', 's2']\n",
-    "    \n",
-    "    # Create hamtide output directory\n",
+    "\n",
+    "    # List of HAMTIDE11 tidal constituents\n",
+    "    constituents = [\"2n\", \"k1\", \"k2\", \"m2\", \"n2\", \"o1\", \"p1\", \"q1\", \"s2\"]\n",
+    "\n",
+    "    # Create HAMTIDE11 output directory\n",
     "    hamtide_dir = base_dir / \"hamtide\"\n",
     "    hamtide_dir.mkdir(parents=True, exist_ok=True)\n",
-    "    \n",
+    "\n",
     "    # Create and save a NetCDF for each constituent\n",
     "    for constituent in constituents:\n",
     "\n",
-    "        # Create synthetic hamtide dataset with random data\n",
+    "        # Create synthetic HAMTIDE11 dataset with random data\n",
     "        shape = (len(lat), len(lon))  # 1441, 2881\n",
     "        data = np.random.random(shape).astype(np.float32)\n",
     "        ds = xr.Dataset(\n",
     "            {\n",
-    "                'RE': (('LAT', 'LON'), data),\n",
-    "                'IM': (('LAT', 'LON'), data),\n",
-    "                'AMPL': (('LAT', 'LON'), data),\n",
-    "                'PHAS': (('LAT', 'LON'), data)\n",
+    "                \"RE\": ((\"LAT\", \"LON\"), data),\n",
+    "                \"IM\": ((\"LAT\", \"LON\"), data),\n",
+    "                \"AMPL\": ((\"LAT\", \"LON\"), data),\n",
+    "                \"PHAS\": ((\"LAT\", \"LON\"), data),\n",
     "            },\n",
-    "            coords={\n",
-    "                'LON': lon,\n",
-    "                'LAT': lat\n",
+    "            coords={\"LON\": lon, \"LAT\": lat},\n",
+    "            attrs={\"title\": f\"HAMTIDE11a: {constituent} ocean tide\"},\n",
+    "        )\n",
+    "\n",
+    "        # Export\n",
+    "        filename = hamtide_dir / f\"{constituent}.hamtide11a.nc\"\n",
+    "        ds.to_netcdf(filename)\n",
+    "\n",
+    "\n",
+    "def create_synthetic_eot20(base_dir=\"tests/data/tide_models_synthetic\"):\n",
+    "    \"\"\"\n",
+    "    Generates and exports synthetic EOT20 model data\n",
+    "    to test clipping functionality.\n",
+    "    \"\"\"\n",
+    "    base_dir = Path(base_dir)  # Ensure base_dir is a Path object\n",
+    "\n",
+    "    # Create coordinate arrays\n",
+    "    lon = np.arange(0, 360.125, 0.125)  # 2881 points\n",
+    "    lat = np.arange(-90, 90.125, 0.125)  # 1441 points\n",
+    "\n",
+    "    # List of EOT20 tidal constituents\n",
+    "    constituents = [\n",
+    "        \"2N2\", \"J1\", \"K1\", \"K2\", \"M2\", \"M4\", \"MF\", \"MM\", \"N2\",\n",
+    "        \"O1\", \"P1\", \"Q1\", \"S1\", \"S2\", \"SA\", \"SSA\", \"T2\",\n",
+    "    ]\n",
+    "\n",
+    "    # Create EOT20 output directory\n",
+    "    eot20_dir = base_dir / \"EOT20/ocean_tides\"\n",
+    "    eot20_dir.mkdir(parents=True, exist_ok=True)\n",
+    "\n",
+    "    # Create and save a NetCDF for each constituent\n",
+    "    for constituent in constituents:\n",
+    "\n",
+    "        # Create synthetic EOT20 dataset with random data\n",
+    "        shape = (len(lat), len(lon))  # 1441, 2881\n",
+    "        data = np.random.random(shape).astype(np.float64)\n",
+    "\n",
+    "        # Add NaN values to match original\n",
+    "        mask = np.random.random(shape) < 0.2\n",
+    "        data[mask] = np.nan\n",
+    "\n",
+    "        # Create the dataset\n",
+    "        ds = xr.Dataset(\n",
+    "            {\n",
+    "                \"amplitude\": ((\"lat\", \"lon\"), data),\n",
+    "                \"phase\": ((\"lat\", \"lon\"), data),\n",
+    "                \"imag\": ((\"lat\", \"lon\"), data),\n",
+    "                \"real\": ((\"lat\", \"lon\"), data),\n",
     "            },\n",
-    "            attrs={\"title\": f'HAMTIDE11a: {constituent} ocean tide'}\n",
+    "            coords={\"lat\": lat, \"lon\": lon},\n",
+    "            attrs={\"title\": f\"DGFI-TUM global empirical ocean tide model\"},\n",
     "        )\n",
     "\n",
     "        # Export\n",
-    "        filename = hamtide_dir / f'{constituent}.hamtide11a.nc'\n",
+    "        filename = eot20_dir / f\"{constituent}_ocean_eot20.nc\"\n",
     "        ds.to_netcdf(filename)\n",
     "\n",
     "\n",
     "satellite_ds = load_satellite_ds()\n",
     "measured_tides_ds = load_measured_tides_ds()\n",
-    "create_synthetic_model()"
+    "create_synthetic_eot20()\n",
+    "create_synthetic_hamtide11()"
    ]
   },
   {
@@ -235,7 +282,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": 5,
    "metadata": {},
    "outputs": [
     {
@@ -248,28 +295,33 @@
       "rootdir: /home/jovyan/Robbi/eo-tides\n",
       "configfile: pyproject.toml\n",
       "plugins: anyio-4.6.2.post1, nbval-0.11.0\n",
-      "collected 25 items / 20 deselected / 5 selected                                \u001b[0m\u001b[1m\n",
+      "collected 29 items / 20 deselected / 9 selected                                \u001b[0m\u001b[1m\n",
       "\n",
-      "tests/test_utils.py::test_clip_models \u001b[32mPASSED\u001b[0m\u001b[33m                             [ 20%]\u001b[0m\n",
-      "tests/test_utils.py::test_clip_models_bbox[bbox0-point0-hawaii] \u001b[32mPASSED\u001b[0m\u001b[33m   [ 40%]\u001b[0m\n",
-      "tests/test_utils.py::test_clip_models_bbox[bbox1-point1-uk] \u001b[32mPASSED\u001b[0m\u001b[33m       [ 60%]\u001b[0m\n",
-      "tests/test_utils.py::test_clip_models_bbox[bbox2-point2-aus] \u001b[32mPASSED\u001b[0m\u001b[33m      [ 80%]\u001b[0m\n",
-      "tests/test_utils.py::test_clip_models_bbox[bbox3-point3-pacific] \u001b[32mPASSED\u001b[0m\u001b[33m  [100%]\u001b[0m\n",
+      "tests/test_utils.py::test_clip_models \u001b[32mPASSED\u001b[0m\u001b[33m                             [ 11%]\u001b[0m\n",
+      "tests/test_utils.py::test_clip_models_bbox[EOT20-bbox0-point0-hawaii] \u001b[32mPASSED\u001b[0m\u001b[33m [ 22%]\u001b[0m\n",
+      "tests/test_utils.py::test_clip_models_bbox[EOT20-bbox1-point1-uk] \u001b[32mPASSED\u001b[0m\u001b[33m [ 33%]\u001b[0m\n",
+      "tests/test_utils.py::test_clip_models_bbox[EOT20-bbox2-point2-aus] \u001b[32mPASSED\u001b[0m\u001b[33m [ 44%]\u001b[0m\n",
+      "tests/test_utils.py::test_clip_models_bbox[EOT20-bbox3-point3-pacific] \u001b[32mPASSED\u001b[0m\u001b[33m [ 55%]\u001b[0m\n",
+      "tests/test_utils.py::test_clip_models_bbox[HAMTIDE11-bbox4-point4-hawaii] \u001b[32mPASSED\u001b[0m\u001b[33m [ 66%]\u001b[0m\n",
+      "tests/test_utils.py::test_clip_models_bbox[HAMTIDE11-bbox5-point5-uk] \u001b[32mPASSED\u001b[0m\u001b[33m [ 77%]\u001b[0m\n",
+      "tests/test_utils.py::test_clip_models_bbox[HAMTIDE11-bbox6-point6-aus] \u001b[32mPASSED\u001b[0m\u001b[33m [ 88%]\u001b[0m\n",
+      "tests/test_utils.py::test_clip_models_bbox[HAMTIDE11-bbox7-point7-pacific] \u001b[32mPASSED\u001b[0m\u001b[33m [100%]\u001b[0m\n",
       "\n",
       "\u001b[33m=============================== warnings summary ===============================\u001b[0m\n",
       "<frozen importlib._bootstrap>:241\n",
       "  <frozen importlib._bootstrap>:241: RuntimeWarning: numpy.ndarray size changed, may indicate binary incompatibility. Expected 16 from C header, got 96 from PyObject\n",
       "\n",
-      "tests/test_utils.py: 20 warnings\n",
+      "tests/test_utils.py: 36 warnings\n",
       "  /env/lib/python3.10/site-packages/pyproj/transformer.py:817: DeprecationWarning: Conversion of an array with ndim > 0 to a scalar is deprecated, and will error in future. Ensure you extract a single element from your array before performing this operation. (Deprecated NumPy 1.25.)\n",
       "    return self._transformer._transform_point(\n",
       "\n",
-      "tests/test_utils.py::test_clip_models_bbox[bbox0-point0-hawaii]\n",
-      "  /home/jovyan/Robbi/eo-tides/eo_tides/model.py:127: UserWarning: On-the-fly cropping is not compatible with the provided clipped model files; running with `crop=False`.\n",
-      "    warnings.warn(\"On-the-fly cropping is not compatible with the provided \"\n",
+      "tests/test_utils.py::test_clip_models_bbox[EOT20-bbox0-point0-hawaii]\n",
+      "tests/test_utils.py::test_clip_models_bbox[HAMTIDE11-bbox4-point4-hawaii]\n",
+      "  /home/jovyan/Robbi/eo-tides/eo_tides/model.py:125: UserWarning: On-the-fly cropping is not compatible with the provided clipped model files; running with `crop=False`.\n",
+      "    warnings.warn(\n",
       "\n",
       "-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html\n",
-      "\u001b[33m================ \u001b[32m5 passed\u001b[0m, \u001b[33m\u001b[1m20 deselected\u001b[0m, \u001b[33m\u001b[1m22 warnings\u001b[0m\u001b[33m in 16.32s\u001b[0m\u001b[33m ================\u001b[0m\n"
+      "\u001b[33m=========== \u001b[32m9 passed\u001b[0m, \u001b[33m\u001b[1m20 deselected\u001b[0m, \u001b[33m\u001b[1m39 warnings\u001b[0m\u001b[33m in 74.74s (0:01:14)\u001b[0m\u001b[33m ===========\u001b[0m\n"
      ]
     }
    ],