Cross sample alignment matrix construction

cross-sample-alignment-matrix-construction

Summary

Construct a unified, comparable matrix by aggregating per-sample MS2 fingerprints (vectors of MS2 peak and neutral loss counts) across multiple samples, enabling cross-sample metabolomic comparison. This skill is essential for retention-time-agnostic sample alignment in chemodiverse datasets where feature overlap is poor or LC/MS conditions vary.

When to use

You have already generated per-sample MS2 fingerprints (count vectors of MS2 peaks and neutral losses to the precursor) from matchms-processed spectra using spec2vec document representations, and you need to align these fingerprints into a single matrix to enable comparison across samples. This is particularly appropriate when samples are chemodiverse (poor feature overlap) or acquired under different LC methods, retention time ranges, or MS technologies.

When NOT to use

• You have not yet generated per-sample MS2 fingerprints; you are still at the raw spectra or pre-processing stage.
• Your input is already a feature abundance table (e.g., from untargeted LC-MS peak picking); this skill assumes MS2-derived fingerprints, not LC-MS features.
• Your samples have been acquired at different precursor mass ranges or with fundamentally incompatible MS2 fragmentation protocols; feature alignment will not be meaningful.

Inputs

• per-sample MS2 fingerprint vectors (1D numpy arrays or lists, one per sample)
• sample metadata or identifiers (to label rows)

Outputs

• unified MS2 fingerprint matrix (2D numpy array; rows = samples, columns = MS2 features)
• matrix validation report (dimensions, feature counts, alignment confirmation)

How to apply

Load all per-sample MS2 fingerprint vectors (each sample produces one fingerprint vector generated by counting occurrences of MS2 peaks and neutral losses in that sample). Aggregate these vectors into a unified matrix using numpy array operations, ensuring that feature alignment is consistent across samples—each row represents one sample, and each column represents a unique MS2 peak or neutral loss feature. Validate matrix dimensions (rows = number of samples, columns = total unique features) and confirm feature consistency by checking that no samples have missing or misaligned feature columns. Once validated, the matrix is ready for downstream filtering (e.g., removing blank-derived peaks/losses) and visualization or comparison techniques (MDS/PCoA, TMAP, heatmap).

Related tools

• matchms (Core framework for importing and processing MS2 spectra into standardized spectrum objects; feeds into spec2vec fingerprint generation) — https://github.com/matchms/matchms
• spec2vec (Learns spectral embeddings and generates per-sample MS2 fingerprint document representations from matchms spectra) — https://github.com/iomega/spec2vec
• numpy (Performs efficient array aggregation and matrix construction operations; validates matrix dimensions and consistency)
• MEMO (Complete pipeline integrating matchms, spec2vec, and matrix construction; handles fingerprint generation, alignment, filtering, and visualization) — https://github.com/mandelbrot-project/memo

Examples

import numpy as np; from memo import MemoMatrix; fingerprints = [spec2vec.get_embedding(spec) for spec in spectra_list]; memo_matrix = np.vstack(fingerprints); print(f'Matrix shape: {memo_matrix.shape}')

Evaluation signals

• Matrix dimensions match expected values: rows = number of input samples, columns = number of unique MS2 peaks/neutral losses across all samples
• All per-sample fingerprint vectors have been included with no missing or dropped samples
• Feature columns are consistently ordered and aligned across all rows (no reordering or feature misalignment between samples)
• Matrix values are non-negative counts (MS2 occurrences); no NaN, Inf, or negative values present
• Downstream filtering and visualization steps (MDS, heatmap, TMAP) execute without dimension mismatch errors

Limitations

• Samples with very low spectral diversity or very few MS2 peaks may result in sparse fingerprints, reducing downstream discrimination power.
• Cross-sample feature alignment assumes consistent MS2 fragmentation ionization and collision energy conditions; samples from different MS instruments (e.g., Q-Exactive vs. Q-TOF) may exhibit subtle feature shifts that are not corrected at this stage.
• Blank/control sample contamination is not automatically removed during matrix construction; filtering of blank-derived peaks/losses must be applied as a separate downstream step.
• The method is retention-time agnostic, so it cannot distinguish isobaric or isomeric compounds that produce identical MS2 fragmentation patterns.

Evidence

• [other] MS2 fingerprints are generated by counting occurrences of MS2 peaks and neutral losses in each sample, and these fingerprints are then aligned in a second stage to compare different samples.: "MS2 fingerprints are generated by counting occurrences of MS2 peaks and neutral losses in each sample, and these fingerprints are then aligned in a second stage to compare different samples."
• [other] Aggregate fingerprint vectors across all samples into a unified matrix using numpy array operations, ensuring consistent feature alignment.: "Aggregate fingerprint vectors across all samples into a unified matrix using numpy array operations, ensuring consistent feature alignment."
• [other] Validate matrix dimensions and feature consistency across samples to confirm preparedness for downstream alignment and filtering steps.: "Validate matrix dimensions and feature consistency across samples to confirm preparedness for downstream alignment and filtering steps."
• [other] MEMO is mainly built on matchms_ and spec2vec_ packages for handling the MS2 spectra: "MEMO is mainly built on matchms_ and spec2vec_ packages for handling the MS2 spectra"
• [intro] The occurence of MS2 peaks and neutral losses (to the precursor) in each sample is counted and used to generate an MS2 fingerprint: "The occurence of MS2 peaks and neutral losses (to the precursor) in each sample is counted and used to generate an MS2 fingerprint"
• [intro] These fingerprints can in a second stage be aligned to compare different samples: "These fingerprints can in a second stage be aligned to compare different samples"
• [other] MEMO suits particularly well to compare chemodiverse samples, ie with a poor features overlap, or to compare samples with a strong RT shift: "MEMO suits particularly well to compare chemodiverse samples, ie with a poor features overlap, or to compare samples with a strong RT shift"