S4 Class Object Memory Profiling

---
name: s4-class-object-memory-profiling
description: Use when when designing or optimizing S4-based data backends (such as
  MsBackend subclasses) and you need to decide whether to pre-populate all slots with
  complete data structures or defer initialization until data access.
license: CC-BY-4.0
metadata:
  edam_operation: http://edamontology.org/operation_3445
  edam_topics:
  - http://edamontology.org/topic_0121
  - http://edamontology.org/topic_3520
  tools:
  - R
  - S4Vectors
  - Spectra
  techniques:
  - mass-spectrometry
  license_tier: open
  provenance_tier: literature
derived_from:
- doi: 10.3390/metabo12020173
  title: spectra
evidence_spans:
- library(Spectra) library(IRanges)
- library(Spectra)
- return the **full** spectra data within a backend as a `DataFrame` object (defined
  in the `r Biocpkg("S4Vectors")`
claims: []
provenance:
  collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v2
  assembled_by: scripts/collect_metabolomics_collection.py
  sources:
  - build: coll_spectra
    doi: 10.3390/metabo12020173
    title: spectra
  dedup_kept_from: coll_spectra
schema_version: 0.2.0
attribution:
  generator: AgenticScienceBuilder
  original_doi: 10.3390/metabo12020173
  all_source_dois:
  - 10.3390/metabo12020173
  zenodo_doi: 10.5281/zenodo.20794027
  curators: []
  promoter: Louis-Félix Nothias
  sponsor: CNRS & Université Côte d'Azur
---

# S4-class object memory profiling

## Summary

A technique for measuring and comparing the in-memory footprint of S4 objects under different initialization strategies, revealing tradeoffs between eager pre-population and lazy on-demand data loading. This is essential for optimizing backend design in large-scale mass spectrometry data infrastructure.

## When to use

When designing or optimizing S4-based data backends (such as MsBackend subclasses) and you need to decide whether to pre-populate all slots with complete data structures or defer initialization until data access. Use this skill when comparing memory consumption between eager initialization of all spectra variables (e.g., all core spectra variable columns in @spectraVars) versus lazy filling strategies that populate missing columns on-the-fly during method invocation.

## When NOT to use

- Input is already a finalized, production-deployed backend with no optimization goals — profiling is unnecessary if memory and speed are already acceptable.
- Comparing backends across fundamentally different data sources (e.g., in-memory versus SQL database) — use backend-agnostic benchmarking instead.
- Optimizing peak data (m/z, intensity matrices) rather than spectra metadata — peak data compression and lazy-loading strategies require different profiling approaches.

## Inputs

- S4 object instance (e.g., MsBackendTest) with pre-populated @spectraVars slot
- S4 object instance with minimal @spectraVars initialization
- Data structure defining all expected core spectra variables (column names, types)

## Outputs

- Numeric vector of object sizes (bytes) before and after data access for each variant
- Execution timing (seconds) for spectraData() calls on each variant
- Memory overhead ratio (pre-populated size / lazy-loaded size)
- Summary table documenting the memory-speed tradeoff with recommendations

## How to apply

Create two parallel instances of your S4 backend class: one initialized with all expected slots and data structures pre-populated, and one with minimal initialization. Invoke the key data-accessor methods (e.g., spectraData()) on each instance to trigger any lazy-loading logic in the second variant. Measure in-memory object size for both using object.size() before and after accessor method calls. Record execution timing alongside size measurements to quantify the memory-versus-speed tradeoff. Document whether pre-population increases footprint due to storage of empty or sparse columns, and whether on-the-fly initialization via helper functions (e.g., fillCoreSpectraVariables()) reduces peak memory at the cost of repeated computation or slower access.

## Related tools

- **R** (Environment for running object.size() profiling and timing comparisons)
- **S4Vectors** (Provides DataFrame class returned by spectraData() for encapsulating spectra metadata)
- **Spectra** (Defines MsBackend virtual class and backend implementations (MsBackendMemory, MsBackendMzR, etc.) to be profiled) — https://github.com/RforMassSpectrometry/Spectra

## Examples

```
# Create two MsBackendTest variants and profile memory
library(Spectra)
mb_eager <- MsBackendTest()
# Pre-populate all core spectra variables
mb_lazy <- MsBackendTest()
size_eager_before <- object.size(mb_eager)
df_eager <- spectraData(mb_eager)
size_eager_after <- object.size(mb_eager)
size_lazy_before <- object.size(mb_lazy)
df_lazy <- spectraData(mb_lazy)
size_lazy_after <- object.size(mb_lazy)
cat("Eager overhead (bytes):", size_eager_after - size_eager_before, "\n")
cat("Lazy overhead (bytes):", size_lazy_after - size_lazy_before, "\n")
```

## Evaluation signals

- Object size measurements are consistent across repeated calls and follow expected monotonicity (pre-populated ≥ lazy-loaded before first access).
- spectraData() method successfully populates all expected core spectra variable columns (mz, intensity, rtime, scanIndex, precursorMz, precursorIntensity, acquisitionNum, msLevel) in both variants, yielding identical DataFrame output.
- Timing measurements for spectraData() show measurable difference between variants (lazy-loading may incur observable overhead on first invocation vs. pre-loaded efficiency).
- Memory overhead from pre-population correlates with the number and sparsity of initialized-but-empty columns; absent columns in lazy variant do not consume storage until accessed.
- fillCoreSpectraVariables() helper function is called during spectraData() on the lazy-loaded variant and successfully populates missing columns without data loss or type mismatches.

## Limitations

- object.size() measures in-process memory only; does not account for garbage collection, memory fragmentation, or peak transient memory usage during DataFrame construction.
- Timing comparisons are sensitive to R session state, CPU load, and garbage collection; multiple replicate measurements are recommended to establish statistical significance.
- Pre-population overhead may be amortized across many spectraData() calls; the tradeoff favors pre-population if accessor methods are called frequently, but lazy-loading if data is accessed rarely or only partially.
- Memory measurements do not capture on-disk storage of raw MS data files (relevant for MsBackendMzR and other file-backed backends); this profiling technique is most applicable to in-memory backends like MsBackendMemory.

## Evidence

- [other] Pre-populating @spectraVars with all core spectra variables increases memory footprint because all variables, including those with only missing values, must be stored in the object, whereas on-the-fly initialization via fillCoreSpectraVariables() avoids storing empty columns but may be less efficient for data extraction.: "Pre-populating @spectraVars with all core spectra variables increases memory footprint because all variables, including those with only missing values, must be stored in the object, whereas"
- [intro] The `spectraData()` method should return the **full** spectra data within a backend as a `DataFrame` object (defined in the `r Biocpkg("S4Vectors")`: "The `spectraData()` method should return the **full** spectra data within a backend as a `DataFrame` object (defined in the `r Biocpkg("S4Vectors")`"
- [other] Measure in-memory object size for both objects using object.size() in R before and after spectraData() invocation.: "Measure in-memory object size for both objects using object.size() in R before and after spectraData() invocation."
- [other] Compare memory footprints and record timing of spectraData() execution for each variant.: "Compare memory footprints and record timing of spectraData() execution for each variant."