elastic_barycenter_average

elastic_barycenter_average(X: ndarray, distance: str = 'dtw', max_iters: int = 30, tol: float = 1e-05, init_barycenter: ndarray | str = 'mean', method: str = 'petitjean', weights: ndarray | None = None, initial_step_size: float = 0.05, final_step_size: float = 0.005, precomputed_medoids_pairwise_distance: ndarray | None = None, verbose: bool = False, random_state: int | None = None, decay_rate: float = 0.1, previous_cost: float | None = None, previous_distance_to_center: ndarray | None = None, ba_subset_size: float = 0.5, return_cost: bool = False, return_distances_to_center: bool = False, n_jobs: int = 1, **kwargs)

Compute the barycenter average of time series using an elastic distance.

This is a utility function that computes the barycenter average of a collection of time series instances using one of several available elastic barycenter averaging (EBA) algorithms, specified via the method parameter:

• “petitjean”: Adapted version of the original Petitjean DBA algorithm [1].

• “subgradient”: Stochastic subgradient DBA algorithm [2].

• “kasba”: KASBA algorithm [3], a fast stochastic variant that samples subsets of time series during each iteration.

Petitjean is slower but more reliable at converging to the optimal solution. Subgradient is faster but not guaranteed to converge optimally. KASBA is designed for large datasets, trading off some accuracy for a much faster runtime.

Parameters:

X: np.ndarray of shape (n_cases, n_channels, n_timepoints) or (n_cases,

n_timepoints) Collection of time series instances to average.

distancestr, default=”dtw”

Distance function to use for averaging. See aeon.distances.get_distance_function for valid options.

max_itersint, default=30

Maximum number of update iterations.

tolfloat, default=1e-5

Early-stopping tolerance: if the decrease in cost between iterations is smaller than this value, the procedure stops.

init_barycenter: {“mean”, “medoids”, “random”} or np.ndarray of shape (n_channels,

n_timepoints), default=”mean” Initial barycenter. If a string is provided, it specifies the initialisation strategy. If an array is provided, it is used directly as the starting barycenter. - “mean”: Uses the mean of the time series. - “medoids”: Uses the medoid of the time series. - “random”: Uses a randomly selected time series instance.

method{“petitjean”, “subgradient”, “kasba”}, default=”petitjean”

The algorithm to use for barycenter averaging.

initial_step_sizefloat, default=0.05

Initial step size for gradient-based methods (“subgradient” and “kasba”).

final_step_sizefloat, default=0.005

Final step size for the subgradient method (suggested in [2]).

decay_ratefloat, default=0.1

Exponential decay rate for the step size in the KASBA method.

ba_subset_sizefloat, default=0.5

Proportion of data sampled in each iteration of the KASBA method.

weightsnp.ndarray of shape (n_cases,), default=None

Weights for each time series. If None, all series receive weight 1.

precomputed_medoids_pairwise_distancenp.ndarray of shape (n_cases, n_cases),

default=None Optional precomputed pairwise distance matrix (used when relevant, e.g., for “medoids” initialisation). If None, distances are computed on the fly.

previous_costfloat, default=None

Used by the KASBA method. Previous total cost, if already known.

previous_distance_to_centernp.ndarray of shape (n_cases,), default=None

Used by the KASBA method. Previous distances to center, if already known.

verbosebool, default=False

If True, prints progress information.

random_stateint or None, default=None

Random seed for reproducibility.

**kwargs

Additional keyword arguments passed to the chosen distance function.

Returns:

np.ndarray of shape (n_channels, n_timepoints)

The barycenter (elastic average) of the input time series.

References

[1]

F. Petitjean, A. Ketterlin & P. Gancarski. “A global averaging method for dynamic time warping, with applications to clustering.” Pattern Recognition, 44(3), 678–693, 2011.

[2] (1,2)

D. Schultz & B. Jain. “Nonsmooth Analysis and Subgradient Methods for Averaging in Dynamic Time Warping Spaces.” Pattern Recognition, 74, 340–358, 2018.

[3]

C. Holder & A. Bagnall. “Rock the KASBA: Blazingly Fast and Accurate Time Series Clustering.” arXiv:2411.17838, 2024.