cayula_cornillon

Cayula-Cornillon algorithm.

This only include histogram analysis and cohesion check. It does not include cloud detection (this is left to the data provider) or contour following.

DEFAULT_DIMS: list[Hashable] = ['lat', 'lon']

Default dimensions names.

Used for Xarray input where the dims argument is None and window_size is not a Mapping.

cayula_cornillon_dask(input_field, window_size=32, window_step=None, bins_width=0.1, bins_shift=0.0, bimodal_criteria=0.7, axes=None, **kwargs)

Apply Cayula-Cornillon algorithm.

This only include histogram analysis and cohesion check. It does not include cloud detection (this is left to the data provider) or contour following.

Parameters:

• input_field (Array) – Array of the input field.

• window_size (int | Sequence[int]) – Total size of the moving window, in pixels. If an integer, the size is taken identical for both axis. Otherwise it must be a sequence of 2 integers specifying the window size along both axis. The order must then follow that of the data. For instance, for data arranged as (‘time’, ‘lat’, ‘lon’) if we specify window_size=[3, 5] the window will be of size 3 along latitude and size 5 for longitude.

• window_step (int | Sequence[int] | None) – Step by which to shift the moving window. If None (default), use the window size (meaning there is no overlap). If an integer, the step is taken identical for both axis. Otherwise it must be a sequence of 2 integers specifying the window step along both axis, in the same order as the window size.

• bins_width (float) – Width of the bins used to construct the histogram.

• bins_shift (float) – If non-zero, shift the leftmost and rightmost edges of the bins by this amount to avoid artefacts caused by the discretization of the input field data.

• bimodal_criteria (float) – Criteria for determining if the distribution is bimodal or not. The default is 0.7, as choosen in Cayula & Cornillon (1992).

• axes (Sequence[int] | None) – Indices of the the y/lat and x/lon axes on which to work. If None (default), the last two axes are used.

• kwargs – See available kwargs for universal functions at Generalized universal function API.

Returns:

Array of the number of fronts detected for each pixel. If there is overlap when shifting the moving window, the value can be greater than 1.

Return type:

Array

cayula_cornillon_numpy(input_field, window_size=32, window_step=None, bins_width=0.1, bins_shift=0.0, bimodal_criteria=0.7, axes=None, **kwargs)

Apply Cayula-Cornillon algorithm.

This only include histogram analysis and cohesion check. It does not include cloud detection (this is left to the data provider) or contour following.

Parameters:

• input_field (ndarray[_Size, dtype[Any]]) – Array of the input field.

• window_size (int | Sequence[int]) – Total size of the moving window, in pixels. If an integer, the size is taken identical for both axis. Otherwise it must be a sequence of 2 integers specifying the window size along both axis. The order must then follow that of the data. For instance, for data arranged as (‘time’, ‘lat’, ‘lon’) if we specify window_size=[3, 5] the window will be of size 3 along latitude and size 5 for longitude.

• window_step (int | Sequence[int] | None) – Step by which to shift the moving window. If None (default), use the window size (meaning there is no overlap). If an integer, the step is taken identical for both axis. Otherwise it must be a sequence of 2 integers specifying the window step along both axis, in the same order as the window size.

• bins_width (float) – Width of the bins used to construct the histogram.

• bins_shift (float) – If non-zero, shift the leftmost and rightmost edges of the bins by this amount to avoid artefacts caused by the discretization of the input field data.

• bimodal_criteria (float) – Criteria for determining if the distribution is bimodal or not. The default is 0.7, as choosen in Cayula & Cornillon (1992).

• axes (Sequence[int] | None) – Indices of the the y/lat and x/lon axes on which to work. If None (default), the last two axes are used.

• kwargs – See available kwargs for universal functions at Generalized universal function API.

Returns:

Array of the number of fronts detected for each pixel. If there is overlap when shifting the moving window, the value can be greater than 1.

Return type:

ndarray[_Size, dtype[int64]]

cayula_cornillon_xarray(input_field, window_size=32, window_step=None, bins_width=0.1, bins_shift=0.0, bimodal_criteria=0.7, dims=None)

Apply Cayula-Cornillon algorithm.

This only include histogram analysis and cohesion check. It does not include cloud detection (this is left to the data provider) or contour following.

Parameters:

• input_field (DataArray) – Array of the input field.

• window_size (int | Mapping[Hashable, int]) – Total size of the moving window, in pixels. If a single integer, the size is taken identical for both axis. Otherwise it can be a mapping of the dimensions names to the window size along this axis.

