Spring API

The Spring class

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

Bases: object

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

alpha: float = 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.

property current_x: float

The current normalized/non-normalized input value.

Returns:

The current normalized/non-normalized input value.

Return type:

float

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.

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

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.

step(x: float) → Searcher

property t: int

The internal time step counter.

Returns:

The current time step.

Return type:

int

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.

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.