Distance Metrics¶

Pure-numpy distance metrics for multivariate time series.

class confetti.distances.TimeSeriesKNN(n_neighbors: int = 1, metric: str = 'euclidean', metric_params: dict[str, Any] | None = None)¶

Bases: object

K-nearest-neighbors search for multivariate time series.

For Euclidean distance the search is done via sklearn on flattened vectors. For all other metrics a precomputed distance matrix is built with the corresponding cdist_* function.

Parameters:

n_neighbors (int, default=1) – Number of neighbours to return.
metric (str, default="euclidean") – Distance metric name ("euclidean", "dtw", etc.).
metric_params (dict or None, default=None) – Extra keyword arguments forwarded to the underlying cdist_* function (e.g. {"global_constraint": "sakoe_chiba", "sakoe_chiba_radius": 2}).

fit(X: ndarray) → TimeSeriesKNN¶

Store the training dataset.

Parameters:: X (np.ndarray) – Training time series of shape (N, T, C).
Returns:: self
Return type:: TimeSeriesKNN

kneighbors(X: ndarray, return_distance: bool = True) → ndarray | tuple[ndarray, ndarray]¶

Find the k nearest neighbors for each query.

Parameters:

X (np.ndarray) – Query time series of shape (Q, T, C).
return_distance (bool, default=True) – If True, return (distances, indices); otherwise return only indices.

Returns:

distances (np.ndarray) – Shape (Q, n_neighbors). Only returned when return_distance is True.
indices (np.ndarray) – Shape (Q, n_neighbors).

confetti.distances.cdist_ctw(X: ndarray, Y: ndarray, *, max_iter: int = 100, n_components: int | None = None, global_constraint: str | None = None, sakoe_chiba_radius: int | None = None) → ndarray¶

Pairwise CTW distance between two sets of time series.

Parameters:

X (np.ndarray) – First dataset of shape (N, T1, C1).
Y (np.ndarray) – Second dataset of shape (M, T2, C2).
max_iter (int, default=100) – Maximum number of CTW iterations per pair.
n_components (int or None, default=None) – Number of CCA components.
global_constraint (str or None, default=None) – If "sakoe_chiba", applies the Sakoe-Chiba band constraint.
sakoe_chiba_radius (int or None, default=None) – Radius for the Sakoe-Chiba band.

Returns:

Distance matrix of shape (N, M).

Return type:

np.ndarray

confetti.distances.cdist_dtw(X: ndarray, Y: ndarray, *, global_constraint: str | None = None, sakoe_chiba_radius: int | None = None) → ndarray¶

Pairwise DTW distance between two sets of time series.

Parameters:

X (np.ndarray) – First dataset of shape (N, T1, C).
Y (np.ndarray) – Second dataset of shape (M, T2, C).
global_constraint (str or None, default=None) – If "sakoe_chiba", applies the Sakoe-Chiba band constraint.
sakoe_chiba_radius (int or None, default=None) – Radius for the Sakoe-Chiba band.

Returns:

Distance matrix of shape (N, M).

Return type:

np.ndarray

confetti.distances.cdist_gak(X: ndarray, Y: ndarray, *, sigma: float = 1.0) → ndarray¶

Pairwise normalized GAK between two sets of time series.

Parameters:

X (np.ndarray) – First dataset of shape (N, T1, C).
Y (np.ndarray) – Second dataset of shape (M, T2, C).
sigma (float, default=1.0) – Bandwidth of the internal Gaussian kernel.

Returns:

Kernel matrix of shape (N, M) with values in [0, 1].

Return type:

np.ndarray

confetti.distances.cdist_manhattan(X: ndarray, Y: ndarray) → ndarray¶

Pairwise Manhattan distance between two sets of time series.

Parameters:

X (np.ndarray) – First dataset of shape (N, T, C).
Y (np.ndarray) – Second dataset of shape (M, T, C).

Returns:

Distance matrix of shape (N, M).

Return type:

np.ndarray

confetti.distances.cdist_soft_dtw(X: ndarray, Y: ndarray, *, gamma: float = 1.0) → ndarray¶

Pairwise Soft-DTW between two sets of time series.

Parameters:

X (np.ndarray) – First dataset of shape (N, T, C).
Y (np.ndarray) – Second dataset of shape (M, T, C).
gamma (float, default=1.0) – Smoothing parameter.

Returns:

Similarity matrix of shape (N, M).

Return type:

np.ndarray

confetti.distances.ctw(x: ndarray, y: ndarray, *, max_iter: int = 100, n_components: int | None = None, sakoe_chiba_radius: int | None = None) → float¶

Canonical Time Warping distance between two time series.

Aligns the feature spaces of two time series via Canonical Correlation Analysis and then computes DTW in the shared canonical space.

Parameters:

x (np.ndarray) – First time series of shape (T1, C1).
y (np.ndarray) – Second time series of shape (T2, C2).
max_iter (int, default=100) – Maximum number of CTW iterations.
n_components (int or None, default=None) – Number of CCA components. Defaults to min(C1, C2).
sakoe_chiba_radius (int or None, default=None) – Sakoe-Chiba band radius for the internal DTW calls.

