deltametrics.mobility.calculate_planform_overlap

deltametrics.mobility.calculate_planform_overlap(chmap, landmap, basevalues=None, basevalues_idx=None, window=None, window_idx=None)

Calculate channel planform overlap.

This metric is calculated per Wickert et al 2013 [1] and measures the loss of channel system overlap with previous channel patterns. This requires an input channel map, land map, as well as defining the base maps to use and the time window over which you want to look.

The normalized overlap is calculated as:

\[O_\Phi = 1 - \left( \frac{D}{A \cdot \Phi} \right)\]

where \(D\) is the number of chaneged pixels between the base and target maps, \(A\) is the total number of pixels in a single map, and \(\Phi\) is a random scatter parameter.

\(D\) is calculated as:

\[D(B, T) = \sum\limits^{m_r}_{i=1} \sum\limits^{n_c}_{j=1} \left| K_B - K_T \right|\]

where \(K_B\) and \(K_T\) are the channel mask values at the base and target maps, respectively.

\(\Phi\) is calculated as:

\[\Phi = f_{w,B} \cdot f_{d,T} + f_{d,B} \cdot f_{w,T}\]

where \(f_{w,B}\) is the fraction of water pixels in the base map, \(f_{d,B}\) is the fraction of dry pixels in the base map, \(f_{w,T}\) is the fraction of water pixels in the target map, and \(f_{d,T}\) is the fraction of dry pixels in the target map.

The calculation of \(O_\Phi\) is conducted between the base map(s) and channel maps (target maps) at each time lag for the duration of the time window specified. When multiple base maps are used, this calculation is conducted for each base map and its corresponding target maps, and the results are returned as an array in which each row represents the overlap results for a given base map. Each column represents the overlap results for a given time lag relative to the base map.

[1]

Wickert, Andrew D., John M. Martin, Michal Tal, Wonsuck Kim, Ben Sheets, and Chris Paola. “River channel lateral mobility: Metrics, time scales, and controls.” Journal of Geophysical Research: Earth Surface 118, no. 2 (2013): 396-412.

Parameters:

• chmap (list, xarray.DataArray, numpy.ndarray) – Either a list of 2-D deltametrics.mask, xarray.DataArray, or numpy.ndarray objects, or a t-x-y 3-D xarray.DataArray or numpy.ndarray with channel mask values.

• landmap (list, xarray.DataArray, numpy.ndarray) – Either a list of 2-D deltametrics.mask, xarray.DataArray, or numpy.ndarray objects, or a t-x-y 3-D xarray.DataArray or numpy.ndarray with land mask values.

• basevalues (list, int, float, optional) – List of time values to use as the base channel map. (or single value)

• basevalues_idx (list, optional) – List of time indices to use as the base channel map. (or single value)

• window (int, float, optional) – Duration of time to use as the time lag (aka how far from the basemap will be analyzed).

• window_idx (int, float, optional) – Duration of time in terms of indices (# of save states) to use as the time lag.

Returns:

Ophi – A 2-D array of the normalized overlap values, array is of shape len(basevalues) x time_window so each row in the array represents the overlap values associated with a given base value and the columns are associated with each time lag.

Return type:

ndarray