eo-tides 0.5.0__py3-none-any.whl

eo_tides/validation.py

@@ -0,0 +1,334 @@
+import datetime
+import warnings
+from math import sqrt
+from numbers import Number
+
+import geopandas as gpd
+import pandas as pd
+import tqdm
+from odc.geo.geom import BoundingBox
+from pandas.tseries.offsets import MonthBegin, MonthEnd, YearBegin, YearEnd
+from scipy import stats
+from shapely.geometry import Point
+from sklearn.metrics import mean_absolute_error, mean_squared_error
+
+
+def eval_metrics(x, y, round=3, all_regress=False):
+    """
+    Calculate a set of common statistical metrics
+    based on two input actual and predicted vectors.
+
+    These include:
+
+    * Pearson correlation
+    * Root Mean Squared Error
+    * Mean Absolute Error
+    * R-squared
+    * Bias
+    * Linear regression parameters (slope, p-value, intercept, standard error)
+
+    Parameters
+    ----------
+    x : numpy.array
+        An array providing "actual" variable values.
+    y : numpy.array
+        An array providing "predicted" variable values.
+    round : int
+        Number of decimal places to round each metric
+        to. Defaults to 3.
+    all_regress : bool
+        Whether to return linear regression p-value,
+        intercept and standard error (in addition to
+        only regression slope). Defaults to False.
+
+    Returns
+    -------
+    pandas.Series
+        A `pd.Series` containing all calculated metrics.
+    """
+
+    # Create dataframe to drop na
+    xy_df = pd.DataFrame({"x": x, "y": y}).dropna()
+
+    # Compute linear regression
+    lin_reg = stats.linregress(x=xy_df.x, y=xy_df.y)
+
+    # Calculate statistics
+    stats_dict = {
+        "Correlation": xy_df.corr().iloc[0, 1],
+        "RMSE": sqrt(mean_squared_error(xy_df.x, xy_df.y)),
+        "MAE": mean_absolute_error(xy_df.x, xy_df.y),
+        "R-squared": lin_reg.rvalue**2,
+        "Bias": (xy_df.y - xy_df.x).mean(),
+        "Regression slope": lin_reg.slope,
+    }
+
+    # Additional regression params
+    if all_regress:
+        stats_dict.update({
+            "Regression p-value": lin_reg.pvalue,
+            "Regression intercept": lin_reg.intercept,
+            "Regression standard error": lin_reg.stderr,
+        })
+
+    # Return as
+    return pd.Series(stats_dict).round(round)
+
+
+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.
+
+    Parameters
+    ----------
+    date : str
+        Date string of variable precision (e.g. "2020", "2020-01",
+        "2020-01-01").
+    round_type : str, optional
+        Type of rounding to perform. Valid options are "start" or "end".
+        If "start", date is rounded down to the start of the time period.
+        If "end", date is rounded up to the end of the time period.
+        Default is "end".
+
+    Returns
+    -------
+    date_rounded : str
+        The rounded date string.
+
+    Examples
+    --------
+    >>> round_date_strings('2020')
+    '2020-12-31 00:00:00'
+
+    >>> round_date_strings('2020-01', round_type='start')
+    '2020-01-01 00:00:00'
+
+    >>> round_date_strings('2020-01', round_type='end')
+    '2020-01-31 00:00:00'
+    """
+
+    # Determine precision of input date string
+    date_segments = len(date.split("-"))
+
+    # If provided date has no "-", treat it as having year precision
+    if date_segments == 1 and round_type == "start":
+        date_rounded = str(pd.to_datetime(date) + YearBegin(0))
+    elif date_segments == 1 and round_type == "end":
+        date_rounded = str(pd.to_datetime(date) + YearEnd(0))
+
+    # If provided date has one "-", treat it as having month precision
+    elif date_segments == 2 and round_type == "start":
+        date_rounded = str(pd.to_datetime(date) + MonthBegin(0))
+    elif date_segments == 2 and round_type == "end":
+        date_rounded = str(pd.to_datetime(date) + MonthEnd(0))
+
+    # If more than one "-", then return date as-is
+    elif date_segments > 2:
+        date_rounded = date
+
+    return date_rounded
+
+
+def _load_gauge_metadata(metadata_path):
+    # Load metadata
+    metadata_df = pd.read_csv(metadata_path)
+    metadata_df.columns = (
+        metadata_df.columns.str.replace(" ", "_", regex=False)
+        .str.replace("(", "", regex=False)
+        .str.replace(")", "", regex=False)
+        .str.replace("/", "_", regex=False)
+        .str.lower()
+    )
+    metadata_df = metadata_df.set_index("site_code")
+
+    # Convert metadata to GeoDataFrame
+    metadata_gdf = gpd.GeoDataFrame(
+        data=metadata_df,
+        geometry=gpd.points_from_xy(metadata_df.longitude, metadata_df.latitude),
+        crs="EPSG:4326",
+    )
+
+    return metadata_df, metadata_gdf
+
+
+def _load_gesla_dataset(site, path, na_value):
+    # Read dataset
+    gesla_df = pd.read_csv(
+        path,
+        skiprows=41,
+        names=["date", "time", "sea_level", "qc_flag", "use_flag"],
+        sep=r"\s+",
+        na_values=na_value,
+    )
+
+    # Combine two date fields
+    gesla_df = (
+        gesla_df.assign(
+            time=pd.to_datetime(gesla_df["date"] + " " + gesla_df["time"]),
+            site_code=site,
+        )
+        .drop(columns=["date"])
+        .set_index("time")
+    )
+
+    return gesla_df
+
+
+def _nearest_row(gdf, x, y, max_distance=None):
+    # Create a point to find the nearest neighbor for
+    target_point = gpd.GeoDataFrame({"geometry": [Point(x, y)]}, crs="EPSG:4326")
+
+    # Use sjoin_nearest to find the closest point
+    return gpd.sjoin_nearest(target_point, gdf, how="left", max_distance=max_distance)
+
+
+def load_gauge_gesla(
+    x=None,
+    y=None,
+    site_code=None,
+    time=("2018", "2020"),
+    max_distance=None,
+    correct_mean=False,
+    filter_use_flag=True,
+    site_metadata=True,
+    data_path="/gdata1/data/sea_level/gesla/",
+    metadata_path="/gdata1/data/sea_level/GESLA3_ALL 2.csv",
+):
+    """
+    Load Global Extreme Sea Level Analysis (GESLA) tide gauge data.
+
+    Load and process all available GESLA measured sea-level data
+    with an `x, y, time` spatio-temporal query, or from a list of
+    specific tide gauges. Can optionally filter by gauge quality
+    and append detailed gauge metadata.
+
+    Modified from original code in <https://github.com/philiprt/GeslaDataset>.
+
+    Parameters
+    ----------
+    x, y : numeric or list/tuple, optional
+        Coordinates (in degrees longitude, latitude) used to load GESLA
+        tide gauge observations. If provided as singular values
+        (e.g. `x=150, y=-32`), then the nearest tide gauge will be returned.
+        If provided as a list or tuple (e.g. `x=(150, 152), y=(-32, -30)`),
+        then all gauges within the provided bounding box will be loaded.
+        Leave as `None` to return all available gauges, or if providing a
+        list of site codes using `site_code`.
+    site_code : str or list of str, optional
+        GESLA site code(s) for which to load data (e.g. `site_code="62650"`).
+        If `site_code` is provided, `x` and `y` will be ignored.
+    time : tuple or list of str, optional
+        Time range to consider, given as a tuple of start and end dates,
+        e.g. `time=("2020", "2021")`. The default of None will return all
+        tide observations from the year 1800 onward.
+    max_distance : numeric, optional
+        Optional max distance within which to return the nearest tide gauge
+        when `x` and `y` are provided as singular coordinates. Defaults to
+        None, which will always return a tide gauge no matter how far away
+        it is located from `x` and `y`.
+    correct_mean : bool, optional
+        Whether to correct sea level measurements to a standardised mean
+        sea level by subtracting the mean of all observed sea level
+        observations. This can be useful when GESLA tide heights come
+        from different or unknown tide datums. Note: the observed mean
+        sea level calculated here may differ from true long-term/
+        astronomical Mean Sea Level (MSL) datum.
+    filter_use_flag : bool, optional
+        Whether to filter out low quality observations with a "use_flag"
+        value of 0 (do not use). Defaults to True.
+    site_metadata : bool, optional
+        Whether to add tide gauge station metadata as additional columns
+        in the output DataFrame. Defaults to True.
+    data_path : str, optional
+        Path to the raw GESLA data files. Default is
+        `/gdata1/data/sea_level/gesla/`.
+    metadata_path : str, optional
+        Path to the GESLA station metadata file.
+        Default is `/gdata1/data/sea_level/GESLA3_ALL 2.csv`.
+
+    Returns
+    -------
+    pd.DataFrame
+        Processed GESLA data as a DataFrame with columns including:
+
+        - "time": Timestamps,
+        - "sea_level": Observed sea level (m),
+        - "qc_flag": Observed sea level QC flag,
+        - "use_flag": Use-in-analysis flag (1 = use, 0 = do not use),
+
+        ...and additional columns from station metadata.
+    """
+    # Load tide gauge metadata
+    metadata_df, metadata_gdf = _load_gauge_metadata(metadata_path)
+
+    # Use supplied site codes if available
+    if site_code is not None:
+        site_code = [site_code] if not isinstance(site_code, list) else site_code
+
+    # If x and y are tuples, use xy bounds to identify sites
+    elif isinstance(x, (tuple, list)) & isinstance(y, (tuple, list)):
+        bbox = BoundingBox.from_xy(x, y)
+        site_code = metadata_gdf.cx[bbox.left : bbox.right, bbox.top : bbox.bottom].index
+
+    # If x and y are single numbers, select nearest row
+    elif isinstance(x, Number) & isinstance(y, Number):
+        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():
+            raise Exception(f"No tide gauge found within {max_distance} degrees of {x}, {y}.")
+
+    # Otherwise if all are None, return all available site codes
+    elif (site_code is None) & (x is None) & (y is None):
+        site_code = metadata_df.index.to_list()
+
+    else:
+        raise TypeError(
+            "`x` and `y` must be provided as either singular coordinates (e.g. `x=150`), or as a tuple bounding box (e.g. `x=(150, 152)`)."
+        )
+
+    # Prepare times
+    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")
+
+    # Identify paths to load and nodata values for each site
+    metadata_df["file_name"] = data_path + metadata_df["file_name"]
+    paths_na = metadata_df.loc[site_code, ["file_name", "null_value"]]
+
+    # Load and combine into a single dataframe
+    gauge_list = [
+        _load_gesla_dataset(s, p, na_value=na)
+        for s, p, na in tqdm.tqdm(paths_na.itertuples(), total=len(paths_na), desc="Loading GESLA gauges")
+    ]
+    data_df = pd.concat(gauge_list).sort_index().loc[slice(start_time, end_time)].reset_index().set_index("site_code")
+
+    # Optionally filter by use flag column
+    if filter_use_flag:
+        data_df = data_df.loc[data_df.use_flag == 1]
+
+    # Optionally insert metadata into dataframe
+    if site_metadata:
+        data_df[metadata_df.columns] = metadata_df.loc[site_code]
+
+    # Add time to index and remove duplicates
+    data_df = data_df.set_index("time", append=True)
+    duplicates = data_df.index.duplicated()
+    if duplicates.sum() > 0:
+        warnings.warn("Duplicate timestamps were removed.")
+        data_df = data_df.loc[~duplicates]
+
+    # Remove observed mean sea level if requested
+    if correct_mean:
+        data_df["sea_level"] = data_df["sea_level"].sub(data_df.groupby("site_code")["sea_level"].transform("mean"))
+
+    # Return data
+    return data_df

eo_tides-0.5.0.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.5.0.dist-info/METADATA

@@ -0,0 +1,118 @@
+Metadata-Version: 2.2
+Name: eo-tides
+Version: 0.5.0
+Summary: Tide modelling tools for large-scale satellite earth observation analysis
+Author: Robbi Bishop-Taylor, Stephen Sagar, Claire Phillips, Vanessa Newey
+Author-email: 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: 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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: <4.0,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+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: psutil>=5.8.0
+Requires-Dist: pyogrio>=0.10.0
+Requires-Dist: pyproj>=3.7.0
+Requires-Dist: pyTMD==2.2.0
+Requires-Dist: scikit-learn>=1.4.0
+Requires-Dist: scipy>=1.14.1
+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: 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
+
+<img align="right" width="200" src="https://github.com/GeoscienceAustralia/eo-tides/blob/main/docs/assets/eo-tides-logo.gif?raw=true" 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/pypi/pyversions/eo-tides)](https://github.com/GeoscienceAustralia/eo-tides/blob/main/pyproject.toml)
+[![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)
+
+- ⚙️ **Github repository**: <https://github.com/GeoscienceAustralia/eo-tides/>
+- 📘 **Documentation**: <https://GeoscienceAustralia.github.io/eo-tides/>
+- 🐍 **PyPI**: <https://pypi.org/project/eo-tides/>
+
+<br>
+
+`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 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](https://github.com/GeoscienceAustralia/eo-tides/blob/main/docs/assets/eo-tides-abstract.gif?raw=true)
+
+## Highlights
+
+- 🌊 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 heights based on the exact moment of image acquisition
+- 🌐 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 -->
+
+## Supported tide models
+
+`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)
+
+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.
+
+## Jupyter Notebooks code examples
+
+Interactive Jupyter Notebook usage examples and more complex coastal EO case studies can be found in the [`docs/notebooks/`](https://github.com/GeoscienceAustralia/eo-tides/tree/main/docs/notebooks) directory, or [rendered in the documentation here](https://geoscienceaustralia.github.io/eo-tides/notebooks/Model_tides/).
+
+## 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. 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/).
+This repository was initialised using the [`cookiecutter-uv`](https://github.com/fpgmaas/cookiecutter-uv) package.

eo_tides-0.5.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+eo_tides/__init__.py,sha256=pGvVlxMKiYjm_273G-oYcOgVuPra7uEdNZv0oN1i69c,1693
+eo_tides/eo.py,sha256=nuaOppYJCVL8mbFyaL9e4ahHB_LBGBrr5XfnAopmW5M,22746
+eo_tides/model.py,sha256=xpKaVO1_cLLwbODpffqDL80Hw7Yv9JchH42tKhX1oto,34585
+eo_tides/stats.py,sha256=RXs3J3YZH3yOrzDibEDp3-7wjkleOEFzO33lp27ATuE,22993
+eo_tides/utils.py,sha256=9xJ1q-b-TVHg5zFyLy6AT_srrPQDvmFdWJmlGSPaJF0,26563
+eo_tides/validation.py,sha256=KP8WLT5z7KLFjQ9oDla7VJOyLQAK4SVbcz2ySAbsbwI,11882
+eo_tides-0.5.0.dist-info/LICENSE,sha256=owxWsXViCL2J6Ks3XYhot7t4Y93nstmXAT95Zf030Cc,11350
+eo_tides-0.5.0.dist-info/METADATA,sha256=CtP3dQKJAbs1bEZaJz0egfina4OD4jba4TGDlLxxIPg,7906
+eo_tides-0.5.0.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+eo_tides-0.5.0.dist-info/top_level.txt,sha256=lXZDUUM1DlLdKWHRn8zdmtW8Rx-eQOIWVvt0b8VGiyQ,9
+eo_tides-0.5.0.dist-info/RECORD,,

eo_tides-0.5.0.dist-info/WHEEL

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

eo_tides-0.5.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+eo_tides