Sample membership tracking

sample-membership-tracking

Summary

Track which samples contributed each aligned feature across multiple LC-IMS-MS/MS datasets by assigning cluster membership flags during N-dimensional feature alignment. This enables downstream filtering, validation, and cross-sample feature interpretation.

When to use

When aligning detected features across multiple LC-IMS-MS/MS samples and you need to identify which input samples contributed to each consensus feature cluster, especially to filter out spurious or low-confidence alignments, validate clustering completeness, or perform sample-specific downstream analyses (e.g., isotope detection, CCS calibration) on subsets of aligned features.

When NOT to use

• Input is already a curated, non-redundant feature list with known sample origins — membership tracking adds redundancy and computational overhead.
• Single-sample analysis: membership tracking is only meaningful when aligning across two or more samples.
• Real-time streaming acquisition with no fixed sample boundaries: membership tracking assumes discrete, pre-defined sample cohorts.

Inputs

• Multiple detected feature tables (HDF5 or mzML format) with columns: mz, drift_time, retention_time, intensity, and sample identifier
• N-dimensional distance-based clusters from feature alignment (cluster_id assignments in mz, drift_time, retention_time space)
• User-defined tolerances for each dimension and optional minimum sample-membership threshold

Outputs

• Aligned feature table with columns: original_mz, original_drift_time, original_retention_time, consensus_mz, consensus_drift_time, consensus_retention_time, intensity, cluster_id, sample_membership_vector
• Sample-membership summary (cluster_id → set of contributing sample IDs or binary membership array)

How to apply

During the cross-sample feature alignment workflow, after N-dimensional distance-based clustering groups features across samples in (mz, drift_time, retention_time) space, assign a sample-membership vector to each cluster that records which input samples contributed at least one feature to that cluster. Represent this vector as a binary indicator array (or equivalent sparse representation) with length equal to the number of input samples. Optionally apply a minimum sample-membership threshold (e.g., 'only report clusters present in ≥2 samples') to filter out singleton or instrument-artifact features before output. Validate that each feature row is assigned exactly one cluster ID and that the membership vector is consistent with the cluster's constituent features.

Related tools

• DEIMoS (N-dimensional feature alignment and clustering engine; handles feature detection, alignment, and cluster assignment before membership tracking) — https://github.com/pnnl/deimos
• Python (Programming language for implementing sample-membership vector assignment, threshold filtering, and validation logic)
• numpy (Efficient array operations for constructing and manipulating binary or sparse sample-membership vectors)
• ProteoWizard (Converts LC-IMS-MS/MS data from proprietary formats (e.g. .raw, .d) to mzML before DEIMoS ingestion)

Examples

import deimos; import numpy as np
data_A = deimos.load('example_alignment.h5', key='A')
data_B = deimos.load('example_alignment.h5', key='B')
aligned = deimos.align(data_A, data_B, tol_mz=10, tol_dt=5, tol_rt=10)
print(aligned[['cluster_id', 'sample_membership']].head())

Evaluation signals

• Output feature table contains exactly one cluster_id per row and all rows have a sample_membership_vector assigned (no orphaned features).
• Total number of output rows ≥ input feature count (no features lost during clustering and membership assignment).
• Each cluster's membership vector is consistent: the set of samples listed in the vector matches the set of sample origins for all features in that cluster.
• If minimum sample-membership threshold is applied, all output clusters have ≥ threshold members; if threshold = 2, no singleton clusters remain in final output.
• Row count and membership statistics match expected values from controlled test data (e.g., example_alignment.h5) with known ground truth.

Limitations

• Sample-membership tracking accuracy depends on prior feature detection and alignment quality; clustering errors will propagate to membership assignments.
• Membership vectors assume discrete, non-overlapping sample cohorts; they do not capture within-sample technical replication or pooled/mixed samples.
• High-dimensional (>4D) alignment may suffer from the curse of dimensionality, leading to loose or spurious clusters with mixed sample membership despite low tolerance thresholds.
• Minimum sample-membership thresholds can discard genuine low-abundance features present in few samples, creating a bias toward high-abundance analytes.

Evidence

• [methods] Clusters are formed and membership tracked during cross-sample alignment.: "For each cluster, compute consensus coordinates (weighted mean or median) and assign cluster membership flags to track which samples contributed each feature."
• [methods] Sample-membership output is a key deliverable of the alignment workflow.: "Output the aligned feature table with original coordinates, consensus coordinates, cluster ID, and sample-membership vector; optionally filter clusters below a minimum sample-membership threshold."
• [methods] Validation includes checking that membership tracking is complete and consistent.: "Validation: confirm that output contains expected columns (mz, drift_time, retention_time, cluster_id, sample_membership), row count equals or exceeds input feature count, and no features are"
• [readme] DEIMoS is instrument-agnostic and operates on multi-dimensional data using cluster-based alignment.: "DEIMoS operates on N-dimensional data, largely agnostic to acquisition instrumentation; algorithm implementations simultaneously utilize all dimensions to (ii) increase alignment/feature matching"