roboto.analytics.signal_similarity.match#

Module Contents#

class roboto.analytics.signal_similarity.match.Match#

A subsequence of a target signal that is similar to a query signal.

context: MatchContext#

Correlate a matched subsequence back to its source.

distance: float#

Measure of similarity between a query signal and the subsequence of the target signal this Match represents. A smaller distance indicates a closer match.

In single-scale search (scale=None) this is the raw z-normalised Euclidean distance produced by MASS, with range [0, 2·√N] where N is the query length.

In multi-scale search (scale provided) this is multiplied by √N / √M (where N is the original needle length and M is the resampled length at that scale step), projecting onto the same [0, 2·√N] range as single-scale search. This means a max_distance threshold calibrated on single-scale search transfers directly to multi-scale search without adjustment.

end_idx: int#

The end index in the target signal of this match.

end_time: pandas.Timestamp#

The end time in the target signal of this match.

scale: float = 1.0#

The time-scale factor at which this match was found.

A value of 1.0 means the matched subsequence has the same length as the query. Values greater than 1.0 mean the matched subsequence is proportionally longer (the action occurred more slowly in the target than in the query). Values less than 1.0 mean the matched subsequence is proportionally shorter (the action occurred more quickly).

This field is only meaningful when scale is passed to find_similar_signals().

start_idx: int#

The start index in the target signal of this match.

start_time: pandas.Timestamp#

The start time in the target signal of this match.

subsequence: pandas.DataFrame#

The subsequence of the target signal this Match represents. It is equivalent to target[start_idx:end_idx].

to_event(name='Signal Similarity Match Result', caller_org_id=None, roboto_client=None)#

Create a Roboto Platform event out of this similarity match result.

Parameters:
Return type:

roboto.domain.events.Event

class roboto.analytics.signal_similarity.match.MatchContext#

Correlate a matched subsequence back to its source.

dataset_id: str | None = None#
file_id: str | None = None#
message_paths: collections.abc.Sequence[str]#
topic_id: str#
topic_name: str#
class roboto.analytics.signal_similarity.match.Scale#

Configuration for rate-invariant (multi-scale) signal similarity search.

Searching across multiple scales finds a query pattern regardless of how quickly or slowly it unfolds in the target. For example, a robot lifting a cup in 1 second and the same robot lifting a cup in 3 seconds would both be found.

min and max are positive scale factors relative to the original query length. A scale of 1.0 corresponds to the original query length; 2.0 searches for target subsequences twice as long (action happened at half speed); 0.5 searches for subsequences half as long (action happened at double speed).

While Scale.any() provides a convenient wide-range preset, providing domain-informed bounds (e.g. Scale(min=0.5, max=3.0) for a motion that can happen between half and triple speed) will both improve match quality — by concentrating the search grid where matches are physically plausible — and reduce compute by avoiding unnecessary scale steps.

classmethod any()#

Well-known preset covering a wide range of speed ratios (0.1x to 10x).

Return type:

Scale

factors()#

Return a list of scale factors spanning the configured range.

Return type:

list[float]

max: float#

Maximum scale factor (must be >= min).

min: float#

Minimum scale factor (must be positive).

spacing: Literal['log', 'linear'] = 'log'#

How to distribute scale values across the range.

  • "log" (default) — geometrically spaced; equal ratio between adjacent steps, which is more natural for speed ratios (e.g. 0.5x, 1x, 2x are equally spaced on a log scale).

  • "linear" — linearly spaced.

steps: int = 10#

Number of scale values to sample across the range.

On this page