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

eo_tides/eo.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 import os
+import warnings
 from typing import TYPE_CHECKING
 
 import odc.geo.xr
@@ -93,19 +94,17 @@ def _pixel_tides_resample(
 
 
 def tag_tides(
-    ds: xr.Dataset,
+    ds: xr.Dataset | xr.DataArray,
     model: str | list[str] = "EOT20",
     directory: str | os.PathLike | None = None,
     tidepost_lat: float | None = None,
     tidepost_lon: float | None = None,
-    ebb_flow: bool = False,
-    swap_dims: bool = False,
     **model_tides_kwargs,
-) -> xr.Dataset:
+) -> xr.DataArray:
     """
     Model tide heights for every timestep in a multi-dimensional
-    dataset, and add them as a new `tide_height` (and optionally,
-    `ebb_flow`) variable that "tags" each observation with tide data.
+    dataset, and return a new `tide_height` array that can
+    be used to "tag" each observation with tide data.
 
     The function models tides at the centroid of the dataset
     by default, but a custom tidal modelling location can
@@ -123,7 +122,7 @@ def tag_tides(
 
     Parameters
     ----------
-    ds : xarray.Dataset
+    ds : xarray.Dataset or xarray.DataArray
         A multi-dimensional dataset (e.g. "x", "y", "time") to
         tag with tide heights. This dataset must contain a "time"
         dimension.
@@ -143,16 +142,6 @@ def tag_tides(
         Optional coordinates used to model tides. The default is None,
         which uses the centroid of the dataset as the tide modelling
         location.
-    ebb_flow : bool, optional
-        An optional boolean indicating whether to compute if the
-        tide phase was ebbing (falling) or flowing (rising) for each
-        observation. The default is False; if set to True, a new
-        "ebb_flow" variable will be added to the dataset with each
-        observation labelled with "Ebb" or "Flow".
-    swap_dims : bool, optional
-        An optional boolean indicating whether to swap the `time`
-        dimension in the original `ds` to the new "tide_height"
-        variable. Defaults to False.
     **model_tides_kwargs :
         Optional parameters passed to the `eo_tides.model.model_tides`
         function. Important parameters include `cutoff` (used to
@@ -174,8 +163,6 @@ def tag_tides(
 
     # Standardise model into a list for easy handling. and verify only one
     model = [model] if isinstance(model, str) else model
-    if (len(model) > 1) & swap_dims:
-        raise ValueError("Can only swap dimensions when a single tide model is passed to `model`.")
 
     # If custom tide modelling locations are not provided, use the
     # dataset centroid
@@ -208,48 +195,38 @@ def tag_tides(
             f"`tidepost_lat` and `tidepost_lon` parameters."
         )
 
-    # Optionally calculate the tide phase for each observation
-    if ebb_flow:
-        # Model tides for a time 15 minutes prior to each previously
-        # modelled satellite acquisition time. This allows us to compare
-        # tide heights to see if they are rising or falling.
-        print("Modelling tidal phase (e.g. ebb or flow)")
-        tide_pre_df = model_tides(
-            x=lon,  # type: ignore
-            y=lat,  # type: ignore
-            time=(ds.time - pd.Timedelta("15 min")),
-            model=model,
-            directory=directory,
-            crs="EPSG:4326",
-            **model_tides_kwargs,
-        )
-
-        # Compare tides computed for each timestep. If the previous tide
-        # was higher than the current tide, the tide is 'ebbing'. If the
-        # previous tide was lower, the tide is 'flowing'
-        tide_df["ebb_flow"] = (tide_df.tide_height < tide_pre_df.tide_height.values).replace({
-            True: "Ebb",
-            False: "Flow",
-        })
+    # # Optionally calculate the tide phase for each observation
+    # if ebb_flow:
+    #     # Model tides for a time 15 minutes prior to each previously
+    #     # modelled satellite acquisition time. This allows us to compare
+    #     # tide heights to see if they are rising or falling.
+    #     print("Modelling tidal phase (e.g. ebb or flow)")
+    #     tide_pre_df = model_tides(
+    #         x=lon,  # type: ignore
+    #         y=lat,  # type: ignore
+    #         time=(ds.time - pd.Timedelta("15 min")),
+    #         model=model,
+    #         directory=directory,
+    #         crs="EPSG:4326",
+    #         **model_tides_kwargs,
+    #     )
+
+    #     # Compare tides computed for each timestep. If the previous tide
+    #     # was higher than the current tide, the tide is 'ebbing'. If the
+    #     # previous tide was lower, the tide is 'flowing'
+    #     tide_df["ebb_flow"] = (tide_df.tide_height < tide_pre_df.tide_height.values).replace({
+    #         True: "Ebb",
+    #         False: "Flow",
+    #     })
 
     # Convert to xarray format
-    tide_xr = tide_df.reset_index().set_index(["time", "tide_model"]).drop(["x", "y"], axis=1).to_xarray()
+    tide_xr = tide_df.reset_index().set_index(["time", "tide_model"]).drop(["x", "y"], axis=1).tide_height.to_xarray()
 
     # If only one tidal model exists, squeeze out "tide_model" dim
     if len(tide_xr.tide_model) == 1:
-        tide_xr = tide_xr.squeeze("tide_model", drop=True)
-
-    # Add each array into original dataset
-    for var in tide_xr.data_vars:
-        ds[var] = tide_xr[var]
-
-    # Swap dimensions and sort by tide height
-    if swap_dims:
-        ds = ds.swap_dims({"time": "tide_height"})
-        ds = ds.sortby("tide_height")
-        ds = ds.drop_vars("time")
+        tide_xr = tide_xr.squeeze("tide_model")
 
-    return ds
+    return tide_xr
 
 
 def pixel_tides(
@@ -493,8 +470,10 @@ def pixel_tides(
     # Set dtype to dtype of the input data as quantile always returns
     # float64 (memory intensive)
     if calculate_quantiles is not None:
-        print("Computing tide quantiles")
-        tides_lowres = tides_lowres.quantile(q=calculate_quantiles, dim="time").astype(tides_lowres.dtype)
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            print("Computing tide quantiles")
+            tides_lowres = tides_lowres.quantile(q=calculate_quantiles, dim="time").astype(tides_lowres.dtype)
 
     # If only one tidal model exists, squeeze out "tide_model" dim
     if len(tides_lowres.tide_model) == 1:

eo_tides/model.py

@@ -5,6 +5,7 @@ import os
 import pathlib
 import warnings
 from concurrent.futures import ProcessPoolExecutor
+from concurrent.futures.process import BrokenProcessPool
 from functools import partial
 from typing import TYPE_CHECKING
 
@@ -130,7 +131,7 @@ def list_models(
                 # Mark available models with a green tick
                 status = "✅"
                 print(f"{status:^{status_width}}│ {m:<{name_width}} │ {expected_paths[m]:<{path_width}}")
-        except:
+        except FileNotFoundError:
             if show_supported:
                 # Mark unavailable models with a red cross
                 status = "❌"
@@ -199,84 +200,99 @@ def _model_tides(
         lat.max() + buffer,
     ]
 
-    # Read tidal constants and interpolate to grid points
-    if pytmd_model.format in ("OTIS", "ATLAS-compact", "TMD3"):
-        amp, ph, D, c = pyTMD.io.OTIS.extract_constants(
-            lon,
-            lat,
-            pytmd_model.grid_file,
-            pytmd_model.model_file,
-            pytmd_model.projection,
-            type=pytmd_model.type,
-            grid=pytmd_model.file_format,
-            crop=crop,
-            bounds=bounds,
-            method=method,
-            extrapolate=extrapolate,
-            cutoff=cutoff,
-        )
+    try:
+        # Read tidal constants and interpolate to grid points
+        if pytmd_model.format in ("OTIS", "ATLAS-compact", "TMD3"):
+            amp, ph, D, c = pyTMD.io.OTIS.extract_constants(
+                lon,
+                lat,
+                pytmd_model.grid_file,
+                pytmd_model.model_file,
+                pytmd_model.projection,
+                type=pytmd_model.type,
+                grid=pytmd_model.file_format,
+                crop=crop,
+                bounds=bounds,
+                method=method,
+                extrapolate=extrapolate,
+                cutoff=cutoff,
+            )
 
-        # Use delta time at 2000.0 to match TMD outputs
-        deltat = np.zeros((len(timescale)), dtype=np.float64)
-
-    elif pytmd_model.format in ("ATLAS-netcdf",):
-        amp, ph, D, c = pyTMD.io.ATLAS.extract_constants(
-            lon,
-            lat,
-            pytmd_model.grid_file,
-            pytmd_model.model_file,
-            type=pytmd_model.type,
-            crop=crop,
-            bounds=bounds,
-            method=method,
-            extrapolate=extrapolate,
-            cutoff=cutoff,
-            scale=pytmd_model.scale,
-            compressed=pytmd_model.compressed,
-        )
+            # Use delta time at 2000.0 to match TMD outputs
+            deltat = np.zeros((len(timescale)), dtype=np.float64)
+
+        elif pytmd_model.format in ("ATLAS-netcdf",):
+            amp, ph, D, c = pyTMD.io.ATLAS.extract_constants(
+                lon,
+                lat,
+                pytmd_model.grid_file,
+                pytmd_model.model_file,
+                type=pytmd_model.type,
+                crop=crop,
+                bounds=bounds,
+                method=method,
+                extrapolate=extrapolate,
+                cutoff=cutoff,
+                scale=pytmd_model.scale,
+                compressed=pytmd_model.compressed,
+            )
 
-        # Use delta time at 2000.0 to match TMD outputs
-        deltat = np.zeros((len(timescale)), dtype=np.float64)
-
-    elif pytmd_model.format in ("GOT-ascii", "GOT-netcdf"):
-        amp, ph, c = pyTMD.io.GOT.extract_constants(
-            lon,
-            lat,
-            pytmd_model.model_file,
-            grid=pytmd_model.type,
-            crop=crop,
-            bounds=bounds,
-            method=method,
-            extrapolate=extrapolate,
-            cutoff=cutoff,
-            scale=pytmd_model.scale,
-            compressed=pytmd_model.compressed,
-        )
+            # Use delta time at 2000.0 to match TMD outputs
+            deltat = np.zeros((len(timescale)), dtype=np.float64)
+
+        elif pytmd_model.format in ("GOT-ascii", "GOT-netcdf"):
+            amp, ph, c = pyTMD.io.GOT.extract_constants(
+                lon,
+                lat,
+                pytmd_model.model_file,
+                grid=pytmd_model.file_format,
+                crop=crop,
+                bounds=bounds,
+                method=method,
+                extrapolate=extrapolate,
+                cutoff=cutoff,
+                scale=pytmd_model.scale,
+                compressed=pytmd_model.compressed,
+            )
 
-        # Delta time (TT - UT1)
-        deltat = timescale.tt_ut1
-
-    elif pytmd_model.format in ("FES-ascii", "FES-netcdf"):
-        amp, ph = pyTMD.io.FES.extract_constants(
-            lon,
-            lat,
-            pytmd_model.model_file,
-            type=pytmd_model.type,
-            version=pytmd_model.version,
-            crop=crop,
-            bounds=bounds,
-            method=method,
-            extrapolate=extrapolate,
-            cutoff=cutoff,
-            scale=pytmd_model.scale,
-            compressed=pytmd_model.compressed,
-        )
+            # Delta time (TT - UT1)
+            deltat = timescale.tt_ut1
+
+        elif pytmd_model.format in ("FES-ascii", "FES-netcdf"):
+            amp, ph = pyTMD.io.FES.extract_constants(
+                lon,
+                lat,
+                pytmd_model.model_file,
+                type=pytmd_model.type,
+                version=pytmd_model.version,
+                crop=crop,
+                bounds=bounds,
+                method=method,
+                extrapolate=extrapolate,
+                cutoff=cutoff,
+                scale=pytmd_model.scale,
+                compressed=pytmd_model.compressed,
+            )
 
-        # Available model constituents
-        c = pytmd_model.constituents
+            # Available model constituents
+            c = pytmd_model.constituents
 
-        # Delta time (TT - UT1)
-        deltat = timescale.tt_ut1
+            # 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`."
+            )
+
+    # Raise error if constituent files no not cover analysis extent
+    except IndexError:
+        error_msg = (
+            f"The {model} tide model constituent files do not cover the requested analysis extent. "
+            "This can occur if you are using clipped model files to improve run times. "
+            "Consider using model files that cover your analysis area, or set `crop=False` "
+            "to reduce the extent of tide model constituent files that is loaded."
+        )
+        raise Exception(error_msg)
 
     # Calculate complex phase in radians for Euler's
     cph = -1j * ph * np.pi / 180.0
@@ -783,12 +799,19 @@ def model_tides(
                 )
 
             # Apply func in parallel, iterating through each input param
-            model_outputs = list(
-                tqdm(
-                    executor.map(iter_func, model_iters, x_iters, y_iters, time_iters),
-                    total=len(model_iters),
-                ),
-            )
+            try:
+                model_outputs = list(
+                    tqdm(
+                        executor.map(iter_func, model_iters, x_iters, y_iters, time_iters),
+                        total=len(model_iters),
+                    ),
+                )
+            except BrokenProcessPool:
+                error_msg = (
+                    "Parallelised tide modelling failed, likely to to an out-of-memory error. "
+                    "Try reducing the size of your analysis, or set `parallel=False`."
+                )
+                raise RuntimeError(error_msg)
 
     # Model tides in series if parallelisation is off
     else:

eo_tides/stats.py

@@ -8,16 +8,133 @@ import matplotlib.pyplot as plt
 import numpy as np
 import odc.geo.xr
 import pandas as pd
+import xarray as xr
 from scipy import stats
 
 # Only import if running type checking
 if TYPE_CHECKING:
     import xarray as xr
 
-from .eo import tag_tides
+from .eo import pixel_tides, tag_tides
 from .model import model_tides
 
 
+def _plot_biases(
+    all_tides_df,
+    obs_tides_da,
+    lat,
+    lot,
+    hat,
+    hot,
+    offset_low,
+    offset_high,
+    spread,
+    plot_col,
+    obs_linreg,
+    obs_x,
+    all_timerange,
+):
+    """
+    Plot tide bias statistics as a figure, including both
+    satellite observations and all modelled tides.
+    """
+
+    # Create plot and add all time and observed tide data
+    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(plot_col)):
+            obs_tides_da.sel(time=plot_col == value).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:
+        obs_tides_da.plot.line(
+            ax=ax,
+            marker="o",
+            linewidth=0.0,
+            color="black",
+            markersize=3.5,
+            label="Satellite observations",
+        )
+
+    # Add legend and remove title
+    ax.legend(
+        loc="upper center",
+        bbox_to_anchor=(0.5, 1.04),
+        ncol=20,
+        borderaxespad=0,
+        frameon=False,
+    )
+    ax.set_title("")
+
+    # Add linear regression line
+    if obs_linreg is not None:
+        ax.plot(
+            obs_tides_da.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(lot, color="black", linestyle=":", linewidth=1)
+    ax.axhline(hot, color="black", linestyle=":", linewidth=1)
+    ax.axhline(lat, color="black", linestyle=":", linewidth=1)
+    ax.axhline(hat, color="black", linestyle=":", linewidth=1)
+
+    # Add text annotations for spread/offsets
+    ax.annotate(
+        f"    High tide\n    offset ({offset_high:.0%})",
+        xy=(all_timerange.max(), np.mean([hat, hot])),
+        va="center",
+    )
+    ax.annotate(
+        f"    Spread\n    ({spread:.0%})",
+        xy=(all_timerange.max(), np.mean([lot, hot])),
+        va="center",
+    )
+    ax.annotate(
+        f"    Low tide\n    offset ({offset_low:.0%})",
+        xy=(all_timerange.max(), np.mean([lat, lot])),
+    )
+
+    # Remove top right axes and add labels
+    ax.spines["right"].set_visible(False)
+    ax.spines["top"].set_visible(False)
+    ax.set_ylabel("Tide height (m)")
+    ax.set_xlabel("")
+    ax.margins(x=0.015)
+
+    return fig
+
+
 def tide_stats(
     ds: xr.Dataset,
     model: str = "EOT20",
@@ -26,15 +143,18 @@ def tide_stats(
     tidepost_lon: float | None = None,
     plain_english: bool = True,
     plot: bool = True,
-    modelled_freq: str = "2h",
+    plot_col: str | None = None,
+    modelled_freq: str = "3h",
     linear_reg: bool = False,
+    min_max_q: tuple = (0.0, 1.0),
     round_stats: int = 3,
     **model_tides_kwargs,
 ) -> pd.Series:
     """