Returns:

CTW distance.

Return type:

float

confetti.distances.dtw(x: ndarray, y: ndarray, *, sakoe_chiba_radius: int | None = None) → float¶

Dynamic Time Warping distance between two time series.

Parameters:

x (np.ndarray) – First time series of shape (T1, C).
y (np.ndarray) – Second time series of shape (T2, C).
sakoe_chiba_radius (int or None, default=None) – Sakoe-Chiba band radius. If None, no constraint is applied.

Returns:

DTW distance (square root of the accumulated squared Euclidean cost).

Return type:

float

confetti.distances.gak(x: ndarray, y: ndarray, *, sigma: float = 1.0) → float¶

Normalized Global Alignment Kernel between two time series.

Parameters:

x (np.ndarray) – First time series of shape (T1, C).
y (np.ndarray) – Second time series of shape (T2, C).
sigma (float, default=1.0) – Bandwidth of the internal Gaussian kernel.

Returns:

Normalized kernel value in [0, 1]. A value of 1 means the two series are identical.

Return type:

float

confetti.distances.get_cdist_function(metric_name: str) → Callable[[...], Any]¶

Look up a pairwise distance function by name.

Parameters:: metric_name (str) – One of "dtw", "ctw", "softdtw", "gak", or "manhattan" (case-insensitive).
Returns:: The corresponding cdist_* function.
Return type:: Callable
Raises:: CONFETTIConfigurationError – If the metric name is not recognized.

confetti.distances.manhattan(x: ndarray, y: ndarray) → float¶

Manhattan distance between two time series.

Parameters:

x (np.ndarray) – First time series of shape (T, C).
y (np.ndarray) – Second time series of shape (T, C).

Returns:

Sum of element-wise absolute differences.

Return type:

float

confetti.distances.soft_dtw(x: ndarray, y: ndarray, *, gamma: float = 1.0) → float¶

Soft-DTW similarity between two time series.

Parameters:

x (np.ndarray) – First time series of shape (T1, C).
y (np.ndarray) – Second time series of shape (T2, C).
gamma (float, default=1.0) – Smoothing parameter. Smaller values approximate hard DTW.

Returns:

Soft-DTW value. Unlike standard DTW this is a similarity score that can be negative.

Return type:

float

Dynamic Time Warping distance for multivariate time series.

confetti.distances._dtw.cdist_dtw(X: ndarray, Y: ndarray, *, global_constraint: str | None = None, sakoe_chiba_radius: int | None = None) → ndarray¶

Pairwise DTW distance between two sets of time series.

Parameters:

X (np.ndarray) – First dataset of shape (N, T1, C).
Y (np.ndarray) – Second dataset of shape (M, T2, C).
global_constraint (str or None, default=None) – If "sakoe_chiba", applies the Sakoe-Chiba band constraint.
sakoe_chiba_radius (int or None, default=None) – Radius for the Sakoe-Chiba band.

Returns:

Distance matrix of shape (N, M).

Return type:

np.ndarray

confetti.distances._dtw.dtw(x: ndarray, y: ndarray, *, sakoe_chiba_radius: int | None = None) → float¶

Dynamic Time Warping distance between two time series.

Parameters:

x (np.ndarray) – First time series of shape (T1, C).
y (np.ndarray) – Second time series of shape (T2, C).
sakoe_chiba_radius (int or None, default=None) – Sakoe-Chiba band radius. If None, no constraint is applied.

Returns:

DTW distance (square root of the accumulated squared Euclidean cost).

Return type:

float

Soft-DTW distance for multivariate time series.

confetti.distances._soft_dtw.cdist_soft_dtw(X: ndarray, Y: ndarray, *, gamma: float = 1.0) → ndarray¶

Pairwise Soft-DTW between two sets of time series.

Parameters:

X (np.ndarray) – First dataset of shape (N, T, C).
Y (np.ndarray) – Second dataset of shape (M, T, C).
gamma (float, default=1.0) – Smoothing parameter.

Returns:

Similarity matrix of shape (N, M).

Return type:

np.ndarray

confetti.distances._soft_dtw.soft_dtw(x: ndarray, y: ndarray, *, gamma: float = 1.0) → float¶

Soft-DTW similarity between two time series.

Parameters:

x (np.ndarray) – First time series of shape (T1, C).
y (np.ndarray) – Second time series of shape (T2, C).
gamma (float, default=1.0) – Smoothing parameter. Smaller values approximate hard DTW.

Returns:

Soft-DTW value. Unlike standard DTW this is a similarity score that can be negative.

Return type:

float

Global Alignment Kernel (GAK) for multivariate time series.

confetti.distances._gak.cdist_gak(X: ndarray, Y: ndarray, *, sigma: float = 1.0) → ndarray¶

Pairwise normalized GAK between two sets of time series.

Parameters:

X (np.ndarray) – First dataset of shape (N, T1, C).
Y (np.ndarray) – Second dataset of shape (M, T2, C).
sigma (float, default=1.0) – Bandwidth of the internal Gaussian kernel.

