petitjean_barycenter_average

petitjean_barycenter_average(X: ndarray, distance: str = 'dtw', max_iters: int = 30, tol: float = 1e-05, init_barycenter: ndarray | str = 'mean', 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 barycenter average of time series using an elastic distance.

This implements an adapted version of the original Petitjean DBA algorithm [1]_.

Parameters:

Xnp.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 DBA 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.

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 “random” 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:

barycenternp.ndarray of shape (n_channels, n_timepoints)

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

distances_to_centernp.ndarray of shape (n_cases,), optional

Returned if return_distances_to_center=True. Distances between each time series and the barycenter.

costfloat, optional

Returned if return_cost=True. The total cost (sum of distances to barycenter).

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.