pattern_recognition

pattern_recognition ¤

PatternRecognition ¤

PatternRecognition(
    dataframe: DataFrame, time_column: str = "systime"
)

Bases: Base

Pattern Recognition for univariate timeseries.

Discover motifs, discords, and template matches using Matrix Profile and Dynamic Time Warping approaches.

Every method reads one signal: rows are put in time order (when the frame has time_column), and a frame with several uuids needs uuid= to pick one. Positions in the results (index_a, start_index, ...) count samples of that time-ordered signal. A window that contains a missing value is skipped.

Methods: - discover_motifs: Find top-k recurring subsequence patterns. - discover_discords: Find top-k anomalous subsequences. - similarity_search: Find subsequences most similar to a query (DTW). - template_match: Find all occurrences of a reference template. - compute_distance_profile: Distance from query to every subsequence.

discover_motifs `classmethod` ¤

discover_motifs(
    dataframe: DataFrame,
    value_column: str = "value_double",
    window_size: int = 50,
    top_k: int = 5,
    exclusion_zone: int | None = None,
    time_column: str = "systime",
    *,
    uuid: str | None = None
) -> pd.DataFrame

Find the top-k recurring subsequence patterns (motifs).

Parameters:

Name	Type	Description	Default
`dataframe`	`DataFrame`	Input DataFrame.	required
`value_column`	`str`	Column containing numeric values.	`'value_double'`
`window_size`	`int`	Length of subsequences to compare.	`50`
`top_k`	`int`	Number of motif pairs to return.	`5`
`exclusion_zone`	`int \| None`	Indices to exclude around matches. Defaults to window_size // 2. Also applied between motifs: no member of a returned pair starts within `exclusion_zone` of a member of a better-ranked pair, so later motifs are not the first one shifted by a sample or two.	`None`
`time_column`	`str`	Column containing timestamps.	`'systime'`
`uuid`	`str \| None`	Signal to analyze when the frame holds several uuids.	`None`

Returns:

Type	Description
`DataFrame`	DataFrame with motif_rank, index_a, index_b, distance, time_a, time_b (the time columns only when the frame has `time_column`; they keep its timezone). Empty, with these columns, when the signal is shorter than `window_size`.

Raises:

Type	Description
`ColumnNotFoundError`	If `value_column` is missing.
`ValueError`	If the frame holds several uuids and `uuid` is not given.

discover_discords `classmethod` ¤

discover_discords(
    dataframe: DataFrame,
    value_column: str = "value_double",
    window_size: int = 50,
    top_k: int = 5,
    exclusion_zone: int | None = None,
    time_column: str = "systime",
    *,
    uuid: str | None = None
) -> pd.DataFrame

Find the top-k anomalous subsequences (discords).

Parameters:

Name	Type	Description	Default
`dataframe`	`DataFrame`	Input DataFrame.	required
`value_column`	`str`	Column containing numeric values.	`'value_double'`
`window_size`	`int`	Length of subsequences to compare.	`50`
`top_k`	`int`	Number of discords to return.	`5`
`exclusion_zone`	`int \| None`	Indices to exclude around matches. Defaults to window_size // 2.	`None`
`time_column`	`str`	Column containing timestamps.	`'systime'`
`uuid`	`str \| None`	Signal to analyze when the frame holds several uuids.	`None`

Returns:

Type	Description
`DataFrame`	DataFrame with discord_rank, start_index, distance, start_time (the time column only when the frame has `time_column`). Windows with a missing value are never discords. Empty, with these columns, when the signal is shorter than `window_size`.

Raises:

Type	Description
`ColumnNotFoundError`	If `value_column` is missing.
`ValueError`	If the frame holds several uuids and `uuid` is not given.

similarity_search `classmethod` ¤

similarity_search(
    dataframe: DataFrame,
    query: ndarray,
    value_column: str = "value_double",
    top_k: int = 5,
    normalize: bool = True,
    time_column: str = "systime",
    *,
    uuid: str | None = None
) -> pd.DataFrame