Returns:

Kernel matrix of shape (N, M) with values in [0, 1].

Return type:

np.ndarray

confetti.distances._gak.gak(x: ndarray, y: ndarray, *, sigma: float = 1.0) → float¶

Normalized Global Alignment Kernel between two time series.

Parameters:

x (np.ndarray) – First time series of shape (T1, C).
y (np.ndarray) – Second time series of shape (T2, C).
sigma (float, default=1.0) – Bandwidth of the internal Gaussian kernel.

Returns:

Normalized kernel value in [0, 1]. A value of 1 means the two series are identical.

Return type:

float

Canonical Time Warping distance for multivariate time series.

confetti.distances._ctw.cdist_ctw(X: ndarray, Y: ndarray, *, max_iter: int = 100, n_components: int | None = None, global_constraint: str | None = None, sakoe_chiba_radius: int | None = None) → ndarray¶

Pairwise CTW distance between two sets of time series.

Parameters:

X (np.ndarray) – First dataset of shape (N, T1, C1).
Y (np.ndarray) – Second dataset of shape (M, T2, C2).
max_iter (int, default=100) – Maximum number of CTW iterations per pair.
n_components (int or None, default=None) – Number of CCA components.
global_constraint (str or None, default=None) – If "sakoe_chiba", applies the Sakoe-Chiba band constraint.
sakoe_chiba_radius (int or None, default=None) – Radius for the Sakoe-Chiba band.

Returns:

Distance matrix of shape (N, M).

Return type:

np.ndarray

confetti.distances._ctw.ctw(x: ndarray, y: ndarray, *, max_iter: int = 100, n_components: int | None = None, sakoe_chiba_radius: int | None = None) → float¶

Canonical Time Warping distance between two time series.

Aligns the feature spaces of two time series via Canonical Correlation Analysis and then computes DTW in the shared canonical space.

Parameters:

x (np.ndarray) – First time series of shape (T1, C1).
y (np.ndarray) – Second time series of shape (T2, C2).
max_iter (int, default=100) – Maximum number of CTW iterations.
n_components (int or None, default=None) – Number of CCA components. Defaults to min(C1, C2).
sakoe_chiba_radius (int or None, default=None) – Sakoe-Chiba band radius for the internal DTW calls.

Returns:

CTW distance.

Return type:

float

Manhattan (L1) distance for multivariate time series.

confetti.distances._manhattan.cdist_manhattan(X: ndarray, Y: ndarray) → ndarray¶

Pairwise Manhattan distance between two sets of time series.

Parameters:

X (np.ndarray) – First dataset of shape (N, T, C).
Y (np.ndarray) – Second dataset of shape (M, T, C).

Returns:

Distance matrix of shape (N, M).

Return type:

np.ndarray

confetti.distances._manhattan.manhattan(x: ndarray, y: ndarray) → float¶

Manhattan distance between two time series.

Parameters:

x (np.ndarray) – First time series of shape (T, C).
y (np.ndarray) – Second time series of shape (T, C).

Returns:

Sum of element-wise absolute differences.

Return type:

float

KNN for time series

class confetti.distances._neighbors.TimeSeriesKNN(n_neighbors: int = 1, metric: str = 'euclidean', metric_params: dict[str, Any] | None = None)¶

Bases: object

K-nearest-neighbors search for multivariate time series.

For Euclidean distance the search is done via sklearn on flattened vectors. For all other metrics a precomputed distance matrix is built with the corresponding cdist_* function.

Parameters:

n_neighbors (int, default=1) – Number of neighbours to return.
metric (str, default="euclidean") – Distance metric name ("euclidean", "dtw", etc.).
metric_params (dict or None, default=None) – Extra keyword arguments forwarded to the underlying cdist_* function (e.g. {"global_constraint": "sakoe_chiba", "sakoe_chiba_radius": 2}).

fit(X: ndarray) → TimeSeriesKNN¶

Store the training dataset.

Parameters:: X (np.ndarray) – Training time series of shape (N, T, C).
Returns:: self
Return type:: TimeSeriesKNN

kneighbors(X: ndarray, return_distance: bool = True) → ndarray | tuple[ndarray, ndarray]¶

Find the k nearest neighbors for each query.

Parameters:

X (np.ndarray) – Query time series of shape (Q, T, C).
return_distance (bool, default=True) – If True, return (distances, indices); otherwise return only indices.

Returns:

distances (np.ndarray) – Shape (Q, n_neighbors). Only returned when return_distance is True.
indices (np.ndarray) – Shape (Q, n_neighbors).

Metric name to cdist function dispatch.

confetti.distances._registry.get_cdist_function(metric_name: str) → Callable[[...], Any]¶

Look up a pairwise distance function by name.

Parameters:: metric_name (str) – One of "dtw", "ctw", "softdtw", "gak", or "manhattan" (case-insensitive).
Returns:: The corresponding cdist_* function.
Return type:: Callable
Raises:: CONFETTIConfigurationError – If the metric name is not recognized.