spectral-peak-data-extraction
Summary
Extract m/z and intensity peak data from mass spectrometry spectra stored in a MsBackend, returning them as a list of numerical matrices with one matrix per spectrum. This is a core operation for accessing and validating MS peak data before downstream analysis.
When to use
When you need to retrieve m/z–intensity pairs from a MsBackend-backed Spectra object for visualization, comparison, or processing; particularly when the backend stores peak data separately (e.g., in distinct m/z and intensity slots) and you need them merged into matrix form, or when validating that peaks are correctly sorted and dimensioned.
When NOT to use
- When you only need aggregated statistics (e.g., total ion current, maximum intensity) without the full peak list—use intensity() or mz() accessors instead.
- When peaks are already stored as pre-merged matrices in your backend and you do not need subsetting—direct access is faster.
- When working with a read-only backend (e.g., MsBackendMzR) that does not support peak replacement—query peaksData() for read access, but do not attempt to modify and re-insert.
Inputs
- MsBackend object with populated m/z and intensity data slots or list
- Integer indices (for subsetting operations within peaksData)
- Spectrum identifiers to access individual peak data
Outputs
- List of numerical matrices, one per spectrum
- Each matrix has 2 columns: m/z values (sorted increasingly) and intensity values
- Matrices preserve order and can support duplicated spectra if extracted via extractByIndex()
How to apply
Implement a peaksData() method in your MsBackend subclass that iterates over the m/z and intensity slots for each spectrum and merges them into numerical matrices (one per spectrum) with two columns: m/z (first column, sorted increasingly) and intensity (second column). The method should return a list of these matrices, preserving spectrum order and supporting subsetting by index. If your backend pre-stores data as a list of matrices (like MsBackendMemory), the implementation is more efficient because it can return data directly without looping. Always validate that m/z values are sorted increasingly within each spectrum and that no NA values appear in m/z columns, as the Spectra design requires this.
Related tools
- Spectra (Primary package providing the MsBackend virtual class and peaksData() generic; manages spectrum objects and delegates peak retrieval to backend implementations) — https://github.com/RforMassSpectrometry/Spectra
- S4Vectors (Provides DataFrame and NumericList classes used to store and return spectra variables and peak data in structured form)
- MsBackendMemory (Reference backend implementation that stores peaks as a list of matrices, demonstrating the most efficient peaksData() approach) — https://github.com/RforMassSpectrometry/Spectra
- MsBackendMzR (Example of a partially read-only backend that retrieves peaks on-the-fly from raw MS files; illustrates peaksData() for lazy-loaded backends) — https://github.com/RforMassSpectrometry/Spectra
Examples
setMethod("peaksData", "MyMsBackend", function(object, ...) { mapply(function(mz, intensity) { cbind(mz = mz, intensity = intensity) }, object@mz, object@intensity, SIMPLIFY = FALSE) })
Evaluation signals
- peaksData() returns a list with length equal to the number of spectra in the backend.
- Each element of the list is a numerical matrix with exactly 2 columns (m/z and intensity) and number of rows equal to the peak count for that spectrum.
- m/z values in each matrix are sorted in strictly increasing order with no NA values; intensity values are non-negative.
- extractByIndex() followed by peaksData() returns matrices in the same order as the indices, allowing duplicates and reordering.
- backendMerge() on two backends followed by peaksData() returns a concatenated list with no data loss or duplicate rows within each spectrum.
Limitations
- peaksData() performance depends on whether the backend pre-stores data as matrices (fast, like MsBackendMemory) or must loop and merge from separate m/z and intensity slots (slower); backends retrieving data on-the-fly from external files (e.g., MsBackendMzR) may have additional I/O overhead.
- m/z values must be sorted increasingly and NA values are not supported; spectra with unsorted or missing m/z will violate the Spectra design contract.
- For very large datasets or read-only backends, calling peaksData() on the entire Spectra object may be memory-intensive; subsetting via extractByIndex() first is recommended.
- Some backends are partially or fully read-only and do not support peak data modification after extraction; peaksData() is for reading only in such cases.
Evidence
- [intro] peaksData() design and return format: "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] m/z sorting requirement: "m/z values within each spectrum are expected to be sorted increasingly. Missing values (
NA) for m/z values are not supported."
- [intro] MsBackendMemory efficiency: "The
MsBackendMemory backend for example stores the MS data already as a list of matrices"
- [intro] Implementation workflow for peaksData(): "peaksData() must loop over m/z and intensity slots to merge them into matrices for each spectrum; storing m/z and intensity in separate slots requires this looping but is less efficient than"
- [intro] extractByIndex() behavior with peaksData(): "The
extractByIndex() and [ methods allows to subset MsBackend objects. This operation is expected to reduce a MsBackend object to the selected spectra."
1---2name: spectral-peak-data-extraction3description: Use when when you need to retrieve m/z–intensity pairs from a MsBackend-backed Spectra object for visualization, comparison, or processing; particularly when the backend stores peak data separately (e.4license: CC-BY-4.05---67# spectral-peak-data-extraction89## Summary1011Extract m/z and intensity peak data from mass spectrometry spectra stored in a MsBackend, returning them as a list of numerical matrices with one matrix per spectrum. This is a core operation for accessing and validating MS peak data before downstream analysis.1213## When to use1415When you need to retrieve m/z–intensity pairs from a MsBackend-backed Spectra object for visualization, comparison, or processing; particularly when the backend stores peak data separately (e.g., in distinct m/z and intensity slots) and you need them merged into matrix form, or when validating that peaks are correctly sorted and dimensioned.1617## When NOT to use1819- When you only need aggregated statistics (e.g., total ion current, maximum intensity) without the full peak list—use intensity() or mz() accessors instead.20- When peaks are already stored as pre-merged matrices in your backend and you do not need subsetting—direct access is faster.21- When working with a read-only backend (e.g., MsBackendMzR) that does not support peak replacement—query peaksData() for read access, but do not attempt to modify and re-insert.2223## Inputs2425- MsBackend object with populated m/z and intensity data slots or list26- Integer indices (for subsetting operations within peaksData)27- Spectrum identifiers to access individual peak data2829## Outputs3031- List of numerical matrices, one per spectrum32- Each matrix has 2 columns: m/z values (sorted increasingly) and intensity values33- Matrices preserve order and can support duplicated spectra if extracted via extractByIndex()3435## How to apply3637Implement a peaksData() method in your MsBackend subclass that iterates over the m/z and intensity slots for each spectrum and merges them into numerical matrices (one per spectrum) with two columns: m/z (first column, sorted increasingly) and intensity (second column). The method should return a list of these matrices, preserving spectrum order and supporting subsetting by index. If your backend pre-stores data as a list of matrices (like MsBackendMemory), the implementation is more efficient because it can return data directly without looping. Always validate that m/z values are sorted increasingly within each spectrum and that no NA values appear in m/z columns, as the Spectra design requires this.3839## Related tools4041- **Spectra** (Primary package providing the MsBackend virtual class and peaksData() generic; manages spectrum objects and delegates peak retrieval to backend implementations) — https://github.com/RforMassSpectrometry/Spectra42- **S4Vectors** (Provides DataFrame and NumericList classes used to store and return spectra variables and peak data in structured form)43- **MsBackendMemory** (Reference backend implementation that stores peaks as a list of matrices, demonstrating the most efficient peaksData() approach) — https://github.com/RforMassSpectrometry/Spectra44- **MsBackendMzR** (Example of a partially read-only backend that retrieves peaks on-the-fly from raw MS files; illustrates peaksData() for lazy-loaded backends) — https://github.com/RforMassSpectrometry/Spectra4546## Examples4748```49setMethod("peaksData", "MyMsBackend", function(object, ...) { mapply(function(mz, intensity) { cbind(mz = mz, intensity = intensity) }, object@mz, object@intensity, SIMPLIFY = FALSE) })50```5152## Evaluation signals5354- peaksData() returns a list with length equal to the number of spectra in the backend.55- Each element of the list is a numerical matrix with exactly 2 columns (m/z and intensity) and number of rows equal to the peak count for that spectrum.56- m/z values in each matrix are sorted in strictly increasing order with no NA values; intensity values are non-negative.57- extractByIndex() followed by peaksData() returns matrices in the same order as the indices, allowing duplicates and reordering.58- backendMerge() on two backends followed by peaksData() returns a concatenated list with no data loss or duplicate rows within each spectrum.5960## Limitations6162- peaksData() performance depends on whether the backend pre-stores data as matrices (fast, like MsBackendMemory) or must loop and merge from separate m/z and intensity slots (slower); backends retrieving data on-the-fly from external files (e.g., MsBackendMzR) may have additional I/O overhead.63- m/z values must be sorted increasingly and NA values are not supported; spectra with unsorted or missing m/z will violate the Spectra design contract.64- For very large datasets or read-only backends, calling peaksData() on the entire Spectra object may be memory-intensive; subsetting via extractByIndex() first is recommended.65- Some backends are partially or fully read-only and do not support peak data modification after extraction; peaksData() is for reading only in such cases.6667## Evidence6869- [intro] peaksData() design and return format: "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"70- [intro] m/z sorting requirement: "m/z values within each spectrum are expected to be sorted increasingly. Missing values (`NA`) for m/z values are not supported."71- [intro] MsBackendMemory efficiency: "The `MsBackendMemory` backend for example stores the MS data already as a `list` of matrices"72- [intro] Implementation workflow for peaksData(): "peaksData() must loop over m/z and intensity slots to merge them into matrices for each spectrum; storing m/z and intensity in separate slots requires this looping but is less efficient than"73- [intro] extractByIndex() behavior with peaksData(): "The `extractByIndex()` and `[` methods allows to subset `MsBackend` objects. This operation is expected to reduce a `MsBackend` object to the selected spectra."
HolobiomicsLab 