Package {ValCurvaR}

Type: Package
Title: Validation of Analytical Calibration Curves
Version: 0.1.0
Description: Provides transparent tools for fitting and evaluating analytical calibration curves. Ordinary and weighted least squares fits are supported, together with lack-of-fit, heteroscedasticity and influence diagnostics, back-calculation, prediction uncertainty and publication-ready base graphics. The workflow is designed to support validation studies rather than rely on a single goodness-of-fit statistic. Methods follow Magnusson and Ornemark (2014) https://www.eurachem.org/images/stories/Guides/pdf/MV_guide_2nd_ed_EN.pdf and International Council for Harmonisation (2023) https://database.ich.org/sites/default/files/ICH_Q2%28R2%29_Guideline_2023_1130_ErrorCorrection_2025.pdf.
License: MIT + file LICENSE
URL: https://github.com/isaquebrand/ValCurvaR
BugReports: https://github.com/isaquebrand/ValCurvaR/issues
Encoding: UTF-8
Imports: graphics, grDevices, lmtest, nortest, outliers, stats
Suggests: knitr, rmarkdown, testthat (≥ 3.0.0)
VignetteBuilder: knitr
Config/testthat/edition: 3
Config/roxygen2/version: 8.0.0
NeedsCompilation: no
Packaged: 2026-09-11 11:43:01 UTC; isaqu
Author: Isaque Wilkson de Sousa Brandão [aut, cre]
Maintainer: Isaque Wilkson de Sousa Brandão <isaquebrand@gmail.com>
Repository: CRAN
Date/Publication: 2026-09-21 21:20:02 UTC

Fit an analytical calibration curve

Description

Fit an analytical calibration curve

Usage

ajustar_curva(
  dados,
  metodo = c("auto", "ols", "wls"),
  pesos = c("variancia_nivel", "1/x", "1/x2", "1/y", "1/y2")
)

Arguments

dados

Validated data from validar_curva() or a data frame with internal .x and .y columns.

metodo

One of "auto", "ols" or "wls".

pesos

WLS strategy. "variancia_nivel" uses the inverse experimental variance at each concentration; other choices are empirical alternatives.

Value

A valcurva_fit object.

Evaluate the impact of suspicious observations without deleting them

Description

Fits leave-one-out models solely for technical review. It never changes the original data or approves exclusion of a measurement.

Usage

analisar_sensibilidade(ajuste, observacoes = NULL)

Arguments

ajuste

A valcurva_fit object.

observacoes

Optional row numbers. By default, all observations flagged by Cook's distance, leverage, DFFITS, DFBETAS or studentized residuals are used.

Value

A data frame comparing each leave-one-out model with the original fit.

Evaluate calibration-curve adequacy against explicit criteria

Description

No universal acceptance limits are imposed. Supply only the limits applicable to the analytical procedure, matrix, and intended range. A missing criterion is reported as not assessed rather than silently approved.

Usage

avaliar_adequacao(ajuste, criterios = list())

Arguments

ajuste

A valcurva_fit object.

criterios

A named list. Supported names are p_falta_ajuste_min, p_mandel_min, cv_max_percentual, and erro_relativo_retrocalculo_max_percentual.

Value

An object of class valcurva_adequacao with a criterion table, back-calculation table, and conclusion.

Compare OLS and WLS calibration models

Description

Compare OLS and WLS calibration models

Usage

comparar_modelos(ols, wls)

Arguments

ols

An OLS valcurva_fit object.

wls

A WLS valcurva_fit object.

Value

A data frame intended as decision support, not an automatic approval.

Eurachem A5.2 calibration data

Description

Fifteen individual absorbance measurements at five cadmium calibration levels. Values are transcribed from Table A5.2 of the Eurachem/CITAC uncertainty guide and are supplied in long format to preserve replicates.

Usage

dados_eurachem_a52()

Value

A data frame with concentracao_mg_L, replica, and absorbancia.

Examples

dados <- dados_eurachem_a52()
curva <- validar_curva(dados, concentracao_mg_L, absorbancia, replica)
ajuste <- ajustar_curva(curva, metodo = "ols")
grafico_calibracao(ajuste)

Calculate calibration-curve diagnostics

Description

Calculate calibration-curve diagnostics

Usage

diagnosticar_curva(ajuste)

Arguments

ajuste

An object returned by ajustar_curva().

Value

A named list of diagnostic results.

Generate a complete calibration-validation report in PDF

Description

Generate a complete calibration-validation report in PDF

Usage

gerar_relatorio_pdf(
  ajuste,
  arquivo = file.path(tempdir(), "relatorio-calibracao.pdf"),
  titulo = "Relatorio de validacao da curva de calibracao",
  criterios = list(),
  quiet = TRUE
)

