382 lines
12 KiB
Python
382 lines
12 KiB
Python
|
#!/usr/bin/env python
|
||
|
|
# -*- coding: utf-8 -*-
|
||
|
|
"""Matching functions"""
|
||
|
|
|
||
|
|
import numpy as np
|
||
|
|
import numba
|
||
|
|
|
||
|
|
from .exceptions import ParameterError
|
||
|
|
from .utils import valid_intervals
|
||
|
|
from .._typing import _SequenceLike
|
||
|
|
|
||
|
|
__all__ = ["match_intervals", "match_events"]
|
||
|
|
|
||
|
|
|
||
|
|
@numba.jit(nopython=True, cache=True) # type: ignore
|
||
|
|
def __jaccard(int_a: np.ndarray, int_b: np.ndarray): # pragma: no cover
|
||
|
|
"""Jaccard similarity between two intervals
|
||
|
|
|
||
|
|
Parameters
|
||
|
|
----------
|
||
|
|
int_a, int_b : np.ndarrays, shape=(2,)
|
||
|
|
|
||
|
|
Returns
|
||
|
|
-------
|
||
|
|
Jaccard similarity between intervals
|
||
|
|
"""
|
||
|
|
ends = [int_a[1], int_b[1]]
|
||
|
|
if ends[1] < ends[0]:
|
||
|
|
ends.reverse()
|
||
|
|
|
||
|
|
starts = [int_a[0], int_b[0]]
|
||
|
|
if starts[1] < starts[0]:
|
||
|
|
starts.reverse()
|
||
|
|
|
||
|
|
intersection = ends[0] - starts[1]
|
||
|
|
if intersection < 0:
|
||
|
|
intersection = 0.0
|
||
|
|
|
||
|
|
union = ends[1] - starts[0]
|
||
|
|
|
||
|
|
if union > 0:
|
||
|
|
return intersection / union
|
||
|
|
|
||
|
|
return 0.0
|
||
|
|
|
||
|
|
|
||
|
|
@numba.jit(nopython=True, cache=True)
|
||
|
|
def __match_interval_overlaps(query, intervals_to, candidates): # pragma: no cover
|
||
|
|
"""Find the best Jaccard match from query to candidates"""
|
||
|
|
best_score = -1
|
||
|
|
best_idx = -1
|
||
|
|
for idx in candidates:
|
||
|
|
score = __jaccard(query, intervals_to[idx])
|
||
|
|
|
||
|
|
if score > best_score:
|
||
|
|
best_score, best_idx = score, idx
|
||
|
|
return best_idx
|
||
|
|
|
||
|
|
|
||
|
|
@numba.jit(nopython=True, cache=True) # type: ignore
|
||
|
|
def __match_intervals(
|
||
|
|
intervals_from: np.ndarray, intervals_to: np.ndarray, strict: bool = True
|
||
|
|
) -> np.ndarray: # pragma: no cover
|
||
|
|
"""Numba-accelerated interval matching algorithm."""
|
||
|
|
# sort index of the interval starts
|
||
|
|
start_index = np.argsort(intervals_to[:, 0])
|
||
|
|
|
||
|
|
# sort index of the interval ends
|
||
|
|
end_index = np.argsort(intervals_to[:, 1])
|
||
|
|
|
||
|
|
# and sorted values of starts
|
||
|
|
start_sorted = intervals_to[start_index, 0]
|
||
|
|
# and ends
|
||
|
|
end_sorted = intervals_to[end_index, 1]
|
||
|
|
|
||
|
|
search_ends = np.searchsorted(start_sorted, intervals_from[:, 1], side="right")
|
||
|
|
search_starts = np.searchsorted(end_sorted, intervals_from[:, 0], side="left")
|
||
|
|
|
||
|
|
output = np.empty(len(intervals_from), dtype=numba.uint32)
|
||
|
|
for i in range(len(intervals_from)):
|
||
|
|
query = intervals_from[i]
|
||
|
|
|
||
|
|
# Find the intervals that start after our query ends
|
||
|
|
after_query = search_ends[i]
|
||
|
|
# And the intervals that end after our query begins
|
||
|
|
before_query = search_starts[i]
|
||
|
|
|
||
|
|
# Candidates for overlapping have to (end after we start) and (begin before we end)
|
||
|
|
candidates = set(start_index[:after_query]) & set(end_index[before_query:])
|
||
|
|
|
||
|
|
# Proceed as before
|
||
|
|
if len(candidates) > 0:
|
||
|
|
output[i] = __match_interval_overlaps(query, intervals_to, candidates)
|
||
|
|
elif strict:
|
||
|
|
# Numba only lets us use compile-time constants in exception messages
|
||
|
|
raise ParameterError
|
||
|
|
else:
|
||
|
|
# Find the closest interval
|
||
|
|
# (start_index[after_query] - query[1]) is the distance to the next interval
|
||
|
|
# (query[0] - end_index[before_query])
|
||
|
|
dist_before = np.inf
|
||
|
|
dist_after = np.inf
|
||
|
|
if search_starts[i] > 0:
|
||
|
|
dist_before = query[0] - end_sorted[search_starts[i] - 1]
|
||
|
|
if search_ends[i] + 1 < len(intervals_to):
|
||
|
|
dist_after = start_sorted[search_ends[i] + 1] - query[1]
|
||
|
|
if dist_before < dist_after:
|
||
|
|
output[i] = end_index[search_starts[i] - 1]
|
||
|
|
else:
|
||
|
|
output[i] = start_index[search_ends[i] + 1]
|
||
|
|
return output
|
||
|
|
|
||
|
|
|
||
|
|
def match_intervals(
|
||
|
|
intervals_from: np.ndarray, intervals_to: np.ndarray, strict: bool = True
|
||
|
|
) -> np.ndarray:
|
||
|
|
"""Match one set of time intervals to another.
|
||
|
|
|
||
|
|
This can be useful for tasks such as mapping beat timings
|
||
|
|
to segments.
|
||
|
|
|
||
|
|
Each element ``[a, b]`` of ``intervals_from`` is matched to the
|
||
|
|
element ``[c, d]`` of ``intervals_to`` which maximizes the
|
||
|
|
Jaccard similarity between the intervals::
|
||
|
|
|
||
|
|
max(0, |min(b, d) - max(a, c)|) / |max(d, b) - min(a, c)|
|
||
|
|
|
||
|
|
In ``strict=True`` mode, if there is no interval with positive
|
||
|
|
intersection with ``[a,b]``, an exception is thrown.
|
||
|
|
|
||
|
|
In ``strict=False`` mode, any interval ``[a, b]`` that has no
|
||
|
|
intersection with any element of ``intervals_to`` is instead
|
||
|
|
matched to the interval ``[c, d]`` which minimizes::
|
||
|
|
|
||
|
|
min(|b - c|, |a - d|)
|
||
|
|
|
||
|
|
that is, the disjoint interval [c, d] with a boundary closest
|
||
|
|
to [a, b].
|
||
|
|
|
||
|
|
.. note:: An element of ``intervals_to`` may be matched to multiple
|
||
|
|
entries of ``intervals_from``.
|
||
|
|
|
||
|
|
Parameters
|
||
|
|
----------
|
||
|
|
intervals_from : np.ndarray [shape=(n, 2)]
|
||
|
|
The time range for source intervals.
|
||
|
|
The ``i`` th interval spans time ``intervals_from[i, 0]``
|
||
|
|
to ``intervals_from[i, 1]``.
|
||
|
|
``intervals_from[0, 0]`` should be 0, ``intervals_from[-1, 1]``
|
||
|
|
should be the track duration.
|
||
|
|
intervals_to : np.ndarray [shape=(m, 2)]
|
||
|
|
Analogous to ``intervals_from``.
|
||
|
|
strict : bool
|
||
|
|
If ``True``, intervals can only match if they intersect.
|
||
|
|
If ``False``, disjoint intervals can match.
|
||
|
|
|
||
|
|
Returns
|
||
|
|
-------
|
||
|
|
interval_mapping : np.ndarray [shape=(n,)]
|
||
|
|
For each interval in ``intervals_from``, the
|
||
|
|
corresponding interval in ``intervals_to``.
|
||
|
|
|
||
|
|
See Also
|
||
|
|
--------
|
||
|
|
match_events
|
||
|
|
|
||
|
|
Raises
|
||
|
|
------
|
||
|
|
ParameterError
|
||
|
|
If either array of input intervals is not the correct shape
|
||
|
|
|
||
|
|
If ``strict=True`` and some element of ``intervals_from`` is disjoint from
|
||
|
|
every element of ``intervals_to``.
|
||
|
|
|
||
|
|
Examples
|
||
|
|
--------
|
||
|
|
>>> ints_from = np.array([[3, 5], [1, 4], [4, 5]])
|
||
|
|
>>> ints_to = np.array([[0, 2], [1, 3], [4, 5], [6, 7]])
|
||
|
|
>>> librosa.util.match_intervals(ints_from, ints_to)
|
||
|
|
array([2, 1, 2], dtype=uint32)
|
||
|
|
>>> # [3, 5] => [4, 5] (ints_to[2])
|
||
|
|
>>> # [1, 4] => [1, 3] (ints_to[1])
|
||
|
|
>>> # [4, 5] => [4, 5] (ints_to[2])
|
||
|
|
|
||
|
|
The reverse matching of the above is not possible in ``strict`` mode
|
||
|
|
because ``[6, 7]`` is disjoint from all intervals in ``ints_from``.
|
||
|
|
With ``strict=False``, we get the following:
|
||
|
|
|
||
|
|
>>> librosa.util.match_intervals(ints_to, ints_from, strict=False)
|
||
|
|
array([1, 1, 2, 2], dtype=uint32)
|
||
|
|
>>> # [0, 2] => [1, 4] (ints_from[1])
|
||
|
|
>>> # [1, 3] => [1, 4] (ints_from[1])
|
||
|
|
>>> # [4, 5] => [4, 5] (ints_from[2])
|
||
|
|
>>> # [6, 7] => [4, 5] (ints_from[2])
|
||
|
|
"""
|
||
|
|
if len(intervals_from) == 0 or len(intervals_to) == 0:
|
||
|
|
raise ParameterError("Attempting to match empty interval list")
|
||
|
|
|
||
|
|
# Verify that the input intervals has correct shape and size
|
||
|
|
valid_intervals(intervals_from)
|
||
|
|
valid_intervals(intervals_to)
|
||
|
|
|
||
|
|
try:
|
||
|
|
# Suppress type check because of numba wrapper
|
||
|
|
return __match_intervals(intervals_from, intervals_to, strict=strict) # type: ignore
|
||
|
|
except ParameterError as exc:
|
||
|
|
raise ParameterError(f"Unable to match intervals with strict={strict}") from exc
|
||
|
|
|
||
|
|
|
||
|
|
def match_events(
|
||
|
|
events_from: _SequenceLike,
|
||
|
|
events_to: _SequenceLike,
|
||
|
|
left: bool = True,
|
||
|
|
right: bool = True,
|
||
|
|
) -> np.ndarray:
|
||
|
|
"""Match one set of events to another.
|
||
|
|
|
||
|
|
This is useful for tasks such as matching beats to the nearest
|
||
|
|
detected onsets, or frame-aligned events to the nearest zero-crossing.
|
||
|
|
|
||
|
|
.. note:: A target event may be matched to multiple source events.
|
||
|
|
|
||
|
|
Examples
|
||
|
|
--------
|
||
|
|
>>> # Sources are multiples of 7
|
||
|
|
>>> s_from = np.arange(0, 100, 7)
|
||
|
|
>>> s_from
|
||
|
|
array([ 0, 7, 14, 21, 28, 35, 42, 49, 56, 63, 70, 77, 84, 91,
|
||
|
|
98])
|
||
|
|
>>> # Targets are multiples of 10
|
||
|
|
>>> s_to = np.arange(0, 100, 10)
|
||
|
|
>>> s_to
|
||
|
|
array([ 0, 10, 20, 30, 40, 50, 60, 70, 80, 90])
|
||
|
|
>>> # Find the matching
|
||
|
|
>>> idx = librosa.util.match_events(s_from, s_to)
|
||
|
|
>>> idx
|
||
|
|
array([0, 1, 1, 2, 3, 3, 4, 5, 6, 6, 7, 8, 8, 9, 9])
|
||
|
|
>>> # Print each source value to its matching target
|
||
|
|
>>> zip(s_from, s_to[idx])
|
||
|
|
[(0, 0), (7, 10), (14, 10), (21, 20), (28, 30), (35, 30),
|
||
|
|
(42, 40), (49, 50), (56, 60), (63, 60), (70, 70), (77, 80),
|
||
|
|
(84, 80), (91, 90), (98, 90)]
|
||
|
|
|
||
|
|
Parameters
|
||
|
|
----------
|
||
|
|
events_from : ndarray [shape=(n,)]
|
||
|
|
Array of events (eg, times, sample or frame indices) to match from.
|
||
|
|
events_to : ndarray [shape=(m,)]
|
||
|
|
Array of events (eg, times, sample or frame indices) to
|
||
|
|
match against.
|
||
|
|
left : bool
|
||
|
|
right : bool
|
||
|
|
If ``False``, then matched events cannot be to the left (or right)
|
||
|
|
of source events.
|
||
|
|
|
||
|
|
Returns
|
||
|
|
-------
|
||
|
|
event_mapping : np.ndarray [shape=(n,)]
|
||
|
|
For each event in ``events_from``, the corresponding event
|
||
|
|
index in ``events_to``::
|
||
|
|
|
||
|
|
event_mapping[i] == arg min |events_from[i] - events_to[:]|
|
||
|
|
|
||
|
|
See Also
|
||
|
|
--------
|
||
|
|
match_intervals
|
||
|
|
|
||
|
|
Raises
|
||
|
|
------
|
||
|
|
ParameterError
|
||
|
|
If either array of input events is not the correct shape
|
||
|
|
"""
|
||
|
|
if len(events_from) == 0 or len(events_to) == 0:
|
||
|
|
raise ParameterError("Attempting to match empty event list")
|
||
|
|
|
||
|
|
# If we can't match left or right, then only strict equivalence
|
||
|
|
# counts as a match.
|
||
|
|
if not (left or right) and not np.all(np.in1d(events_from, events_to)):
|
||
|
|
raise ParameterError(
|
||
|
|
"Cannot match events with left=right=False "
|
||
|
|
"and events_from is not contained "
|
||
|
|
"in events_to"
|
||
|
|
)
|
||
|
|
|
||
|
|
# If we can't match to the left, then there should be at least one
|
||
|
|
# target event greater-equal to every source event
|
||
|
|
if (not left) and max(events_to) < max(events_from):
|
||
|
|
raise ParameterError(
|
||
|
|
"Cannot match events with left=False "
|
||
|
|
"and max(events_to) < max(events_from)"
|
||
|
|
)
|
||
|
|
|
||
|
|
# If we can't match to the right, then there should be at least one
|
||
|
|
# target event less-equal to every source event
|
||
|
|
if (not right) and min(events_to) > min(events_from):
|
||
|
|
raise ParameterError(
|
||
|
|
"Cannot match events with right=False "
|
||
|
|
"and min(events_to) > min(events_from)"
|
||
|
|
)
|
||
|
|
|
||
|
|
# array of matched items
|
||
|
|
output = np.empty_like(events_from, dtype=np.int32)
|
||
|
|
|
||
|
|
# Suppress type check because of numba
|
||
|
|
return __match_events_helper(output, events_from, events_to, left, right) # type: ignore
|
||
|
|
|
||
|
|
|
||
|
|
@numba.jit(nopython=True, cache=True) # type: ignore
|
||
|
|
def __match_events_helper(
|
||
|
|
output: np.ndarray,
|
||
|
|
events_from: np.ndarray,
|
||
|
|
events_to: np.ndarray,
|
||
|
|
left: bool = True,
|
||
|
|
right: bool = True,
|
||
|
|
): # pragma: no cover
|
||
|
|
# mock dictionary for events
|
||
|
|
from_idx = np.argsort(events_from)
|
||
|
|
sorted_from = events_from[from_idx]
|
||
|
|
|
||
|
|
to_idx = np.argsort(events_to)
|
||
|
|
sorted_to = events_to[to_idx]
|
||
|
|
|
||
|
|
# find the matching indices
|
||
|
|
matching_indices = np.searchsorted(sorted_to, sorted_from)
|
||
|
|
|
||
|
|
# iterate over indices in matching_indices
|
||
|
|
for ind, middle_ind in enumerate(matching_indices):
|
||
|
|
left_flag = False
|
||
|
|
right_flag = False
|
||
|
|
|
||
|
|
left_ind = -1
|
||
|
|
right_ind = len(matching_indices)
|
||
|
|
|
||
|
|
left_diff = 0
|
||
|
|
right_diff = 0
|
||
|
|
mid_diff = 0
|
||
|
|
|
||
|
|
middle_ind = matching_indices[ind]
|
||
|
|
sorted_from_num = sorted_from[ind]
|
||
|
|
|
||
|
|
# Prevent oob from chosen index
|
||
|
|
if middle_ind == len(sorted_to):
|
||
|
|
middle_ind -= 1
|
||
|
|
|
||
|
|
# Permitted to look to the left
|
||
|
|
if left and middle_ind > 0:
|
||
|
|
left_ind = middle_ind - 1
|
||
|
|
left_flag = True
|
||
|
|
|
||
|
|
# Permitted to look to right
|
||
|
|
if right and middle_ind < len(sorted_to) - 1:
|
||
|
|
right_ind = middle_ind + 1
|
||
|
|
right_flag = True
|
||
|
|
|
||
|
|
mid_diff = abs(sorted_to[middle_ind] - sorted_from_num)
|
||
|
|
if left and left_flag:
|
||
|
|
left_diff = abs(sorted_to[left_ind] - sorted_from_num)
|
||
|
|
if right and right_flag:
|
||
|
|
right_diff = abs(sorted_to[right_ind] - sorted_from_num)
|
||
|
|
|
||
|
|
if left_flag and (
|
||
|
|
not right
|
||
|
|
and (sorted_to[middle_ind] > sorted_from_num)
|
||
|
|
or (not right_flag and left_diff < mid_diff)
|
||
|
|
or (left_diff < right_diff and left_diff < mid_diff)
|
||
|
|
):
|
||
|
|
output[ind] = to_idx[left_ind]
|
||
|
|
|
||
|
|
# Check if right should be chosen
|
||
|
|
elif right_flag and (right_diff < mid_diff):
|
||
|
|
output[ind] = to_idx[right_ind]
|
||
|
|
|
||
|
|
# Selected index wins
|
||
|
|
else:
|
||
|
|
output[ind] = to_idx[middle_ind]
|
||
|
|
|
||
|
|
# Undo sorting
|
||
|
|
solutions = np.empty_like(output)
|
||
|
|
solutions[from_idx] = output
|
||
|
|
|
||
|
|
return solutions
|