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