Msbackend API Implementation

msbackend-api-implementation

Summary

Implement a custom MsBackend subclass that extends the virtual MsBackend API to store and provide mass spectrometry spectral data (m/z, intensity, and metadata) to Spectra objects. This skill involves designing S4 class slots, enforcing data consistency through validity methods, and implementing core accessor and data-manipulation methods.

When to use

You need to create a new backend to integrate MS data from a novel file format, database, or in-memory storage system into the Spectra ecosystem. Use this skill when existing backends (MsBackendMemory, MsBackendMzR, MsBackendSql, etc.) do not support your data source or storage paradigm.

When NOT to use

• Your data source is already supported by an existing backend (e.g., mzML files via MsBackendMzR, SQL databases via MsBackendSql, in-memory matrices via MsBackendMemory).
• You only need to analyze pre-loaded Spectra objects without defining new storage or access patterns.
• Your m/z values are not sorted increasingly or contain NA values per spectrum, as these violate MsBackend core requirements.

Inputs

• S4 class definition extending MsBackend
• data.frame containing spectra variables (e.g., retention time, precursor m/z, scan index)
• list or NumericList of m/z values (sorted increasingly per spectrum)
• list or NumericList of intensity values (parallel to m/z)
• optional: complete DataFrame containing both variables and peak data

Outputs

• MsBackend subclass instance with populated slots
• DataFrame returned by spectraData() with core and backend-specific columns
• NumericList returned by mz() and intensity()
• list of numerical matrices (m/z and intensity columns) from peaksData()
• extracted or merged MsBackend objects from extractByIndex() and backendMerge()

How to apply

Define an S4 class extending MsBackend with slots for spectra variables (data.frame) and peak data (NumericList for m/z and intensity). Implement a setValidity method enforcing that spectraVars row count matches m/z and intensity list lengths, with m/z values sorted increasingly and free of NA. Implement backendInitialize() to populate slots from input data (data.frame, lists, or complete DataFrame), automatically setting dataStorage and dataOrigin variables. Implement accessor methods (spectraVariables(), spectraData(), peaksData(), mz(), intensity()) that return core variables combined with backend-specific columns; use fillCoreSpectraVariables() to avoid circular dependencies. Implement data manipulation methods (extractByIndex(), backendMerge()) to subset and combine backends; for peaksData() efficiency, consider storing peak data as pre-assembled matrices rather than separate lists.

Related tools

• Spectra (defines the virtual MsBackend class API and Spectra object that uses backend implementations; provides fillCoreSpectraVariables() helper and S4 class infrastructure) — https://github.com/RforMassSpectrometry/Spectra
• S4Vectors (provides DataFrame and NumericList classes for storing spectra variables and peak data)
• MsBackendMemory (reference implementation storing peak data as list of matrices, demonstrating efficient peaksData() pattern) — https://github.com/RforMassSpectrometry/Spectra
• MSnbase (predecessor package; Spectra extends in-memory and on-disk representations originally defined here)

Examples

setClass("MsBackendTest", contains="MsBackend", slots=c(spectraVars="data.frame", mz="NumericList", intensity="NumericList")); setValidity("MsBackendTest", function(object) { if(nrow(object@spectraVars) != length(object@mz)) return("spectraVars rows must match mz length"); TRUE }); setMethod("backendInitialize", "MsBackendTest", function(object, ...) { object@spectraVars <- data.frame(...); object@mz <- as(list(...), "NumericList"); object@intensity <- as(list(...), "NumericList"); object })

Evaluation signals

• Validity checks reject objects where spectraVars row count does not match mz and intensity list lengths
• spectraVariables() returns character vector containing union of core names (mz, intensity, rtime, scanIndex) and backend-specific column names without duplicates
• spectraData() returns a DataFrame with m/z and intensity as NumericList columns; does not call spectraVariables()
• peaksData() returns list of numerical matrices with correct dimensionality (one matrix per spectrum, two columns: m/z and intensity)
• extractByIndex() and backendMerge() preserve peak data ordering and allow spectrum duplication; no data is lost during merge

Limitations

• m/z values must be sorted increasingly with no missing (NA) values per spectrum; backends cannot relax this constraint
• Backends storing peak data in separate m/z and intensity slots require looping to assemble matrices in peaksData(), incurring performance overhead compared to pre-stored matrix storage (e.g., MsBackendMemory pattern)
• Read-only backends must implement only accessor methods but not data replacement methods; partially read-only backends (like MsBackendMzR) may allow spectra variable modification but prevent peak data changes
• Circular dependencies between spectraData() and spectraVariables() must be avoided; use fillCoreSpectraVariables() in spectraData() and populate spectraVariables() only from backend column names

Evidence

• [intro] MsBackend virtual class defines API; S4 class with data.frame and NumericList slots: "The MsBackend virtual class defines the API that new backend classes need to implement in order to be used with the Spectra object."
• [intro] spectraData must return full data as DataFrame; spectraVariables must return available variable names: "The spectraData() method should return the full spectra data within a backend as a DataFrame object"
• [intro] m/z values sorted increasingly; NA not supported: "m/z values within each spectrum are expected to be sorted increasingly. Missing values (NA) for m/z values are not supported."
• [intro] backendInitialize prepares backend after instantiation: "The backendInitialize() method is expected to be called after creating an instance of the backend class and should prepare (initialize) the backend"
• [intro] peaksData returns list of matrices; extractByIndex subsets; backendMerge combines: "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] MsBackendMemory stores data as list of matrices for efficient peaksData: "The MsBackendMemory backend for example stores the MS data already as a list of matrices"