check_orders_with_bounds

sofia_redux.toolkit.resampling.check_orders_with_bounds(orders, coordinates, reference, mask=None, required=False)

Checks maximum order for sample coordinates bounding a reference.

Given the coordinates of a sample distribution (\(X\)), a reference position (\(X_{ref}\)), and the desired orders of fit (\(o\)), returns the maximum available order of fit.

For dimension \(k\) define the sets of unique values:

\[\begin{split}s_k^- = \{ x \in X_k |\, x < X_{ref, k} \} \\ s_k^+ = \{ x \in X_k |\, x > X_{ref, k} \}\end{split}\]

The maximum order is then given as:

\[o_k^{max} = min\{ |s_k^-|, |s_k^+|, o_k \}\]

where \(|.|\) represents the cardinality (size) of the set.

For example, consider a 1-dimensional set of coordinates:

\[X = [1, 1, 1, 2, 3, 4, 5, 5, 5, 5, 6]\]

and we wish to perform an order=3 polynomial fit at \(X_{ref}=2.5\). There are 4 unique values of \(X > X_{ref}\) (\(\{3, 4, 5, 6\}\)), but only 2 unique values of \(X < X_{ref}\) (\(\{1, 2\}\)). The return value will be 2, indicating that only a 2nd order polynomial fit should be attempted. If a 1st order polynomial fit was requested, the return value would be 1 since there are enough points less than and greater than the reference.

Parameters:

ordersnumpy.ndarray of int

The desired order of the fit as a (1,) or (n_dimensions,) array. If only a single value is supplied, it will be applied over all dimensions. This serves as an upper limit for the check. If the samples are distributed in a way that allows for a fit to be performed using orders, the return value will also be orders.

coordinatesnumpy.ndarray (n_dimensions, n_coordinates)

The coordinates of the sample distribution.

referencenumpy.ndarray (n_dimensions,)

The reference coordinate.

masknumpy.ndarray of bool (n_coordinates,), optional

An optional mask where False values indicate the associated sample should not be included in determining the maximum order.

requiredbool, optional

If required is False, the maximum available order given the distribution will be returned (up to a maximum of orders). If required is True, and the maximum available order is less than orders, the first element of the return value will be set to -1, indicating the criteria was not met.

Returns:

maximum_ordersnumpy.ndarray

An array of shape (1,) or (n_dimensions,) based on whether a single orders was passed in for all dimensions, or each dimension has a separate order requirement. If required was set to True, and the sample distribution did not allow for the requested order, the first element will be set to -1. Otherwise, if required was False, the maximum order for each dimension will be returned. If a single orders was to be applied over all dimensions, the return value will also be of size 1, but contains the min(maximum_order) over all dimensions.