# Type Safety And Length Matching Validation

> Use when implementing data replacement methods (such as `[<-`, `$<-`, `mz<-`, `intensity<-`, `peaksData<-`) in a writable MsBackend subclass.

- Skill: `holobiomicslab/type-safety-and-length-matching-validation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/type-safety-and-length-matching-validation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/type-safety-and-length-matching-validation/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/type-safety-and-length-matching-validation

---


# Type-safety-and-length-matching-validation

## Summary

Enforce data integrity constraints in writable MS backends by validating that replacement values match expected types (NumericList for m/z and intensity, character for names) and vector lengths (equal to spectrum count or individual spectrum peak counts). This ensures that m/z values remain sorted, peak counts are preserved, and NA values are excluded from critical fields.

## When to use

Apply this skill when implementing data replacement methods (such as `[<-`, `$<-`, `mz<-`, `intensity<-`, `peaksData<-`) in a writable MsBackend subclass. Use it whenever you must modify spectra variables or peak data in place and need to prevent silent data corruption or inconsistency between m/z and intensity vector lengths within a spectrum.

## When NOT to use

- When working with read-only backends (e.g., MsBackendMzR, MsBackendMassbankSql) that do not implement replacement methods.
- When the backend is immutable by design and replacement functionality is not required or supported.
- When input data has already been pre-validated upstream and re-validation would introduce redundant computation without added safety.

## Inputs

- MsBackend subclass instance (writable backend)
- Replacement vector or matrix (NumericList, numeric vector, character vector, or DataFrame)
- Spectrum index or variable name (for selective replacement)
- Expected length (number of spectra or peaks per spectrum)

## Outputs

- MsBackend object with validated and replaced data
- Validation errors or warnings (if constraints violated)
- Updated internal data structure (DataFrame, list of matrices, or equivalent)

## How to apply

Define replacement method signatures using S4 method definitions (`setReplaceMethod`) in the MsBackend subclass. For each replacement operation: (1) validate input length against the number of spectra in the backend using `.match_length()` or equivalent length checking; (2) verify data types before assignment (e.g., confirm m/z and intensity inputs are NumericList objects, names are character vectors); (3) for peak data replacement, check that m/z values are sorted in increasing order using `is.unsorted()` and that intensity vector length equals m/z vector length for each spectrum; (4) enforce that m/z values contain no NA values and that peak-count consistency is maintained across all spectra; (5) apply the validated replacement values to the internal data structure (e.g., DataFrame or list of matrices); (6) test all replacement methods on a concrete backend instance to confirm constraint enforcement.

## Related tools

- **Spectra** (Provides MsBackend virtual class and S4 method definitions for implementing replacement methods with schema validation) — https://github.com/RforMassSpectrometry/Spectra
- **S4Vectors** (Supplies DataFrame and NumericList container classes used to store and validate spectra variables and peak data)
- **R** (Execution environment for S4 method definitions and constraint checking logic (is.unsorted, length matching))

## Examples

```
setReplaceMethod("mz", "MsBackendMemory", function(object, value) { if (!is(value, "NumericList")) stop("mz must be NumericList"); if (length(value) != length(object)) stop("Length mismatch"); if (any(is.na(unlist(value)))) stop("NA values not allowed in mz"); if (any(sapply(value, is.unsorted))) stop("mz values must be sorted"); object@data[["mz"]] <- value; object })
```

## Evaluation signals

- Replacement values are accepted only if their length matches the number of spectra (for spectra variables) or individual spectrum peak counts (for peak data).
- m/z and intensity values are confirmed to be NumericList objects; character data is confirmed to be character vectors; numeric data types match expected schema.
- m/z values within each spectrum are verified to be sorted in increasing order via `is.unsorted()` check; NA values are rejected for m/z fields.
- For peak data replacement, intensity vector length equals m/z vector length for every spectrum; total peak count per spectrum is preserved.
- Replacement operations on concrete backend instances (e.g., MsBackendMemory or MsBackendDataFrame) succeed and produce consistent internal state; failed replacements throw informative errors without partial updates.

## Limitations

- Validation overhead increases with backend size (number of spectra and peaks per spectrum); large backends may see performance impact during bulk replacement operations.
- The skill is specific to writable backends; read-only backends do not implement replacement methods and thus cannot be modified in place.
- Constraint checking (e.g., m/z sorting) is performed only at replacement time; pre-existing data corruption in the underlying data structure will not be detected or corrected unless explicitly accessed.
- Parallel processing of replacement operations is not addressed; concurrent modifications to the same backend instance may violate constraints if synchronization is not handled at a higher level.

## Evidence

- [other] Replacement methods enforce length matching via `.match_length()` to ensure value length equals spectrum count: "length matching via `.match_length()` to ensure value length equals spectrum count"
- [other] Data type validation checking that m/z and intensity are NumericList objects: "data type validation checking that m/z and intensity are NumericList objects"
- [other] m/z ordering validation using `is.unsorted()` to verify m/z values are increasingly sorted within each spectrum: "m/z ordering validation using `is.unsorted()` to verify m/z values are increasingly sorted within each spectrum"
- [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."
- [other] Implement input validation in each replacement method to check that replacement vectors match the length of the backend (number of spectra) or individual spectrum peak counts: "Implement input validation in each replacement method to check that replacement vectors match the length of the backend (number of spectra) or individual spectrum peak counts"