Arguments

ajuste

A valcurva_fit object.

arquivo

Output PDF path. By default, a temporary file is used so the function does not write to the user's working directory.

titulo

Title shown in the report.

criterios

Optional acceptance criteria forwarded to avaliar_adequacao().

quiet

Logical; suppress R Markdown progress messages.

Value

Invisibly, the normalized path to the generated PDF.

Plot an analytical calibration diagram

Description

Draws individual data, centroids, fitted line and 95% prediction limits in the visual language of the metrology article supplied for this project.

Usage

grafico_calibracao(ajuste, nivel = 0.95, ...)

Arguments

ajuste

A valcurva_fit object.

nivel

Confidence level for prediction limits.

...

Graphical parameters passed to graphics::plot().

Value

Invisibly, a data frame used to draw the prediction curves.

Plot inverse prediction uncertainty over the calibration range

Description

Plot inverse prediction uncertainty over the calibration range

Usage

grafico_incerteza_predicao(ajuste, k = c(1, 2, 3, 4, 9, 16))

Arguments

ajuste

A valcurva_fit object.

k

Numeric vector of numbers of replicate measurements.

Value

Invisibly, plotted uncertainty data.

Plot Cook's distance and leverage against their screening limits

Description

Plot Cook's distance and leverage against their screening limits

Usage

grafico_influencia(ajuste)

Arguments

ajuste

A valcurva_fit object.

Value

Invisibly, the influence diagnostics.

Plot a normal Q-Q graph with a simulation envelope for residuals

Description

Plot a normal Q-Q graph with a simulation envelope for residuals

Usage

grafico_qq(ajuste, nivel = 0.95, simulacoes = 999L, semente = NULL)

Arguments

ajuste

A valcurva_fit object.

nivel

Envelope coverage level.

simulacoes

Number of normal samples used to build the envelope.

semente

Optional seed for a reproducible envelope.

Value

Invisibly, data used to construct the graph.

Plot standardized residuals against concentration

Description

Plot standardized residuals against concentration

Usage

grafico_residuos(ajuste)

Arguments

ajuste

A valcurva_fit object.

Value

Invisibly, residual diagnostic data.

Plot instrumental-response variability by concentration

Description

Plot instrumental-response variability by concentration

Usage

grafico_variancia(ajuste)

Arguments

ajuste

A valcurva_fit object.

Value

Invisibly, the level summary.

Create the four-panel calibration figure

Description

Create the four-panel calibration figure

Usage

painel_calibracao(ajuste, k = c(1, 2, 3, 4, 9, 16))

Arguments

ajuste

A valcurva_fit object.

k

Replicate counts for the uncertainty panel.

Value

Invisibly, ajuste.

Build an auditable calibration summary

Description

Build an auditable calibration summary

Usage

relatorio_auditoria(ajuste, criterios = list())

Arguments

ajuste

A valcurva_fit object.

criterios

Optional criteria forwarded to avaliar_adequacao().

Value

A named list with model, diagnostics, adequacy assessment, and data.

Back-calculate concentration with GUM uncertainty propagation

Description

The measurement model is x = (y - a) / b. The covariance of the fitted intercept (a) and slope (b) is retained explicitly in the combined uncertainty. It must not be discarded or treated as two independent inputs.

Usage

retrocalcular_concentracao(
  ajuste,
  sinal,
  k = 1L,
  u_sinal = NULL,
  nivel = 0.95,
  fator_cobertura = NULL
)

Arguments

ajuste

A valcurva_fit object.

sinal

Numeric vector of instrumental responses.

k

Number of replicate signals averaged for each result.

u_sinal

Standard uncertainty of each reported signal. If NULL, the residual standard deviation of the fit divided by sqrt(k) is used as a data-derived estimate.

nivel

Confidence level.

fator_cobertura

Optional coverage factor. If NULL, a two-sided Student t factor using the regression degrees of freedom is used. This keeps the correlated regression coefficients as one uncertainty block.

Value

A data frame with concentration, combined and expanded GUM uncertainty, and the individual variance contributions.

Validate analytical calibration data

Description

Keeps the original measurements in long format. A horizontal table is also accepted: omit sinal and every numeric column other than concentracao is converted internally to a replicate column. Replicates must not be averaged before validation because they are needed for variance and lack-of-fit diagnostics.

Usage

validar_curva(dados, concentracao, sinal = NULL, replica = NULL)

Arguments

dados

A data frame.

concentracao

Concentration column, supplied bare or as a string.

sinal

Instrumental response column, supplied bare or as a string. Omit it for horizontal data with one numeric response column per replicate.

replica

Optional replicate identifier column.

Value

A data.frame with standard internal columns .x, .y and .replica.