# Cross Sample Alignment Matrix Construction

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

- Skill: `holobiomicslab/cross-sample-alignment-matrix-construction` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/cross-sample-alignment-matrix-construction`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/cross-sample-alignment-matrix-construction/raw
- Safety review: pending
- 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/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"