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

eo_tides/stats.py

@@ -1,15 +1,266 @@
-def tide_stats(a):
+# Used to postpone evaluation of type annotations
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING
+
+import matplotlib.pyplot as plt
+import numpy as np
+import odc.geo.xr
+import pandas as pd
+from scipy import stats
+
+# Only import if running type checking
+if TYPE_CHECKING:
+    import xarray as xr
+
+from .eo import tag_tides
+from .model import model_tides
+
+
+def tide_stats(
+    ds: xr.Dataset,
+    model: str = "EOT20",
+    directory: str | os.PathLike | None = None,
+    tidepost_lat: float | None = None,
+    tidepost_lon: float | None = None,
+    plain_english: bool = True,
+    plot: bool = True,
+    modelled_freq: str = "2h",
+    linear_reg: bool = False,
+    round_stats: int = 3,
+    **model_tides_kwargs,
+) -> pd.Series:
     """
-    Test function.
+    Takes a multi-dimensional dataset and generate statistics
+    about the data's astronomical and satellite-observed tide
+    conditions.
+
+    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).
+
+    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
     ----------
-    a : int
-        Test
+    ds : xarray.Dataset
+        A multi-dimensional dataset (e.g. "x", "y", "time") to
+        use 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";
+        for a full list of available/supported models, run
+        `eo_tides.model.list_models`.
+    directory : string, 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/>).
+    tidepost_lat, tidepost_lon : float or int, optional
+        Optional coordinates used to model tides. The default is None,
+        which uses the centroid of the dataset as the tide modelling
+        location.
+    plain_english : bool, optional
+        An optional boolean indicating whether to print a plain english
+        version of the tidal statistics to the screen. Defaults to True.
+    plot : bool, optional
+        An optional boolean indicating whether to plot how satellite-
+        observed tide heights compare against the full tidal range.
+        Defaults to True.
+    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
+        temporal extent of `ds`.
+    linear_reg: bool, optional
+        Whether to return linear regression statistics that assess
+        whether satellite-observed tides show any decreasing  or
+        increasing trends over time. This may indicate whether your
+        satellite data may produce misleading trends based on uneven
+        sampling of the local tide regime.
+    round_stats : int, optional
+        The number of decimal places used to round the output statistics.
+        Defaults to 3.
+    **model_tides_kwargs :
+        Optional parameters passed to the `eo_tides.model.model_tides`
+        function. Important parameters include `cutoff` (used to
+        extrapolate modelled tides away from the coast; defaults to
+        `np.inf`), `crop` (whether to crop tide model constituent files
+        on-the-fly to improve performance) etc.
 
     Returns
     -------
-    Test
+    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:
+
+        - `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
 
     """
-    return a
+    # Verify that only one tide model is provided
+    if isinstance(model, list):
+        raise Exception("Only single tide models are supported by `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]
+
+    # Model tides for each observation in the supplied xarray object
+    ds_tides = tag_tides(
+        ds,
+        model=model,
+        directory=directory,
+        tidepost_lat=tidepost_lat,  # type: ignore
+        tidepost_lon=tidepost_lon,  # type: ignore
+        return_tideposts=True,
+        **model_tides_kwargs,
+    )
+
+    # Drop spatial ref for nicer plotting
+    ds_tides = ds_tides.drop_vars("spatial_ref")
+
+    # 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(),
+        freq=modelled_freq,
+    )
+
+    # Model tides for each timestep
+    all_tides_df = model_tides(
+        x=tidepost_lon,  # type: ignore
+        y=tidepost_lat,  # type: ignore
+        time=all_timerange,
+        model=model,
+        directory=directory,
+        crs="EPSG:4326",
+        **model_tides_kwargs,
+    )
+
+    # 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
+
+    # Calculate tidal range
+    obs_range = obs_max - obs_min
+    all_range = all_max - all_min
+
+    # 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()
+
+    # 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)
+
+    # Compute linear regression
+    obs_linreg = stats.linregress(x=obs_x, y=obs_y)
+
+    if plain_english:
+        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"
+        )
+
+        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.")
+            else:
+                obs_slope_desc = "decrease" if obs_linreg.slope < 0 else "increase"
+                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)."
+                )
+
+    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])),
+        )
+
+        # 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,
+        "spread": spread,
+        "low_tide_offset": low_tide_offset,
+        "high_tide_offset": high_tide_offset,
+    }
+
+    if linear_reg:
+        output_stats.update({
+            "observed_slope": obs_linreg.slope,
+            "observed_pval": obs_linreg.pvalue,
+        })
+
+    return pd.Series(output_stats).round(round_stats)

