eo-tides 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

eo_tides/stats.py

@@ -13,10 +13,13 @@ from scipy import stats
 
 # Only import if running type checking
 if TYPE_CHECKING:
+    import datetime
+
     import xarray as xr
+    from odc.geo.geobox import GeoBox
 
-from .eo import pixel_tides, tag_tides
-from .model import model_tides
+from .eo import _standardise_inputs, pixel_tides, tag_tides
+from .model import DatetimeLike, model_tides
 
 
 def _plot_biases(
@@ -136,7 +139,8 @@ def _plot_biases(
 
 
 def tide_stats(
-    ds: xr.Dataset,
+    data: xr.Dataset | xr.DataArray | GeoBox,
+    time: DatetimeLike | None = None,
     model: str = "EOT20",
     directory: str | os.PathLike | None = None,
     tidepost_lat: float | None = None,
@@ -167,15 +171,23 @@ def tide_stats(
 
     Parameters
     ----------
-    ds : xarray.Dataset
-        A multi-dimensional dataset (e.g. "x", "y", "time") used
-        to calculate tide statistics. This dataset must contain
-        a "time" dimension.
-    model : string, optional
+    data : xarray.Dataset or xarray.DataArray or odc.geo.geobox.GeoBox
+        A multi-dimensional dataset or GeoBox pixel grid that will
+        be used to calculate tide statistics. If `data` is an
+        xarray object, it should include a "time" dimension.
+        If no "time" dimension exists or if `data` is a GeoBox,
+        then times must be passed using the `time` parameter.
+    time : DatetimeLike, optional
+        By default, tides will be modelled using times from the
+        "time" dimension of `data`. Alternatively, this param can
+        be used to provide a custom set of times. Accepts any format
+        that can be converted by `pandas.to_datetime()`. For example:
+        `time=pd.date_range(start="2000", end="2001", freq="5h")`
+    model : str, optional
         The tide model to use to model tides. Defaults to "EOT20";
         for a full list of available/supported models, run
         `eo_tides.model.list_models`.
-    directory : string, optional
+    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.
@@ -201,7 +213,7 @@ def tide_stats(
         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`.
+        temporal extent of `data`.
     linear_reg: bool, optional
         Whether to return linear regression statistics that assess
         whether satellite-observed tides show any decreasing  or
@@ -247,6 +259,9 @@ def tide_stats(
         - `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
     """
+    # Standardise data inputs, time and models
+    gbox, time_coords = _standardise_inputs(data, time)
+
     # Verify that only one tide model is provided
     if isinstance(model, list):
         raise Exception("Only single tide models are supported by `tide_stats`.")
@@ -254,11 +269,13 @@ def tide_stats(
     # If custom tide modelling locations are not provided, use the
     # dataset centroid
     if not tidepost_lat or not tidepost_lon:
-        tidepost_lon, tidepost_lat = ds.odc.geobox.geographic_extent.centroid.coords[0]
+        tidepost_lon, tidepost_lat = gbox.geographic_extent.centroid.coords[0]
 
     # Model tides for each observation in the supplied xarray object
+    assert time_coords is not None
     obs_tides_da = tag_tides(
-        ds,
+        gbox,
+        time=time_coords,
         model=model,
         directory=directory,
         tidepost_lat=tidepost_lat,  # type: ignore
@@ -266,12 +283,13 @@ def tide_stats(
         return_tideposts=True,
         **model_tides_kwargs,
     )
-    obs_tides_da = obs_tides_da.sortby("time")
+    if isinstance(data, (xr.Dataset, xr.DataArray)):
+        obs_tides_da = obs_tides_da.reindex_like(data)
 
     # Generate range of times covering entire period of satellite record
     all_timerange = pd.date_range(
-        start=obs_tides_da.time.min().item(),
-        end=obs_tides_da.time.max().item(),
+        start=time_coords.min().item(),
+        end=time_coords.max().item(),
         freq=modelled_freq,
     )
 
@@ -355,7 +373,7 @@ def tide_stats(
             offset_low=low_tide_offset,
             offset_high=high_tide_offset,
             spread=spread,
-            plot_col=ds[plot_col] if plot_col else None,
+            plot_col=data[plot_col] if plot_col else None,
             obs_linreg=obs_linreg if linear_reg else None,
             obs_x=obs_x,
             all_timerange=all_timerange,
@@ -390,12 +408,13 @@ def tide_stats(
 
 
 def pixel_stats(
-    ds: xr.Dataset | xr.DataArray,
+    data: xr.Dataset | xr.DataArray | GeoBox,
+    time: DatetimeLike | None = None,
     model: str | list[str] = "EOT20",
     directory: str | os.PathLike | None = None,
     resample: bool = False,
-    modelled_freq="3h",
-    min_max_q=(0.0, 1.0),
+    modelled_freq: str = "3h",
+    min_max_q: tuple[float, float] = (0.0, 1.0),
     extrapolate: bool = True,
     cutoff: float = 10,
     **pixel_tides_kwargs,
@@ -420,13 +439,21 @@ def pixel_stats(
 
     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.
+    data : xarray.Dataset or xarray.DataArray or odc.geo.geobox.GeoBox
+        A multi-dimensional dataset or GeoBox pixel grid that will
+        be used to calculate 2D tide statistics. If `data`
+        is an xarray object, it should include a "time" dimension.
+        If no "time" dimension exists or if `data` is a GeoBox,
+        then times must be passed using the `time` parameter.
+    time : DatetimeLike, optional
+        By default, tides will be modelled using times from the
+        "time" dimension of `data`. Alternatively, this param can
+        be used to provide a custom set of times. Accepts any format
+        that can be converted by `pandas.to_datetime()`. For example:
+        `time=pd.date_range(start="2000", end="2001", freq="5h")`
     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`.
+        provided, a new "tide_model" dimension will be added to `data`.
         Defaults to "EOT20"; for a full list of available/supported
         models, run `eo_tides.model.list_models`.
     directory : str, optional
@@ -437,7 +464,7 @@ def pixel_stats(
         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
+        Whether to resample tide statistics back into `data`'s original
         higher resolution grid. Defaults to False, which will return
         lower-resolution statistics that are typically sufficient for
         most purposes.
@@ -445,7 +472,7 @@ def pixel_stats(
         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`.
+        temporal extent of `data`.
     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
@@ -478,9 +505,15 @@ def pixel_stats(
         - `offset_high`: proportion of the highest tides never observed by the satellite
 
     """
+    # Standardise data inputs, time and models
+    gbox, time_coords = _standardise_inputs(data, time)
+    model = [model] if isinstance(model, str) else model
+
     # Model observed tides
+    assert time_coords is not None
     obs_tides = pixel_tides(
-        ds,
+        gbox,
+        time=time_coords,
         resample=False,
         model=model,
         directory=directory,
@@ -492,15 +525,15 @@ def pixel_stats(
 
     # Generate times covering entire period of satellite record
     all_timerange = pd.date_range(
-        start=ds.time.min().item(),
-        end=ds.time.max().item(),
+        start=time_coords.min().item(),
+        end=time_coords.max().item(),
         freq=modelled_freq,
     )
 
     # Model all tides
     all_tides = pixel_tides(
-        ds,
-        times=all_timerange,
+        gbox,
+        time=all_timerange,
         model=model,
         directory=directory,
         calculate_quantiles=min_max_q,
@@ -510,6 +543,11 @@ def pixel_stats(
         **pixel_tides_kwargs,
     )
 
+    # # Calculate means
+    # TODO: Find way to make this work with `calculate_quantiles`
+    # mot = obs_tides.mean(dim="time")
+    # mat = all_tides.mean(dim="time")
+
     # Calculate min and max tides
     lot = obs_tides.isel(quantile=0)
     hot = obs_tides.isel(quantile=-1)
@@ -531,10 +569,12 @@ def pixel_stats(
     stats_ds = (
         xr.merge(
             [
-                hat.rename("hat"),
+                # mot.rename("mot"),
+                # mat.rename("mat"),
                 hot.rename("hot"),
-                lat.rename("lat"),
+                hat.rename("hat"),
                 lot.rename("lot"),
+                lat.rename("lat"),
                 otr.rename("otr"),
                 tr.rename("tr"),
                 spread.rename("spread"),
@@ -544,11 +584,11 @@ def pixel_stats(
             compat="override",
         )
         .drop_vars("quantile")
-        .odc.assign_crs(crs=ds.odc.crs)
+        .odc.assign_crs(crs=gbox.crs)
     )
 
-    # Optionally resample into the original pixel grid of `ds`
+    # Optionally resample into the original pixel grid of `data`
     if resample:
-        stats_ds = stats_ds.odc.reproject(how=ds.odc.geobox, resample_method="bilinear")
+        stats_ds = stats_ds.odc.reproject(how=gbox, resample_method="bilinear")
 
     return stats_ds

{eo_tides-0.1.0.dist-info → eo_tides-0.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: eo-tides
-Version: 0.1.0
+Version: 0.2.0
 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/
@@ -29,7 +29,7 @@ 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: pyTMD ==2.1.7
 Requires-Dist: scikit-learn >=1.4.0
 Requires-Dist: scipy >=1.11.2
 Requires-Dist: shapely >=2.0.6
@@ -68,9 +68,9 @@ These tools can be applied to petabytes of freely available satellite data (e.g.
 
 ## Highlights
 
-- 🌊 Model tides from multiple global ocean tide models in parallel, and return tide heights in standardised `pandas.DataFrame` format for further analysis
+- 🌊 Model tide heights and phases (e.g. high, low, ebb, flow) from multiple global ocean tide models in parallel, and return a `pandas.DataFrame` 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
+- 🌐 Model tides for every individual satellite pixel through time, producing three-dimensional "tide height" `xarray`-format datacubes that can be integrated with satellite data
 - 📈 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 -->
@@ -103,6 +103,12 @@ 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
 ```
 
+In addition, please consider also citing the underlying [`pyTMD` Python package](https://pytmd.readthedocs.io/en/latest/) which powers the tide modelling functionality behind `eo-tides`:
+
+```
+Sutterley, T. C., Alley, K., Brunt, K., Howard, S., Padman, L., Siegfried, M. (2017) pyTMD: Python-based tidal prediction software. 10.5281/zenodo.5555395
+```
+
 ## Acknowledgements
 
 For a full list of acknowledgements, refer to [Citations and Credits](https://geoscienceaustralia.github.io/eo-tides/credits/).

eo_tides-0.2.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+eo_tides/__init__.py,sha256=MKL_HjRECVHHQVnMVg-TSz3J-vjxPZgbnyWu0RAXZ0U,1623
+eo_tides/eo.py,sha256=98llXpF2lSDfsVQBao-dpr8Z4zH5q0C2Rfu4X-qmPiE,22400
+eo_tides/model.py,sha256=kaYXU_jmv91ONam_CpoVN137aJsmqHvKHEPWe-DRJnI,38280
+eo_tides/stats.py,sha256=sOwXEh8RPb8muh2o9-z1c0GDnV5FJa_TgsiGb4rMkiU,22689
+eo_tides/utils.py,sha256=l9VXJawQzaRBYaFMsP8VBeaN5VA3rFDdzcvF7Rk04Vc,5620
+eo_tides/validation.py,sha256=JjTUqDfbR189m_6W1bpaSolQIHNTLicTHN7z9O_nr3s,11828
+eo_tides-0.2.0.dist-info/LICENSE,sha256=owxWsXViCL2J6Ks3XYhot7t4Y93nstmXAT95Zf030Cc,11350
+eo_tides-0.2.0.dist-info/METADATA,sha256=msiUYdlCm5pTix7LXA7RzM8Hg-9r4JHpWTSUyxdPpg4,7637
+eo_tides-0.2.0.dist-info/WHEEL,sha256=P9jw-gEje8ByB7_hXoICnHtVCrEwMQh-630tKvQWehc,91
+eo_tides-0.2.0.dist-info/top_level.txt,sha256=lXZDUUM1DlLdKWHRn8zdmtW8Rx-eQOIWVvt0b8VGiyQ,9
+eo_tides-0.2.0.dist-info/RECORD,,

{eo_tides-0.1.0.dist-info → eo_tides-0.2.0.dist-info}/WHEEL

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

eo_tides-0.1.0.dist-info/RECORD

@@ -1,11 +0,0 @@
-eo_tides/__init__.py,sha256=TWmQNplePCcNAlua5WI_H7SShkWNk-Gd3X70EDEknSo,1557
-eo_tides/eo.py,sha256=OTFjchQWpSfgi2Q62mFBj6ckmy_1B_ExCAmex4UT4js,21616
-eo_tides/model.py,sha256=Bwc2VVhDDBJB0wuKUAdSKYfBPZG4XDfldb_BO5Wcy6Y,34517
-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.1.0.dist-info/LICENSE,sha256=owxWsXViCL2J6Ks3XYhot7t4Y93nstmXAT95Zf030Cc,11350
-eo_tides-0.1.0.dist-info/METADATA,sha256=S8nHZcj3TWi2w_RpYilZFeBM_Hjw38hXE16eFJhNPQc,7260
-eo_tides-0.1.0.dist-info/WHEEL,sha256=OVMc5UfuAQiSplgO0_WdW7vXVGAt9Hdd6qtN4HotdyA,91
-eo_tides-0.1.0.dist-info/top_level.txt,sha256=lXZDUUM1DlLdKWHRn8zdmtW8Rx-eQOIWVvt0b8VGiyQ,9
-eo_tides-0.1.0.dist-info/RECORD,,