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/LICENSE-2.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=open-data-cube) using the open-data-cube tag (you can view previously asked questions here: https://gis.stackexchange.com/questions/tagged/open-data-cube).

If you would like to report an issue with this script, you can file one on Github (https://github.com/digitalearthafrica/deafrica-sandbox-notebooks/issues/new/).

Functions

tidal_stats(ds[, tidepost_lat, …])

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

tidal_tag(ds[, tidepost_lat, tidepost_lon, …])

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/tpxo8-atlas

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
  • 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 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)

  • 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/p-value of any relationship between

    observed tide heights and time

  • all_pval: significance/p-value 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/tpxo8-atlas

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 ebb-flow 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