| Title: | Continuous Norming |
| Version: | 1.0.0 |
| Description: | A toolbox for continuous norming of psychological and educational tests, supporting regression-based norming where norms can vary as a continuous function of age or another norm predictor. Norms are estimated using Generalized Additive Models for Location, Scale, and Shape (GAMLSS), enabling flexible modelling of the full score distribution in a normative sample. The package supports applications in psychometrics and psychological testing, and includes functions for model selection, reliability estimation, and norm calculation, including confidence intervals, and normed score precision evaluation and visualization. For more details, see Timmerman et al. (2021) <doi:10.1037/met0000348>. |
| License: | GPL (≥ 3) |
| Encoding: | UTF-8 |
| Depends: | R (≥ 3.5.0) |
| Imports: | dplyr, foreach, gamlss, gamlss.dist, ggplot2, openxlsx2, rlang, Rdpack, stats, utils, withr, scales, lpSolve, doParallel |
| RdMacros: | Rdpack |
| Suggests: | gamlss.tr, knitr, rmarkdown, testthat (≥ 3.0.0) |
| Config/testthat/edition: | 3 |
| VignetteBuilder: | knitr |
| Config/roxygen2/version: | 8.1.1 |
| NeedsCompilation: | no |
| Packaged: | 2026-11-20 09:19:48 UTC; jinpi |
| Author: | Klazien de Vries |
| Maintainer: | Marieke Timmerman <m.e.timmerman@rug.nl> |
| Repository: | CRAN |
| Date/Publication: | 2026-11-20 14:30:29 UTC |
Plot bootstrap standard errors across continuous predictor with reference thresholds
Description
Visualizes bootstrap-based standard errors (SE) across a continuous predictor (e.g., age, grade) for selected centiles, and compares them to reference standard errors derived under a traditional norming framework.
Usage
boot_centiles(
boot,
centiles = c(5, 25, 50, 75, 95),
age_range = NULL,
benchmark_n = c(200, 300, 400),
interpolate = TRUE
)
Arguments
boot |
Object of class |
centiles |
Numeric vector of centiles (0–100 scale) to evaluate (e.g., |
age_range |
Optional numeric vector of length 2 specifying the range of the independent variable to include. |
benchmark_n |
Numeric vector of sample sizes used to compute benchmark standard errors. |
interpolate |
Logical. If |
Value
A ggplot2 object.
See Also
boot_subtest(), boot_heatmap()
Examples
# 1. Prepare example data from normref
invisible(data("ids_data", package = "normref"))
mydata.BB <- shape_data(
ids_data,
age_name = "age",
score_name = "y7",
family = "BB")
# 2. Fit a GAMLSS model
mod <- fb_select(
data = mydata.BB,
age_name = "age",
score_name = "shaped_score",
family = "BB",
selcrit = "BIC")
# 3. Run nonparametric bootstrap on subtest norms
boot_res <- boot_subtest(
model = mod,
age_name = "age",
normtype = "IQ",
boot_type = "nonparametric",
B = 10, # 1000
min_age = 5,
max_age = 20,
seed = 42,
parallel = FALSE # TRUE
)
# 4. Standard error along centile trajectories
boot_centiles(boot_res, centiles = c(5, 50, 95), benchmark_n = c(200, 400))
Bootstrap uncertainty for composite norm tables
Description
Computes bootstrap estimates, standard errors (SE), Monte Carlo standard errors of the SE, and percentile confidence intervals for composite norm tables and sample observations derived from multiple subtests.
Usage
boot_composite(
subtest_models,
composite_model,
age_name = "age",
composite_score_name = NULL,
subtest_score_names = NULL,
normtype = "Z",
weights = NULL,
min_age = NULL,
max_age = NULL,
step_size_age = NULL,
min_score = NULL,
max_score = NULL,
step_size_score = 1,
cont_cor = TRUE,
ci_level = 0.95,
B = 500,
reselect = FALSE,
seed = NULL,
parallel = FALSE,
ncores = NULL,
trim = 3,
keep_boot = FALSE,
fb_control = NULL
)
Arguments
subtest_models |
Named list of fitted |
composite_model |
Fitted |
age_name |
Character. Name of the continuous independent variable (e.g. |
composite_score_name |
Optional character. Label for the composite score variable in output tables.
If |
subtest_score_names |
Optional named list or character vector of labels for each subtest score.
Defaults to |
normtype |
Character. Norm score type: |
weights |
Optional numeric weights for the subtests. |
min_age, max_age |
Numeric. Bounds for the independent variable grid. |
step_size_age |
Numeric. Increment for the continuous variable grid. |
min_score, max_score |
Numeric. Score grid bounds for composite score. |
step_size_score |
Numeric. Increment for composite score grid. |
cont_cor |
Logical. Apply continuity correction to subtests. |
ci_level |
Numeric. Nominal confidence level for bias-corrected percentile CIs (default 0.95). |
B |
Integer. Number of bootstrap replicates (default 500). |
reselect |
Logical or named list controlling model reselection per subtest / composite. |
seed |
Optional integer seed for reproducibility. |
parallel |
Logical. If |
ncores |
Integer. Number of worker cores when |
trim |
Numeric or named list. Truncation threshold for extreme scores (in Z units).
If numeric (default |
keep_boot |
Logical. Whether to retain raw bootstrap replicate matrices. |
fb_control |
Named list of control arguments for |
Details
boot_composite() operates directly on complete observations across all subtests.
Fitting data and response variables are extracted directly from the model data
and model$mu.formula of each subtest model in subtest_models and composite_model.
Important: All subtest models in subtest_models must have been
fitted on the exact same sample of complete observations with identical row counts
and row ordering in their model data.
Value
An object of class "normref_bootstrap" containing:
- normtable
Tidy data.frame of normtable-level bootstrap statistics.
- sample
Data.frame of observation-level bootstrap statistics with all subtest and composite scores.
- mcse_normtable
Monte Carlo standard error metrics for the norm table.
- mcse_sample
Monte Carlo standard error metrics for the sample.
- B, trueB
Requested and successfully converged replicate counts.
- model_freq_table
Model selection frequencies across replicates.
- model_selection_history
Model selection history per subtest and composite.
- meta
Metadata including weights, correlation matrix, models, data, and normtype.
- grid
Evaluation grid for the continuous variable and composite scores.
- boot
Optional raw bootstrap results (if
keep_boot = TRUE).
See Also
boot_subtest(), boot_heatmap(), boot_centiles(), boot_sample()
Examples
# 1. Prepare example data from normref
invisible(data("ids_data", package = "normref"))
# 2. Fit subtest models
mydata1 <- shape_data(ids_data, age_name = "age", score_name = "y7", family = "BB")
mod1 <- fb_select(mydata1, age_name = "age", score_name = "shaped_score", family = "BB")
mydata2 <- shape_data(ids_data, age_name = "age", score_name = "y14", family = "NO")
mod2 <- fb_select(mydata2, age_name = "age", score_name = "shaped_score", family = "NO")
normtable1 <- normtable_create(mod1, mydata1, age_name = "age", score_name = "shaped_score",
trim = Inf)
normtable2 <- normtable_create(mod2, mydata2, age_name = "age", score_name = "shaped_score",
trim = Inf)
# 3. Construct composite score
comp_data <- composite_shape(list(y7 = normtable1, y14 = normtable2))
comp_model <- fb_select(comp_data, age_name = "age", score_name = "z_sum", family = "NO")
# 4. Bootstrap composite score precision
boot_comp <- boot_composite(
subtest_models = list(y7 = mod1, y14 = mod2),
composite_model = comp_model,
age_name = "age",
composite_score_name = "z_sum",
step_size_score = 0.1,
B = 10, # 1000
seed = 42,
parallel = FALSE #TRUE
)
head(boot_comp$sample)
# Observed sample-level standard error ratios by score bin
boot_sample(
boot_comp,
type = "ratio",
benchmark_n = 300,
z_bins = seq(-3, 3, by = 1)
)
Plot heatmap of bootstrap norm table uncertainty
Description
Visualizes bootstrap-based uncertainty from normtables as a heatmap over the independent variable and score. Regions trimmed or set to NA appear blank.
Usage
boot_heatmap(
boot,
type = "se",
benchmark_n = NULL,
centiles = NULL,
add_points = FALSE,
point_style = "hollow",
add_contour = FALSE,
age_range = NULL,
score_range = NULL,
limits = NULL,
centile_label_nudge = 0.5,
print_pct = FALSE
)
Arguments
boot |
Object of class |
type |
Character. Either
|
benchmark_n |
Numeric. Reference sample size used to compute benchmark standard errors (required when |
centiles |
Optional numeric vector of centiles (0–100 scale) to overlay. |
add_points |
Logical. If |
point_style |
Character. Style for points: |
add_contour |
Logical. If |
age_range |
Numeric vector of length 2 specifying bounds for the continuous variable. |
score_range |
Numeric vector of length 2 specifying score limits for plotting. |
limits |
Optional numeric vector of length 2 for color scale limits. |
centile_label_nudge |
Numeric. Horizontal offset for centile labels. |
print_pct |
Logical. If |
Value
A ggplot2 object.
See Also
boot_subtest(), boot_centiles()
Examples
# 1. Prepare example data from normref
invisible(data("ids_data", package = "normref"))
mydata.BB <- shape_data(
ids_data,
age_name = "age",
score_name = "y7",
family = "BB")
# 2. Fit a GAMLSS model
mod <- fb_select(
data = mydata.BB,
age_name = "age",
score_name = "shaped_score",
family = "BB",
selcrit = "BIC")
# 3. Run nonparametric bootstrap on subtest norms
boot_res <- boot_subtest(
model = mod,
age_name = "age",
normtype = "IQ",
boot_type = "nonparametric",
B = 10, #1000
min_age = 5,
max_age = 20,
seed = 42,
parallel = FALSE # TRUE
)
# 4. Standard error heatmap across age and score
boot_heatmap(
boot_res,
type = "se",
add_points = TRUE,
centiles = c(1, 5, 25, 50, 75, 95, 99),
centile_label_nudge = 2.0
)
# 5. Benchmark difference heatmap against discrete norming (N = 300 per group)
boot_heatmap(
boot_res,
type = "difference",
benchmark_n = 300,
add_points = TRUE,
add_contour = TRUE,
centiles = c(5,25,50,75,95)
)
Plot sample-level bootstrap precision across age, faceted by score bins
Description
Visualizes person-level bootstrap standard errors, differences, or relative ratios against a continuous predictor (such as age), faceted into standard-score bins (e.g., z-score bins from -3 to +3). Individual points represent observed sample cases.
Usage
boot_sample(
boot,
benchmark_n = 300,
type = c("ratio", "difference", "se"),
z_bins = seq(-3, 3, by = 1),
age_range = NULL,
smooth = FALSE,
point_alpha = 0.5
)
Arguments
boot |
Object of class |
benchmark_n |
Numeric. Reference sample size used to compute benchmark standard errors (default = 300). |
type |
Character. One of
|
z_bins |
Numeric vector specifying bin edges on the |
age_range |
Optional numeric vector of length 2 specifying bounds for the continuous age variable. |
smooth |
Logical. If |
point_alpha |
Numeric. Alpha transparency for individual points (default = 0.5). |
Value
A ggplot2 object.
See Also
boot_centiles(), boot_heatmap(), boot_composite()
Examples
# 1. Prepare example data from normref
invisible(data("ids_data", package = "normref"))
# 2. Fit subtest models
mydata1 <- shape_data(ids_data, age_name = "age", score_name = "y7", family = "BB")
mod1 <- fb_select(mydata1, age_name = "age", score_name = "shaped_score", family = "BB")
mydata2 <- shape_data(ids_data, age_name = "age", score_name = "y14", family = "NO")
mod2 <- fb_select(mydata2, age_name = "age", score_name = "shaped_score", family = "NO")
# 3. Construct composite score
normtable1 <- normtable_create(mod1, mydata1, age_name = "age", score_name = "shaped_score",
trim = Inf)
normtable2 <- normtable_create(mod2, mydata2, age_name = "age", score_name = "shaped_score",
trim = Inf)
comp_data <- composite_shape(list(y7 = normtable1, y14 = normtable2))
comp_model <- fb_select(comp_data, age_name = "age", score_name = "z_sum", family = "NO")
# 4. Bootstrap composite score precision
boot_comp <- boot_composite(
subtest_models = list(y7 = mod1, y14 = mod2),
composite_model = comp_model,
age_name = "age",
composite_score_name = "z_sum",
step_size_score = 0.1,
B = 10, # 1000
seed = 42,
parallel = FALSE #TRUE
)
head(boot_comp$sample)
# 5. Observed sample-level standard error ratios by score bin
boot_sample(
boot_comp,
type = "ratio",
benchmark_n = 400,
z_bins = seq(-3, 3, by = 1)
)
Bootstrap uncertainty for single GAMLSS norm tables
Description
Computes bootstrap estimates, standard errors (SE), Monte Carlo standard
errors of the SE, and percentile confidence intervals for continuous norm
tables and sample observations fitted with gamlss. Supports both
nonparametric resampling and parametric simulation for sample size planning.
Usage
boot_subtest(
model,
age_name = "age",
score_name = NULL,
boot_type = c("nonparametric", "parametric"),
n_sim = NULL,
age_sampling_frame = NULL,
normtype = "Z",
min_age = NULL,
max_age = NULL,
min_score = NULL,
max_score = NULL,
step_size_score = 1,
step_size_age = NULL,
cont_cor = TRUE,
ci_level = 0.95,
B = 500,
seed = NULL,
parallel = FALSE,
ncores = NULL,
trim = 3,
keep_boot = FALSE,
reselect = FALSE,
fb_control = list()
)
Arguments
model |
A fitted |
age_name |
Character. Column name of the continuous independent variable
(e.g., |
score_name |
Optional character. Label for the score variable in output tables
and plots. If |
boot_type |
Character. Either |
n_sim |
Optional integer. Total sample size to simulate when |
age_sampling_frame |
Optional function or numeric vector defining the continuous age distribution
when |
normtype |
Character. One of |
min_age, max_age |
Numeric. Grid bounds for the continuous independent variable. Defaults to the observed range in model data. |
min_score, max_score |
Numeric. Grid bounds for the score variable. Defaults to the observed range. |
step_size_score |
Numeric. Increment for the score grid (default 1). |
step_size_age |
Numeric. Increment for the independent variable grid. Defaults to approximately 100 points. |
cont_cor |
Logical. Whether to apply continuity correction for discrete families. |
ci_level |
Numeric. Nominal confidence level for bias-corrected percentile CIs (default 0.95). |
B |
Integer. Number of bootstrap replicates (default 500). |
seed |
Optional integer seed for reproducibility. |
parallel |
Logical. If |
ncores |
Integer. Number of worker cores when |
trim |
Numeric. Truncation threshold for extreme scores in Z scale (default 3). |
keep_boot |
Logical. Whether to retain raw bootstrap replications. |
reselect |
Logical. Whether to re-select polynomial degrees per replicate. |
fb_control |
Named list of options passed to |
Value
An object of class "normref_bootstrap" containing:
- normtable
Tidy data.frame of normtable-level bootstrap statistics.
- sample
Data.frame of observation-level bootstrap statistics with all subtest scores.
- mcse_normtable
Monte Carlo standard error metrics for the norm table.
- mcse_sample
Monte Carlo standard error metrics for the sample.
- B, trueB
Requested and successfully converged replicate counts.
- model_freq_table
Model selection frequencies across replicates.
- model_selection_history
Model selection history (if
reselect = TRUE).- meta
Metadata including models, data, and normtype.
- grid
Evaluation grid for the continuous variable and composite scores.
- boot
Optional raw bootstrap results (if
keep_boot = TRUE).
See Also
boot_composite(), boot_heatmap(), boot_centiles()
Examples
# # 1. Prepare example data from normref
invisible(data("ids_data", package = "normref"))
mydata.BB <- shape_data(
ids_data,
age_name = "age",
score_name = "y7",
family = "BB")
# 2. Fit a GAMLSS model
mod <- fb_select(
data = mydata.BB,
age_name = "age",
score_name = "shaped_score",
family = "BB",
selcrit = "BIC")
# 2. Alternatively, fit a spline model:
# library(gamlss)
# mod <- gamlss(shaped_score ~ pb(age), family = "BB", data = mydata.BB, trace = FALSE)
# 3. Run nonparametric bootstrap on subtest norms
boot_res <- boot_subtest(
model = mod,
age_name = "age",
normtype = "IQ",
boot_type = "nonparametric",
B = 10, # 1000
min_age = 5,
max_age = 20,
seed = 42,
parallel = FALSE #TRUE
)
head(boot_res$normtable[1050:1055,]) # inspect results
# 4. Parametric bootstrap for sample size planning (e.g., N = 300)
frame_uniform <- function(n) {runif(n, min = 5, max = 20)} # define sampling frame
boot_plan <- boot_subtest(
model = mod,
age_name = "age",
score_name = "y7",
boot_type = "parametric",
n_sim = 300,
age_sampling_frame = frame_uniform,
normtype = "Z",
min_age = 5,
max_age = 20,
B = 10, # 1000,
parallel = FALSE, #TRUE,
seed = 123
)
boot_centiles(
boot_plan,
centiles = c(5,50,95)
)
Plot centiles of a fitted GAMLSS model (binomial-type)
Description
centiles_bin() plots centile curves and the sample data for
binomial-type distributions (see gamlss::.gamlss.bi.list) based on a
fitted GAMLSS object.
Usage
centiles_bin(
model,
xvar,
cent = c(0.4, 2, 10, 25, 50, 75, 90, 98, 99.6),
legend = TRUE,
ylab = "y",
xlab = "x",
main = NULL,
main.gsub = "@",
xleg = min(xvar),
yleg = max(model$y),
xlim = range(xvar),
ylim = range(model$y),
save = FALSE,
plot = TRUE,
points = TRUE,
pch = 15,
cex = 0.5,
col = "grey",
col.centiles = seq_along(cent) + 2,
lty.centiles = 1,
lwd.centiles = 1,
colors = "rainbow",
...
)
Arguments
model |
a GAMLSS fitted model, for example the result of |
xvar |
the unique explanatory variable |
cent |
a vector with elements the % centile values for which the centile curves have to be evaluated |
legend |
whether a legend is required in the plot or not, the default is |
ylab |
the y-variable label |
xlab |
the x-variable label |
main |
the main title here as character. If NULL the default title "centile curves using NO" (or the relevant distributions name) is shown |
main.gsub |
if the |
xleg |
position of the legend in the x-axis |
yleg |
position of the legend in the y-axis |
xlim |
the limits of the x-axis |
ylim |
the limits of the y-axis |
save |
whether to save the sample percentages or not with default equal to |
plot |
whether to plot the centiles. This option is useful for |
points |
whether the data points should be plotted, default is |
pch |
the character to be used as the default in plotting points see |
cex |
size of character see |
col |
plotting colour see |
col.centiles |
Plotting colours for the centile curves |
lty.centiles |
line type for the centile curves |
lwd.centiles |
The line width for the centile curves |
colors |
the different colour schemes to be used for the fan-chart. The following are available
|
... |
for extra arguments |
Value
No return value, only graphical output.
See Also
Examples
data("ids_data")
mydata_BB_y14 <- shape_data(
data = ids_data,
age_name = "age",
score_name = "y14",
family = "BB"
)
mod_BB_y14 <- fb_select(
data = mydata_BB_y14,
age_name = "age",
score_name = "shaped_score",
family = "BB",
selcrit = "BIC"
)
centiles_bin(mod_BB_y14, xvar = age)
Shape data for a composite scale based on normalized Z-scores
Description
composite_shape() creates a data.frame with age values and a weighted sum of normalized
z-scores from multiple NormTable objects, suitable for use as input to fb_select().
Usage
composite_shape(normtables, weights = NULL)
Arguments
normtables |
list of NormTable objects created by |
weights |
Optional numeric vector of weights for a weighted composite score.
If |
Details
The function combines normalized z-scores across multiple norm tables into a composite score. By default, scores are equally weighted. Optional weights allow differential contribution of subtests to the composite.
Value
A data.frame with:
age |
Age values from the first NormTable |
z_sum |
Weighted sum of normalized z-scores across all objects |
See Also
shape_data(), fb_select(), normtable_create()
Examples
invisible(data("ids_data"))
# Example with two normtables
mydata1 <- shape_data(ids_data, age_name = "age", score_name = "y7", family = "BCPE")
mod1 <- fb_select(mydata1, age_name = "age", score_name = "shaped_score",
family = "BCPE", selcrit = "BIC")
norm1 <- normtable_create(mod1, mydata1, age_name = "age", score_name = "shaped_score")
mydata2 <- shape_data(ids_data, age_name = "age", score_name = "y14", family = "BCPE")
mod2 <- fb_select(mydata2, age_name = "age", score_name = "shaped_score",
family = "BCPE", selcrit = "BIC")
norm2 <- normtable_create(mod2, mydata2, age_name = "age", score_name = "shaped_score")
composite_data <- composite_shape(list(norm1, norm2))
cotapp data
Description
The data are perturbed variants of the scores on
the raw speed of block 1 (rt) and
the raw number of errors of block 7 (error)
of the normative sample of the cotapp test (Rommelse et al., 2018).
More information on the cotapp test: https://www.boom.nl/productgroep/101-45_COTAPP
Usage
data(cotapp_data)
Format
A dataframe with three columns:
ageage in years
rtreaction time: scores on the raw speed of block 1
errornumber of errors of block 7
References
Rommelse N, Brinkman A, Slaats-Willemse D, Timmerman ME, Voncken L, de Zeeuw P, Luman M, Hartman C (2020). “De Cognitieve Test Applicatie (COTAPP): geavanceerde computertest voor het meten van aandacht, informatieverwerking en executieve functies bij kinderen.” Kind en Adolescent, 41, 50–80.
Estimate reliability across multiple window widths and age steps
Description
Estimates reliability curves across various combinations of window widths and age step sizes, with optional per-individual estimation.
Usage
different_rel(
data,
item_variables,
age_name,
step_window,
min_agegroup = NULL,
max_agegroup = NULL,
step_agegroup,
include_window_per_person = FALSE,
complete.obs = TRUE
)
Arguments
data |
data.frame containing item scores and age variable. |
item_variables |
character vector. Names of the columns with item scores. |
age_name |
string. Name of the age variable. Default is |
step_window |
numeric vector. Window widths to evaluate. |
min_agegroup |
numeric. Minimum age to include. Defaults to the floor of the minimum age in the data. |
max_agegroup |
numeric. Maximum age to include. Defaults to the ceiling of the maximum age in the data. |
step_agegroup |
numeric vector. Step sizes between evaluated age points. |
include_window_per_person |
logical. If |
complete.obs |
logical. If |
Value
An object of class Drel (a data.frame) with:
-
rel: Reliability estimates -
age: Corresponding evaluated ages -
window_width: Width of the window used -
age_group_width: Step size between evaluated age groups -
version: Type of estimation ("step"or"window_per_person")
See Also
Examples
invisible(data("ids_kn_data"))
rel_int <- different_rel(
data = ids_kn_data,
item_variables = colnames(ids_kn_data),
age_name = "age_years",
step_window = c(0.5, 1, 2, 5, 10, 20),
min_agegroup = 5,
max_agegroup = 20,
step_agegroup = c(0.5, 1, 1.5, 2)
)
Free order model selection procedure
Description
fb_select() applies the free order model selection procedure, using forward–backward selection
(Voncken et al. 2019).
For a given GAMLSS distribution and model selection criterion, it selects the optimal
polynomial degrees for all distribution parameters.
Usage
fb_select(
data,
age_name,
score_name,
family,
selcrit = "BIC",
spline = FALSE,
method = "RS(10000)",
max_poly = c(5, 5, 2, 2),
min_poly = c(0, 0, 0, 0),
start_poly = c(2, 1, 0, 0),
start.from = NULL,
trace = TRUE,
seed = 123
)
Arguments
data |
data.frame. Sample on which to fit the distribution; contains the scores and ages. |
age_name |
string. Name of the age variable. |
score_name |
string. Name of the score variable. |
family |
string. For example, |
selcrit |
string. Model selection criterion: |
spline |
logical. If |
method |
string. Estimation method for |
max_poly |
vector. Maximum polynomial degrees for each parameter. |
min_poly |
vector. Minimum polynomial degrees for each parameter. |
start_poly |
vector. Starting polynomial degrees for each parameter. |
start.from |
gamlss object (optional). A pre-fitted GAMLSS model to serve as the
initial warm start for fitting the starting model ( |
trace |
logical. If |
seed |
integer. Random seed for cross-validation folds. |
Details
The search history of the free order model selection procedure can be accessed in search_history. This allows the user to investigate whether a more parsimonious model with similar model fit to the selected model exists.
Value
A selected GAMLSS model with the chosen polynomial degrees. This is a gamlss object with additional components
-
selcrit: the value of the selection criterion for the chosen model. -
search_history: search history, containing the polynomial degrees for examined models (poly_deg) and their selection criteria (selcrit).
References
Voncken L, Albers CJ, Timmerman ME (2019). “Model selection in continuous test norming with GAMLSS.” Assessment, 26(7), 1329–1346. doi:10.1177/1073191117715113.
See Also
shape_data(), fb_select(), normtable_create()
Examples
invisible(data("ids_data"))
mydata <- shape_data(ids_data, age_name = "age", score_name = "y14", family = "BB")
mod <- fb_select(mydata, age_name = "age", score_name = "shaped_score",
family = "BB", selcrit = "BIC")
mod$search_history
ids data
Description
The data are perturbed data, based on scores on Test 14 (“naming antonyms”) and Test 7 (“naming categories”) of the intelligence test IDS-2 (Grob & Hagmann-von Arx, 2018a; Grob et al., 2018b). The data are provided as supplementary material to Timmerman et al. (2021).
Usage
data(ids_data)
Format
A dataframe with three columns:
ageage in years
y7raw test score on Test 7
y14raw test score on Test 14
Source
References
Grob A, Hagmann-von Arx P (2018). IDS 2: Intelligence and Development Scales-2. Hogrefe.
Grob A, Hagmann-von Arx P, Ruiter S, Timmerman ME, Visser L (2018). IDS-2: Intelligentie-en ontwikkelingsschalen voor kinderen en jongeren. Hogrefe Publishing.
Timmerman ME, Voncken L, Albers CJ (2021). “A tutorial on regression-based norming of psychological tests with GAMLSS.” Psychological methods, 26(3), 357. doi:10.1037/met0000348.
The ids_kn_data are simulated data for demonstration purposes
Description
The data are simulated data for demonstration purposes, akin to Test 7 (“naming categories”) of the intelligence test IDS-2 (Grob & Hagmann-von Arx, 2018). It consists of the binary scores on 34 items (KN_1,...,KN_34). The raw test score is the sum of the 34 item scores. The data are provided as supplementary material to Heister et al. (2024).
Usage
data(ids_kn_data)
Format
A dataframe with 36 columns:
KN_1binary score on item 1
KN_2binary score on item 2
...
KN_34binary score on item 34
rawscoreraw test score as the unweighted sum of the scores on item 1 to item 34
age_yearsage in year
Source
https://osf.io/dc5k9/files/osfstorage
References
Grob A, Hagmann-von Arx P (2018). IDS 2: Intelligence and Development Scales-2. Hogrefe.
Heister HM, Albers CJ, Wiberg M, Timmerman ME (2024). “Item response theory-based continuous test norming.” Psychological methods. doi:10.1037/met0000686.
These fictional reliability data are for demonstration purposes.
Description
Dataframe with the vectors age and rel, with the ages evaluated, and rel the (fictional) test reliability per age.
Usage
data(ids_rel_data)
Format
A dataframe with two columns:
ageage in years
relreliability
Source
constructed by authors
Create a norm table based on a GAMLSS fitted model
Description
normtable_create() creates a norm table based on a fitted GAMLSS model.
Usage
normtable_create(
model,
data = NULL,
age_name,
score_name,
datarel = NULL,
normtype = "Z",
min_age = NULL,
max_age = NULL,
min_score = NULL,
max_score = NULL,
step_size_score = 1,
step_size_age = NULL,
cont_cor = TRUE,
ci_level = 0.95,
trim = 3,
excel = FALSE,
excel_name = tempfile("norms", fileext = ".xlsx"),
new_data = NULL,
newdata = NULL,
warn_extrapolation = TRUE
)
Arguments
model |
a GAMLSS fitted model, for example the result of |
data |
data.frame. The sample on which the model was fitted. If omitted,
it is retrieved directly from |
age_name |
string. Name of the age variable. |
score_name |
string. Name of the score variable. |
datarel |
data.frame or numeric. If a data.frame, must contain columns |
normtype |
string. Norm score type: |
min_age |
numeric. Lowest age value in the norm table; default is the first integer below the minimum observed age. |
max_age |
numeric. Highest age value in the norm table; default is the first integer above the maximum observed age. |
min_score |
numeric. Lowest score value in the norm table; default is the minimum observed score. |
max_score |
numeric. Highest score value in the norm table; default is the maximum observed score. |
step_size_score |
numeric. Increment of the scores in the norm table; default is 1. |
step_size_age |
numeric. Increment of the ages in the norm table; defaults to approximately 100 ages in total. |
cont_cor |
Logical. If |
ci_level |
numeric. Confidence interval level (if |
trim |
numeric. Trim norm scores at ± |
excel |
logical. If |
excel_name |
character. Path to the Excel file. Defaults to a temporary file.
Ignored if |
new_data |
logical. Deprecated; kept for backward compatibility. Use |
newdata |
data.frame. Optional new data on which sample-level norm scores are evaluated. If provided, full norm matrices are omitted. |
warn_extrapolation |
logical. If |
Details
If excel = TRUE, results are written to an Excel file via the openxlsx2 package.
If the package is not installed, a message is printed and the function continues
without writing an Excel file. By default, the file is written to a temporary path
(see tempfile()); if you want to keep the file permanently, provide your own file
name via the excel_name argument (e.g., "norms.xlsx").
Value
A list of class NormTable containing:
-
norm_sample: Estimated norm scores (normtype) in the sample, trimmed attrim. -
norm_sample_lower,norm_sample_upper: Lower and upperci_levelconfidence bounds ofnorm_sample. -
norm_matrix: Norm scores (normtype) by age. -
norm_matrix_lower,norm_matrix_upper: Lower and upperci_levelbounds ofnorm_matrix. -
znorm_sample: Estimated Z scores in the sample. -
cdf_sample: Estimated percentiles in the sample. -
cdf_matrix: Percentile table by age. -
data,age_name,score_name: Copies of respective function arguments. -
pop_age: Evaluated ages in the norm table.
References
Timmerman ME, Voncken L, Albers CJ (2021). “A tutorial on regression-based norming of psychological tests with GAMLSS.” Psychological methods, 26(3), 357. doi:10.1037/met0000348.
See Also
Examples
# Load example data
invisible(data("ids_data"))
# Prepare data for modeling
mydata_BB_y14 <- shape_data(
data = ids_data,
age_name = "age",
score_name = "y14",
family = "BB"
)
# Fit model using BIC as selection criterion
mod_BB_y14 <- fb_select(
data = mydata_BB_y14,
age_name = "age",
score_name = "shaped_score",
family = "BB",
selcrit = "BIC"
)
# Create norm table from fitted model
norm_mod_BB_y14 <- normtable_create(
model = mod_BB_y14,
data = mydata_BB_y14,
age_name = "age",
score_name = "shaped_score"
)
# Calculate norms for a new sample using reliability data
invisible(data("ids_rel_data"))
newdata <- ids_data[1:5, c("age", "y14")]
norm_mod_BB_newdata <- normtable_create(
model = mod_BB_y14,
newdata = newdata,
age_name = "age",
score_name = "y14",
datarel = ids_rel_data
)
Plot reliability estimates over age
Description
plot_drel() plots reliability estimates as a function of age,
based on different window widths, using a Drel object.
Usage
plot_drel(drel, ncol = 3, nrow = 2, ...)
Arguments
drel |
a |
ncol |
number of plots per row (default: |
nrow |
number of plots per column (default: |
... |
additional arguments passed to plotting functions. |
Value
graphical output and the ggplot object used to create it.
See Also
Examples
data("ids_kn_data")
rel_int <- different_rel(
data = ids_kn_data,
item_variables = colnames(ids_kn_data),
age_name = "age_years",
step_window = c(0.5, 1, 2, 5, 10, 20),
min_agegroup = 5,
max_agegroup = 20,
step_agegroup = c(0.5, 1, 1.5, 2)
)
plot_drel(rel_int, ncol = 2)
Plot norm curves from a NormTable object
Description
plot_normtable() plots norm curves as a function of the predictor,
along with the sample data, based on a NormTable object.
Usage
plot_normtable(
normtable,
lty = 1,
lwd = 3,
pch = 1,
cex = 0.5,
col = "aquamarine4",
xlab = "Age",
ylab = "Percentile",
...
)
Arguments
normtable |
a |
lty |
line type(s) for curves. |
lwd |
line width(s) for curves. |
pch |
symbol for sample points. |
cex |
point size (default: |
col |
point colour (default: |
xlab |
x-axis label (default: |
ylab |
y-axis label (default: |
... |
additional graphical parameters passed to
|
Value
graphical output and the ggplot object used to create it.
See Also
Examples
data("ids_data")
mydata_BB_y14 <- shape_data(
data = ids_data,
age_name = "age",
score_name = "y14",
family = "BB"
)
mod_BB_y14 <- fb_select(
data = mydata_BB_y14,
age_name = "age",
score_name = "shaped_score",
family = "BB",
selcrit = "BIC"
)
norm_mod_BB_y14 <- normtable_create(
model = mod_BB_y14,
data = mydata_BB_y14,
age_name = "age",
score_name = "shaped_score"
)
# default plot
plot_normtable(norm_mod_BB_y14)
Estimate test reliability by age using a sliding window
Description
Estimates reliability across age using a sliding window approach, either at fixed age points or per individual.
Usage
reliability_window(
data,
age_name,
item_variables,
window_width,
window_version = "step",
min_agegroup = NULL,
max_agegroup = NULL,
step_agegroup = 1,
complete.obs = TRUE
)
Arguments
data |
data.frame containing the item scores and age variable. |
age_name |
string. Name of the age variable. |
item_variables |
numeric or character vector. Column indices or names of the item variables. |
window_width |
numeric. Width of the sliding window used to group individuals by age. |
window_version |
string. Type of windowing:
|
min_agegroup |
numeric. Minimum age to include. Defaults to the floor of the minimum age in the data. |
max_agegroup |
numeric. Maximum age to include. Defaults to the ceiling of the maximum age in the data. |
step_agegroup |
numeric. Step size between evaluated ages. Used only when |
complete.obs |
logical. If |
Value
A data.frame with:
-
rel: Reliability estimates -
age: Corresponding age values -
window_width: The width of the sliding window -
window_per: Description of age step or observation unit
This output can be used as the datarel argument in normtable_create().
References
Heister HM, Albers CJ, Wiberg M, Timmerman ME (2024). “Item response theory-based continuous test norming.” Psychological methods. doi:10.1037/met0000686.
See Also
Examples
invisible(data("ids_kn_data"))
rel_est <- reliability_window(
data = ids_kn_data,
age_name = "age_years",
item_variables = colnames(ids_kn_data),
window_width = 2
)
Sample size planning for continuous norming using polynomial regression
Description
Computes optimal sample sizes per group under a distribution free polynomial regression model for group means, following Hessen (2026).
Usage
sample_size_poly(
n_groups,
poly_degree,
n0,
variances = NULL,
solution_type = c("balanced", "all", "range")
)
Arguments
n_groups |
Integer. Number of groups (e.g., age groups). |
poly_degree |
Integer scalar or vector. Polynomial degree(s) of polynomial regression model. |
n0 |
Integer scalar or vector. Reference sample size per group under traditional norming. Typical values are 200, 300, or 400 (see e.g., Egberink et al. (2026)). |
variances |
Optional numeric vector of length |
solution_type |
Character string indicating which solution(s) to return. Must be one of:
|
Details
In the assumed continuous norming model, group means are first estimated and then smoothed using a polynomial model that regresses group means on age. This function determines group sample sizes such that the precision of the estimated means (not higher-order moments) is at least as high as under traditional norming.
This function implements the linear programming (LP) approach described in
Hessen (2026). Multiple optimal solutions may exist:
different combinations of n_{min} and n_{max} can yield the same minimal
total sample size while satisfying the precision constraints.
By default (solution_type = "balanced"), a single solution is returned,
defined as the solution minimizing the difference between the largest and smallest group sample sizes. This yields
a practically balanced design. Alternatively, users can inspect all optimal
solutions (solution_type = "all") or examine the range of optimal sample
sizes per group (solution_type = "range").
How to use:
Before data collection: do not provide
variances(assumes homoscedasticity).During/after data collection: provide estimated
variancesper group.
Value
A data.frame. The structure depends on solution_type:
- solution_type = "balanced"
Returns one optimal solution with:
- n0
Reference sample size per group
- group
Group index
- poly_degree
Polynomial degree
- n
Sample size per group
- variance
Expected variance of estimated mean
- variance_traditional
Variance under traditional norming (
\sigma_j^2 / n0)- total_n
Total sample size across all groups
- traditional_total_n
Total sample size under traditional norming
- n_min
Lower bound used in LP
- n_max
Upper bound used in LP
- solution_type = "all"
Returns all optimal solutions with the same columns as above, plus:
- solution_id
Identifier for solution number
- solution_type = "range"
Returns one row per group with:
- n0
Reference sample size per group
- group
Group index
- degree
Polynomial degree
- n_range
Range of sample sizes over optimal solutions
References
Egberink I, De Leng W, Evers A, Hemker B, Lucassen W (2026). COTAN Beoordelingssysteem voor de Kwaliteit van Tests. Geheel herziene versie 2026. Nederlands Instituut van Psychologen. Hessen DJ (2026). “Richtlijnen voor steekproefgroottes bij continu normeren.” Utrecht University, https://github.com/djhessen/COTAN.
Examples
# Example 1: Planning before data collection (homoscedastic)
res1 <- sample_size_poly(
n_groups = 5,
poly_degree = 2,
n0 = 10 #400
)
# Example 2: Midway planning with variance estimates (heteroscedastic)
invisible(data("ids_data"))
ids_data$age_group <- cut(ids_data$age, breaks = seq(6, 18, by = 1))
v <- tapply(ids_data$y7, ids_data$age_group, var, na.rm = TRUE)
res2 <- sample_size_poly(
n_groups = length(v),
poly_degree = c(1,2,3),
n0 = c(10,20), #c(300,400),
variances = v
)
Shape data as input for fb_select()
Description
shape_data() reshapes the response variable into the right format for the specified
distribution and removes all cases with missing data on the score or age variable.
The result is suitable for use as input to fb_select().
Usage
shape_data(
data,
age_name,
score_name,
family,
max_score = NULL,
verbose = TRUE
)
Arguments
data |
data.frame. Sample on which to fit the distribution; contains the scores and ages. |
age_name |
string. Name of the age variable. |
score_name |
string. Name of the score variable. |
family |
string. For example, |
max_score |
numeric. Highest possible score in the norm table. Defaults to the maximum observed score in the sample. |
verbose |
logical. If |
Details
The function checks whether the response values are valid for the specified
GAMLSS distribution family. If not, transformations are applied to ensure compatibility.
Messages are printed (if verbose = TRUE) to describe each transformation.
Unexpected transformations should prompt inspection of the original data. Note that the function does not assess whether the chosen family is appropriate for the data. It only ensures compatibility.
Compatible with all gamlss distributions, with the exception of distributions in the multinomial family (gamlss::.gamlss.multin.list). This includes user-defined distributions, such as truncated distributions.
Value
A data.frame containing the original variables and a new column shaped_score,
with the response variable in the correct format for GAMLSS modeling.
References
Voncken L, Albers CJ, Timmerman ME (2019). “Model selection in continuous test norming with GAMLSS.” Assessment, 26(7), 1329–1346. doi:10.1177/1073191117715113.
See Also
Examples
invisible(data("ids_data"))
mydata_BB <- shape_data(ids_data, age_name = "age", score_name = "y14", family = "BB")
mydata_BCPE <- shape_data(ids_data, age_name = "age", score_name = "y14", family = "BCPE")