• window_step (int | Mapping[Hashable, int] | None) – Step by which to shift the moving window. If None (default), use the window size (meaning there is no overlap). If an integer, the step is taken identical for both axis. Otherwise it can be a mapping of the dimensions names to the window step along this axis.

• bins_width (float) – Width of the bins used to construct the histogram.

• bins_shift (float) –

  If a non-zero float, shift the leftmost and rightmost edges of the bins by this amount to avoid artefacts caused by the discretization of the input field data. If True (default), wether to shift and by which amount is determined using the input metadata.

  Set to 0 or False to not shift bins.

• bimodal_criteria (float) – Criteria for determining if the distribution is bimodal or not. The default is 0.7, as choosen in Cayula & Cornillon (1992).

• kwargs – See available kwargs for universal functions at Generalized universal function API.

• dims (Collection[Hashable] | None) – Names of the dimensions along which to apply the algorithm. Order is irrelevant, no reordering will be made between the two dimensions. If the window_size argument is given as a mapping, its keys are used instead. If not specified, is taken as module-wide variable DEFAULT_DIMS which defaults to {'lat', 'lon'}.

Returns:

Array of the number of fronts detected for each pixel. If there is overlap when shifting the moving window, the value can be greater than 1.

Return type:

DataArray

cohesion(cluster, valid)

Compiled with Numba

• Options: nopython: True, parallel: True

Check the cohesion of the two clusters.

Criteria for cohesion is hardcoded at:

\[ \begin{align}\begin{aligned}C1, C2 > 0.92\\C > 0.90\end{aligned}\end{align} \]

Parameters:

• cluster (ndarray[tuple[int, int], dtype[int8]]) – Array giving the cluster index (0 or 1 for cold/warm). Size of the moving window.

• valid (ndarray[tuple[int, int], dtype[bool]]) – Mask of the moving window. True is valid value.

Returns:

True if the clusters are spatially coherent.

Return type:

bool

count_neighbor(cluster, invalid, pixel, neighbor)

Compiled with Numba

• Options: nopython: True, nogil: True

Count one neighbor.

Parameters:

• cluster (ndarray[tuple[int, int], dtype[int8]]) – Array giving the cluster index (0 or 1 for cold/warm). Size of the moving window.

• invalid (ndarray[tuple[int, int], dtype[bool]]) – Mask of the moving window. True is invalid value.

• pixel (tuple[int, int]) – Location of the first pixel in the window.

• neighbor (tuple[int, int]) – Location of the considered neighbor in the window.

Returns:

Array of T0, T1, R

Return type:

ndarray[tuple[int], dtype[uint16]]

get_edges(cluster, invalid)

Compiled with Numba

• Options: nopython: True, parallel: True

• Signatures:

  • (Array(int8, 2, ‘A’, False, aligned=True), Array(bool, 2, ‘A’, False, aligned=True)) -> array(bool, 2d, A)

Find edges between clusters inside the window.

Parameters:

• cluster (ndarray[tuple[int, int], dtype[int8]]) – Array giving the cluster index (0 or 1 for cold/warm). Size of the moving window.

• invalid (ndarray[tuple[int, int], dtype[bool]]) – Mask of the moving window. True is invalid value.

Returns:

Array of edges the size of the window, True if the pixel is an edge.

Return type:

ndarray[tuple[int, int], dtype[bool]]

get_threshold(values, bins_width, bins_shift, bimodal_criteria)

Compiled with Numba

• Options: nopython: True, parallel: True

• Signatures:

  • (Array(float32, 1, ‘A’, False, aligned=True), float64, float64, float64) -> OptionalType(float64)

  • (Array(float64, 1, ‘A’, False, aligned=True), float64, float64, float64) -> OptionalType(float64)

Find optimal separation temperature between water masses.

This is the histogram analysis part of Cayula-Cornillon.

Parameters:

• values (ndarray[tuple[Any, ...], dtype[_ScalarT]]) – 1D array of valid values in the moving window.

• bins_width (float) – Width of the bins used to construct the histogram when computing the bimodality. Must have same units and same data type as the input array.

• bins_shift (float) – If non-zero, shift the leftmost and rightmost edges of the bins by this amount to avoid artefacts caused by the discretization of the input field data.

• bimodal_criteria (float) – Criteria for determining if the distribution is bimodal or not.

Returns:

Optimal separation temperature if the criterion is reached. None otherwise.

Return type:

float | None