Cross Sample Alignment Matrix Construction

---
name: cross-sample-alignment-matrix-construction
description: Use when 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.
license: CC-BY-4.0
metadata:
  edam_operation: http://edamontology.org/operation_3891
  edam_topics:
  - http://edamontology.org/topic_3370
  - http://edamontology.org/topic_0091
  tools:
  - matchms
  - spec2vec
  - numpy
  - Python
  - MEMO
  techniques:
  - LC-MS
  license_tier: open
  provenance_tier: literature
derived_from:
- doi: 10.3389/fbinf.2022.842964
  title: memo
evidence_spans:
- 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 and converting them into documents.
- pip install numpy
- conda create --name memo python=3.8
claims: []
provenance:
  collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v2
  assembled_by: scripts/collect_metabolomics_collection.py
  sources:
  - build: coll_memo_cq
    doi: 10.3389/fbinf.2022.842964
    title: memo
  dedup_kept_from: coll_memo_cq
schema_version: 0.2.0
attribution:
  generator: AgenticScienceBuilder
  original_doi: 10.3389/fbinf.2022.842964
  all_source_dois:
  - 10.3389/fbinf.2022.842964
  zenodo_doi: 10.5281/zenodo.20794027
  curators: []
  promoter: Louis-Félix Nothias
  sponsor: CNRS & Université Côte d'Azur
---

# 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"