# Peak Data Extraction And Formatting

> Use when when you have initialized an MsBackend subclass (e.

- Skill: `holobiomicslab/peak-data-extraction-and-formatting` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/peak-data-extraction-and-formatting`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/peak-data-extraction-and-formatting/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/peak-data-extraction-and-formatting

---


# peak-data-extraction-and-formatting

## Summary

Extract m/z and intensity peak values from mass spectrometry backend objects and format them as NumericList or matrix structures for downstream analysis. This skill bridges MsBackend data storage and Spectra-based processing by implementing standardized accessor methods that present raw peak data in expected formats.

## When to use

When you have initialized an MsBackend subclass (e.g., MsBackendTest, MsBackendMemory) containing spectral peak data stored as NumericList or matrix objects and need to retrieve, subset, or reformat m/z and intensity values for processing, visualization, or comparison within a Spectra workflow.

## When NOT to use

- Input backend is read-only (e.g., MsBackendMzR, MsBackendCached) and you need to modify peak values — use intensity<- and mz<- replacement methods instead, which are only implemented for writable backends.
- You need only summary statistics (e.g., precursor m/z, total intensity) rather than full peak arrays — use spectraData() or dedicated accessor methods instead.
- Peak data is already in expected format (NumericList or matrix) and you are not extracting from raw storage — skip this skill and work directly with the formatted peaks.

## Inputs

- MsBackend subclass instance (e.g., MsBackendTest) with populated intensity and mz slots
- spectrum indices or boolean mask for subsetting (optional)
- spectra variable names to filter by (optional)

## Outputs

- NumericList: peak m/z values, one element per spectrum
- NumericList: peak intensity values, one element per spectrum
- list of matrices: combined m/z and intensity as [mz, intensity] rows per spectrum (from peaksData())
- DataFrame: extracted peaks data integrated with spectrum metadata (from peaksData())

## How to apply

Implement the peaksData() method to extract m/z and intensity values from the backend's internal storage (NumericList slots or database) and return them as a list of matrices with one row per spectrum; implement the intensity() and mz() accessor methods to return NumericList objects preserving the one-spectrum-per-element structure; ensure m/z values are sorted increasingly within each spectrum as required by the API. Use extractByIndex() or [ subsetting to isolate specific spectra before peak extraction when processing subsets. Validate that output dimensionality matches the input spectrum count and that all m/z values are numeric and sorted.

## Related tools

- **Spectra** (Container package defining MsBackend virtual class and Spectra object that uses backend instances via @backend slot to provide peak data access) — https://github.com/RforMassSpectrometry/Spectra
- **S4Vectors** (Provides NumericList and DataFrame data structures for storing and returning peak m/z and intensity values with list-like semantics)
- **IRanges** (Imported by Spectra; provides underlying infrastructure for efficient range and list operations on peak data)
- **MsBackendMemory** (Reference in-memory backend implementation that stores peaks as list of matrices; serves as model for implementing peaksData(), intensity(), and mz() methods) — https://github.com/RforMassSpectrometry/Spectra
- **MsBackendMzR** (Example on-the-fly backend that retrieves peaks from raw MS files; demonstrates lazy loading pattern in peaksData() without storing full NumericList in slots) — https://github.com/RforMassSpectrometry/Spectra

## Evaluation signals

- peaksData() returns a list with length equal to the number of spectra in the backend, with each element being a 2-row matrix (mz, intensity) or named list containing 'mz' and 'intensity' columns.
- intensity() and mz() each return a NumericList object with length equal to spectrum count, where each element is a numeric vector corresponding to one spectrum's peaks; all NumericList elements can be accessed via integer or logical indexing.
- All m/z values are numeric, finite, and increasingly sorted within each spectrum (checksum: min(diff(mz)) >= 0 for each spectrum).
- Subsetting via extractByIndex() or [ on the backend followed by peak extraction returns correctly reduced peak arrays matching the selected spectrum indices.
- Round-trip test: extract peaks, verify dimensions match input spectra count, verify no NAs or infinities in output, and verify spectra variable count is consistent before and after subsetting.

## Limitations

- Peak extraction assumes m/z and intensity data are already sorted and validated at backend initialization; no automatic sorting or duplicate-removal is performed by these accessor methods.
- For very large datasets or on-disk backends (e.g., MsBackendMzR), calling peaksData() on the entire backend may trigger full file I/O and consume significant memory; use extractByIndex() to process spectra in batches.
- Read-only backends (e.g., MsBackendMzR, MsBackendCached, MsBackendMassbankSql) do not implement intensity<-, mz<-, or peaksData<- replacement methods; peak modification requires copying data to a writable backend like MsBackendMemory.
- The API expects core variables 'dataStorage' and 'dataOrigin' to be present in every backend; peaks extraction will fail if these required variables are missing from spectraVars.

## Evidence

- [intro] The `peaksData()` method extracts the MS peaks data from a backend, which includes the m/z and intensity values of each MS peak of a spectrum.: "The `peaksData()` method extracts the MS peaks data from a backend, which includes the m/z and intensity values of each MS peak of a spectrum."
- [intro] Extract the intensity values for each spectrum in the backend. The result is expected to be a `NumericList`: "Extract the intensity values for each spectrum in the backend. The result is expected to be a `NumericList`"
- [intro] m/z values within each spectrum are expected to be sorted increasingly.: "m/z values within each spectrum are expected to be sorted increasingly."
- [intro] Each `Spectra` object contains an implementation of such a `MsBackend` within its `@backend` slot which provides the MS data to the `Spectra` object.: "Each `Spectra` object contains an implementation of such a `MsBackend` within its `@backend` slot which provides the MS data to the `Spectra` object."
- [intro] slots = c(
             spectraVars = "data.frame",
             mz = "NumericList",
             intensity = "NumericList"
         ): "slots = c(
             spectraVars = "data.frame",
             mz = "NumericList",
             intensity = "NumericList"
         )"