Metrics#

Philosophy: Hierarchical Composition

The metrics module implements a three-tier hierarchy of distance functions:

  1. EntityMetric: Single point-in-time comparisons (categorical feature equality)

  2. SequenceMetric: Built on EntityMetric, aligned/aggregated across timesteps

  3. TrajectoryMetric: Aggregates SequenceMetrics across multiple sequence types

This composition allows flexible metric selection at each level while maintaining consistent interfaces.

Entity Metrics#

Entity metrics compare individual states or events on categorical features.

Metric

Purpose

HammingEntityMetric

Categorical mismatch counter; building block for all sequence metrics

Sequence Metrics#

Sequence metrics operate on entire sequences, leveraging an EntityMetric as a foundation.

Metric

Purpose

LinearPairwiseSequenceMetric

Position-wise alignment with configurable aggregation (mean, max, sum)

EditSequenceMetric

Needleman-Wunsch edit distance; insertions, deletions, substitutions

LCPSequenceMetric

Longest Common Prefix distance between sequences

LCSSequenceMetric

Longest Common Subsequence distance

DTWSequenceMetric

Dynamic Time Warping; flexible time alignment

SoftDTWSequenceMetric

Differentiable DTW variant for optimization

Chi2SequenceMetric

Chi-squared distance between state-time distributions

Trajectory Metrics#

Trajectory metrics compare trajectories (multi-sequence entities) by aggregating sequence-level distances.

Metric

Purpose

AggregationTrajectoryMetric

Compute per-alias SequenceMetric, then aggregate via mean/min/max/sum

Key feature: Use different SequenceMetrics for different sequence types (aliases). For example, use EditSequenceMetric for states and LCSSequenceMetric for events, then aggregate the results.

Distance Matrix#

DistanceMatrix is a matrix wrapper that stores pairwise distances and pool IDs, enabling efficient cluster operations.

SequenceMetric classes provide a compute_matrix() method to compute the full pairwise distance matrix:

metric = EditSequenceMetric(entity_metric=hamming, normalize=True)
distance_matrix = metric.compute_matrix(pool)

Similarly, TrajectoryMetric classes have a compute_matrix() method that computes the full distance matrix across multiple trajectories.

See Also#