Multidimensional coordinate alignment

multidimensional-coordinate-alignment

Summary

Aligns detected features across multiple LC-IMS-MS/MS samples by clustering them in N-dimensional space (m/z, drift time, retention time) using configurable tolerances, producing consensus coordinates and sample-membership vectors. This skill is essential when matching corresponding chemical features across datasets to account for instrument drift, calibration variation, and nonlinear retention-time shifts.

When to use

Apply this skill when you have detected feature tables from two or more LC-IMS-MS/MS samples (each containing m/z, drift_time, retention_time, and intensity measurements) and need to identify which features correspond to the same chemical compound across samples. Specifically, when reference-based alignment (matching against a single reference sample) or cross-sample alignment (matching all features within user-defined windows) is required to combine multi-sample datasets for downstream analysis such as comparative metabolomics or biomarker discovery.

When NOT to use

• Input is already an aligned feature table from a single sample or prior alignment step; skip to downstream analysis (e.g., isotope detection, CCS calibration).
• Samples contain only a single feature or fewer than two samples to align; alignment requires cross-sample correspondence.
• Feature coordinates are already in a normalized, consensus space; re-alignment would introduce redundant normalization.
• Raw MS data (mzML/mzXML) has not yet been processed through feature detection; run feature detection first.

Inputs

• Detected feature table (HDF5 or mzML format) with columns: m/z, drift_time, retention_time, intensity
• Multiple sample datasets (≥2 samples for cross-sample alignment)
• User-defined tolerances for each dimension (m/z ppm, drift_time ms, retention_time min)
• Optional: reference sample designation or global coordinate frame definition

Outputs

• Aligned feature table (HDF5 format) with columns: original_mz, original_drift_time, original_retention_time, intensity, consensus_mz, consensus_drift_time, consensus_retention_time, cluster_id, sample_membership_vector
• Cluster-level metadata: cluster ID, consensus coordinates, per-sample contribution counts
• Optional: filtered feature table (clusters meeting minimum sample-membership threshold)

How to apply

Load detected feature tables from each sample using the deimos.load() API, extracting m/z, drift_time, retention_time, and intensity columns. Normalize feature coordinates across samples to a common reference frame (either a designated reference sample or a global coordinate system) to correct for instrument variation such as drift and calibration shifts. Apply N-dimensional distance-based clustering in (m/z, drift_time, retention_time) space using configurable tolerances (e.g., ppm for m/z, ms for drift_time, min for retention_time) to group features that occupy the same region across samples. For each cluster, compute consensus coordinates using weighted mean or median, and assign a cluster ID and sample-membership vector tracking which samples contributed each feature. Filter clusters below a minimum sample-membership threshold if desired (e.g., retain only clusters present in ≥2 samples). Output the aligned feature table with original coordinates, consensus coordinates, cluster ID, and sample-membership vector.

Related tools

• DEIMoS (N-dimensional feature detection and alignment API; executes distance-based clustering in multidimensional space and computes consensus coordinates) — https://github.com/pnnl/deimos
• Python (Programming language for DEIMoS API scripting and data manipulation)
• numpy (Numerical computation for coordinate transformation, distance metrics, and weighted mean/median calculations)
• ProteoWizard msconvert (Format conversion to mzML for input to DEIMoS; enables reading of raw MS data from vendor instruments)

Examples

import deimos
data_A = deimos.load('sample_A.h5', key='ms1', columns=['mz', 'drift_time', 'retention_time', 'intensity'])
data_B = deimos.load('sample_B.h5', key='ms1', columns=['mz', 'drift_time', 'retention_time', 'intensity'])
aligned = deimos.align([data_A, data_B], mz_tol=10, drift_time_tol=0.5, retention_time_tol=1.0)

Evaluation signals

• Output feature table contains all expected columns: original_mz, original_drift_time, original_retention_time, consensus_mz, consensus_drift_time, consensus_retention_time, cluster_id, sample_membership_vector.
• Row count in output ≥ row count in input (no features orphaned or lost).
• Each output row is assigned exactly one cluster_id; no features belong to multiple clusters or zero clusters.
• Consensus coordinates lie within the bounding box of the original coordinates for each cluster; no wildly displaced centroids.
• Sample-membership vectors correctly reflect which input samples contributed to each cluster (binary or count vector with expected cardinality).
• r-squared between reference and consensus coordinates is ≥ 0.99 (indicating high fidelity of alignment; article reports r² ≈ 0.9999).

Limitations

• Alignment accuracy depends critically on user-defined tolerance thresholds; overly loose tolerances lead to false positives (merging distinct features), while overly tight tolerances cause false negatives (missed alignments). No automatic tolerance selection is provided.
• N-dimensional clustering assumes that corresponding features occupy nearby regions in all dimensions simultaneously; complex nonlinear relationships (e.g., time-dependent drift or calibration shifts) may require pre-normalization or reference-sample-based alignment to account for systematic offsets.
• Consensus coordinate computation (weighted mean or median) may not reflect the true molecular m/z or CCS if samples have systematic biases; validation against external standards is recommended.
• DEIMoS is largely agnostic to instrumentation but assumes input features have been correctly detected; poor feature detection upstream will propagate errors into alignment.
• No changelog is available, limiting visibility into version-to-version changes or known issues.

Evidence

• [other] Reference-based alignment defines corresponding features between two samples by minimum distance in the dimension of interest using selected tolerances to accommodate potentially complex nonlinear relationships: "Reference-based alignment defines corresponding features between two samples by minimum distance in the dimension of interest using selected tolerances to accommodate potentially complex nonlinear"
• [other] Apply N-dimensional distance-based clustering in (mz, drift_time, retention_time) space to group features across samples that occupy the same region; use configurable tolerances for each dimension: "Apply N-dimensional distance-based clustering in (mz, drift_time, retention_time) space to group features across samples that occupy the same region; use configurable tolerances for each dimension"
• [other] For each cluster, compute consensus coordinates (weighted mean or median) and assign cluster membership flags to track which samples contributed each feature: "For each cluster, compute consensus coordinates (weighted mean or median) and assign cluster membership flags to track which samples contributed each feature"
• [other] 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: "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"
• [other] Load detected feature tables from multiple samples using the deimos.load() API, extracting mz, drift_time, retention_time, and intensity columns: "Load detected feature tables from multiple samples using the deimos.load() API, extracting mz, drift_time, retention_time, and intensity columns"
• [readme] DEIMoS operates on N-dimensional data, largely agnostic to acquisition instrumentation: "DEIMoS operates on N-dimensional data, largely agnostic to acquisition instrumentation"
• [readme] algorithm implementations simultaneously utilize all dimensions to (i) offer greater separation between features, thus improving detection sensitivity, (ii) increase alignment/feature matching confidence among datasets: "algorithm implementations simultaneously utilize all dimensions to (i) offer greater separation between features, thus improving detection sensitivity, (ii) increase alignment/feature matching"