# Spectra Variable And Peak Data Storage

> Use when when building a new mass spectrometry data backend for the Spectra package that must store and serve multiple spectra with their associated m/z and intensity peaks. Use this when you need a backend that combines efficient metadata lookup (via data.

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

---


# spectra-variable-and-peak-data-storage

## Summary

Design and implement an S4 class extending MsBackend to store mass spectrometry spectral data, separating spectrum metadata (spectra variables) in a data.frame from peak data (m/z and intensity) in NumericList objects, with validity constraints ensuring consistency. This skill enables creation of custom backend implementations for the Spectra infrastructure.

## When to use

When building a new mass spectrometry data backend for the Spectra package that must store and serve multiple spectra with their associated m/z and intensity peaks. Use this when you need a backend that combines efficient metadata lookup (via data.frame spectra variables) with flexible peak data storage (via NumericList), and must enforce invariants that m/z values are sorted increasingly within each spectrum with no missing values.

## When NOT to use

- Input is already a valid Spectra object or MsBackend instance ready for use; implement accessor/transformation methods instead.
- Peak data is not mass spectrometry spectra (e.g., chromatographic, imaging, or non-m/z-sorted data); this design assumes sorted m/z within each spectrum.
- You require mutable peak data storage but only read-only access is needed; consider MsBackendCached or similar read-only backends instead.

## Inputs

- Mass spectrometry spectral data (peaks with m/z and intensity values)
- Spectrum metadata (spectra variables: retention time, precursor m/z, scan number, etc.)
- Data in any format that can be converted to data.frame and NumericList structures

## Outputs

- S4 MsBackend subclass instance with valid spectraVars, mz, and intensity slots
- Spectra object backed by the custom MsBackend implementation
- DataFrame (via spectraData() method) combining spectra variables with NumericList peak data

## How to apply

Define an S4 class extending the virtual MsBackend using setClass() with three primary slots: a data.frame (spectraVars) storing spectrum-level properties like retention time and precursor m/z, and NumericList objects (mz, intensity) storing the corresponding peak data for each spectrum. Implement a constructor (initialize method) that accepts input data and populates all three slots consistently. Define a setValidity() method that enforces the core constraint: the number of rows in spectraVars must equal the length of both mz and intensity slots, that all m/z values within each spectrum are sorted increasingly with no NA elements, and that m/z and intensity have matching lengths per spectrum. Instantiate the class and verify that validity checks correctly reject objects with mismatched slot lengths or unsorted/missing m/z values. This separation of concerns allows backends to implement different access strategies (e.g., on-disk vs. in-memory) while maintaining a consistent interface.

## Related tools

- **Spectra** (Provides the virtual MsBackend class to extend and the Spectra wrapper class that uses backend instances to store and process spectral data) — https://github.com/RforMassSpectrometry/Spectra
- **S4Vectors** (Provides DataFrame and NumericList data structures used for storing spectra variables and peak data with efficient memory representation)
- **IRanges** (Used with S4Vectors for efficient range and list operations on spectral data)
- **MSnbase** (Predecessor package providing in-memory and on-disk data representation design patterns that informed MsBackend architecture)

## Examples

```
setClass('MsBackendTest', contains='MsBackend', slots=list(spectraVars='data.frame', mz='NumericList', intensity='NumericList')); setValidity('MsBackendTest', function(object) { if(nrow(object@spectraVars) != length(object@mz)) return('Mismatch: nrow(spectraVars) != length(mz)'); TRUE }); obj <- new('MsBackendTest', spectraVars=data.frame(id=1:2), mz=NumericList(c(100, 200), c(150, 250)), intensity=NumericList(c(10, 20), c(15, 25)))
```

## Evaluation signals

- Class instantiation succeeds without error; object contains populated spectraVars (data.frame), mz (NumericList), and intensity (NumericList) slots.
- Validity check passes for well-formed objects: nrow(spectraVars) == length(mz) == length(intensity); each mz element is sorted increasingly with no NA values.
- Validity check correctly rejects mismatched objects: nrow(spectraVars) ≠ length(mz), or mz values contain NA, or mz values are not sorted increasingly within a spectrum.
- spectraData() method returns a DataFrame with spectra variable columns plus mz and intensity as NumericList columns with matching row/element counts.
- Backend can be passed to Spectra() constructor and used in analysis workflows (e.g., subsetting, filtering) without errors.

## Limitations

- m/z values must be sorted increasingly within each spectrum and cannot contain missing (NA) values; data preprocessing to enforce this constraint is required before slot assignment.
- The data.frame spectraVars slot stores only tabular metadata; S4 objects as spectra variables require MsBackendDataFrame instead.
- Performance depends on NumericList implementation and the chosen data access strategy (in-memory vs. on-disk); lazy loading of peaks requires additional backend methods.
- Parallel processing may be limited if the backend does not implement backendParallelFactor() to suggest a preferred splitting strategy.

## Evidence

- [intro] Class design structure: "An MsBackend extension class (MsBackendTest) uses three slots: a data.frame (spectraVars) storing spectra variable properties, and NumericList objects (mz, intensity) storing peak data."
- [intro] Validity constraint rationale: "A setValidity method enforces that the number of rows in spectraVars matches the length of both mz and intensity slots, ensuring data consistency across the backend."
- [intro] m/z ordering requirement: "m/z values within each spectrum are expected to be sorted increasingly. Missing values (NA) for m/z values are not supported."
- [intro] Backend virtual class role: "The MsBackend virtual class defines the API that new backend classes need to implement in order to be used with the Spectra object."
- [intro] Spectra variables definition: "Properties of a spectrum are called spectra variables. While backends can define their own properties, a minimum required set of spectra variables must be provided by each backend."