Calculates API

calculates.simplify(trajectory, tolerance)

Simplify a trajectory using the Ramer-Douglas-Peucker algorithm.

Parameters

trajectorylist[tuple[float, float]]

The trajectory points to simplify.

tolerancefloat

The tolerance value that determines the degree of simplification.

Returns

list[tuple[float, float]]

A simplified version of the input trajectory.

calculates.distance(a, b, algorithm=Algorithms.SPAD, *args)

Compute the distance between two trajectories using a specified algorithm.

This function supports multiple distance metrics for comparing trajectories. The algorithm used can be specified via the algorithm parameter. Additional arguments required by specific algorithms can be passed via *args.

Parameters

alist[tuple[float, float]]

The first trajectory, represented as a list of (x, y) coordinate tuples.

blist[tuple[float, float]]

The second trajectory, represented as a list of (x, y) coordinate tuples.

algorithmAlgorithms, optional

The algorithm to use for computing the distance. Defaults to Algorithms.SPAD. Supported algorithms: - Algorithms.EUCLIDEAN: Euclidean distance. - Algorithms.DTW: Dynamic Time Warping. - Algorithms.LCSS: Longest Common Subsequence. - Algorithms.FRECHET: Frechet distance. - Algorithms.HAUSDORFF: Hausdorff distance. - Algorithms.ERS: Edit Distance on Real Sequences (ERS). - Algorithms.ERP: Edit Distance with Real Penalty (ERP). - Algorithms.SPAD: Spatial Aspects Distance (SPAD).

*argsoptional

Additional arguments specific to the selected algorithm.

Returns

float

The computed distance between the two trajectories.

Raises

ValueError

If the specified algorithm is not supported.

Examples

Compute the Euclidean distance between two trajectories:

>>> a = [(0, 0), (1, 1), (2, 2)]
>>> b = [(0, 0), (2, 2), (3, 3)]
>>> distance(a, b, algorithm=Algorithms.EUCLIDEAN)
2.0

calculates.euclidean_distance(a, b)

Compute the Euclidean distance between two trajectories.

The Euclidean distance is a simple metric that calculates the straight-line distance between corresponding points in two trajectories. It assumes that the trajectories are of the same length and aligned point-to-point.

Parameters

a, blist[tuple[float, float]]

Trajectories represented as lists of (x, y) coordinate tuples.

Returns

float

The Euclidean distance between the two trajectories.

Notes

• This metric is best suited for cases where trajectories are already aligned and have the same length.

• Euclidean distance is computationally efficient but does not handle differences in trajectory lengths or misalignment well.

Examples

>>> a = [(0, 0), (1, 1), (2, 2)]
>>> b = [(1, 1), (2, 2), (3, 3)]
>>> stmeasures.euclidean_distance(a, b)
2.449489742783178

calculates.hausdorff_distance(a, b)

Compute the Hausdorff distance between two trajectories.

The Hausdorff distance measures the greatest distance from a point in one trajectory to the closest point in the other trajectory. It quantifies the “maximum mismatch” between two trajectories.

Parameters

a, blist[tuple[float, float]]

Trajectories represented as lists of (x, y) coordinate tuples.

Returns

float

The Hausdorff distance between the two trajectories.

Notes

• Suitable for applications where the maximum deviation between trajectories is critical, such as detecting outliers or evaluating the worst-case alignment.

• It is sensitive to noise and outliers, as it focuses on the largest discrepancy.

Examples

>>> a = [(0, 0), (1, 1), (2, 2)]
>>> b = [(1, 1), (2, 2), (3, 3)]
>>> stmeasures.hausdorff_distance(a, b)
1.4142135623730951

calculates.frechet_distance(a, b)

Compute the Frechet distance between two trajectories.

The Frechet distance considers the location and ordering of points, making it suitable for comparing the shapes of trajectories. It is often visualized as the shortest leash needed for a person and a dog to walk along two curves without retracing steps.

Parameters

a, blist[tuple[float, float]]

Trajectories represented as lists of (x, y) coordinate tuples.

Returns

float

The Frechet distance between the two trajectories.

Notes

• Ideal for shape-based trajectory comparisons, such as analyzing similar movement patterns.

• Handles trajectory misalignment but assumes continuous traversal.

Examples

>>> a = [(0, 0), (1, 1), (2, 2)]
>>> b = [(0, 0), (1, 2), (2, 2)]
>>> stmeasures.frechet_distance(a, b)
1.0

calculates.spatial_assembling_distance(a, b, epsilon=1.0)

Compute the Spatial Assembling Distance (SPAD) between two trajectories.

The SPAD distance evaluates the spatial similarity of trajectories based on assembling smaller spatial segments. It is particularly useful for analyzing highly fragmented or irregular trajectories.

Parameters

a, blist[tuple[float, float]]

Trajectories represented as lists of (x, y) coordinate tuples.

epsilonfloat, optional

The threshold for assembling segments. Defaults to 1.0.

Returns

float

The SPAD distance between the two trajectories.

Notes

• Useful for comparing irregular or complex trajectory shapes.

• Balances global and local trajectory characteristics through its segment-based approach.

Examples

>>> a = [(0, 0), (1, 1), (2, 4)]
>>> b = [(0, 0), (1, 2), (0, 1)]
>>> stmeasures.spatial_assembling_distance(a, b)
0.5

calculates.lcss_distance(a, b, sigma=1.0)

Compute the Longest Common Subsequence (LCSS) distance between two trajectories.

The LCSS distance measures the similarity between trajectories by finding the longest subsequence of matching points within a given tolerance sigma. It handles noise and trajectory misalignment well.

Parameters

a, blist[tuple[float, float]]

Trajectories represented as lists of (x, y) coordinate tuples.

sigmafloat, optional

The tolerance for matching points. Defaults to 1.0.

Returns

float

The LCSS distance between the two trajectories.

Notes

• Effective for scenarios with noisy or incomplete data, such as GPS tracking.

• Robust to outliers, as it focuses on subsequences rather than point-by-point comparison.

Examples

>>> a = [(0, 0), (1, 1), (2, 2)]
>>> b = [(0, 0), (1, 2), (2, 2)]
>>> stmeasures.lcss_distance(a, b, sigma=1.0)
1.0

class _algorithms.Algorithms(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Enum for distance algorithms, categorizing types based on application context (spatial, temporal, geometrical, sequential).

Attributes

EUCLIDEANstr

Standard Euclidean distance, often used for spatial measurements.

DTWstr

Dynamic Time Warping, useful for time series alignment and measuring similarity in temporal sequences.

LCSSstr

Longest Common Subsequence on real sequences, applicable for matching patterns in sequential data.

FRECHETstr

Frechet distance, commonly used in geometrical contexts for comparing curves.

HAUSDORFFstr

Hausdorff distance, used for comparing geometrical shapes or spatial sets.

ERSstr

Edit Distance on Real Sequences, useful for sequential data comparison with real values.

ERPstr

Edit Distance with Real Penalty, used for sequence comparison with a penalty for gaps in sequences.

Class Attributes

SEQUENTIALlist[Algorithms]

Group of algorithms suitable for sequential data (ERP, ERS, LCSS).

TEMPORALlist[Algorithms]

Group of algorithms suitable for temporal data, which includes DTW and sequential algorithms.

GEOMETRICALlist[Algorithms]

Group of algorithms suitable for geometrical measurements (Hausdorff, Frechet).

SPATIALlist[Algorithms]

Group of algorithms suitable for spatial measurements, including Euclidean and geometrical algorithms.

Methods

__str__() -> str

Returns a formatted string representation of the algorithm with class, enum name, and value.