eo_tides/validation.py

@@ -75,7 +75,7 @@ def eval_metrics(x, y, round=3, all_regress=False):
     return pd.Series(stats_dict).round(round)
 
 
-def round_date_strings(date, round_type="end"):
+def _round_date_strings(date, round_type="end"):
     """
     Round a date string up or down to the start or end of a given time
     period.
@@ -286,8 +286,8 @@ def load_gauge_gesla(
     if time is None:
         time = ["1800", str(datetime.datetime.now().year)]
     time = [time] if not isinstance(time, (list, tuple)) else time
-    start_time = round_date_strings(time[0], round_type="start")
-    end_time = round_date_strings(time[-1], round_type="end")
+    start_time = _round_date_strings(time[0], round_type="start")
+    end_time = _round_date_strings(time[-1], round_type="end")
 
     # Identify paths to load and nodata values for each site
     metadata_df["file_name"] = data_path + metadata_df["file_name"]

eo_tides-0.0.21.dist-info/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2024 Geoscience Australia
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

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

@@ -1,18 +1,31 @@
 Metadata-Version: 2.1
 Name: eo-tides
-Version: 0.0.20
+Version: 0.0.21
 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/
 Project-URL: Repository, https://github.com/GeoscienceAustralia/eo-tides
 Project-URL: Documentation, https://GeoscienceAustralia.github.io/eo-tides/
-Keywords: python
-Requires-Python: >=3.9
+Keywords: earth observation,tide modelling,tide modeling,satellite data,coastal analysis,oceanography,remote sensing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Scientific/Engineering :: Oceanography
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+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[xr]
+Requires-Dist: odc-geo
 Requires-Dist: pandas
 Requires-Dist: pyproj
 Requires-Dist: pyTMD ==2.1.6
@@ -20,18 +33,21 @@ Requires-Dist: scikit-learn
 Requires-Dist: scipy
 Requires-Dist: shapely
 Requires-Dist: tqdm
+Requires-Dist: xarray
 Provides-Extra: notebooks
-Requires-Dist: odc-stac ; 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'
 
-# `eo-tides:` Tide modelling tools for large-scale satellite earth observation analysis
+# `eo-tides`: Tide modelling tools for large-scale satellite earth observation analysis
+
+<img align="right" width="200" src="docs/assets/eo-tides-logo.gif" alt="eo-tides logo" style="margin-right: 40px;">
 
 [![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)
 [![codecov](https://codecov.io/gh/GeoscienceAustralia/eo-tides/branch/main/graph/badge.svg)](https://codecov.io/gh/GeoscienceAustralia/eo-tides)
-[![Commit activity](https://img.shields.io/github/commit-activity/m/GeoscienceAustralia/eo-tides)](https://img.shields.io/github/commit-activity/m/GeoscienceAustralia/eo-tides)
 [![License](https://img.shields.io/github/license/GeoscienceAustralia/eo-tides)](https://img.shields.io/github/license/GeoscienceAustralia/eo-tides)
 
 - **Github repository**: <https://github.com/GeoscienceAustralia/eo-tides/>
@@ -40,18 +56,20 @@ Requires-Dist: matplotlib ; extra == 'notebooks'
 > [!CAUTION]
 > This package is a work in progress, and not currently ready for operational use.
 
-The `eo-tides` package provides powerful, parallelized tools for seamlessly integrating satellite Earth observation data with tide modelling.
+`eo-tides` provides powerful parallelized tools for integrating satellite Earth observation data with tide modelling. 🛠️🌊🛰️
 
-`eo-tides` combines advanced tide modelling functionality from the [`pyTMD`](https://pytmd.readthedocs.io/en/latest/) package and integrates it with [`pandas`](https://pandas.pydata.org/docs/index.html), [`xarray`](https://docs.xarray.dev/en/stable/) and [`odc-geo`](https://odc-geo.readthedocs.io/en/latest/), providing a suite of flexible tools for efficient analysis of coastal and ocean earth observation data – from regional, continental, to global scale.
+`eo-tides` combines advanced tide modelling functionality from the [`pyTMD`](https://pytmd.readthedocs.io/en/latest/) package with [`pandas`](https://pandas.pydata.org/docs/index.html), [`xarray`](https://docs.xarray.dev/en/stable/) and [`odc-geo`](https://odc-geo.readthedocs.io/en/latest/), providing a suite of flexible tools for efficient analysis of coastal and ocean Earth observation data – from regional, continental, to global scale.
 
 These tools can be applied to petabytes of freely available satellite data (e.g. from [Digital Earth Australia](https://knowledge.dea.ga.gov.au/) or [Microsoft Planetary Computer](https://planetarycomputer.microsoft.com/)) loaded via Open Data Cube's [`odc-stac`](https://odc-stac.readthedocs.io/en/latest/) or [`datacube`](https://opendatacube.readthedocs.io/en/latest/) packages, supporting coastal and ocean earth observation analysis for any time period or location globally.
 
+![eo-tides abstract showing satellite data, tide data array and tide animation](docs/assets/eo-tides-abstract.gif)
+
 ## Highlights
 
 - 🌊 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 combined 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
+- 🌐 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/))
 
@@ -59,18 +77,18 @@ These tools can be applied to petabytes of freely available satellite data (e.g.
 
 `eo-tides` supports [all ocean tide models supported by `pyTMD`](https://pytmd.readthedocs.io/en/latest/getting_started/Getting-Started.html#model-database). These include:
 
-- [Empirical Ocean Tide model](https://doi.org/10.5194/essd-13-3869-2021) (`EOT20`)
-- [Finite Element Solution tide models](https://doi.org/10.5194/os-2020-96) (`FES2022`, `FES2014`, `FES2012`)
-- [TOPEX/POSEIDON global tide models](https://www.tpxo.net/global) (`TPXO10`, `TPXO9`, `TPXO8`)
-- [Global Ocean Tide models](https://doi.org/10.1002/2016RG000546) (`GOT5.6`, `GOT5.5`, `GOT4.10`, `GOT4.8`, `GOT4.7`)
-- [Hamburg direct data Assimilation Methods for Tides models](https://doi.org/10.1002/2013JC009766) (`HAMTIDE11`)
+- [Empirical Ocean Tide model](https://doi.org/10.5194/essd-13-3869-2021) (EOT20)
+- [Finite Element Solution tide models](https://doi.org/10.5194/os-2020-96) (FES2022, FES2014, FES2012)
+- [TOPEX/POSEIDON global tide models](https://www.tpxo.net/global) (TPXO10, TPXO9, TPXO8)
+- [Global Ocean Tide models](https://doi.org/10.1002/2016RG000546) (GOT5.6, GOT5.5, GOT4.10, GOT4.8, GOT4.7)
+- [Hamburg direct data Assimilation Methods for Tides models](https://doi.org/10.1002/2013JC009766) (HAMTIDE11)
 
-For instructions on how to set up these models for use in `eo-tides`, refer to [Setting up tide models](https://geoscienceaustralia.github.io/eo-tides/setup/).
+For instructions on how to set up these models for use in `eo-tides`, refer to [Setting up tide models](setup.md).
 
 ## Citing `eo-tides`
 
 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 [Computer software]. https://github.com/GeoscienceAustralia/eo-tides
+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
 ```

eo_tides-0.0.21.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=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,,

eo_tides-0.0.20.dist-info/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2024 Geoscience Australia
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

eo_tides-0.0.20.dist-info/RECORD

@@ -1,10 +0,0 @@
-eo_tides/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-eo_tides/model.py,sha256=wo2bsWEefpTFd3KrkzZelIU4FV_noCNJjMQs2arwypk,46021
-eo_tides/stats.py,sha256=Lzo46pWUhox3ZUnMLtyLzqZ9FrCNG6nJ6iS5IpqEsy8,158
-eo_tides/utils.py,sha256=l9VXJawQzaRBYaFMsP8VBeaN5VA3rFDdzcvF7Rk04Vc,5620
-eo_tides/validation.py,sha256=kpYGHOeK-YP11c3tHt9l5_8IvOHF1SAJP79PXA7i-Vs,11434
-eo_tides-0.0.20.dist-info/LICENSE,sha256=NYULqbFuDRV6CysPbkR2WZk863YwwHeftBtnsb4cWf8,1077
-eo_tides-0.0.20.dist-info/METADATA,sha256=_Ns8em48OsUfgl97Rw4hSPXPqfJV9FelTtq25qcb4ag,5335
-eo_tides-0.0.20.dist-info/WHEEL,sha256=GV9aMThwP_4oNCtvEC2ec3qUYutgWeAzklro_0m4WJQ,91
-eo_tides-0.0.20.dist-info/top_level.txt,sha256=lXZDUUM1DlLdKWHRn8zdmtW8Rx-eQOIWVvt0b8VGiyQ,9
-eo_tides-0.0.20.dist-info/RECORD,,