Quantification with calibration standards
2026-08-21
Package
quantMSImageR 0.99.6
1 Introduction
Mass spectrometry imaging measures analyte response at each pixel rather
than analyte amount directly. Using calibration standards, quantMSImageR can
convert this response into an estimated amount per pixel (pg/pixel) and,
when pixel dimensions are known, an estimated real amount (pg/mm²). These
estimates are conditional on the calibration design, internal standard choice
and strategy, matrix matching, acquisition conditions, and validity of the
fitted model.
1.1 On-slide versus on-tissue calibration
On-slide (external) calibration deposits standards on the slide adjacent to
the tissue. This captures instrumental response during the same acquisition but
does not reproduce tissue-specific matrix effects. Use cal_type = "cal".
Figure 1: On-slide calibration
Standards are deposited on the slide beside the section, so they share the acquisition but not the tissue matrix. Amount is read straight off the fitted line, whose intercept is instrument background. Schematic.
On-tissue calibration deposits standards onto tissue, or onto a
representative tissue homogenate. Matrix matching is better, but endogenous
analyte signal and spatial heterogeneity still need careful treatment. Use
cal_type = "std_addition". Standard addition: createCalCurve() fits
response against deposited amount, takes the x-intercept of that line as the endogenous
amount already present in the tissue, shifts every deposited amount by it so the
axis expresses total amount (endogenous + added), drops the background level
and refits. The estimate therefore accounts for analyte the tissue already
contained.
Figure 2: On-tissue calibration by standard addition
Standards are deposited onto the section, so they experience the same matrix as the analyte. The response at zero added amount already contains endogenous analyte, so the line is extrapolated back (dashed) to the x-intercept, and that amount is added to every deposited amount. Schematic.
cal_type has no default: the two modes do materially different things, so it
must be chosen explicitly.
1.2 Scope and assumptions
Amount estimates are only meaningful where the following hold. Each is the user’s responsibility:
- the standard is the same chemical species as the endogenous analyte;
- transitions and acquisition settings match between standards and sample;
- calibration levels expand the response range of the signal actually measured
in tissue (checked by
plotCalCoverage()); - the fitted model is adequate, with acceptable residual behaviour;
- the calibration substrate is a reasonable matrix match for the tissue;
- any internal standard is analogous to the endogenous analyte and is consistently measured throughout the acquisition;
- pixel dimensions are known, for conversion to pg/mm².
2 Installation
if (!requireNamespace("BiocManager", quietly = TRUE))
install.packages("BiocManager")
BiocManager::install("quantMSImageR")3 Calibration workflow overview
When a calibration standards acquisition is available, quantMSImageR fits a
response-versus-amount model per analyte and converts tissue-pixel responses to
pg_pixel and pg_mm2. The workflow is three steps:
summariseCalLevels()– average each calibration level per standard spot,createCalCurve()– fit the response-vs-amount model per analyte,int2conc()– apply those models to convert tissue-pixel responses to estimated amounts,
then plotCalCoverage() to confirm the standards actually bracket the signal
measured in tissue.
Family: calibration.
| Function | Takes | Produces |
|---|---|---|
summariseCalLevels() |
object with Cal pixels + identifier; cal_metadata (identifier, analyte, amount_pg, level) |
fills cal_response_data and the per-level pixel counts |
createCalCurve() |
that object; cal_type = "cal" or "std_addition" |
fills cal_list (one linear model per analyte) and r2_df |
int2conc() |
object carrying cal_list; pixel_header / pixels; experimentData$pixelSize for the mm² layer |
adds pg_pixel and pg_mm2; features without a curve are dropped |
plotCalCoverage() |
a calibrated object (after int2conc()) |
a patchwork figure: pixel histogram above the calibration curve |
This vignette demonstrates the workflow on a small synthetic calibration
dataset bundled with the package. It applies the resulting models to a study
section, and then shows how the same steps are driven from a study YAML
configuration. runExample(calibrate = TRUE) runs the chain end-to-end. The
core imaging workflow that produces the object these operate on – SNR
filtering, ion images, heatmaps – is covered in the
Introduction to quantMSImageR vignette.
The approach is described and applied in Smith et al. (2024); see References.
4 The bundled calibration dataset
The synthetic calibration object (generated by inst/scripts/generate_cal_data.R) is a
quant_MSImagingExperiment whose pixels are labelled Cal (standard spots),
Tissue or Background in sample_type, with a unique identifier per standard
spot. Its analytes are named to match features in the imaging example, so the
fitted curves can be applied to a study section later.
library(quantMSImageR)
library(ggplot2)
cal_dir <- system.file("extdata", "cal_example.raw", package = "quantMSImageR")
cal <- as(readRDS(file.path(cal_dir, "cal_MSI.RDS")),
"quant_MSImagingExperiment")
cal_metadata <- read.csv(file.path(cal_dir, "calibration_metadata.csv"))
pix <- as.data.frame(table(pData(cal)$sample_type))
names(pix) <- c("sample_type", "n_pixels")DT::datatable(pix, rownames = FALSE,
options = list(dom = "t", scrollX = TRUE))Table 1. How the calibration acquisition’s pixels are labelled. Cal are the
standard spots used to build the curves; Tissue and Background are the
surrounding sample and background.
The companion metadata table is the link between a physical standard spot and
what was deposited on it: each identifier maps to an analyte, the
amount spotted (amount_pg) and which dilution level it belongs to.
DT::datatable(cal_metadata, rownames = FALSE,
options = list(pageLength = 10, scrollX = TRUE))Table 2. Calibration metadata: amount of each analyte deposited at every standard spot.
5 Fitting and diagnosing calibration models
summariseCalLevels() averages the signal at each calibration spot, and
createCalCurve() fits a linear response-vs-amount model per analyte (here
cal_type = "cal" for on-slide standards; use "std_addition" for standard
addition on tissue).
cal <- summariseCalLevels(cal, cal_metadata, val_slot = "intensity",
cal_label = "Cal", id = "identifier")
cal <- createCalCurve(cal, cal_type = "cal")Each fit is a straight line, response = slope x (pg/pixel) + intercept, which
int2conc() later inverts to go from response back to amount. The slope is the
analyte’s sensitivity.
cal_list <- calibrationModels(cal)
r2_df <- calibrationDiagnostics(cal)
eqn <- data.frame(
analyte = names(cal_list),
slope = vapply(cal_list, function(m) unname(coef(m)[2]), numeric(1)),
intercept = vapply(cal_list, function(m) unname(coef(m)[1]), numeric(1)),
row.names = NULL
)
eqn$r2 <- r2_df$r2[match(eqn$analyte, r2_df$feature)]DT::datatable(eqn, rownames = FALSE,
options = list(dom = "t", scrollX = TRUE)) |>
DT::formatSignif(c("slope", "intercept", "r2"), digits = 4)Table 3. Fitted calibration model per analyte: the slope, intercept and
R-squared of the line that int2conc() inverts.
Whilst a useful metric R² reports only how much of the variance in the standards the straight line accounts for. Treat a low R² as a definite warning and a high R² as necessary but not sufficient.
Before relying on the estimates, examine at minimum:
- the calibration range, and whether the tissue signal falls inside it
(
plotCalCoverage(), below); - residual patterns against fitted amount;
- precision across calibration replicates;
- the lower and upper quantifiable limits implied by the design;
- whether the fit needs weighting.
createCalCurve()currently applies inverse-amount (1/amount) weighting. This reduces the influence of the highest calibration levels, but its suitability should be assessed from the residual structure of your analytical method.
Plotting those fits gives the calibration curves. The line must come from the stored model:
cal_data <- calibrationLevels(cal)
models <- calibrationModels(cal)
# Predict from each stored model across the amounts it was fitted to.
cal_lines <- lapply(names(models), function(analyte) {
m <- models[[analyte]]
xx <- seq(min(m$model$pg_perpixel), max(m$model$pg_perpixel),
length.out = 100)
data.frame(analyte = analyte,
pg_perpixel = xx,
response_perpixel = predict(m, newdata = data.frame(pg_perpixel = xx)))
})
cal_lines <- do.call(rbind, cal_lines)
ggplot(cal_data, aes(pg_perpixel, response_perpixel)) +
geom_point() +
geom_line(data = cal_lines, colour = "steelblue", linewidth = 0.8) +
facet_wrap(~ analyte, scales = "free") +
labs(x = "amount (pg / pixel)", y = "response per pixel")
Figure 3: Calibration curves
Each point is one standard spot’s summarised response; the line is predicted from the stored, weighted model that int2conc() inverts.
6 Applying the models to a study section
The models are fitted on the standards, then carried across to the study data. Here we load one section of the imaging example (the circular tissue of group A) and attach the fitted models before converting its tissue pixels:
study <- as(readRDS(system.file("extdata", "example.raw", "section01.RDS",
package = "quantMSImageR")),
"quant_MSImagingExperiment")
# carry the fitted curves over, then convert this section's tissue pixels
calibrationData(study) <- calibrationData(cal)
study <- int2conc(study, val_slot = "intensity",
pixel_header = "sample_name", pixels = "tissue_pixels")
analyte <- fData(study)$name[1]
analyte
#> [1] "12-HHTrE"6.1 Checking calibration coverage
Converting a response into an amount estimate is only trustworthy where the
standards constrain the fit. plotCalCoverage() enables this to be
evaluated. The lower panel is the calibration itself – the standard spots (red) and the fitted model (dashed) that
int2conc() inverts. The upper panel is the distribution of the section’s own
pixels on exactly the same x-axis, with the calibration levels marked in red.
When the histogram sits inside the span of the red lines, every converted
pixel is interpolated between real standards.
plotCalCoverage(study, features = analyte, val_slot = "intensity")
Figure 4: Calibration coverage of the measured data
Pixels falling inside the marked range are interpolated between real standards rather than extrapolated.
Called without features it draws one facet per calibrated analyte, which is
the usual way to screen a whole panel at once for standards that do not bracket
the data.
6.2 Handling out-of-range pixels
Either the calibration needs re-acquiring such that tissue pixels are
interpolated (recheck with plotCalCoverage() as above). Or a small % of
extrapolation of extreme pixels is acceptable for your purpose and is set by
max_out_of_range (1 accepts any).
The proportion is recorded per feature, so it can be carried into a report alongside R-squared:
calibrationDiagnostics(study)
#> # A tibble: 3 × 3
#> feature r2 out_of_range
#> <chr> <dbl> <dbl>
#> 1 12-HHTrE 0.999 0
#> 2 12-HOPE 1.000 0
#> 3 9-HOTE 0.999 0Here the synthetic standards span 1.25 to 100 pg/pixel and every tissue pixel
falls inside that, so out_of_range is zero throughout.
The same section can now be imaged either way. First in raw response, where the colour scale is arbitrary instrument signal:
imageR(study, feat_ind = 1, sample_lab = "run", val_slot = "intensity",
scale = "suppress")
Figure 5: Study section in raw intensity
The colour scale is arbitrary instrument response and is not comparable to any other acquisition.
Then the same data in calibrated units, where the colour scale is an estimated amount per unit area:
imageR(study, feat_ind = 1, sample_lab = "run",
val_slot = "pg_mm2", value = "pg/mm2", scale = "suppress")
Figure 6: The same section after int2conc()
The colour scale is now an estimated amount per unit area rather than instrument response, which is interpretable on its own terms and comparable across acquisitions where standards, matrix and acquisition conditions are matched.
7 Driving calibration from a study YAML
In a full study, calibration is enabled through the calibration: block of the
configuration file (system.file("config_template.yaml", package = "quantMSImageR")), positioned just before the ratios: block:
calibration:
enabled: true
cal_acquisition: "cal_run_slide1" # standards .raw acquisition
cal_roi_csv: "cal_ROIs.csv" # pixel -> sample_type = "Cal" + identifier
cal_metadata: "calibration_metadata.csv"
cal_type: "std_addition" # std_addition | cal
val_slot: "intensity"
background_level: "background"
quantify_pixels: ["tissue_pixels"]With enabled: true, the study runner builds the models from the standards
acquisition and writes a <study>_calibrated.RDS alongside the reports. The
rendered report gains a Quantification section carrying the fits, the coverage
plot and calibrated ion images:
runStudy("path/to/study_config.yaml")8 Interpretation and limitations
The values produced here are calibrated amount estimates, not volumetric
concentrations and not traceable reference measurements. Reporting them as
pg/pixel or pg/mm² is a statement about the calibration, not a claim about
the absolute biological content of a voxel.
External or on-slide calibration in particular does not automatically account for:
- tissue-specific ion suppression;
- regional variation in desorption and extraction efficiency;
- differences in section thickness;
- analyte recovery;
- source geometry and day-to-day instrumental changes;
- mismatch between the calibration substrate and the biological tissue.
On-tissue calibration improves matrix matching but does not remove these concerns, and adds the problem of separating added from endogenous analyte.
In practice this means amount estimates are most defensible when used to compare like with like – the same analyte, prepared and acquired the same way, with standards that bracket the observed signal – and progressively weaker as any of those conditions relax. Where a comparison matters, report the calibration diagnostics (range, coverage, R², out-of-range proportion) alongside the values.
9 References
Appendix
Smith MJ, Nie M, Adner M, Säfholm J, Wheelock CE. Development of a Desorption Electrospray Ionization–Multiple-Reaction-Monitoring Mass Spectrometry (DESI-MRM) Workflow for Spatially Mapping Oxylipins in Pulmonary Tissue. Analytical Chemistry (2024). https://doi.org/10.1021/acs.analchem.4c02350
A Session information
sessionInfo()
#> R version 4.6.1 (2026-06-24)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 24.04.4 LTS
#>
#> Matrix products: default
#> BLAS: /home/biocbuild/bbs-3.24-bioc/R/lib/libRblas.so
#> LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.12.0 LAPACK version 3.12.0
#>
#> locale:
#> [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C
#> [3] LC_TIME=en_GB LC_COLLATE=C
#> [5] LC_MONETARY=en_US.UTF-8 LC_MESSAGES=en_US.UTF-8
#> [7] LC_PAPER=en_US.UTF-8 LC_NAME=C
#> [9] LC_ADDRESS=C LC_TELEPHONE=C
#> [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
#>
#> time zone: America/New_York
#> tzcode source: system (glibc)
#>
#> attached base packages:
#> [1] stats4 stats graphics grDevices utils datasets methods
#> [8] base
#>
#> other attached packages:
#> [1] ggplot2_4.0.3 quantMSImageR_0.99.6 Cardinal_3.15.0
#> [4] S4Vectors_0.51.7 ProtGenerics_1.45.0 BiocGenerics_0.59.12
#> [7] generics_0.1.4 BiocParallel_1.47.0 BiocStyle_2.41.0
#>
#> loaded via a namespace (and not attached):
#> [1] tidyselect_1.2.1 viridisLite_0.4.3 dplyr_1.2.1
#> [4] farver_2.1.2 viridis_0.6.5 S7_0.2.2
#> [7] fastmap_1.2.0 digest_0.6.39 lifecycle_1.0.5
#> [10] cluster_2.1.8.3 Cairo_1.7-0 magrittr_2.0.5
#> [13] compiler_4.6.1 rlang_1.3.0 sass_0.4.10
#> [16] tools_4.6.1 utf8_1.2.6 yaml_2.3.12
#> [19] knitr_1.51 labeling_0.4.3 htmlwidgets_1.6.4
#> [22] ontologyIndex_2.12 RColorBrewer_1.1-3 withr_3.0.3
#> [25] purrr_1.2.2 grid_4.6.1 chemCal_0.2.3
#> [28] colorspace_2.1-3 scales_1.4.0 iterators_1.0.14
#> [31] dichromat_2.0-1 tinytex_0.60 cli_3.6.6
#> [34] rmarkdown_2.31 crayon_1.5.3 otel_0.2.0
#> [37] matter_2.15.0 rjson_0.2.23 cachem_1.1.0
#> [40] parallel_4.6.1 BiocManager_1.30.27 matrixStats_1.5.0
#> [43] vctrs_0.7.3 Matrix_1.7-6 jsonlite_2.0.0
#> [46] bookdown_0.47 CardinalIO_1.11.0 IRanges_2.47.2
#> [49] GetoptLong_1.1.1 patchwork_1.3.2 irlba_2.3.7
#> [52] clue_0.3-68 magick_2.9.1 crosstalk_1.2.2
#> [55] foreach_1.5.2 tidyr_1.3.2 jquerylib_0.1.4
#> [58] glue_1.8.1 codetools_0.2-20 DT_0.34.0
#> [61] shape_1.4.6.1 gtable_0.3.6 ComplexHeatmap_2.29.0
#> [64] tibble_3.3.1 pillar_1.11.1 htmltools_0.5.9
#> [67] circlize_0.4.18 R6_2.6.1 doParallel_1.0.17
#> [70] evaluate_1.0.5 lattice_0.23-1 Biobase_2.73.2
#> [73] png_0.1-9 bslib_0.12.0 Rcpp_1.1.2
#> [76] gridExtra_2.3.1 nlme_3.1-170 xfun_0.60
#> [79] pkgconfig_2.0.3 GlobalOptions_0.1.4