syncopy.shared.tools.best_match#

syncopy.shared.tools.best_match(source, selection, span=False, tol=None, squash_duplicates=False)[source]#

Find matching elements in a given 1d-array/list

Parameters:

  • source (NumPy 1d-array/list) – Reference array whose elements are to be matched by selection

  • selection (NumPy 1d-array/list) – Array of query-values whose closest matches are to be found in source. Note that source and selection need not be the same length.

  • span (bool) – If True, selection is interpreted as (closed) interval [lo, hi] and source is queried for all elements contained in the interval, i.e., lo <= src <= hi for src in source (typically used for toilim/foilim-like selections).

  • tol (None or float) – If None for each component of selection the closest value in source is selected, e.g., for source = [10, 20] and selection = [-50, 0, 50] the closest values are [10, 10, 20]. If not None, ensures values in selection do not deviate further than tol from source. If any element sel of selection is outside a tol-neighborhood around source, i.e., np.abs(sel - source).max() >= tol, a SPYValueError is raised.

  • squash_duplicates (bool) – If True, identical matches are removed from the result.

Returns:

  • values (NumPy 1darray) – Values of source that most closely match given elements in selection

  • idx (NumPy 1darray) – Indices of values with respect to source, such that, source[idx] == values

Notes

This is an auxiliary method that is intended purely for internal use. Thus, no error checking is performed.

Examples

Exact matching, ordered source and selection:

>>> best_match(np.arange(10), [2,5])
(array([2, 5]), array([2, 5]))

Inexact matching, ordered source and selection:

>>> source = np.arange(10)
>>> selection = np.array([1.5, 1.5, 2.2, 6.2, 8.8])
>>> best_match(source, selection)
(array([2, 2, 2, 6, 9]), array([2, 2, 2, 6, 9]))

Inexact matching, unordered source and selection:

>>> source = np.array([2.2, 1.5, 1.5, 6.2, 8.8])
>>> selection = np.array([1.9, 9., 1., -0.4, 1.2, 0.2, 9.3])
>>> best_match(source, selection)
(array([2.2, 8.8, 1.5, 1.5, 1.5, 1.5, 8.8]), array([0, 4, 1, 1, 1, 1, 4]))

Same as above, but ignore duplicate matches

>>> best_match(source, selection, squash_duplicates=True)
(array([2.2, 8.8, 1.5]), array([0, 4, 1]))

Interval-matching:

>>> best_match(np.arange(10), [2.9, 6.1], span=True)
(array([3, 4, 5, 6]), array([3, 4, 5, 6]))