deafrica_tools.coastal¶
This module contains functions for conducting coastal analyses on Digital Earth Africa data.
License¶
The code in this notebook is licensed under the Apache License, Version 2.0 (https://www.apache.org/licenses/LICENSE2.0). Digital Earth Africa data is licensed under the Creative Commons by Attribution 4.0 license (https://creativecommons.org/licenses/by/4.0/).
Contact¶
If you need assistance, post a question on the Open Data Cube Slack channel (http://slack.opendatacube.org/) or the GIS Stack Exchange (https://gis.stackexchange.com/questions/ask?tags=opendatacube) using the opendatacube tag (you can view previously asked questions here: https://gis.stackexchange.com/questions/tagged/opendatacube).
If you would like to report an issue with this script, you can file one on Github (https://github.com/digitalearthafrica/deafricasandboxnotebooks/issues/new/).
Functions

Takes an xarray.Dataset and statistically compares the tides modelled for each satellite observation against the full modelled tidal range. 

Takes an xarray.Dataset and returns the same dataset with a new tide_height variable giving the height of the tide at the exact moment of each satellite acquisition. 

deafrica_tools.coastal.
tidal_stats
(ds, tidepost_lat=None, tidepost_lon=None, plain_english=True, plot=True, modelled_freq='2h', round_stats=3)¶ Takes an xarray.Dataset and statistically compares the tides modelled for each satellite observation against the full modelled tidal range.
This comparison can be used to evaluate whether the tides observed by satellites (e.g. Landsat) are biased compared to the natural tidal range (e.g. fail to observe either the highest or lowest tides etc).
By default, the function models tides for the centroid of the dataset, but a custom tidal modelling location can be specified using tidepost_lat and tidepost_lon.
Tides are modelled using the OTPS tidal modelling software based on the TPXO8 tidal model: https://www.tpxo.net/global/tpxo8atlas
For more information about the tidal statistics computed by this function, refer to Figure 8 in BishopTaylor et al. 2018: https://www.sciencedirect.com/science/article/pii/S0272771418308783#fig8
 Parameters
ds (xarray.Dataset) – An xarray.Dataset object with x, y and time dimensions
tidepost_lat (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.
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.
round_stats (int, optional) – The number of decimal places used to round the output statistics. Defaults to 3.
 Returns
A pandas.Series object 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 full modelled tidal range
observed_max_m: maximum tide height observed by the satellite
all_max_m: maximum tide height from full modelled tidal range
observed_range_m: tidal range observed by the satellite
all_range_m: full modelled tidal range
 spread_m: proportion of the full modelled tidal range observed
by the satellite (see BishopTaylor et al. 2018)
 low_tide_offset: proportion of the lowest tides never observed
by the satellite (see BishopTaylor et al. 2018)
 high_tide_offset: proportion of the highest tides never observed
by the satellite (see BishopTaylor et al. 2018)
 observed_slope: slope of any relationship between observed tide
heights and time
 all_slope: slope of any relationship between all modelled tide
heights and time
 observed_pval: significance/pvalue of any relationship between
observed tide heights and time
 all_pval: significance/pvalue of any relationship between
all modelled tide heights and time
 Return type
pandas.Series

deafrica_tools.coastal.
tidal_tag
(ds, tidepost_lat=None, tidepost_lon=None, ebb_flow=False, swap_dims=False, return_tideposts=False)¶ Takes an xarray.Dataset and returns the same dataset with a new tide_height variable giving the height of the tide at the exact moment of each satellite acquisition.
By default, the function models tides for the centroid of the dataset, but a custom tidal modelling location can be specified using tidepost_lat and tidepost_lon.
Tides are modelled using the OTPS tidal modelling software based on the TPXO8 tidal model: https://www.tpxo.net/global/tpxo8atlas
 Parameters
ds (xarray.Dataset) – An xarray.Dataset object with x, y and time dimensions
tidepost_lat (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.
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.
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 xarray.Dataset to the new tide_height variable. Defaults to False.
return_tideposts (bool, optional) – An optional boolean indicating whether to return the tidepost_lat and tidepost_lon location used to model tides in addition to the xarray.Dataset. Defaults to False.
 Returns
The original xarray.Dataset with a new tide_height variable giving the height of the tide (and optionally, its ebbflow phase) at the exact moment of each satellite acquisition.
(if return_tideposts=True, the function will also return the tidepost_lon and tidepost_lat location used in the analysis)
 Return type
xarray.Dataset