find_nearest

mdtools.numpy_helper_functions.find_nearest(a, val, axis=None, return_index=False)[source]

Find the values in an array which are closest to a given value along an axis.

Parameters:

a (array_like) – The input array.
val (scalar or array_like) – The value(s) to search for. If a search value itself is not contained in a along the search axis, the value closest to val is returned. If val is an array, a and val must be broadcastable.
axis (None or int, optional) – The axis along which to search. If axis is None (default), a global search over the flattened array will be performed.
return_index (bool, optional) – If True, also return the indices of the first values in a that are closest to val along the search axis.

Returns:

nearest (scalar or numpy.ndarray) – The first value(s) in a closest to val along axis.
ix (int or numpy.ndarray of ints) – The indices of the first values in a nearest to val along the given axis. Only returned if return_index is True.

See also

numpy.searchsorted(): Find indices where elements should be inserted to maintain order
numpy.unravel_index(): Convert the returned index ix to a tuple of index arrays suitable to index a multidimensional input array a if axis was None
mdtools.numpy_helper_functions.ix_along_axis_to_global_ix(): Same as numpy.unravel_index(), but to be used when axis was not None

Notes

In case of multiple occurrences of the closest values, only the first occurrence (and its index) is returned.

Examples

>>> a = np.arange(-1, 1.5, 0.5)
>>> a
array([-1. , -0.5,  0. ,  0.5,  1. ])
>>> mdt.nph.find_nearest(a, 0)
0.0
>>> mdt.nph.find_nearest(a, 0, return_index=True)
(0.0, 2)

mdtools.numpy_helper_functions.find_nearest() returns the first value that is closest to the given value.

>>> mdt.nph.find_nearest(a, -0.75, return_index=True)
(-1.0, 0)
>>> mdt.nph.find_nearest(a, 0.75, return_index=True)
(0.5, 3)

>>> b = np.array([0, 2, 4, 2])
>>> mdt.nph.find_nearest(b, 2, return_index=True)
(2, 1)

If axis is None, mdtools.numpy_helper_functions.find_nearest() searches globally in the flattened array for the value closest to the given value and returns its first occurrence. To get an object suitable to index the input array, use numpy.unravel_index().

>>> c = np.array([[0, 1, 2],
...               [1, 2, 0]])
>>> n, ix = mdt.nph.find_nearest(c, 1.8, return_index=True)
>>> n
2
>>> ix
2
>>> ix_global = np.unravel_index(ix, c.shape)
>>> ix_global
(0, 2)
>>> c[ix_global]
2

If axis is not None, mdtools.numpy_helper_functions.find_nearest() returns the first occurrences along the given axis. To get an object suitable to index the input array, use mdtools.numpy_helper_functions.ix_along_axis_to_global_ix().

>>> mdt.nph.find_nearest(c, 1.8, axis=0, return_index=True)
(array([1, 2, 2]), array([1, 1, 0]))
>>> n, ix = mdt.nph.find_nearest(c, 1.8, axis=1, return_index=True)
>>> n
array([2, 2])
>>> ix
array([2, 1])
>>> ix_global = mdt.nph.ix_along_axis_to_global_ix(ix, axis=1)
>>> ix_global
(array([0, 1]), array([2, 1]))
>>> c[ix_global]
array([2, 2])

3-dimensional example:

>>> d = np.array([[[0, 1, 2],
...                [1, 2, 0]],
...
...               [[2, 0, 1],
...                [0, 2, 1]]])
>>> n, ix = mdt.nph.find_nearest(d, 1.8, axis=0, return_index=True)
>>> n
array([[2, 1, 2],
       [1, 2, 1]])
>>> ix
array([[1, 0, 0],
       [0, 0, 1]])
>>> n, ix = mdt.nph.find_nearest(d, 1.8, axis=1, return_index=True)
>>> n
array([[1, 2, 2],
       [2, 2, 1]])
>>> ix
array([[1, 1, 0],
       [0, 1, 0]])
>>> n, ix = mdt.nph.find_nearest(d, 1.8, axis=2, return_index=True)
>>> n
array([[2, 2],
       [2, 2]])
>>> ix
array([[2, 1],
       [0, 1]])

You can also specify an array of values to search for.

>>> c
array([[0, 1, 2],
       [1, 2, 0]])
>>> x = np.array([1, 1, 0])
>>> mdt.nph.find_nearest(c, x, axis=0, return_index=True)
(array([1, 1, 0]), array([1, 0, 1]))

Edge cases:

>>> x = np.array([])
>>> mdt.nph.find_nearest(x, 0, return_index=True)
(array([], dtype=float64), array([], dtype=int64))
>>> mdt.nph.find_nearest(x, 0, axis=0, return_index=True)
(array([], dtype=float64), array([], dtype=int64))

>>> x = np.array(0)
>>> mdt.nph.find_nearest(x, 0, return_index=True)
Traceback (most recent call last):
...
ValueError: The dimension of a must be greater than zero