check_orders

sofia_redux.toolkit.resampling.check_orders(orders, coordinates, reference, algorithm=1, mask=None, minimum_points=None, required=False, counts=-1)

Checks the sample distribution is suitable for a polynomial fit order.

For a polynomial fit to be successful at a given order, one needs to ensure that the sample distribution is suitable for such a fit. At a minimum, there need to be enough samples to derive a fit. However, unless the samples are known to be distributed in such a way where a fit is always possible (such as regularly spaced samples), there is the possibility that the fit may be under-determined. For example, it is not possible to perform any other fit than the mean of sample values (order 0) if the samples all share the same coordinate.

This problem is compounded by the use of numba which does not allow any exception handling. If a fit fails at a single reference position, the whole algorithm will fail.

There are several algorithms available, ordered in decreasing robustness, but increasing speed. The chosen algorithm must be supplied using an integer label (because numba). Please see the relevant function listed in the table below for a more detailed description of each. The order_algorithm parameter is supplied to the main resampling algorithm during __init__ and is used to select the relevant algorithm.

algorithm	Function	order_algorithm
1	check_orders_with_bounds()	‘bounded’
2	check_orders_without_bounds()	‘extrapolate’
3	check_orders_with_counts()	‘counts’

Generally, check_orders_with_bounds() is the most robust and ensures that a fit will not only succeed, but is not likely to deviate widely from the expected result. The check_orders_without_bounds() function should also allow fits to succeed, but allow fits to be generated away from the sample distribution. This may be desirable, for example, if one is resampling an image and wishes to perform fits close to the edge. Finally, check_orders_with_counts() is fast, but there is a decent possibility that the fit will fail if the user cannot guarantee that the samples are distributed appropriately.

In rare cases, a distribution of collinear samples, not aligned along any dimensional axis may pass the check_orders test causing resampling algorithm to fail. In this case, please consider using check_edge_with_distribution() to perform such a check. This may be invoked by supplying edge_algorithm='distribution' during the initialization of the main resampling algorithm.

Parameters:

algorithmint

An integer specifying the order checking algorithm to use. If an invalid option is supplied (not listed in the table above), the return value of -1 will abort any subsequent fitting.

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

The coordinates of the sample distribution. Not used by the counts algorithm, but must still be supplied as an array with the correct dimensions.

referencenumpy.ndarray (n_dimensions,)

The coordinates of the point at which to perform a fit. Only required by the ‘bounded’ algorithm, but a value of the correct array shape must still be supplied.

masknumpy.ndarray of bool (n_samples,), optional

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

minimum_pointsint, optional

The minimum number of points required to perform a fit of the desired order, optionally passed in for speed if pre-calculated. Only used by the ‘counts’ algorithm.

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.

countsint, optional

This is required by the ‘counts’ algorithm. If counts < 0, it will be determined by sum(mask). If counts is less than zero, and a mask is not supplied, not fit will be performed.

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.