Migrating from dea_tools¶
The eo-tides package contains functions that were previously available in the Digital Earth Australia Notebooks and Tools repository.
To migrate your code from DEA Tools to eo-tides, please be aware of the following breaking changes:
Breaking changes¶
"tide_m" renamed to "tide_height"¶
The default output tide heights column generated by the model_tides function and the xarray.DataArray outputs generated by tag_tides and pixel_tides have been renamed from tide_m to tide_height.
This more clearly describes the data, particularly when used in combination with output_units="cm" or output_units="mm" which returns tide heights in non-metre units.
Action required
Update any references of tide_m to tide_height
Default model changed to "EOT20"¶
The default tide model has been changed from "FES2014" to the open source "EOT20" Empirical Ocean Tide tide model (CC BY 4.0):
Hart-Davis Michael, Piccioni Gaia, Dettmering Denise, Schwatke Christian, Passaro Marcello, Seitz Florian (2021). EOT20 - A global Empirical Ocean Tide model from multi-mission satellite altimetry. SEANOE. https://doi.org/10.17882/79489
Note that this change in default is primarily due to the permissive license of this model; the choice of optimal model will vary by study area and application.
Action required
To use FES2014, set model="FES2014" instead of leaving the default model=None.
tidal_tag renamed to tag_tides¶
Renamed for consistency with model_tides and pixel_tides.
Action required
Update references to tidal_tag to tag_tides.
ds param renamed to data, now accepts GeoBox¶
The ds param in all satellite data functions (tag_tides, pixel_tides, tide_stats, pixel_tides) has been updated to accept either xarray.Dataset, xarray.DataArray or a odc.geo.geobox.GeoBox. To account for this change, the ds param has been renamed to a more generic name data.
tag_tides now returns an array instead of updating data in-place¶
The tag_tides function now returns an xarray.DataArray output containing tide heights, rather than appending tide height data to the original input dataset in-place. This change provides better consistency with pixel_tides, which also returns an array of tide heights.
pixel_tides only returns a single array¶
The pixel_tides function has been updated to only ever return a single array as an output: a high-resolution tide height array matching the resolution of the input data by default, and a low-resolution tide height array if resample=False.
Action required
Update code to handle a single tide height array output from pixel_tides, instead of a tuple of high-resolution and low-resolution modelled tide height arrays.
Tide model directory environment variable updated¶
The DEA_TOOLS_TIDE_MODELS environmental variable has been renamed to EO_TIDES_TIDE_MODELS.
Action required
Set the EO_TIDES_TIDE_MODELS environment variable instead of DEA_TOOLS_TIDE_MODELS.
Error raised if both directory parameter and environment variable are missing¶
Previously, tide modelling functions used a fall-back tide modelling directory (/var/share/tide_models) if both the directory parameter and the tide model directory environment variable were absent. This fall-back has been removed, and an error will now be raised if no tide model directory is specified.
Action required
Ensure that either the directory parameter or the EO_TIDES_TIDE_MODELS environment variable are provided.