subgradient_barycenter_average

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

Compute the stochastic subgradient barycenter average of time series.

This implements a stochastic subgradient variant of DBA (cf. [2]_), which updates the barycenter using subgradients computed per time series. It is typically faster than the original Petitjean DBA but is not guaranteed to find the optimal solution.

Parameters:

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

n_timepoints) Collection of time series to average. If 2D, it is internally reshaped to (n_cases, 1, n_timepoints).

distancestr, default=”dtw”

Distance function used during 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.

initial_step_sizefloat, default=0.05

Initial step size for the subgradient descent updates (suggested in [2]_).

final_step_sizefloat, default=0.005

Final step size for the subgradient descent updates (suggested in [2]_).

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.

verbosebool, default=False

If True, prints progress information.

random_stateint or None, default=None

Random seed used where applicable (e.g., for shuffling/initialisation).

n_jobsint, default=1

The number of jobs to run in parallel. If -1, then the number of jobs is set to the number of CPU cores. If 1, then the function is executed in a single thread. If greater than 1, then the function is executed in parallel.

previous_costfloat, default=None

The total cost (sum of distances from all series in X to the current barycenter). If None, it is computed in the first iteration.

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

Distances from each series in X to the current barycenter. If None, they are computed in the first iteration.

return_distances_to_centerbool, default=False

If True, also return the distances between each time series and the barycenter.

return_costbool, default=False

If True, also return the total cost.

**kwargs

Additional keyword arguments forwarded to the chosen distance function.

Returns:

np.ndarray of shape (n_channels, n_timepoints)

The barycenter (stochastic subgradient DBA 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] D. Schultz & B. Jain. “Nonsmooth Analysis and Subgradient Methods

for Averaging in Dynamic Time Warping Spaces.” Pattern Recognition, 74, 340–358, 2018.