normref (version 0.0.0.1)

normtable_create: 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,
  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 = FALSE,
  ci_level = 0.95,
  trim = 3,
  excel = FALSE,
  excel_name = tempfile("norms", fileext = ".xlsx"),
  new_data = FALSE
)

Value

A list of class NormTable containing:

• norm_sample: Estimated norm scores (normtype) in the sample, trimmed at trim.

• norm_sample_lower, norm_sample_upper: Lower and upper ci_level confidence bounds of norm_sample.

• norm_matrix: Norm scores (normtype) by age (only if new_data = FALSE).

• norm_matrix_lower, norm_matrix_upper: Lower and upper ci_level bounds of norm_matrix.

• znorm_sample: Estimated Z scores in the sample.

• cdf_sample: Estimated percentiles in the sample.

• cdf_matrix: Percentile table by age (only if new_data = FALSE).

• data, age_name, score_name: Copies of respective function arguments.

• pop_age: Evaluated ages in the norm table (only if new_data = FALSE).

Arguments

model

a GAMLSS fitted model, for example the result of fb_select().

data

data.frame. The sample on which the model has been fitted, or new data; must contain the score variable (with name given in score_name) and age variable (with name given in age_name).

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 age and rel, with estimated test reliability per age. If numeric, a constant reliability is assumed for all ages (optional, only needed for confidence intervals).

normtype

string. Norm score type: "Z" (N(0,1); default), "T" (N(50,10)), or "IQ" (N(100,15)).

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 TRUE, apply continuity correction for discrete test scores. Default is FALSE.

ci_level

numeric. Confidence interval level (if datarel is provided). Default is 0.95.

trim

numeric. Trim norm scores at ± trim standard deviations. Default is 3.

excel

logical. If TRUE, attempt to write results to an Excel file. Default is FALSE.

excel_name

character. Path to the Excel file. Defaults to a temporary file. Ignored if excel = FALSE.

new_data

logical. If FALSE (default), create a full norm table and norm scores. If TRUE, only return norm scores for the given data.

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").

References

timmerman2021tutorialnormref

See Also

fb_select(), plot_normtable()

Examples

# \donttest{
# 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,
  data = newdata,
  age_name = "age",
  score_name = "y14",
  new_data = TRUE,
  datarel = ids_rel_data
)
# }