Feature Cross Trajectory Reduction Helper

GitHub Link to Code.

Cross-trajectory feature reduction helper.

This module provides utilities for reducing features consistently across multiple trajectories to ensure common denominator features for matrix construction and comparison.

class mdxplain.feature.helper.feature_cross_trajectory_reduction_helper.FeatureCrossTrajectoryReductionHelper

Helper class for cross-trajectory feature reduction operations.

Provides static methods for finding common features across trajectories, performing consistent reduction, and maintaining feature alignment for matrix construction.

static find_common_features(feature_data_dict: Dict[int, FeatureData], metric: str, threshold_min: float | None = None, threshold_max: float | None = None, **kwargs) → Set[int]

Find feature indices that pass reduction criteria in ALL trajectories.

Uses existing calculator logic to find features that meet the criteria in every trajectory, then returns the intersection of valid indices.

Parameters

feature_data_dictDict[int, FeatureData]: Dictionary mapping trajectory indices to their FeatureData
metricstr: Reduction metric to apply (e.g., ‘frequency’, ‘cv’, ‘stability’)
threshold_minfloat, optional: Minimum threshold for feature retention
threshold_maxfloat, optional: Maximum threshold for feature retention
kwargsdict: Additional parameters for reduction metric calculation

Returns

Set[int]: Set of feature indices that pass criteria in all trajectories

Examples

>>> common_indices = FeatureCrossTrajectoryReductionHelper.find_common_features(
...     feature_data_dict, "frequency", threshold_min=0.5
... )

static apply_common_reduction(feature_data_dict: Dict[int, FeatureData], common_indices: Set[int], metric: str, threshold_min: float | None = None, threshold_max: float | None = None) → None

Apply reduction using common feature indices across all trajectories.

Creates results dictionary and uses FeatureReductionHelper to handle the reduction processing, including memmap compatibility.

Parameters

feature_data_dictDict[int, FeatureData]: Dictionary mapping trajectory indices to their FeatureData
common_indicesSet[int]: Set of common feature indices to retain
metricstr: Reduction metric name for metadata
threshold_minfloat, optional: Minimum threshold used (for metadata)
threshold_maxfloat, optional: Maximum threshold used (for metadata)

Returns

None: Updates reduced_data and metadata for all FeatureData objects

Examples

>>> FeatureCrossTrajectoryReductionHelper.apply_common_reduction(
...     feature_data_dict, common_indices, "frequency", 0.5, None
... )

static get_reduction_summary(feature_data_dict: Dict[int, FeatureData], common_indices: Set[int]) → Dict[str, Any]

Generate summary of cross-trajectory reduction.

Parameters

feature_data_dictDict[int, FeatureData]: Dictionary mapping trajectory indices to their FeatureData
common_featuresSet[str]: Set of common features retained

Returns

Dict[str, Any]: Summary dictionary with reduction statistics

Examples

>>> summary = FeatureCrossTrajectoryReductionHelper.get_reduction_summary(
...     feature_data_dict, common_features
... )

static print_cross_trajectory_summary(feature_data_dict: Dict[int, FeatureData], common_indices: Set[int]) → None

Print summary of cross-trajectory reduction results.

Parameters

feature_data_dictDict[int, FeatureData]: Dictionary mapping trajectory indices to their FeatureData
common_featuresSet[str]: Set of common features retained

Returns

None: Prints reduction summary to console

Examples

>>> FeatureCrossTrajectoryReductionHelper.print_cross_trajectory_summary(
...     feature_data_dict, common_features
... )
Cross-trajectory reduction: 3 trajectories, 2500 → 450 features (18.0% retained).