-    Takes a multi-dimensional dataset and generate statistics
-    about the data's astronomical and satellite-observed tide
-    conditions.
+    Takes a multi-dimensional dataset and generate tide statistics
+    and satellite-observed tide bias metrics, calculated based on
+    every timestep in the satellte data and the geographic centroid
+    of the imagery.
 
     By comparing the subset of tides observed by satellites
     against the full astronomical tidal range, we can evaluate
@@ -48,8 +168,8 @@ def tide_stats(
     Parameters
     ----------
     ds : xarray.Dataset
-        A multi-dimensional dataset (e.g. "x", "y", "time") to
-        use to calculate tide statistics. This dataset must contain
+        A multi-dimensional dataset (e.g. "x", "y", "time") used
+        to calculate tide statistics. This dataset must contain
         a "time" dimension.
     model : string, optional
         The tide model to use to model tides. Defaults to "EOT20";
@@ -73,10 +193,14 @@ 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',
-        which computes a tide height for every two hours across the
+        when computing the full modelled tidal range. Defaults to '3h',
+        which computes a tide height for every three hours across the
         temporal extent of `ds`.
     linear_reg: bool, optional
         Whether to return linear regression statistics that assess
@@ -84,6 +208,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.
@@ -96,25 +225,27 @@ def tide_stats(
 
     Returns
     -------
-    A `pandas.Series` containing the following statistics:
-
-        - `tidepost_lat`: latitude used for modelling tide heights
-        - `tidepost_lon`: longitude used for modelling tide heights
-        - `observed_min_m`: minimum tide height observed by the satellite
-        - `all_min_m`: minimum tide height from all available tides
-        - `observed_max_m`: maximum tide height observed by the satellite
-        - `all_max_m`: maximum tide height from all available tides
-        - `observed_range_m`: tidal range observed by the satellite
-        - `all_range_m`: full astronomical tidal range based on all available tides
-        - `spread_m`: proportion of the full astronomical tidal range observed by the satellite (see Bishop-Taylor et al. 2018)
-        - `low_tide_offset`: proportion of the lowest tides never observed by the satellite (see Bishop-Taylor et al. 2018)
-        - `high_tide_offset`: proportion of the highest tides never observed by the satellite (see Bishop-Taylor et al. 2018)
-
-    If `linear_reg = True`, the output will also contain:
+    stats_df : pandas.Series
+        A `pandas.Series` containing the following statistics:
+
+        - `y`: latitude used for modelling tide heights
+        - `x`: longitude used for modelling tide heights
+        - `mot`: mean tide height observed by the satellite (metres)
+        - `mat`: mean modelled astronomical tide height (metres)
+        - `lot`: minimum tide height observed by the satellite (metres)
+        - `lat`: minimum tide height from modelled astronomical tidal range (metres)
+        - `hot`: maximum tide height observed by the satellite (metres)
+        - `hat`: maximum tide height from modelled astronomical tidal range (metres)
+        - `otr`: tidal range observed by the satellite (metres)
+        - `tr`: modelled astronomical tide range (metres)
+        - `spread`: proportion of the full modelled tidal range observed by the satellite
+        - `offset_low`: proportion of the lowest tides never observed by the satellite
+        - `offset_high`: proportion of the highest tides never observed by the satellite
+
+        If `linear_reg = True`, the output will also contain:
 
         - `observed_slope`: slope of any relationship between observed tide heights and time
         - `observed_pval`: significance/p-value of any relationship between observed tide heights and time
-
     """
     # Verify that only one tide model is provided
     if isinstance(model, list):
@@ -126,7 +257,7 @@ def tide_stats(
         tidepost_lon, tidepost_lat = ds.odc.geobox.geographic_extent.centroid.coords[0]
 
     # Model tides for each observation in the supplied xarray object
-    ds_tides = tag_tides(
+    obs_tides_da = tag_tides(
         ds,
         model=model,
         directory=directory,
@@ -135,14 +266,12 @@ def tide_stats(
         return_tideposts=True,
         **model_tides_kwargs,
     )
-
-    # Drop spatial ref for nicer plotting
-    ds_tides = ds_tides.drop_vars("spatial_ref")
+    obs_tides_da = obs_tides_da.sortby("time")
 
     # Generate range of times covering entire period of satellite record
     all_timerange = pd.date_range(
-        start=ds_tides.time.min().item(),
-        end=ds_tides.time.max().item(),
+        start=obs_tides_da.time.min().item(),
+        end=obs_tides_da.time.max().item(),
         freq=modelled_freq,
     )
 
@@ -158,10 +287,10 @@ def tide_stats(
     )
 
     # Get coarse statistics on all and observed tidal ranges
-    obs_mean = ds_tides.tide_height.mean().item()
+    obs_mean = obs_tides_da.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 = obs_tides_da.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,92 +298,84 @@ 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
-
-    # 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)
-    time_period = all_x.max() - all_x.min()
+    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
-    obs_x = ds_tides.time.dt.year + ((ds_tides.time.dt.dayofyear - 1) / 365) + ((ds_tides.time.dt.hour - 1) / 24)
-    obs_y = ds_tides.tide_height.values.astype(np.float32)
+    obs_x = (
+        obs_tides_da.time.dt.year + ((obs_tides_da.time.dt.dayofyear - 1) / 365) + ((obs_tides_da.time.dt.hour) / 24)
+    )
+    obs_y = obs_tides_da.values.astype(np.float32)
 
     # Compute linear regression
     obs_linreg = stats.linregress(x=obs_x, y=obs_y)
 
     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"\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"{high_tide_icon} The highest {high_tide_offset:.0%} ({high_tide_offset_m:.2f} metres) of the tide range was never observed."
+        )
+        print(
+            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)
-
-        # Add horizontal lines for spread/offsets
-        ax.axhline(obs_min, color="black", linestyle=":", linewidth=1)
-        ax.axhline(obs_max, color="black", linestyle=":", linewidth=1)
-        ax.axhline(all_min, color="black", linestyle=":", linewidth=1)
-        ax.axhline(all_max, color="black", linestyle=":", linewidth=1)
-
-        # Add text annotations for spread/offsets
-        ax.annotate(
-            f"    High tide\n    offset ({high_tide_offset:.0%})",
-            xy=(all_timerange.max(), np.mean([all_max, obs_max])),
-            va="center",
-        )
-        ax.annotate(
-            f"    Spread\n    ({spread:.0%})",
-            xy=(all_timerange.max(), np.mean([obs_min, obs_max])),
-            va="center",
-        )
-        ax.annotate(
-            f"    Low tide\n    offset ({low_tide_offset:.0%})",
-            xy=(all_timerange.max(), np.mean([all_min, obs_min])),
+        _plot_biases(
+            all_tides_df=all_tides_df,
+            obs_tides_da=obs_tides_da,
+            lat=all_min,
+            lot=obs_min,
+            hat=all_max,
+            hot=obs_max,
+            offset_low=low_tide_offset,
+            offset_high=high_tide_offset,
+            spread=spread,
+            plot_col=ds[plot_col] if plot_col else None,
+            obs_linreg=obs_linreg if linear_reg else None,
+            obs_x=obs_x,
+            all_timerange=all_timerange,
         )
 
-        # Remove top right axes and add labels
-        ax.spines["right"].set_visible(False)
-        ax.spines["top"].set_visible(False)
-        ax.set_ylabel("Tide height (m)")
-        ax.set_xlabel("")
-        ax.margins(x=0.015)
-
     # Export pandas.Series containing tidal stats
     output_stats = {
-        "tidepost_lat": tidepost_lat,
-        "tidepost_lon": tidepost_lon,
-        "observed_mean_m": obs_mean,
-        "all_mean_m": all_mean,
-        "observed_min_m": obs_min,
-        "all_min_m": all_min,
-        "observed_max_m": obs_max,
-        "all_max_m": all_max,
-        "observed_range_m": obs_range,
-        "all_range_m": all_range,
+        "y": tidepost_lat,
+        "x": tidepost_lon,
+        "mot": obs_mean,
+        "mat": all_mean,
+        "lot": obs_min,
+        "lat": all_min,
+        "hot": obs_max,
+        "hat": all_max,
+        "otr": obs_range,
+        "tr": all_range,
         "spread": spread,
-        "low_tide_offset": low_tide_offset,
-        "high_tide_offset": high_tide_offset,
+        "offset_low": low_tide_offset,
+        "offset_high": high_tide_offset,
     }
 
     if linear_reg:
@@ -263,4 +384,171 @@ def tide_stats(
             "observed_pval": obs_linreg.pvalue,
         })
 
-    return pd.Series(output_stats).round(round_stats)
+    # Return pandas data
+    stats_df = pd.Series(output_stats).round(round_stats)
+    return stats_df
+
+
+def pixel_stats(
+    ds: xr.Dataset | xr.DataArray,
+    model: str | list[str] = "EOT20",
+    directory: str | os.PathLike | None = None,
+    resample: bool = False,
+    modelled_freq="3h",
+    min_max_q=(0.0, 1.0),
+    extrapolate: bool = True,
+    cutoff: float = 10,
+    **pixel_tides_kwargs,
+) -> xr.Dataset:
+    """
+    Takes a multi-dimensional dataset and generate two-dimensional
+    tide statistics and satellite-observed tide bias metrics,
+    calculated based on every timestep in the satellte data and
+    modelled into the spatial extent of the imagery.
+
+    By comparing the subset of tides observed by satellites
+    against the full astronomical tidal range, we can evaluate
+    whether the tides observed by satellites are biased
+    (e.g. fail to observe either the highest or lowest tides).
+
+    Compared to `tide_stats`, this function models tide metrics
+    spatially to produce a two-dimensional output.
+
+    For more information about the tidal statistics computed by this
+    function, refer to Figure 8 in Bishop-Taylor et al. 2018:
+    <https://www.sciencedirect.com/science/article/pii/S0272771418308783#fig8>
+
+    Parameters
+    ----------
+    ds : xarray.Dataset or xarray.DataArray
+        A multi-dimensional dataset (e.g. "x", "y", "time") used
+        to calculate 2D tide statistics. This dataset must contain
+        a "time" dimension.
+    model : str or list of str, optional
+        The tide model (or models) to use to model tides. If a list is
+        provided, a new "tide_model" dimension will be added to `ds`.
+        Defaults to "EOT20"; for a full list of available/supported
+        models, run `eo_tides.model.list_models`.
+    directory : str, optional
+        The directory containing tide model data files. If no path is
+        provided, this will default to the environment variable
+        `EO_TIDES_TIDE_MODELS` if set, or raise an error if not.
+        Tide modelling files should be stored in sub-folders for each
+        model that match the structure required by `pyTMD`
+        (<https://geoscienceaustralia.github.io/eo-tides/setup/>).
+    resample : bool, optional
+        Whether to resample tide statistics back into `ds`'s original
+        higher resolution grid. Defaults to False, which will return
+        lower-resolution statistics that are typically sufficient for
+        most purposes.
+    modelled_freq : str, optional
+        An optional string giving the frequency at which to model tides
+        when computing the full modelled tidal range. Defaults to '3h',
+        which computes a tide height for every three hours across the
+        temporal extent of `ds`.
+    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)`.
+    extrapolate : bool, optional
+        Whether to extrapolate tides for x and y coordinates outside of
+        the valid tide modelling domain using nearest-neighbor. Defaults
+        to True.
+    cutoff : float, optional
+        Extrapolation cutoff in kilometers. To avoid producing tide
+        statistics too far inland, the default is 10 km.
+    **pixel_tides_kwargs :
+        Optional parameters passed to the `eo_tides.eo.pixel_tides`
+        function.
+
+    Returns
+    -------
+    stats_ds : xarray.Dataset
+        An `xarray.Dataset` containing the following statistics as two-dimensional data variables:
+
+        - `lot`: minimum tide height observed by the satellite (metres)
+        - `lat`: minimum tide height from modelled astronomical tidal range (metres)
+        - `hot`: maximum tide height observed by the satellite (metres)
+        - `hat`: maximum tide height from modelled astronomical tidal range (metres)
+        - `otr`: tidal range observed by the satellite (metres)
+        - `tr`: modelled astronomical tide range (metres)
+        - `spread`: proportion of the full modelled tidal range observed by the satellite
+        - `offset_low`: proportion of the lowest tides never observed by the satellite
+        - `offset_high`: proportion of the highest tides never observed by the satellite
+
+    """
+    # Model observed tides
+    obs_tides = pixel_tides(
+        ds,
+        resample=False,
+        model=model,
+        directory=directory,
+        calculate_quantiles=min_max_q,
+        extrapolate=extrapolate,
+        cutoff=cutoff,
+        **pixel_tides_kwargs,
+    )
+
+    # Generate times covering entire period of satellite record
+    all_timerange = pd.date_range(
+        start=ds.time.min().item(),
+        end=ds.time.max().item(),
+        freq=modelled_freq,
+    )
+
+    # Model all tides
+    all_tides = pixel_tides(
+        ds,
+        times=all_timerange,
+        model=model,
+        directory=directory,
+        calculate_quantiles=min_max_q,
+        resample=False,
+        extrapolate=extrapolate,
+        cutoff=cutoff,
+        **pixel_tides_kwargs,
+    )
+
+    # Calculate min and max tides
+    lot = obs_tides.isel(quantile=0)
+    hot = obs_tides.isel(quantile=-1)
+    lat = all_tides.isel(quantile=0)
+    hat = all_tides.isel(quantile=-1)
+
+    # Calculate tidal range
+    otr = hot - lot
+    tr = hat - lat
+
+    # Calculate Bishop-Taylor et al. 2018 tidal metrics
+    spread = otr / tr
+    offset_low_m = abs(lat - lot)
+    offset_high_m = abs(hat - hot)
+    offset_low = offset_low_m / tr
+    offset_high = offset_high_m / tr
+
+    # Combine into a single dataset
+    stats_ds = (
+        xr.merge(
+            [
+                hat.rename("hat"),
+                hot.rename("hot"),
+                lat.rename("lat"),
+                lot.rename("lot"),
+                otr.rename("otr"),
+                tr.rename("tr"),
+                spread.rename("spread"),
+                offset_low.rename("offset_low"),
+                offset_high.rename("offset_high"),
+            ],
+            compat="override",
+        )
+        .drop_vars("quantile")
+        .odc.assign_crs(crs=ds.odc.crs)
+    )
+
+    # Optionally resample into the original pixel grid of `ds`
+    if resample:
+        stats_ds = stats_ds.odc.reproject(how=ds.odc.geobox, resample_method="bilinear")
+
+    return stats_ds

eo_tides/validation.py

@@ -153,19 +153,21 @@ def _load_gauge_metadata(metadata_path):
 
 
 def _load_gesla_dataset(site, path, na_value):
-    gesla_df = (
-        pd.read_csv(
-            path,
-            skiprows=41,
-            names=["date", "time", "sea_level", "qc_flag", "use_flag"],
-            sep=r"\s+",  # sep="\s+",
-            parse_dates=[[0, 1]],
-            index_col=0,
-            na_values=na_value,
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", FutureWarning)
+        gesla_df = (
+            pd.read_csv(
+                path,
+                skiprows=41,
+                names=["date", "time", "sea_level", "qc_flag", "use_flag"],
+                sep=r"\s+",  # sep="\s+",
+                parse_dates=[[0, 1]],
+                index_col=0,
+                na_values=na_value,
+            )
+            .rename_axis("time")
+            .assign(site_code=site)
         )
-        .rename_axis("time")
-        .assign(site_code=site)
-    )
 
     return gesla_df
 
@@ -267,7 +269,12 @@ def load_gauge_gesla(
 
     # If x and y are single numbers, select nearest row
     elif isinstance(x, Number) & isinstance(y, Number):
-        site_code = _nearest_row(metadata_gdf, x, y, max_distance).site_code
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            site_code = (
+                _nearest_row(metadata_gdf, x, y, max_distance).rename({"index_right": "site_code"}, axis=1).site_code
+            )
+            # site_code = _nearest_row(metadata_gdf, x, y, max_distance).site_code
 
         # Raise exception if no valid tide gauges are found
         if site_code.isnull().all():

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: eo-tides
-Version: 0.0.21
+Version: 0.0.23
 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,25 @@ 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: odc-geo[tiff,warp] >=0.4.7 ; 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
 
@@ -46,7 +48,7 @@ Requires-Dist: matplotlib ; extra == 'notebooks'
 
 [![Release](https://img.shields.io/github/v/release/GeoscienceAustralia/eo-tides)](https://pypi.org/project/eo-tides/)
 [![Build status](https://img.shields.io/github/actions/workflow/status/GeoscienceAustralia/eo-tides/main.yml?branch=main)](https://github.com/GeoscienceAustralia/eo-tides/actions/workflows/main.yml?query=branch%3Amain)
-![Python Version from PEP 621 TOML](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2FGeoscienceAustralia%2Feo-tides%2Frefs%2Fheads%2Fmain%2Fpyproject.toml)
+![Python Version from PEP 621 TOML](https://img.shields.io/pypi/pyversions/eo-tides)
 [![codecov](https://codecov.io/gh/GeoscienceAustralia/eo-tides/branch/main/graph/badge.svg)](https://codecov.io/gh/GeoscienceAustralia/eo-tides)
 [![License](https://img.shields.io/github/license/GeoscienceAustralia/eo-tides)](https://img.shields.io/github/license/GeoscienceAustralia/eo-tides)
 
@@ -69,9 +71,9 @@ These tools can be applied to petabytes of freely available satellite data (e.g.
 - 🌊 Model tides from multiple global ocean tide models in parallel, and return tide heights in standardised `pandas.DataFrame` format for further analysis
 - 🛰️ "Tag" satellite data with tide height and stage based on the exact moment of image acquisition
 - 🌐 Model tides for every individual satellite pixel, producing three-dimensional "tide height" `xarray`-format datacubes that can be integrated with satellite data
-<!-- - 🎯 Combine multiple tide models into a single locally-optimised "ensemble" model informed by satellite altimetry and satellite-observed patterns of tidal inundation -->
 - 📈 Calculate statistics describing local tide dynamics, as well as biases caused by interactions between tidal processes and satellite orbits
 - 🛠️ Validate modelled tides using measured sea levels from coastal tide gauges (e.g. [GESLA Global Extreme Sea Level Analysis](https://gesla.org/))
+<!-- - 🎯 Combine multiple tide models into a single locally-optimised "ensemble" model informed by satellite altimetry and satellite-observed patterns of tidal inundation -->
 
 ## Supported tide models
 
@@ -85,6 +87,10 @@ These tools can be applied to petabytes of freely available satellite data (e.g.
 
 For instructions on how to set up these models for use in `eo-tides`, refer to [Setting up tide models](setup.md).
 
+## Installing and setting up `eo-tides`
+
+To get started with `eo-tides`, follow the [Installation](https://geoscienceaustralia.github.io/eo-tides/install/) and [Setting up tide models](https://geoscienceaustralia.github.io/eo-tides/setup/) guides.
+
 ## Citing `eo-tides`
 
 To cite `eo-tides` in your work, please use the following citation:
@@ -92,3 +98,8 @@ To cite `eo-tides` in your work, please use the following citation:
 ```
 Bishop-Taylor, R., Sagar, S., Phillips, C., & Newey, V. (2024). eo-tides: Tide modelling tools for large-scale satellite earth observation analysis. https://github.com/GeoscienceAustralia/eo-tides
 ```
+
+## Acknowledgements
+
+For a full list of acknowledgements, refer to [Citations and Credits](https://geoscienceaustralia.github.io/eo-tides/credits/).
+This repository was initialised using the [`cookiecutter-uv`](https://github.com/fpgmaas/cookiecutter-uv) package.

eo_tides-0.0.23.dist-info/RECORD

@@ -0,0 +1,11 @@
+eo_tides/__init__.py,sha256=TWmQNplePCcNAlua5WI_H7SShkWNk-Gd3X70EDEknSo,1557
+eo_tides/eo.py,sha256=OTFjchQWpSfgi2Q62mFBj6ckmy_1B_ExCAmex4UT4js,21616
+eo_tides/model.py,sha256=XoJoIa6SmcAR8v1IDisqV8nW44XfY4YU4HWCoTgokx0,34390
+eo_tides/stats.py,sha256=9nfa7_obkS4tiHrQ1WTutuy2jlHtFg-cmOqP3l_Q7b8,20644
+eo_tides/utils.py,sha256=l9VXJawQzaRBYaFMsP8VBeaN5VA3rFDdzcvF7Rk04Vc,5620
+eo_tides/validation.py,sha256=JjTUqDfbR189m_6W1bpaSolQIHNTLicTHN7z9O_nr3s,11828
+eo_tides-0.0.23.dist-info/LICENSE,sha256=owxWsXViCL2J6Ks3XYhot7t4Y93nstmXAT95Zf030Cc,11350
+eo_tides-0.0.23.dist-info/METADATA,sha256=P01mYqtSyfTHIVAduGhTPyRbQe-ZNuCJXhYqKa4sq_s,6902
+eo_tides-0.0.23.dist-info/WHEEL,sha256=OVMc5UfuAQiSplgO0_WdW7vXVGAt9Hdd6qtN4HotdyA,91
+eo_tides-0.0.23.dist-info/top_level.txt,sha256=lXZDUUM1DlLdKWHRn8zdmtW8Rx-eQOIWVvt0b8VGiyQ,9
+eo_tides-0.0.23.dist-info/RECORD,,

{eo_tides-0.0.21.dist-info → eo_tides-0.0.23.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.1.0)
+Generator: setuptools (75.2.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

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,,