# Validity Constraint Enforcement For Msdata

> Use when when designing a custom MsBackend subclass (e.g., MsBackendTest) that stores spectral data in multiple slots (a data.frame for spectra variables, NumericList objects for m/z and intensity peaks). Use this skill to guard against slot desynchronization—e.

- Skill: `holobiomicslab/validity-constraint-enforcement-for-msdata` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/validity-constraint-enforcement-for-msdata`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/validity-constraint-enforcement-for-msdata/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/validity-constraint-enforcement-for-msdata

---


# validity-constraint-enforcement-for-msdata

## Summary

Enforce consistency constraints across S4 slots in custom MsBackend classes to ensure that spectra variable metadata, m/z values, and intensity values remain synchronized and meet mass spectrometry data requirements (sorted m/z, no NA values). This is critical when extending the virtual MsBackend class to create new mass spectrometry data storage backends.

## When to use

When designing a custom MsBackend subclass (e.g., MsBackendTest) that stores spectral data in multiple slots (a data.frame for spectra variables, NumericList objects for m/z and intensity peaks). Use this skill to guard against slot desynchronization—e.g., when spectraVars rows do not match the length of mz/intensity elements, or when m/z values are unsorted or contain NA values per spectrum.

## When NOT to use

- Working with an existing, pre-validated backend implementation (e.g., MsBackendMemory, MsBackendMzR)—no need to re-validate.
- Using a read-only backend wrapper (e.g., MsBackendCached) that delegates validation to its parent backend.
- Data is already guaranteed consistent by external constraints (e.g., loaded from a single coherent SQL database via MsBackendSql).

## Inputs

- S4 class definition extending MsBackend
- data.frame slot (spectraVars) with spectrum-level metadata
- NumericList slot (mz) with m/z peak values per spectrum
- NumericList slot (intensity) with intensity values per spectrum

## Outputs

- Validated MsBackend instance (passes setValidity checks)
- Character vector of validation error messages (if validation fails)
- Boolean result from validObject() call

## How to apply

Define a setValidity() method on your MsBackend subclass that enforces three key invariants: (1) nrow(spectraVars) == length(mz) == length(intensity), ensuring all slots index the same number of spectra; (2) for each element in the mz NumericList, values must be sorted increasingly with no NA entries, as required by the Spectra package specification; (3) optionally, validate that spectra variables include required core variables (e.g., dataStorage, dataOrigin) and that intensity values are non-negative. The setValidity method should return TRUE on success or a descriptive character vector of error messages on failure. Call validObject() after instantiation to trigger validation.

## Related tools

- **Spectra** (defines the MsBackend virtual class and spectra data model; provides setValidity and validObject infrastructure for S4 class validation) — https://github.com/RforMassSpectrometry/Spectra
- **S4Vectors** (provides NumericList and DataFrame slot types used to store peak data and spectra metadata in MsBackend subclasses)
- **R (S4 system)** (language and object system; setClass, setValidity, validObject, setMethod are core functions for defining and validating S4 classes)

## Examples

```
setValidity("MsBackendTest", function(object) { if (nrow(object@spectraVars) != length(object@mz)) return("nrow(spectraVars) != length(mz)"); if (length(object@mz) != length(object@intensity)) return("length(mz) != length(intensity)"); if (!all(sapply(object@mz, function(x) !anyNA(x) && !is.unsorted(x)))) return("mz not sorted or contains NA"); TRUE }); validObject(backend_instance)
```

## Evaluation signals

- validObject(backend_instance) returns TRUE for a correctly populated backend; returns an error or character vector listing constraint violations when slots are mismatched.
- nrow(spectraVars) equals length(mz) and length(intensity)—inspect via `all(nrow(backend@spectraVars) == length(backend@mz), length(backend@mz) == length(backend@intensity))`.
- For each element in mz NumericList, m/z values are sorted increasingly and contain no NA: `all(sapply(backend@mz, function(x) all(!is.na(x)) && is.unsorted(x) == FALSE))`.
- Attempt to create an invalid backend (e.g., mismatched slot lengths) and verify setValidity rejects it with a descriptive error message.
- After valid instantiation, call spectraData() and peaksData() methods and confirm returned DataFrame and matrices are internally consistent.

## Limitations

- setValidity is called only at object creation and after explicit validObject() calls; modifications via direct slot assignment (@ operator) may bypass validation—use accessor methods with validity checks instead.
- Validation logic is backend-specific; core requirements (m/z sorting, no NA in mz) apply to all backends, but custom spectra variables or file format constraints must be added per subclass.
- Performance cost scales with number of spectra; for very large backends (millions of spectra), validation may be slow—consider deferred or partial validation strategies.
- The Spectra package requires m/z values sorted increasingly per spectrum with no NA values; backends storing unsorted or missing m/z data must pre-process or reject such data at initialization.

## Evidence

- [other] 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.: "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 values within each spectrum are expected to be sorted increasingly. Missing values (NA) for m/z values are 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] The `MsBackend` virtual class defines the API that new *backend* classes need to implement in order to be used with the `Spectra` object.: "The `MsBackend` virtual class defines the API that new *backend* classes need to implement in order to be used with the `Spectra` object."
- [other] Define a setValidity method that enforces the constraint that the number of rows in the spectraVars data.frame matches the length of the m/z and intensity NumericList elements, and that m/z values are sorted increasingly with no NA values per spectrum.: "Define a setValidity method that enforces the constraint that the number of rows in the spectraVars data.frame matches the length of the m/z and intensity NumericList elements, and that m/z values"
- [intro] One `Spectra` object is supposed to contain MS (spectral) data of multiple MS spectra. m/z values within each spectrum are expected to be sorted increasingly.: "One `Spectra` object is supposed to contain MS (spectral) data of multiple MS spectra. m/z values within each spectrum are expected to be sorted increasingly."