Find the top-k most similar subsequences to a query using DTW.

Parameters:

Name	Type	Description	Default
`dataframe`	`DataFrame`	Input DataFrame.	required
`query`	`ndarray`	Query pattern as numpy array.	required
`value_column`	`str`	Column containing numeric values.	`'value_double'`
`top_k`	`int`	Number of matches to return.	`5`
`normalize`	`bool`	Whether to z-normalize before comparison.	`True`
`time_column`	`str`	Column containing timestamps.	`'systime'`
`uuid`	`str \| None`	Signal to analyze when the frame holds several uuids.	`None`

Returns:

Type	Description
`DataFrame`	DataFrame with rank, start_index, dtw_distance, start_time (the time column only when the frame has `time_column`). Empty, with these columns, when the signal is shorter than the query.

Raises:

Type	Description
`ColumnNotFoundError`	If `value_column` is missing.
`ValueError`	If the frame holds several uuids and `uuid` is not given, or `query` is empty or contains NaN.

template_match `classmethod` ¤

template_match(
    dataframe: DataFrame,
    template: ndarray,
    value_column: str = "value_double",
    threshold: float | None = None,
    normalize: bool = True,
    time_column: str = "systime",
    *,
    uuid: str | None = None
) -> pd.DataFrame

Find all occurrences of a template pattern in the time series.

Parameters:

Name	Type	Description	Default
`dataframe`	`DataFrame`	Input DataFrame.	required
`template`	`ndarray`	Reference pattern as numpy array.	required
`value_column`	`str`	Column containing numeric values.	`'value_double'`
`threshold`	`float \| None`	Maximum distance to consider a match. None = adaptive (mean minus two standard deviations of the distance profile).	`None`
`normalize`	`bool`	Whether to z-normalize before comparison. With `False` the distance is the plain Euclidean distance, so the level and scale of the template matter.	`True`
`time_column`	`str`	Column containing timestamps.	`'systime'`
`uuid`	`str \| None`	Signal to analyze when the frame holds several uuids.	`None`

Returns:

Type	Description
`DataFrame`	DataFrame with start_index, distance, start_time, end_time (the time columns only when the frame has `time_column`). Empty, with these columns, when nothing matches.

Raises:

Type	Description
`ColumnNotFoundError`	If `value_column` is missing.
`ValueError`	If the frame holds several uuids and `uuid` is not given, or `template` is empty or contains NaN.

compute_distance_profile `classmethod` ¤

compute_distance_profile(
    dataframe: DataFrame,
    query: ndarray,
    value_column: str = "value_double",
    metric: str = "euclidean",
    normalize: bool = True,
    *,
    time_column: str = "systime",
    uuid: str | None = None
) -> np.ndarray

Compute distance from query to every subsequence of same length.

Parameters:

Name	Type	Description	Default
`dataframe`	`DataFrame`	Input DataFrame.	required
`query`	`ndarray`	Query subsequence.	required
`value_column`	`str`	Column containing numeric values.	`'value_double'`
`metric`	`str`	'euclidean' (FFT-based) or 'dtw'.	`'euclidean'`
`normalize`	`bool`	Whether to z-normalize. With `False` the Euclidean distance is the plain distance of the raw values.	`True`
`time_column`	`str`	Rows are put in the order of this column (when the frame has it).	`'systime'`
`uuid`	`str \| None`	Signal to analyze when the frame holds several uuids.	`None`

Returns:

Type	Description
`ndarray`	1D numpy array of distances, one per window start; NaN for a window with a missing value. Empty when the signal is shorter than the query.

Raises:

Type	Description
`ColumnNotFoundError`	If `value_column` is missing.
`ValueError`	For an unknown `metric`, several uuids without `uuid`, or a query that is empty or contains NaN.

pattern_recognition