eo-tides 0.0.21__py3-none-any.whl → 0.0.22__py3-none-any.whl

eo_tides/model.py

@@ -243,7 +243,7 @@ def _model_tides(
             lon,
             lat,
             pytmd_model.model_file,
-            grid=pytmd_model.type,
+            grid=pytmd_model.file_format,
             crop=crop,
             bounds=bounds,
             method=method,
@@ -277,6 +277,10 @@ def _model_tides(
 
         # Delta time (TT - UT1)
         deltat = timescale.tt_ut1
+    else:
+        raise Exception(
+            f"Unsupported model format ({pytmd_model.format}). This may be due to an incompatible version of `pyTMD`."
+        )
 
     # Calculate complex phase in radians for Euler's
     cph = -1j * ph * np.pi / 180.0

eo_tides/stats.py

@@ -26,8 +26,10 @@ def tide_stats(
     tidepost_lon: float | None = None,
     plain_english: bool = True,
     plot: bool = True,
+    plot_col: str | None = None,
     modelled_freq: str = "2h",
     linear_reg: bool = False,
+    min_max_q: tuple = (0.0, 1.0),
     round_stats: int = 3,
     **model_tides_kwargs,
 ) -> pd.Series:
@@ -73,6 +75,10 @@ def tide_stats(
         An optional boolean indicating whether to plot how satellite-
         observed tide heights compare against the full tidal range.
         Defaults to True.
+    plot_col : str, optional
+        Optional name of a coordinate, dimension or variable in the array
+        that will be used to plot observations with unique symbols.
+        Defaults to None, which will plot all observations as circles.
     modelled_freq : str, optional
         An optional string giving the frequency at which to model tides
         when computing the full modelled tidal range. Defaults to '2h',
@@ -84,6 +90,11 @@ def tide_stats(
         increasing trends over time. This may indicate whether your
         satellite data may produce misleading trends based on uneven
         sampling of the local tide regime.
+    min_max_q : tuple, optional
+        Quantiles used to calculate max and min observed and modelled
+        astronomical tides. By default `(0.0, 1.0)` which is equivalent
+        to minimum and maximum; to use a softer threshold that is more
+        robust to outliers, use e.g. `(0.1, 0.9)`.
     round_stats : int, optional
         The number of decimal places used to round the output statistics.
         Defaults to 3.
@@ -135,6 +146,7 @@ def tide_stats(
         return_tideposts=True,
         **model_tides_kwargs,
     )
+    ds_tides = ds_tides.sortby("time")
 
     # Drop spatial ref for nicer plotting
     ds_tides = ds_tides.drop_vars("spatial_ref")
@@ -160,8 +172,8 @@ def tide_stats(
     # Get coarse statistics on all and observed tidal ranges
     obs_mean = ds_tides.tide_height.mean().item()
     all_mean = all_tides_df.tide_height.mean()
-    obs_min, obs_max = ds_tides.tide_height.quantile([0.0, 1.0]).values
-    all_min, all_max = all_tides_df.tide_height.quantile([0.0, 1.0]).values
+    obs_min, obs_max = ds_tides.tide_height.quantile(min_max_q).values
+    all_min, all_max = all_tides_df.tide_height.quantile(min_max_q).values
 
     # Calculate tidal range
     obs_range = obs_max - obs_min
@@ -169,47 +181,89 @@ def tide_stats(
 
     # Calculate Bishop-Taylor et al. 2018 tidal metrics
     spread = obs_range / all_range
-    low_tide_offset = abs(all_min - obs_min) / all_range
-    high_tide_offset = abs(all_max - obs_max) / all_range
+    low_tide_offset_m = abs(all_min - obs_min)
+    high_tide_offset_m = abs(all_max - obs_max)
+    low_tide_offset = low_tide_offset_m / all_range
+    high_tide_offset = high_tide_offset_m / all_range
+
+    # Plain text descriptors
+    mean_diff = "higher" if obs_mean > all_mean else "lower"
+    mean_diff_icon = "⬆️" if obs_mean > all_mean else "⬇️"
+    spread_icon = "🟢" if spread >= 0.9 else "🟡" if 0.7 < spread <= 0.9 else "🔴"
+    low_tide_icon = "🟢" if low_tide_offset <= 0.1 else "🟡" if 0.1 <= low_tide_offset < 0.2 else "🔴"
+    high_tide_icon = "🟢" if high_tide_offset <= 0.1 else "🟡" if 0.1 <= high_tide_offset < 0.2 else "🔴"
 
     # Extract x (time in decimal years) and y (distance) values
     all_times = all_tides_df.index.get_level_values("time")
-    all_x = all_times.year + ((all_times.dayofyear - 1) / 365) + ((all_times.hour - 1) / 24)
+    all_x = all_times.year + ((all_times.dayofyear - 1) / 365) + ((all_times.hour) / 24)
     time_period = all_x.max() - all_x.min()
 
     # Extract x (time in decimal years) and y (distance) values
-    obs_x = ds_tides.time.dt.year + ((ds_tides.time.dt.dayofyear - 1) / 365) + ((ds_tides.time.dt.hour - 1) / 24)
+    obs_x = ds_tides.time.dt.year + ((ds_tides.time.dt.dayofyear - 1) / 365) + ((ds_tides.time.dt.hour) / 24)
     obs_y = ds_tides.tide_height.values.astype(np.float32)
 
     # Compute linear regression
     obs_linreg = stats.linregress(x=obs_x, y=obs_y)
 
+    # return obs_linreg
+
     if plain_english:
+        print(f"\n\n🌊 Modelled astronomical tide range: {all_range:.2f} metres.")
+        print(f"🛰️ Observed tide range: {obs_range:.2f} metres.\n")
+        print(f"    {spread_icon} {spread:.0%} of the modelled astronomical tide range was observed at this location.")
+        print(
+            f"    {high_tide_icon} The highest {high_tide_offset:.0%} ({high_tide_offset_m:.2f} metres) of the tide range was never observed."
+        )
         print(
-            f"\n{spread:.0%} of the {all_range:.2f} m modelled astronomical "
-            f"tidal range is observed at this location.\nThe lowest "
-            f"{low_tide_offset:.0%} and highest {high_tide_offset:.0%} "
-            f"of astronomical tides are never observed.\n"
+            f"    {low_tide_icon} The lowest {low_tide_offset:.0%} ({low_tide_offset_m:.2f} metres) of the tide range was never observed.\n"
+        )
+        print(f"🌊 Mean modelled astronomical tide height: {all_mean:.2f} metres.")
+        print(f"🛰️ Mean observed tide height: {obs_mean:.2f} metres.\n")
+        print(
+            f"    {mean_diff_icon} The mean observed tide height was {obs_mean - all_mean:.2f} metres {mean_diff} than the mean modelled astronomical tide height."
         )
 
         if linear_reg:
-            if obs_linreg.pvalue > 0.05:
-                print(f"Observed tides show no significant trends " f"over the ~{time_period:.0f} year period.")
+            if obs_linreg.pvalue > 0.01:
+                print("    ➖ Observed tides showed no significant trends over time.")
             else:
-                obs_slope_desc = "decrease" if obs_linreg.slope < 0 else "increase"
+                obs_slope_desc = "decreasing" if obs_linreg.slope < 0 else "increasing"
                 print(
-                    f"Observed tides {obs_slope_desc} significantly "
-                    f"(p={obs_linreg.pvalue:.3f}) over time by "
-                    f"{obs_linreg.slope:.03f} m per year (i.e. a "
-                    f"~{time_period * obs_linreg.slope:.2f} m "
-                    f"{obs_slope_desc} over the ~{time_period:.0f} year period)."
+                    f"    ⚠️ Observed tides showed a significant {obs_slope_desc} trend over time (p={obs_linreg.pvalue:.3f}, {obs_linreg.slope:.2f} metres per year)"
                 )
 
     if plot:
         # Create plot and add all time and observed tide data
-        fig, ax = plt.subplots(figsize=(10, 5))
-        all_tides_df.reset_index(["x", "y"]).tide_height.plot(ax=ax, alpha=0.4)
-        ds_tides.tide_height.plot.line(ax=ax, marker="o", linewidth=0.0, color="black", markersize=2)
+        fig, ax = plt.subplots(figsize=(10, 6))
+        all_tides_df.reset_index(["x", "y"]).tide_height.plot(ax=ax, alpha=0.4, label="Modelled tides")
+
+        # Look through custom column values if provided
+        if plot_col is not None:
+            # Create a list of marker styles
+            markers = ["o", "^", "s", "D", "v", "<", ">", "p", "*", "h", "H", "+", "x", "d", "|", "_"]
+            for i, value in enumerate(np.unique(ds_tides[plot_col])):
+                ds_tides.where(ds_tides[plot_col] == value, drop=True).tide_height.plot.line(
+                    ax=ax,
+                    linewidth=0.0,
+                    color="black",
+                    marker=markers[i % len(markers)],
+                    markersize=4,
+                    label=value,
+                )
+        # Otherwise, plot all data at once
+        else:
+            ds_tides.tide_height.plot.line(
+                ax=ax, marker="o", linewidth=0.0, color="black", markersize=3.5, label="Satellite observations"
+            )
+
+        ax.legend(loc="upper center", bbox_to_anchor=(0.5, 1.04), ncol=20, borderaxespad=0, frameon=False)
+
+        ax.plot(
+            ds_tides.time.isel(time=[0, -1]),
+            obs_linreg.intercept + obs_linreg.slope * obs_x[[0, -1]],
+            "r",
+            label="fitted line",
+        )
 
         # Add horizontal lines for spread/offsets
         ax.axhline(obs_min, color="black", linestyle=":", linewidth=1)

{eo_tides-0.0.21.dist-info → eo_tides-0.0.22.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: eo-tides
-Version: 0.0.21
+Version: 0.0.22
 Summary: Tide modelling tools for large-scale satellite earth observation analysis
 Author-email: Robbi Bishop-Taylor <Robbi.BishopTaylor@ga.gov.au>
 Project-URL: Homepage, https://GeoscienceAustralia.github.io/eo-tides/
@@ -22,23 +22,24 @@ Classifier: Programming Language :: Python :: 3.12
 Requires-Python: <4.0,>=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: colorama
-Requires-Dist: geopandas >=1.0.0
-Requires-Dist: numpy
-Requires-Dist: odc-geo
-Requires-Dist: pandas
-Requires-Dist: pyproj
+Requires-Dist: colorama >=0.4.3
+Requires-Dist: geopandas >=0.10.0
+Requires-Dist: matplotlib >=3.8.0
+Requires-Dist: numpy >=1.26.0
+Requires-Dist: odc-geo >=0.4.7
+Requires-Dist: pandas >=2.2.0
+Requires-Dist: pyproj >=3.6.1
 Requires-Dist: pyTMD ==2.1.6
-Requires-Dist: scikit-learn
-Requires-Dist: scipy
-Requires-Dist: shapely
-Requires-Dist: tqdm
-Requires-Dist: xarray
+Requires-Dist: scikit-learn >=1.4.0
+Requires-Dist: scipy >=1.11.2
+Requires-Dist: shapely >=2.0.6
+Requires-Dist: tqdm >=4.55.0
+Requires-Dist: xarray >=2022.3.0
 Provides-Extra: notebooks
 Requires-Dist: odc-stac >=0.3.10 ; extra == 'notebooks'
-Requires-Dist: pystac-client ; extra == 'notebooks'
-Requires-Dist: folium ; extra == 'notebooks'
-Requires-Dist: matplotlib ; extra == 'notebooks'
+Requires-Dist: pystac-client >=0.8.3 ; extra == 'notebooks'
+Requires-Dist: folium >=0.16.0 ; extra == 'notebooks'
+Requires-Dist: planetary-computer >=1.0.0 ; extra == 'notebooks'
 
 # `eo-tides`: Tide modelling tools for large-scale satellite earth observation analysis
 

eo_tides-0.0.22.dist-info/RECORD

@@ -0,0 +1,11 @@
+eo_tides/__init__.py,sha256=TWmQNplePCcNAlua5WI_H7SShkWNk-Gd3X70EDEknSo,1557
+eo_tides/eo.py,sha256=K2Ubxvp5yYxVwAOaUZDHCIV_AppRuqMiQRtArhe7YOM,22480
+eo_tides/model.py,sha256=l7RmzRqr_-yrNMVwW0bisCSnxR9NFHrwWda6WvQHZKU,33129
+eo_tides/stats.py,sha256=-piIpX3SmZL8DJntSLORRozyAJ1-od49GU-p56Cs_lc,13663
+eo_tides/utils.py,sha256=l9VXJawQzaRBYaFMsP8VBeaN5VA3rFDdzcvF7Rk04Vc,5620
+eo_tides/validation.py,sha256=yFuIjAxS9qf097_n4DHWG4AOa6n4nt1HGibUkOkJW6o,11437
+eo_tides-0.0.22.dist-info/LICENSE,sha256=owxWsXViCL2J6Ks3XYhot7t4Y93nstmXAT95Zf030Cc,11350
+eo_tides-0.0.22.dist-info/METADATA,sha256=Ae6NT_B98l4eZauFon-YBdb04z02JKRhzI6cxfvMBxc,6452
+eo_tides-0.0.22.dist-info/WHEEL,sha256=GV9aMThwP_4oNCtvEC2ec3qUYutgWeAzklro_0m4WJQ,91
+eo_tides-0.0.22.dist-info/top_level.txt,sha256=lXZDUUM1DlLdKWHRn8zdmtW8Rx-eQOIWVvt0b8VGiyQ,9
+eo_tides-0.0.22.dist-info/RECORD,,

eo_tides-0.0.21.dist-info/RECORD

@@ -1,11 +0,0 @@
-eo_tides/__init__.py,sha256=TWmQNplePCcNAlua5WI_H7SShkWNk-Gd3X70EDEknSo,1557
-eo_tides/eo.py,sha256=K2Ubxvp5yYxVwAOaUZDHCIV_AppRuqMiQRtArhe7YOM,22480
-eo_tides/model.py,sha256=WC-3gBH-ToREl1RS6CxYJLfXlpy03vtwZKd_464QYcU,32958
-eo_tides/stats.py,sha256=gpkewfgM7ixOr_XXepkMHpezmvjlt5-Qo2xbUmzyKhs,10898
-eo_tides/utils.py,sha256=l9VXJawQzaRBYaFMsP8VBeaN5VA3rFDdzcvF7Rk04Vc,5620
-eo_tides/validation.py,sha256=yFuIjAxS9qf097_n4DHWG4AOa6n4nt1HGibUkOkJW6o,11437
-eo_tides-0.0.21.dist-info/LICENSE,sha256=owxWsXViCL2J6Ks3XYhot7t4Y93nstmXAT95Zf030Cc,11350
-eo_tides-0.0.21.dist-info/METADATA,sha256=t60AoRbSg9K6GEXlk3TCd9nrEQbaFrHp7rgAmwAda_g,6298
-eo_tides-0.0.21.dist-info/WHEEL,sha256=GV9aMThwP_4oNCtvEC2ec3qUYutgWeAzklro_0m4WJQ,91
-eo_tides-0.0.21.dist-info/top_level.txt,sha256=lXZDUUM1DlLdKWHRn8zdmtW8Rx-eQOIWVvt0b8VGiyQ,9
-eo_tides-0.0.21.dist-info/RECORD,,