dea_tools.coastal

Coastal analysis and tide modelling tools.

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 Australia 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 (GeoscienceAustralia/dea-notebooks#new).

Last modified: November 2023

Functions

get_coastlines(bbox[, crs, layer, drop_wms])	Load DEA Coastlines annual shorelines or rates of change points data for a provided bounding box using WFS.
glint_angle(solar_azimuth, solar_zenith, ...)	Calculates glint angles for each pixel in a satellite image based on the relationship between the solar and sensor zenith and azimuth viewing angles at the moment the image was acquired.
model_tides(x, y, time[, model, directory, ...])	Compute tides at multiple points and times using tidal harmonics.
pixel_tides(ds[, times, resample, ...])	Obtain tide heights for each pixel in a dataset by modelling tides into a low-resolution grid surrounding the dataset, then (optionally) spatially resample this low-res data back into the original higher resolution dataset extent and resolution.
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_stats_otps(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[, ebb_flow, swap_dims, ...])	Takes an xarray.Dataset and returns the same dataset with a new tide_m variable giving the height of the tide at the exact moment of each satellite acquisition.
tidal_tag_otps(ds[, tidepost_lat, ...])	Takes an xarray.Dataset and returns the same dataset with a new tide_m variable giving the height of the tide at the exact moment of each satellite acquisition.
transect_distances(transects_gdf, lines_gdf)	Take a set of transects (e.g. shore-normal beach survey lines), and determine the distance along the transect to each object in a set of lines (e.g. shorelines).

dea_tools.coastal.get_coastlines(bbox: tuple, crs='EPSG:4326', layer='shorelines_annual', drop_wms=True) → geopandas.GeoDataFrame

Load DEA Coastlines annual shorelines or rates of change points data for a provided bounding box using WFS.

For a full description of the DEA Coastlines dataset, refer to the official Geoscience Australia product description: /data/product/dea-coastlines

Parameters:

• bbox ((xmin, ymin, xmax, ymax), or geopandas object) – Bounding box expressed as a tutple. Alternatively, a bounding box can be automatically extracted by suppling a geopandas.GeoDataFrame or geopandas.GeoSeries.

• crs (str, optional) – Optional CRS for the bounding box. This is ignored if bbox is provided as a geopandas object.

• layer (str, optional) – Which DEA Coastlines layer to load. Options include the annual shoreline vectors (“shorelines_annual”) and the rates of change points (“rates_of_change”). Defaults to “shorelines_annual”.

• drop_wms (bool, optional) – Whether to drop WMS-specific attribute columns from the data. These columns are used for visualising the dataset on DEA Maps, and are unlikely to be useful for scientific analysis. Defaults to True.

Returns:

A GeoDataFrame containing shoreline or point features and associated metadata.

Return type:

gpd.GeoDataFrame

dea_tools.coastal.glint_angle(solar_azimuth, solar_zenith, view_azimuth, view_zenith)

Calculates glint angles for each pixel in a satellite image based on the relationship between the solar and sensor zenith and azimuth viewing angles at the moment the image was acquired.

Glint angle is considered a predictor of sunglint over water; small glint angles (e.g. < 20 degrees) are associated with a high probability of sunglint due to the viewing angle of the sensor being aligned with specular reflectance of the sun from the water’s surface.

Based on code from https://towardsdatascience.com/how-to-implement- sunglint-detection-for-sentinel-2-images-in-python-using-metadata- info-155e683d50

Parameters:

• solar_azimuth (array-like) – Array of solar azimuth angles in degrees. In DEA Collection 3, this is contained in the “oa_solar_azimuth” band.

• solar_zenith (array-like) – Array of solar zenith angles in degrees. In DEA Collection 3, this is contained in the “oa_solar_zenith” band.

• view_azimuth (array-like) – Array of sensor/viewing azimuth angles in degrees. In DEA Collection 3, this is contained in the “oa_satellite_azimuth” band.

• view_zenith (array-like) – Array of sensor/viewing zenith angles in degrees. In DEA Collection 3, this is contained in the “oa_satellite_view” band.

Returns:

glint_array – Array of glint angles in degrees. Small values indicate higher probabilities of sunglint.

Return type:

numpy.ndarray

dea_tools.coastal.model_tides(x, y, time, model='FES2014', directory=None, crs='EPSG:4326', method='spline', extrapolate=True, cutoff=None, mode='one-to-many', parallel=True, parallel_splits=5, output_units='m', output_format='long', epsg=None)

Compute tides at multiple points and times using tidal harmonics.

This function supports any tidal model supported by pyTMD, including the FES2014 Finite Element Solution tide model, and the TPXO8-atlas and TPXO9-atlas-v5 TOPEX/POSEIDON global tide models.

This function requires access to tide model data files. These should be placed in a folder with subfolders matching the formats specified by pyTMD: https://pytmd.readthedocs.io/en/latest/getting_started/Getting-Started.html#directories

For FES2014 (https://www.aviso.altimetry.fr/es/data/products/auxiliary-products/global-tide-fes/description-fes2014.html):

• {directory}/fes2014/ocean_tide/

• {directory}/fes2014/load_tide/

For TPXO8-atlas (https://www.tpxo.net/tpxo-products-and-registration):

• {directory}/tpxo8_atlas/

For TPXO9-atlas-v5 (https://www.tpxo.net/tpxo-products-and-registration):

• {directory}/TPXO9_atlas_v5/

For EOT20 (https://www.seanoe.org/data/00683/79489/):

• {directory}/EOT20/ocean_tides/

• {directory}/EOT20/load_tides/

For GOT4.10c (https://earth.gsfc.nasa.gov/geo/data/ocean-tide-models):

• {directory}/GOT4.10c/grids_oceantide_netcdf/

For HAMTIDE (https://www.cen.uni-hamburg.de/en/icdc/data/ocean/hamtide.html):

• {directory}/hamtide/

This function is a modification of the pyTMD package’s compute_tide_corrections function. For more info: https://pytmd.readthedocs.io/en/stable/user_guide/compute_tide_corrections.html

Parameters:

x, yfloat or list of floats

One or more x and y coordinates used to define the location at which to model tides. By default these coordinates should be lat/lon; use “crs” if they are in a custom coordinate reference system.

timeA datetime array or pandas.DatetimeIndex

An array containing datetime64[ns] values or a pandas.DatetimeIndex providing the times at which to model tides in UTC time.

modelstring, optional

The tide model used to model tides. Options include: - “FES2014” (only pre-configured option on DEA Sandbox) - “TPXO9-atlas-v5” - “TPXO8-atlas” - “EOT20” - “HAMTIDE11” - “GOT4.10”

directorystring, optional

The directory containing tide model data files. If no path is provided, this will default to the environment variable “DEA_TOOLS_TIDE_MODELS” if set, otherwise “/var/share/tide_models”. Tide modelling files should be stored in sub-folders for each model that match the structure provided by pyTMD: https://pytmd.readthedocs.io/en/latest/getting_started/Getting-Started.html#directories For example: - {directory}/fes2014/ocean_tide/

{directory}/fes2014/load_tide/

• {directory}/tpxo8_atlas/

• {directory}/TPXO9_atlas_v5/

crsstr, optional

Input coordinate reference system for x and y coordinates. Defaults to “EPSG:4326” (WGS84; degrees latitude, longitude).

methodstring, optional

Method used to interpolate tidal contsituents from model files. Options include: - “spline”: scipy bivariate spline interpolation (default) - “bilinear”: quick bilinear interpolation - “linear”, “nearest”: scipy regular grid interpolations

extrapolatebool, optional

Whether to extrapolate tides for x and y coordinates outside of the valid tide modelling domain using nearest-neighbor.

cutoffint or float, optional

Extrapolation cutoff in kilometers. The default is None, which will extrapolate for all points regardless of distance from the valid tide modelling domain.

modestring, optional

The analysis mode to use for tide modelling. Supports two options: - “one-to-many”: Models tides for every timestep in “time” at every input x and y coordinate point. This is useful if you want to model tides for a specific list of timesteps across multiple spatial points (e.g. for the same set of satellite acquisition times at various locations across your study area). - “one-to-one”: Model tides using a different timestep for each x and y coordinate point. In this mode, the number of x and y points must equal the number of timesteps provided in “time”.

parallelboolean, optional

Whether to parallelise tide modelling using concurrent.futures. If multiple tide models are requested, these will be run in parallel. Optionally, tide modelling can also be run in parallel across input x and y coordinates (see “parallel_splits” below). Default is True.

parallel_splitsint, optional

Whether to split the input x and y coordinates into smaller, evenly-sized chunks that are processed in parallel. This can provide a large performance boost when processing large numbers of coordinates. The default is 5 chunks, which will split coordinates into 5 parallelised chunks.

output_unitsstr, optional

Whether to return modelled tides in floating point metre units, or integer centimetre units (i.e. scaled by 100) or integer millimetre units (i.e. scaled by 1000. Returning outputs in integer units can be useful for reducing memory usage. Defaults to “m” for metres; set to “cm” for centimetres or “mm” for millimetres.

output_formatstr, optional

Whether to return the output dataframe in long format (with results stacked vertically along “tide_model” and “tide_m” columns), or wide format (with a column for each tide model). Defaults to “long”.

epsgint, DEPRECATED

Deprecated; use “crs” instead.

returns:

• A pandas.DataFrame containing tide heights for every

• combination of time and point coordinates.

dea_tools.coastal.pixel_tides(ds, times=None, resample=True, calculate_quantiles=None, resolution=None, buffer=None, resample_method='bilinear', model='FES2014', dask_chunks='auto', dask_compute=True, **model_tides_kwargs)

Obtain tide heights for each pixel in a dataset by modelling tides into a low-resolution grid surrounding the dataset, then (optionally) spatially resample this low-res data back into the original higher resolution dataset extent and resolution.

Parameters:

dsxarray.Dataset

A dataset whose geobox (ds.odc.geobox) will be used to define the spatial extent of the low resolution tide modelling grid.

timespandas.DatetimeIndex or list of pandas.Timestamps, optional

By default, the function will model tides using the times contained in the time dimension of ds. Alternatively, this param can be used to model tides for a custom set of times instead. For example: times=pd.date_range(start=”2000”, end=”2001”, freq=”5h”)

resamplebool, optional

Whether to resample low resolution tides back into ds’s original higher resolution grid. Set this to False if you do not want low resolution tides to be re-projected back to higher resolution.

calculate_quantileslist or np.array, optional

Rather than returning all individual tides, low-resolution tides can be first aggregated using a quantile calculation by passing in a list or array of quantiles to compute. For example, this could be used to calculate the min/max tide across all times: calculate_quantiles=[0.0, 1.0].

resolution: int, optional

The desired resolution of the low-resolution grid used for tide modelling. The default None will create a 5000 m resolution grid if ds has a projected CRS (i.e. metre units), or a 0.05 degree resolution grid if ds has a geographic CRS (e.g. degree units). Note: higher resolutions do not necessarily provide better tide modelling performance, as results will be limited by the resolution of the underlying global tide model (e.g. 1/16th degree / ~5 km resolution grid for FES2014).

bufferint, optional

The amount by which to buffer the higher resolution grid extent when creating the new low resolution grid. This buffering is important as it ensures that ensure pixel-based tides are seamless across dataset boundaries. This buffer will eventually be clipped away when the low-resolution data is re-projected back to the resolution and extent of the higher resolution dataset. To ensure that at least two pixels occur outside of the dataset bounds, the default None applies a 12000 m buffer if ds has a projected CRS (i.e. metre units), or a 0.12 degree buffer if ds has a geographic CRS (e.g. degree units).

resample_methodstring, optional

If resampling is requested (see resample above), use this resampling method when converting from low resolution to high resolution pixels. Defaults to “bilinear”; valid options include “nearest”, “cubic”, “min”, “max”, “average” etc.

modelstring or list of strings

The tide model or a list of models used to model tides, as supported by the pyTMD Python package. Options include: - “FES2014” (default; pre-configured on DEA Sandbox) - “TPXO8-atlas” - “TPXO9-atlas-v5” - “EOT20” - “HAMTIDE11” - “GOT4.10”

dask_chunksstr or tuple, optional

Can be used to configure custom Dask chunking for the final resampling step. The default of “auto” will automatically set x/y chunks to match those in ds if they exist, otherwise will set x/y chunks that cover the entire extent of the dataset. For custom chunks, provide a tuple in the form (y, x), e.g. (2048, 2048).

dask_computebool, optional

Whether to compute results of the resampling step using Dask. If False, this will return tides_highres as a Dask array.

**model_tides_kwargs :

Optional parameters passed to the dea_tools.coastal.model_tides function. Important parameters include “directory” (used to specify the location of input tide modelling files) and “cutoff” (used to extrapolate modelled tides away from the coast; if not specified here, cutoff defaults to np.inf).

Returns:

If resample is False:

tides_lowresxr.DataArray

A low resolution data array giving either tide heights every timestep in ds (if times is None), tide heights at every time in times (if times is not None), or tide height quantiles for every quantile provided by calculate_quantiles.

If resample is True:

tides_highres, tides_lowrestuple of xr.DataArrays

In addition to tides_lowres (see above), a high resolution array of tide heights will be generated that matches the exact spatial resolution and extent of ds. This will contain either tide heights every timestep in ds (if times is None), tide heights at every time in times (if times is not None), or tide height quantiles for every quantile provided by calculate_quantiles.

dea_tools.coastal.tidal_stats(ds, tidepost_lat=None, tidepost_lon=None, plain_english=True, plot=True, modelled_freq='2h', linear_reg=False, round_stats=3, **model_tides_kwargs)

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

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

The function models tides at the centroid of the dataset by default, but a custom tidal modelling location can be specified using tidepost_lat and tidepost_lon.

The default settings use the FES2014 global tidal model, implemented using the pyTMD Python package. FES2014 was produced by NOVELTIS, LEGOS, CLS Space Oceanography Division and CNES. It is distributed by AVISO, with support from CNES (http://www.aviso.altimetry.fr/).

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.

• linear_reg (bool, optional) – Experimental: whether to return linear regression stats that assess whether dstellite-observed and all available tides show any decreasing or increasing trends over time. Not currently recommended as all observed regressions always return as significant due to far larger sample size.

• 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 dea_tools.coastal.model_tides function. Important parameters include “model” and “directory”, used to specify the tide model to use and the location of its files.

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

  all_slope: slope of any relationship between all available 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 available tide heights and time

dea_tools.coastal.tidal_stats_otps(ds, tidepost_lat=None, tidepost_lon=None, plain_english=True, plot=True, modelled_freq='2h', linear_reg=False, 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.

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

Tides are modelled using the OTPS tidal modelling software based on the TPXO8 tidal model: http://volkov.oce.orst.edu/tides/tpxo8_atlas.html

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.

• linear_reg (bool, optional) – Experimental: whether to return linear regression stats that assess whether dstellite-observed and all available tides show any decreasing or increasing trends over time. Not currently recommended as all observed regressions always return as significant due to far larger sample size.

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

  all_slope: slope of any relationship between all available 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 available tide heights and time

dea_tools.coastal.tidal_tag(ds, ebb_flow=False, swap_dims=False, tidepost_lat=None, tidepost_lon=None, return_tideposts=False, **model_tides_kwargs)

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

The function models tides at the centroid of the dataset by default, but a custom tidal modelling location can be specified using tidepost_lat and tidepost_lon.

The default settings use the FES2014 global tidal model, implemented using the pyTMD Python package. FES2014 was produced by NOVELTIS, LEGOS, CLS Space Oceanography Division and CNES. It is distributed by AVISO, with support from CNES (http://www.aviso.altimetry.fr/).

Parameters:

• ds (xarray.Dataset) – An xarray.Dataset object with x, y and time dimensions

• 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_m variable. Defaults to False.

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

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

• **model_tides_kwargs – Optional parameters passed to the dea_tools.coastal.model_tides function. Important parameters include “model” and “directory”, used to specify the tide model to use and the location of its files.

Returns:

• The original xarray.Dataset with a new tide_m 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).

dea_tools.coastal.tidal_tag_otps(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_m 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: http://volkov.oce.orst.edu/tides/tpxo8_atlas.html

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_m 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_m 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).

dea_tools.coastal.transect_distances(transects_gdf, lines_gdf, mode='distance')

Take a set of transects (e.g. shore-normal beach survey lines), and determine the distance along the transect to each object in a set of lines (e.g. shorelines). Distances are measured in the CRS of the input datasets.

For coastal applications, transects should be drawn from land to water (with the first point being on land so that it can be used as a consistent location from which to measure distances.

The distance calculation can be performed using two modes:

• ‘distance’: Distances are measured from the start of the transect to where it intersects with each line. Any transect that intersects a line more than once is ignored. This mode is useful for measuring e.g. the distance to the shoreline over time from a consistent starting location.

• ‘width’ Distances are measured between the first and last intersection between a transect and each line. Any transect that intersects a line only once is ignored. This is useful for e.g. measuring the width of a narrow area of coastline over time, e.g. the neck of a spit or tombolo.

Parameters:

• transects_gdf (geopandas.GeoDataFrame) – A GeoDataFrame containing one or multiple vector profile lines. The GeoDataFrame’s index column will be used to name the rows in the output distance table.

• lines_gdf (geopandas.GeoDataFrame) – A GeoDataFrame containing one or multiple vector line features that intersect the profile lines supplied to transects_gdf. The GeoDataFrame’s index column will be used to name the columns in the output distance table.

• mode (string, optional) – Whether to use ‘distance’ (for measuring distances from the start of a profile) or ‘width’ mode (for measuring the width between two profile intersections). See docstring above for more info; defaults to ‘distance’.

Returns:

distance_df – A DataFrame containing distance measurements for each profile line (rows) and line feature (columns).

Return type:

pandas.DataFrame