Spring API

The Spring class

class twdspring.spring.Spring(query_vector: ndarray, epsilon: float, alpha: float | None = None, ddof: int = 0, distance_type: str = 'quadratic', use_z_norm: bool = False, query_vector_z_norm: ndarray | None = None)

Bases: object

A class used to represent a Spring object for time series analysis based on Time Warping Distance.

D: ndarray | None

The distance matrix used for calculations. Defaults to None.

M2: float = 0.0

The second moment of the input values. Defaults to 0.0.

S: ndarray | None

The state matrix used for calculations. Defaults to None.

alpha: float | None = None

The smoothing factor for moving average calculations. If value is None aplpha will be equal 2 / (k + 1) where k is the number of past time steps in consideration of moving average. Defaults to None.

current_x: float = nan

The current normalized/non-normalized input value. Defaults to NaN.

d_min: float = inf

The minimum time warping distance. Defaults to infinity.

d_min_status: float = inf

The minimum time warping distance status. Defaults to infinity.

ddof: int = 0

The delta degrees of freedom for variance calculations. Defaults to 0.

distance(x: float) → float

Calculates the distance between the input value x and the query vector.

The distance calculation method depends on the distance_type attribute of the Spring object. It can be either ‘quadratic’ or ‘absolute’.

Parameters:

x (float) – The input value for which the distance is calculated.

Returns:

The calculated distance.

Return type:

float

Raises:

ValueError – If the distance_type is not ‘quadratic’ or ‘absolute’.

distance_type: str = 'quadratic'

The type of distance calculation (‘quadratic’ or ‘absolute’). Defaults to ‘quadratic’.

epsilon: float

The epsilon value used for thresholding.

classmethod from_dict(**kwargs) → Self

Creates a Spring object from a dictionary of parameters.

Parameters:

**kwargs – Keyword arguments representing the parameters for the Spring object.

Returns:

An instance of the Spring object.

Return type:

Spring

mean: float = 0.0

The moving average of the input values. Defaults to 0.0.

moving_average(x: float)

Updates the moving average of the input value x.

Parameters:

x (float) – The input value used to update the moving average.

moving_variance(x: float) → float

Updates the moving variance based on the input value x.

Parameters:

x (float) – The input value used to update the variance.

Returns:

The updated variance.

Return type:

float

query_vector: ndarray

The query vector used for distance calculations.

query_vector_z_norm: ndarray | None = None

The z-score normalized query vector. Will compute z-norm of query vector if None. Defaults to None.

reset() → Self

Resets the internal state of the Spring object.

status: str | None = None

The current status of the Spring object. Defaults to None.

step(x: float) → Searcher

t: int = 0

The internal time step counter. Defaults to 0.

t_end: int = 0

The end time index (0-based). Defaults to 0.

t_end_status: int = 0

The end time index status (0-based). Defaults to 0.

t_start: int = 0

The start time index (0-based). Defaults to 0.

t_start_status: int = 0

The start time index status (0-based). Defaults to 0.

update_state() → Self

Updates the state of the Spring object based on the input value x.

Parameters:

x (float) – The input value used to update the state.

Returns:

The updated Spring object.

Return type:

Spring

update_tick() → Self

Increments the internal time step counter.

use_z_norm: bool = False

Flag to indicate if z-score normalization should be used. Defaults to False.

variance: float = 0.0

The moving variance of the input values. Defaults to 0.0.

z_norm(x: float) → Self

Normalizes the input value x using z-score normalization if enabled.

Parameters:

x (float) – The input value to be normalized.

Returns:

The normalized value or NaN if variance is zero.

Return type:

float

The Searcher class

class twdspring.spring.Searcher(status: str, twd_min: float, t_start: int, t_end: int, t: int)

Bases: NamedTuple

A class used to represent searching result

status: str

Search status (‘tracking’ or ‘match’).

t: int

The time index of status (0-based).

t_end: int

The end time index (0-based).

t_start: int

The start time index (0-based).

twd_min: float

The minimum time warping distance.