# Sample Membership Tracking

> Use when 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.

- Skill: `holobiomicslab/sample-membership-tracking` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/sample-membership-tracking`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/sample-membership-tracking/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/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"