S4 Class Definition and Inheritance
Summary
Define custom S4 classes that extend virtual parent classes and implement required slots and methods to create domain-specific data structures. This skill is essential when building extensible bioinformatics infrastructure where multiple implementations need to conform to a common API contract.
When to use
You are designing a new backend or data container that must integrate seamlessly with an existing Spectra-based workflow. You have identified a virtual parent class (e.g., MsBackend) that defines the API, and you need to create a concrete implementation with specific data representation choices (e.g., in-memory NumericList storage for peaks, data.frame for metadata).
When NOT to use
- You are reading from an existing data source (file, database) where a backend already exists (e.g., MsBackendMzR for mzML files, MsBackendSql for SQL databases) — use the existing backend instead.
- You only need read-only access to a remote or cached resource — extend MsBackendCached rather than implementing the full MsBackend API.
- Your data fits naturally into a simple in-memory list-of-matrices structure — MsBackendMemory or MsBackendDataFrame may already meet your needs without custom class definition.
Inputs
- Virtual parent class definition (e.g., MsBackend from Spectra package)
- Data representation design specification (slot names, types, structure)
- Sample mass spectrometry data (m/z, intensity pairs; metadata variables)
Outputs
- Concrete S4 class extending the virtual parent
- Implemented accessor methods returning typed objects (DataFrame, NumericList, character vectors)
- Implemented data replacement methods for write-capable backends
- Functional backend instance ready for integration into Spectra workflows
How to apply
First, identify the virtual parent class and its required methods by consulting the API documentation. Define your S4 class using setClass() with explicit slots that match your data model (e.g., spectraVars as data.frame, mz and intensity as NumericList). Implement all required accessor methods (spectraData, spectraVariables, peaksData, extractByIndex, backendMerge, intensity, mz, spectraNames) and initialization method (backendInitialize) with signatures matching the parent contract. For read-write backends, also implement replacement methods (intensity<-, mz<-, spectraData<-, etc.). Ensure m/z values within each spectrum are sorted increasingly and that core variables (dataStorage, dataOrigin) are always provided. Validate the implementation by instantiating the class, populating it with test data via backendInitialize(), and confirming all accessor methods return expected types and shapes.
Related tools
- Spectra (Provides the virtual MsBackend class definition and integration framework that your custom S4 class must extend and implement) — https://github.com/RforMassSpectrometry/Spectra
- S4Vectors (Provides DataFrame and NumericList data structures used as return types in spectraData() and peaks accessor methods)
- IRanges (Companion infrastructure package for S4 class and method system integration)
Examples
setClass('MsBackendTest', contains='MsBackend', slots=c(spectraVars='data.frame', mz='NumericList', intensity='NumericList')); setMethod('spectraData', 'MsBackendTest', function(object) { cbind(object@spectraVars, mz=object@mz, intensity=object@intensity) })
Evaluation signals
- All required accessor methods (spectraData, spectraVariables, backendInitialize, peaksData, extractByIndex, backendMerge, intensity, mz, spectraNames) are implemented with correct signatures and return types (DataFrame, character, NumericList, integer-indexed subsets).
- backendInitialize() successfully populates slots with test data and subsequent spectraData() returns a complete DataFrame with all variables and matching row count.
- intensity() and mz() return NumericList objects with length equal to spectrum count, where each element is a numeric vector with increasing m/z values.
- extractByIndex(backend, c(1,3,5)) returns a valid instance with 3 spectra and consistent internal structure (spectraVars nrow equals length of mz/intensity lists).
- Data replacement methods (intensity<-, mz<-) update slots without breaking invariants: m/z remains sorted and list lengths remain synchronized with spectraVars row count.
Limitations
- M/z values within each spectrum are expected to be sorted increasingly — unsorted input data must be preprocessed or will violate API contracts.
- The MsBackend API is read-only-capable; backends extending MsBackendCached avoid implementing expensive replacement methods, meaning write-capable backends incur full implementation cost.
- merging (backendMerge()) two instances of different MsBackend classes is not supported — only same-type backends can be combined.
Evidence
- [intro] S4 class extension definition: "To create a new backend a class extending the virtual
MsBackend needs to be implemented."
- [intro] Slot structure for in-memory backend: "slots = c( spectraVars = "data.frame", mz = "NumericList", intensity = "NumericList" )"
- [intro] spectraData() return type requirement: "The
spectraData() method should return the full spectra data within a backend as a DataFrame object"
- [intro] Required accessor methods enumeration: "MsBackendTest requires implementation of 9 required accessor methods (spectraData, spectraVariables, backendInitialize, peaksData, extractByIndex, backendMerge, intensity, mz, spectraNames)"
- [intro] M/z sorting invariant: "m/z values within each spectrum are expected to be sorted increasingly."
- [intro] Core variables requirement: "
dataStorage and dataOrigin are two special spectra variables that define for each spectrum where the data is stored and from where the data derived"
- [intro] Read-only backend option: "
MsBackend implementations can also represent purely read-only data resources. In this case only data accessor methods need to be implemented but not data replacement methods."
- [intro] peaksData() extraction method: "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."
1---2name: s4-class-definition-and-inheritance3description: Use when you are designing a new backend or data container that must integrate seamlessly with an existing Spectra-based workflow. You have identified a virtual parent class (e.4license: CC-BY-4.05---67# S4 Class Definition and Inheritance89## Summary1011Define custom S4 classes that extend virtual parent classes and implement required slots and methods to create domain-specific data structures. This skill is essential when building extensible bioinformatics infrastructure where multiple implementations need to conform to a common API contract.1213## When to use1415You are designing a new backend or data container that must integrate seamlessly with an existing Spectra-based workflow. You have identified a virtual parent class (e.g., MsBackend) that defines the API, and you need to create a concrete implementation with specific data representation choices (e.g., in-memory NumericList storage for peaks, data.frame for metadata).1617## When NOT to use1819- You are reading from an existing data source (file, database) where a backend already exists (e.g., MsBackendMzR for mzML files, MsBackendSql for SQL databases) — use the existing backend instead.20- You only need read-only access to a remote or cached resource — extend MsBackendCached rather than implementing the full MsBackend API.21- Your data fits naturally into a simple in-memory list-of-matrices structure — MsBackendMemory or MsBackendDataFrame may already meet your needs without custom class definition.2223## Inputs2425- Virtual parent class definition (e.g., MsBackend from Spectra package)26- Data representation design specification (slot names, types, structure)27- Sample mass spectrometry data (m/z, intensity pairs; metadata variables)2829## Outputs3031- Concrete S4 class extending the virtual parent32- Implemented accessor methods returning typed objects (DataFrame, NumericList, character vectors)33- Implemented data replacement methods for write-capable backends34- Functional backend instance ready for integration into Spectra workflows3536## How to apply3738First, identify the virtual parent class and its required methods by consulting the API documentation. Define your S4 class using setClass() with explicit slots that match your data model (e.g., spectraVars as data.frame, mz and intensity as NumericList). Implement all required accessor methods (spectraData, spectraVariables, peaksData, extractByIndex, backendMerge, intensity, mz, spectraNames) and initialization method (backendInitialize) with signatures matching the parent contract. For read-write backends, also implement replacement methods (intensity<-, mz<-, spectraData<-, etc.). Ensure m/z values within each spectrum are sorted increasingly and that core variables (dataStorage, dataOrigin) are always provided. Validate the implementation by instantiating the class, populating it with test data via backendInitialize(), and confirming all accessor methods return expected types and shapes.3940## Related tools4142- **Spectra** (Provides the virtual MsBackend class definition and integration framework that your custom S4 class must extend and implement) — https://github.com/RforMassSpectrometry/Spectra43- **S4Vectors** (Provides DataFrame and NumericList data structures used as return types in spectraData() and peaks accessor methods)44- **IRanges** (Companion infrastructure package for S4 class and method system integration)4546## Examples4748```49setClass('MsBackendTest', contains='MsBackend', slots=c(spectraVars='data.frame', mz='NumericList', intensity='NumericList')); setMethod('spectraData', 'MsBackendTest', function(object) { cbind(object@spectraVars, mz=object@mz, intensity=object@intensity) })50```5152## Evaluation signals5354- All required accessor methods (spectraData, spectraVariables, backendInitialize, peaksData, extractByIndex, backendMerge, intensity, mz, spectraNames) are implemented with correct signatures and return types (DataFrame, character, NumericList, integer-indexed subsets).55- backendInitialize() successfully populates slots with test data and subsequent spectraData() returns a complete DataFrame with all variables and matching row count.56- intensity() and mz() return NumericList objects with length equal to spectrum count, where each element is a numeric vector with increasing m/z values.57- extractByIndex(backend, c(1,3,5)) returns a valid instance with 3 spectra and consistent internal structure (spectraVars nrow equals length of mz/intensity lists).58- Data replacement methods (intensity<-, mz<-) update slots without breaking invariants: m/z remains sorted and list lengths remain synchronized with spectraVars row count.5960## Limitations6162- M/z values within each spectrum are expected to be sorted increasingly — unsorted input data must be preprocessed or will violate API contracts.63- The MsBackend API is read-only-capable; backends extending MsBackendCached avoid implementing expensive replacement methods, meaning write-capable backends incur full implementation cost.64- merging (backendMerge()) two instances of different MsBackend classes is not supported — only same-type backends can be combined.6566## Evidence6768- [intro] S4 class extension definition: "To create a new backend a class extending the virtual `MsBackend` needs to be implemented."69- [intro] Slot structure for in-memory backend: "slots = c( spectraVars = "data.frame", mz = "NumericList", intensity = "NumericList" )"70- [intro] spectraData() return type requirement: "The `spectraData()` method should return the **full** spectra data within a backend as a `DataFrame` object"71- [intro] Required accessor methods enumeration: "MsBackendTest requires implementation of 9 required accessor methods (spectraData, spectraVariables, backendInitialize, peaksData, extractByIndex, backendMerge, intensity, mz, spectraNames)"72- [intro] M/z sorting invariant: "m/z values within each spectrum are expected to be sorted increasingly."73- [intro] Core variables requirement: "`dataStorage` and `dataOrigin` are two special spectra variables that define for each spectrum where the data is stored and from where the data derived"74- [intro] Read-only backend option: "`MsBackend` implementations can also represent purely *read-only* data resources. In this case only data accessor methods need to be implemented but not data replacement methods."75- [intro] peaksData() extraction method: "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."
HolobiomicsLab