Package 'kits'

Description

The default age_ticks of the plots against age: plot() of a kits_item_table(), of a kits_norms() by group and of a kits_vertical().

Usage

AGE_TICKS

Format

A numeric vector: 3, 6, 12, 18, 24, 36, 48, 60, 72, 84, 96.

Examples

AGE_TICKS

Description

Maximizes the conditional likelihood of the partial credit model from the sufficient statistics, with the gradient and Hessian from RTMB. It does not track scales or check its input; kits_cml() and kits_item() do.

Usage

algo_cml(stats)

Arguments

Value

A list: coef (one row per step: item_id, item_score, beta, se), betas (the betas as a named list, one vector per item), vcov (the covariance of the betas), nll (-log L) and optim (the convergence record).

See Also

Other algo: algo_esf(), algo_jme(), algo_line(), algo_link_error(), algo_lw(), algo_mean_sigma(), algo_pcm(), algo_screen(), algo_shash(), algo_shash_z(), algo_thresholds()

Examples

betas <- list(a1 = c(-1, 0), a2 = c(0, 1), a3 = 0.5, a4 = -0.5)
X <- kits_sim(seq(-3, 3, length.out = 400), betas, seed = 1)
cml <- kits_stats(X) |>
  algo_cml()
cml$coef

Description

For one set of items, the elementary symmetric functions gamma_r of CML and, for each item, the distribution of its score given the raw score r, with its mean and variance. It does not track scales or check its input; kits_esf() does.

Usage

algo_esf(betas)

Arguments

Value

A list: items, m (steps per item), max_score, centre, log_gamma (r = 0..R), log_gamma_rest (one row per item: gamma without that item), prob (one matrix per item: P(X_i = x | r), rows r, columns x), expected, variance and free (rows r, columns items).

See Also

Other algo: algo_cml(), algo_jme(), algo_line(), algo_link_error(), algo_lw(), algo_mean_sigma(), algo_pcm(), algo_screen(), algo_shash(), algo_shash_z(), algo_thresholds()

Examples

esf <- list(a1 = c(-1, 0.5), a2 = 0.3) |>
  algo_esf()
exp(esf$log_gamma)
esf$prob$a1

Description

Jeffreys modal estimate: theta-hat = argmax log L(theta) + 1/2 log I(theta). For the PCM it equals Warm's (1989) WLE exactly (Firth, 1993; Magis, 2015), so kits_subj() reports it as the WLE. One estimate per combination of items and raw score, by RTMB's Newton method; finite also for a zero or a perfect score. SE = 1 / sqrt(I(theta-hat)), the asymptotic SE of the WLE (Warm, 1989). With two maxima (few items with very different difficulties) the higher one is taken (the value of the objective decides; it is found on a grid of theta, step 0.05); with two equally high maxima, the smaller theta. It does not track scales or check its input; kits_subj() and kits_subj_table() do.

Usage

algo_jme(
  betas,
  raw = 0:sum(lengths(betas)),
  items = rep(list(names(betas)), length(raw))
)

Arguments

Value

A data.frame with theta and se, one row per raw score.

References

Firth, D. (1993). Bias reduction of maximum likelihood estimates. Biometrika, 80(1), 27-38. doi:10.1093/biomet/80.1.27

Magis, D. (2015). A note on weighted likelihood and Jeffreys modal estimation of proficiency levels in polytomous item response models. Psychometrika, 80(1), 200-204. doi:10.1007/s11336-013-9378-5

Warm, T. A. (1989). Weighted likelihood estimation of ability in item response theory. Psychometrika, 54(3), 427-450. doi:10.1007/BF02294627

See Also

Other algo: algo_cml(), algo_esf(), algo_line(), algo_link_error(), algo_lw(), algo_mean_sigma(), algo_pcm(), algo_screen(), algo_shash(), algo_shash_z(), algo_thresholds()

Examples

betas <- list(a1 = c(-1, 0), a2 = c(0, 1), a3 = 0.5)
betas |>
  algo_jme()
algo_jme(betas, raw = c(1, 1), items = list(c("a1", "a2"), "a2"))

Description

A line is a list with intercept and slope (new value = intercept + slope x old value); a link is one too. A list of lines is composed in the order applied; invert gives the inverse; with x the line is applied. It does not track scales; kits_convert() does.

Usage

algo_line(line, x = NULL, invert = FALSE)

Arguments

Value

Without x, the line (intercept, slope); with x, the converted values.

See Also

Other algo: algo_cml(), algo_esf(), algo_jme(), algo_link_error(), algo_lw(), algo_mean_sigma(), algo_pcm(), algo_screen(), algo_shash(), algo_shash_z(), algo_thresholds()

Examples

l1 <- list(intercept = 1, slope = 2)
l2 <- list(intercept = -1, slope = 0.5)
algo_line(l1, x = c(0, 1))
algo_line(l1, invert = TRUE)
list(l1, l2) |>
  algo_line(x = c(0, 1))

Description

Resamples the items n_boot times and redoes the screening and the mean/sigma line on each draw; the SDs of the intercept and slope over the draws are the linking error. It does not track scales or check much; kits_link_error() does.

Usage

algo_link_error(screen, n_boot = 200, seed = 1)

Arguments

Value

A list: intercept_error, slope_error, n_failed (draws whose screening failed), vcov (2 x 2) and draws (one row per kept draw: intercept, slope).

See Also

Other algo: algo_cml(), algo_esf(), algo_jme(), algo_line(), algo_lw(), algo_mean_sigma(), algo_pcm(), algo_screen(), algo_shash(), algo_shash_z(), algo_thresholds()

Examples

from <- c(-2, -1.1, 0, 0.9, 2, 3.1, 0.5, 1.4)
to <- c(-1, 0, 1.1, 2, 3, 4.2, 1.5, 2.4)
err <- algo_screen(from, to, item = rep(1:4, 2)) |>
  algo_link_error(n_boot = 100)
err$intercept_error

Description

P(r | theta) for a set of PCM items by the Lord-Wingersky recursion: adding item j, f_j(x) = sum_k f_(j-1)(x - k) P_jk. It does not track scales or check its input; kits_precision() does.

Usage

algo_lw(theta, betas)

Arguments

Value

A matrix, one row per theta, one column per raw score 0..R.

References

Thissen, D., Pommerich, M., Billeaud, K., & Williams, V. S. L. (1995). Item response theory for scores on tests including polytomous items with ordered responses. Applied Psychological Measurement, 19(1), 39-49. doi:10.1177/014662169501900105

See Also

Other algo: algo_cml(), algo_esf(), algo_jme(), algo_line(), algo_link_error(), algo_mean_sigma(), algo_pcm(), algo_screen(), algo_shash(), algo_shash_z(), algo_thresholds()

Examples

P <- list(a1 = c(-1, 0), a2 = 0.5) |>
  algo_lw(theta = c(-1, 0, 1))
P
rowSums(P)

Description

The line new value = intercept + slope x old value with slope = SD(to) / SD(from) and the means aligned. It does not track scales or check its input; kits_link_line() does.

Usage

algo_mean_sigma(from, to)

Arguments

Value

A list with intercept and slope.

References

Kolen, M. J., & Brennan, R. L. (2014). Test equating, scaling, and linking (3rd ed.). Springer. doi:10.1007/978-1-4939-0317-7

See Also

Other algo: algo_cml(), algo_esf(), algo_jme(), algo_line(), algo_link_error(), algo_lw(), algo_pcm(), algo_screen(), algo_shash(), algo_shash_z(), algo_thresholds()

Examples

from <- c(-2, -1, 0, 1, 2, 3)
to <- c(-1, 0, 1, 2, 3.2, 6)
algo_mean_sigma(from, to)
algo_screen(from, to) |>
  algo_mean_sigma()

Description

The partial credit model for one item at abilities theta: the category probabilities, the expected score and the variance (the item information). It does not track scales or check its input; kits_pcm_prob() does.

Usage

algo_pcm(theta, beta, third = FALSE)

Arguments

Value

A list: P (a matrix, one row per theta, one column per score 0..m), E, Var, log_S (the log of the normalizing sum), and M3 when third = TRUE.

References

Masters, G. N. (1982). A Rasch model for partial credit scoring. Psychometrika, 47(2), 149-174. doi:10.1007/BF02296272

See Also

Other algo: algo_cml(), algo_esf(), algo_jme(), algo_line(), algo_link_error(), algo_lw(), algo_mean_sigma(), algo_screen(), algo_shash(), algo_shash_z(), algo_thresholds()

Examples

p <- c(-1, 0, 1) |>
  algo_pcm(beta = c(-0.5, 0.5))
p$P
p$E

Description

Fits the mean/sigma line to all points and flags the points whose residual exceeds cut times the spread; with unit = "item" every point of a flagged item is dropped. It does not track scales or check much; kits_link_screen() does.

Usage

algo_screen(
  from,
  to,
  item = seq_along(from),
  cut = 2,
  spread = "sd",
  unit = "step",
  se_from = NULL,
  se_to = NULL
)

Arguments

Value

A list: from, to, item, resid, z, flagged, dropped (one value per point), intercept0, slope0 (the line of all points), cut and rule (spread, unit, and the SEs). Give it to algo_mean_sigma() and algo_link_error().

See Also

Other algo: algo_cml(), algo_esf(), algo_jme(), algo_line(), algo_link_error(), algo_lw(), algo_mean_sigma(), algo_pcm(), algo_shash(), algo_shash_z(), algo_thresholds()

Examples

from <- c(-2, -1, 0, 1, 2, 3, 0.5, 1.5)
to <- c(-1, 0, 1, 2, 3, 4, 1.5, 5.5)
s <- algo_screen(from, to, spread = "mad")
s$dropped
s |>
  algo_mean_sigma()

Description

Fits a sinh-arcsinh (shash) distribution of y whose four parameters (mu, sigma, epsilon, delta) are polynomials in x, by nlminb with the gradient and Hessian from RTMB, from one start of delta. It does not track scales or check its input; kits_norm_fit() does (several starts).

Usage

algo_shash(x, y, degrees = c(5, 4, 3, 2), delta0 = 1)

Arguments

Value

A list: the coefficients mu_est, sigma_est, epsilon_est, delta_est, degrees, age_mean, age_sd (of x), value (-log L), and the convergence record (convergence and message of nlminb, converged, grad_max, hessian_pd, at_bound).

References

Jones, M. C., & Pewsey, A. (2009). Sinh-arcsinh distributions. Biometrika, 96(4), 761-780. doi:10.1093/biomet/asp053

See Also

Other algo: algo_cml(), algo_esf(), algo_jme(), algo_line(), algo_link_error(), algo_lw(), algo_mean_sigma(), algo_pcm(), algo_screen(), algo_shash_z(), algo_thresholds()

Examples

set.seed(1)
age <- runif(600, 3, 36)
D <- 20 + 15 * log(age) + rnorm(600, 0, 3)
fit <- algo_shash(sqrt(age), D, degrees = c(3, 2, 1, 1), delta0 = 0.5)
fit$value

Description

The parameters of an algo_shash() model at x (clamped as in the fit), and the z-score sinh(delta asinh((y - mu) / sigma) + epsilon) of each y. It does not track scales or check its input; kits_norm_z() does (from a norm table).

Usage

algo_shash_z(fit, x, y)

Arguments

Value

The z-scores (a numeric vector).

See Also

Other algo: algo_cml(), algo_esf(), algo_jme(), algo_line(), algo_link_error(), algo_lw(), algo_mean_sigma(), algo_pcm(), algo_screen(), algo_shash(), algo_thresholds()

Examples

set.seed(1)
age <- runif(600, 3, 36)
D <- 20 + 15 * log(age) + rnorm(600, 0, 3)
z <- algo_shash(sqrt(age), D, degrees = c(3, 2, 1, 1), delta0 = 0.5) |>
  algo_shash_z(sqrt(age), D)
c(mean(z), sd(z))

Description

For each step k of each item, the ability where P(X >= k | theta) = rp (by uniroot()), and its SE by the delta method with the derivative from RTMB. It does not track scales or check its input; kits_thresholds() and kits_item() do.

Usage

algo_thresholds(cml, rp = 0.5)

Arguments

Value

A data.frame, one row per step: item_id, item_score, beta, beta_se, thr, thr_se.

See Also

Other algo: algo_cml(), algo_esf(), algo_jme(), algo_line(), algo_link_error(), algo_lw(), algo_mean_sigma(), algo_pcm(), algo_screen(), algo_shash(), algo_shash_z()

Examples

betas <- list(a1 = c(-1, 0), a2 = c(0, 1), a3 = 0.5, a4 = -0.5)
X <- kits_sim(seq(-3, 3, length.out = 400), betas, seed = 1)
kits_stats(X) |>
  algo_cml() |>
  algo_thresholds()

Description

as.data.frame() turns a result that is a list into a plain data.frame with one row (or one row per wave, per method, per item pattern), so that several results can be stacked with dplyr::bind_rows() and compared, for example the links of every domain. The numbers are those of the object (the same as print() and summary()). checks is the most serious status of the diagnostics ("warn", "note" or "ok"; see kits_check()).

Usage

## S3 method for class 'kits_link'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'kits_drift'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'kits_link_check'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'kits_info'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'kits_item'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'kits'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'kits_norm_screen'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'kits_norm_fit'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'kits_stats'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Details

The columns:

• A link (kits_linking(), kits_link_line()), one row: from, to (the scale labels; several from scales are joined with ", "), kind ("calibration", "anchors", or NA for your own points), intercept, slope, intercept_error, slope_error, cov_intercept_slope (their covariance over the draws), intercept0, slope0 (the line before screening), n_points, n_dropped, n_items, n_failed (resamples that could not be computed), cut, spread, unit, step ("all" or the step, as text), n_boot, seed, key (the dscore key of the anchors), checks. Values that do not apply are NA.

• kits_drift(), one row: scale (of ref), intercept, slope, n_items, n_judged, n_drift (judged items with a dropped step), n_fix (items suggested for fixing), n_steps, n_steps_judged, n_steps_dropped, cut, min_n, checks.

• kits_link_check(), one row per method: from, to, method, intercept, slope, basis, max_abs_diff (the largest |diff| over theta), max_abs_z, max_abs_z_both (NA without bootstrap draws), checks.

• kits_info() (the provenance of any result), one row: call, version, settings (as text, "name = value; ..."), n_rows, data_md5 (of the responses, or of the values), persons_md5, input (the name of the data object, when it was a data.frame or a kits_subj).

• kits_item(), one row: scale, n_persons, n_items, n_steps, n_patterns, n_fixed (fixed steps), n_left_out (fixed items left out), neg_loglik, convergence, max_gradient, checks.

• kits(), one row: the columns of kits_item(), then theta_mean, theta_sd, n_zero, n_perfect, n_misfit (persons by flag).

• kits_norm_screen(), one row per (cohort x) wave: its waves table.

• kits_norm_fit(), one row: n, degrees (as text), neg_loglik, convergence, converged, grad_max, n_at_bound.

• kits_stats(), one row per item pattern: pattern_id, n_items, items (as text), n, max_raw.

Value

A data.frame.

Examples

betas <- list(a1 = -2, a2 = -1, a3 = c(-0.5, 0.5), a4 = 0, a5 = c(0.5, 1.5), a6 = 2, a7 = 3)
young <- kits_sim(rnorm(500, 0), betas[1:5], seed = 1)
old <- kits_sim(rnorm(500, 2), betas[3:7], prefix = "q", seed = 2)
item_young <- kits_item(young, scale = "young cohort")
item_old <- kits_item(old, scale = "old cohort")
link <- kits_linking(item_old, item_young, n_boot = 100)
as.data.frame(link)

# Several links in one table
link_step1 <- kits_linking(item_old, item_young, step = 1, n_boot = 100)
dplyr::bind_rows(as.data.frame(link), as.data.frame(link_step1))

# The calibrations and their provenance
dplyr::bind_rows(as.data.frame(item_young), as.data.frame(item_old))
as.data.frame(kits_info(item_young))

Description

Simulated versions of the two Kids in Taiwan (KIT) cohorts, language and motor only, for examples and tutorials. No row comes from a real child. The response columns are those of the real KIT response file, renamed as everywhere in kits: visit_id (KIT: person_id), subj_id (KIT: pid) and cohort (KIT: sample). On the real data, run rename(visit_id = person_id, subj_id = pid, cohort = sample) once and the same code runs.

Usage

kitm03

kitm36

Format

Each is a list with two elements.

responses is a tibble with one row per child x wave x item answered:

visit_id

Visit (person-wave) id: one child at one wave, for example "M03_c55df9b_M12".

subj_id

Child id: 7 random hex characters, like a short git hash, for example "c55df9b".

cohort

Cohort: "M03" (3 to 72 months) or "M36" (36 to 96 months).

sex

"boy" or "girl".

wave_m

Wave, in months.

age_m

Age at the visit, in months.

item_id

Item id, as in KIT.

item_score

Score, 0 to the maximum of the item.

domain

"lan" (language) or "motor".

anchors is a data.frame with the columns of kits_anchors(): item_id, gsed_item, key, tau, note.

An object of class list of length 2.

Details

Each cohort is a list of two tables:

• responses: the responses, in long format (see below).

• anchors: the anchor key for the items of this cohort, from kits_anchors() (key gsed2406): KIT items matched to GSED items, with their GSED difficulty tau. Use it to link to D with kits_linking(items, anchors). kitm03 has 27 anchors, kitm36 12.

The data were simulated from aggregates of the real KIT data (data-raw/kit_demo.R); the waves at 60 and 72 months of kitm03 go beyond the real M03 follow-up (48 months) and are not observed. Details: tutorial_algorithms/01_calibration.html.

Examples

library(dplyr)
kitm03$responses |>
  distinct(visit_id, wave_m) |>
  count(wave_m)
kitm03$anchors |>
  count(key)

Description

kits_item() and then kits_subj() on the same data. Use it when no link is needed in between (for example a single cohort). With linking, call the two functions separately. plot() draws a Wright map: the abilities and the step thresholds on the same theta axis.

Usage

kits(data, ..., scale = NULL, persons = NULL)

## S3 method for class 'kits'
print(x, digits = 2, ...)

## S3 method for class 'kits'
plot(x, ...)

Arguments

Details

Details: kits_algorithm("cml"), kits_algorithm("wle"), tutorial_algorithms/01_calibration.html and 02_scoring.html.

Value

A kits: a list with item (the kits_item() result), subj (the kits_subj() result), scale, diagnostics (those of item and subj) and info.

Examples

betas <- list(a1 = c(-1, 0), a2 = c(0, 1), a3 = 0.5, a4 = -0.5)
X <- kits_sim(seq(-3, 3, length.out = 300), betas, seed = 1)
k <- kits(X)
k
head(k$subj)
p <- plot(k)
if (interactive()) p

Description

Says, in about 30 lines, which algorithm produced a result: its steps, one formula per step, the functions that run the steps (the kits_ steps and the algo_ building blocks, as ⁠|>⁠ pipelines), key references, and where to read more (the tutorial page in ⁠tutorial_algorithms/⁠ and the teaching script in inst/scripts, with its parts).

Usage

kits_algorithm(x)

Arguments

Value

Invisibly, a kits_algorithm object (a list: topic, title, facts, steps, components, references, tutorial, script, parts); it prints the algorithm. For a result, facts is one line on the result itself (items, steps, persons, scale).

References

Masters, G. N. (1982). A Rasch model for partial credit scoring. Psychometrika, 47, 149-174.

Warm, T. A. (1989). Weighted likelihood estimation of ability in item response theory. Psychometrika, 54, 427-450.

Kolen, M. J., & Brennan, R. L. (2014). Test equating, scaling, and linking (3rd ed.). Springer.

Examples

kits_algorithm("cml")

betas <- list(a1 = c(-1, 0), a2 = 0.5, a3 = -0.5)
item <- kits_sim(rnorm(200), betas, seed = 1) |>
  kits_item(scale = "demo")
kits_algorithm(item)

# The teaching script and its parts
algo <- kits_algorithm("link")
system.file("scripts", algo$script, package = "kits")
algo$parts

Description

The anchor items of KIT for the link to the D score of the Global Scales for Early Development (GSED): each row is a KIT item, the GSED item it is matched to, and the difficulty tau of that GSED item in a key of the dscore package (van Buuren et al., 2025). Give the table to kits_linking() as to; use one key per link (the link records it). Details: vignette("kits-flow", package = "kits"), section 3.

Usage

kits_anchors(key = c("gsed2406", "gsed2510"))

Arguments

Value

A data.frame with one row per anchor: item_id (the KIT item), gsed_item (the GSED item), key, tau (on the D scale), note (the matching decision) and domain ("lan", "motor" or "cog").

References

van Buuren, S., Eekhout, I., McCray, G., Lancaster, G. A., Waldman, M. R., McCoy, D. C., Gladstone, M., et al. (2025). Enhancing comparability in early child development assessment with the D-score. International Journal of Behavioral Development, 49(4), 348-364. doi:10.1177/01650254241294033

van Buuren, S., Eekhout, I., Huizing, A., & Seiden, J. (2025). dscore: D-score for child development. R package. https://CRAN.R-project.org/package=dscore

See Also

kits_linking()

Examples

head(kits_anchors())

# A link to D from a simulated calibration whose items carry KIT item ids
anchors <- kits_anchors()
ids <- anchors$item_id[1:8]
betas <- as.list((anchors$tau[1:8] - 55) / 10)
names(betas) <- ids
X <- kits_sim(rnorm(600, 0, 1.5), betas, seed = 1)
item <- kits_item(X, scale = "sim M03")
kits_linking(item, anchors)

Description

Every main result of kits checks itself when it is made and keeps a diagnostics table (x$diagnostics for lists, attr(x, "diagnostics") for tables), one row per check; its printout ends with "Checks: OK" or the number of warnings and notes. kits_check() collects the tables of several results; an object without diagnostics gets a row saying so (a stacked kits_subj() gets its diagnostics recomputed).

Usage

kits_check(..., all = FALSE)

Arguments

Details

The checks:

• kits_item(): convergence, gradient, Hessian, extreme estimates, category counts, item pattern sizes (note below 400 person-waves) and item fit (infit or outfit outside 0.6 to 1.4).

• kits_subj(): shares of zero, perfect and misfit scores, and the reliability of each wave.

• kits_subj_table(): person-waves who answered items outside the standard form of their wave.

• kits_itemfit(): whether the item parameters were calibrated on these data.

• Links (kits_linking(), kits_link_steps): points kept and dropped, the correlation of the kept points, the linking error, slope vs 1, the common-item share and the domain balance.

• kits_link_check(): a check method that differs from the link by more than 2 errors (or tol).

• kits_item_table() with data: items separated by age.

• kits_norms(): convergence, gradient, coefficients at their limits, the largest delta, and the same-age z by age decile.

• kits_norm_screen(): waves left out. kits_drift(): drifted items.

• kits_dif(): the LR test, the largest step difference, the overall DIF test, the largest |dif|, items not compared, steps not observed in a group.

• kits_vertical(): scale shrinkage, falling means, and cohorts that differ at a shared wave.

• kits_precision(): the usable range of each form.

Details: vignette("kits-flow", package = "kits"), section 6.

Value

A table (a data.frame), warnings first: object, and the diagnostics columns check, value, status ("ok", "note" or "warn") and message.

Quality control for a new wave

A short checklist, after Kolen and Brennan (2014; Table 8.8, p. 336, and p. 333):

1. Drift check before fixing: kits_drift() against the original calibration (pp. 288-289).

2. Fix to the original calibration: kits_item(X_new, fixed_params = drift$fix) (pp. 293-294).

3. Double link: a second route to the target scale (kits_link_check(); pp. 295-296).

4. Item pattern n: about 400 person-waves per form (p. 304; the check of kits_item()).

5. Common-item share: at least 20% of the items, a content miniature (kits_linking()).

6. Consistency with the other cohort at the same age (p. 333; kits_vertical()).

7. md5 provenance: compare the fingerprints of kits_info() (p. 333).

References

Kolen, M. J., & Brennan, R. L. (2014). Test equating, scaling, and linking (3rd ed.). Springer. doi:10.1007/978-1-4939-0317-7

Examples

betas <- list(a1 = c(-1, 0), a2 = c(0, 1), a3 = 0.5, a4 = -0.5)
X <- kits_sim(seq(-3, 3, length.out = 300), betas, seed = 1)
item <- kits_item(X)
s <- kits_subj(X, item)
kits_check(item, s)
kits_check(calibration = item, all = TRUE)
summary(item)

Description

Applies the links in order, each a straight line: new value = intercept + slope x old value, and new SE = slope x old SE. Before each link the scale of x must be one the link starts from (link$from_scale), else it stops (class kits_error_scale); an unrecorded scale warns. When every link has bootstrap draws (n_boot > 0), a table also gets se_link (linking error only) and se_total = sqrt(se^2 + se_link^2).

Usage

kits_convert(x, ..., from = NULL)

Arguments

Details

Details: kits_algorithm("wle") (the conversion) and tutorial_algorithms/02_scoring.html.

Value

x on the scale where the last link ends (recorded in attr(, "scale")), with the same column names; with draws also se_link and se_total.

Examples

betas <- list(a1 = -2, a2 = -1, a3 = c(-0.5, 0.5), a4 = 0, a5 = c(0.5, 1.5), a6 = 2, a7 = 3)
X03 <- kits_sim(rnorm(500, 0), betas[1:5], seed = 1)
X36 <- kits_sim(rnorm(500, 2), betas[3:7], prefix = "q", seed = 2)
item03 <- kits_item(X03, scale = "lan M03")
item36 <- kits_item(X36, scale = "lan M36")
co <- kits_linking(item36, item03, n_boot = 0)
anchors <- data.frame(item_id = c("a1", "a2", "a3", "a4", "a5"), tau = c(40, 47, 51, 55, 60))
d_link <- kits_linking(item03, anchors, n_boot = 0)

s36 <- kits_subj(X36, item36)

# One link per line: M36 -> M03, then M03 -> D
D36 <- s36 |>
  kits_convert(co) |>
  kits_convert(d_link)
head(D36)

# The same in one call
all.equal(D36, kits_convert(s36, co, d_link))

# A numeric vector: give its scale
c(-1, 0, 1) |>
  kits_convert(d_link, from = "lan M03")

# Chosen theta values with their linking error (links made with n_boot > 0)
co_boot <- kits_linking(item36, item03, n_boot = 100)
d_boot <- kits_linking(item03, anchors, n_boot = 100)
data.frame(theta = c(-1, 0, 1)) |>
  kits_convert(co_boot, d_boot, from = "lan M36")

# The wrong order stops
try(s36 |> kits_convert(d_link))

Description

Calibrates each group of person-waves on its own by CML and tests whether the step parameters are the same (Andersen, 1973): LR = 2 (sum of log L_g - log L_all), on the steps each group observes. It returns each group's steps on a common origin and the Wald z of the difference between every two groups; with large N, read these sizes rather than the p value. With two groups it also gives each item's DIF (the item-pair method of Bechger & Maris, 2015, as dexter's DIF()): dif is the mean over the item's steps, in logits, positive is harder for the ref group (with ref = "boy", favors girls). print(d) shows the LR test.

Usage

kits_dif(
  data,
  group,
  item = NULL,
  ref = NULL,
  by = NULL,
  persons = NULL,
  unobserved = c("steps", "drop"),
  ...
)

## S3 method for class 'kits_dif'
print(x, digits = 2, n = NULL, ...)

## S3 method for class 'kits_dif'
summary(object, digits = 2, n = 10, ...)

## S3 method for class 'kits_dif_summary'
print(x, ...)

## S3 method for class 'kits_dif'
plot(x, type = c("items", "steps"), items = NULL, cut = 0.3, ...)

Arguments

Details

Details: kits_algorithm("dif") and tutorial_algorithms/05_checks.html.

Value

A data.frame (class kits_dif): with two groups one row per compared item, item_id and dif (logits; no rows with more groups), and the attributes

• lrtest: LR, df, p, split (how the groups were formed), rule (unobserved) and groups, one row per group: group, n, n_info (informative person-waves), n_items, n_steps (steps estimated), n_par (free step parameters), logLik;

• steps: one row per group and estimated step: group, item_id, item_score, beta, se (on the origin of the joint calibration);

• full: the joint calibration: item_id, item_score, beta, se, with attributes logLik and n_par;

• diff: one row per pair of groups and step: item_id, item_score, group_1, group_2, diff (beta in group_2 minus beta in group_1), se, z;

• unobserved: the steps of answered items that a group does not estimate: group, item_id, item_score, reason, left_out (the item's responses in that group are left out of the joint calibration too);

• with two groups (otherwise NULL): overall (stat, df, p: the test that any item has DIF), groups (ref, focal and the person-waves n of each), se (of each dif) and left_out (items not compared: in one group only, or with different scores);

• diagnostics (see kits_check()) and info (see kits_info()).

References

Andersen, E. B. (1973). A goodness of fit test for the Rasch model. Psychometrika, 38, 123-140. doi:10.1007/BF02291180

Bechger, T. M., & Maris, G. (2015). A statistical test for differential item pair functioning. Psychometrika, 80(2), 317-340. doi:10.1007/s11336-014-9408-y

See Also

kits_dif_combine() to combine two cohorts, kits_drift(), kits_itemfit().

Examples

betas <- list(a1 = c(-1, 0), a2 = c(0, 1), a3 = 0.5, a4 = -0.5, a5 = 0)
theta <- seq(-3, 3, length.out = 300)
boys <- kits_sim(theta, betas, prefix = "b", seed = 1)
girls <- kits_sim(theta, modifyList(betas, list(a5 = 1)), prefix = "g", seed = 2)
X <- rbind(boys, girls)

# a5 is harder for girls: negative, favors boys
dif <- X |> kits_dif(rep(c("boy", "girl"), each = 300))
dif
attr(dif, "lrtest")$p

# Andersen's median split; do the steps stay the same across waves?
kits_dif(X, "raw")
resp <- kitm03$responses |>
  dplyr::filter(domain == "lan", wave_m <= 12) |>
  kits_resp()
kits_dif(resp, "wave")

# Each item with its 95% CI; beyond +/- cut in colour; then each step in both groups
p <- plot(dif)
p <- plot(dif, type = "steps")
if (interactive()) p

Description

Decides the direction of each item in each cohort (beyond cut favors the focal group, below -cut the reference group, else "none") and combines the two: an item in one cohort only takes that cohort's result, opposite signs with one side beyond cut are "inconsistent", otherwise the direction that exceeds cut. Both kits_dif() results must use the same ref.

Usage

kits_dif_combine(d1, d2, cut = 0.3, cohorts = NULL)

Arguments

Details

Details: kits_algorithm("dif") and tutorial_algorithms/05_checks.html.

Value

A data.frame, one row per item: item_id, dif_ and dir_ for both cohorts, and the combined DIF ("none", "favors girls", "favors boys" or "inconsistent" with ref = "boy"), which kits_item_table() uses to colour the items.

Examples

d1 <- data.frame(item_id = c("a1", "a2", "a3", "a4"), dif = c(0.1, 0.5, 0.4, -0.5))
d2 <- data.frame(item_id = c("a1", "a2", "a3", "a5"), dif = c(0.2, 0.1, -0.2, 0.6))
kits_dif_combine(d1, d2)

Description

Calibrates the new data freely (kits_item()), links its step thresholds to those of ref (kits_linking(): a mean/sigma line with one round of screening), and flags the items with a dropped step as drifted. Steps need at least min_n persons below and above to be judged. Items that did not drift, or carry too little information to judge, are suggested for fixing (drift$fix), ready for kits_item(X_new, fixed_params = drift$fix) on the scale of ref. An item with a higher score in the new data than in ref ("score range differs") is not judged, since its thresholds depend on all its steps; it is suggested for fixing, and kits_item() then keeps its old steps and estimates the new one. Details: vignette("kits-advanced", package = "kits"), sections 8.1 and 8.2.

Usage

kits_drift(data, ref, cut = 2, min_n = 30, ...)

## S3 method for class 'kits_drift'
print(x, digits = 2, ...)

## S3 method for class 'kits_drift'
plot(x, type = c("scatter", "difference"), items = NULL, ...)

Arguments

Value

A kits_drift: a list that prints briefly. Its elements:

• fix: the ref parameters (item_id, item_score, beta) of the items suggested for fixing, with attr(, "scale"); NULL when ref has no beta column.

• intercept, slope: the line from the free calibration of the new data to the ref scale.

• points: one row per step: the thresholds, the numbers below and above, judged, the residual and whether it was dropped.

• items: one row per item: item_id, max_abs_resid, drift (NA when not judged), suggest_fix, reason (why the item is not judged).

• steps_free: the step table of the free calibration of the new data.

• scale, diagnostics (see kits_check()), info (see kits_info()).

Examples

betas <- list(a1 = c(-1, 0), a2 = c(0, 1), a3 = 0.5, a4 = -0.5, a5 = c(-0.5, 0.5), a6 = 1.5)
old <- kits_sim(seq(-3, 3, length.out = 400), betas, seed = 1)
item_old <- kits_item(old)

drifted <- modifyList(betas, list(a3 = 2))   # a3 became harder in the new data
new <- kits_sim(seq(-2, 4, length.out = 400), drifted, prefix = "n", seed = 2)
drift <- kits_drift(new, item_old)
drift$items

# Calibrate the new data, fixing the items suggested for fixing
item_new <- kits_item(new, fixed_params = drift$fix)
coef(item_new)

# New against old thresholds; the steps of the drifted item in orange
p <- plot(drift)
p <- plot(drift, type = "difference")
if (interactive()) p

Description

A teaching view of the core of conditional maximum likelihood (CML): for one set of items (one item pattern), the elementary symmetric functions gamma_r and the distribution of each item score given the raw score r that they imply, with its mean and variance. The numbers come from the same internal code as kits_item(), kits_itemfit() and kits_item_restscore().

Usage

kits_esf(item, items = NULL, pattern_id = NULL, ...)

## S3 method for class 'kits_esf'
print(x, ...)

## S3 method for class 'kits_esf'
as.data.frame(x, ...)

## S3 method for class 'kits_esf'
plot(x, items = NULL, ...)

Arguments

Details

Details: the models tutorial (tutorial_models/kits_models.html), sections 2 and 6.

Value

A kits_esf object, a list with

• gamma: one row per raw score: r, gamma, log_gamma (also as.data.frame(x));

• prob: the conditional distributions, long: item_id, r, x, prob (P(X_i = x | r); 0 where x cannot occur given r);

• moments: item_id, r, expected (E(X_i | r)), variance (Var(X_i | r));

• items, max_score (the highest raw score), steps (the betas used), scale, info.

See Also

kits_itemfit() (conditional infit and outfit), kits_item_restscore(), kits_algorithm() (the topic "cml").

Examples

# Two items by hand: a1 with 2 steps, a2 with 1 step
parms <- data.frame(item_id = c("a1", "a1", "a2"), item_score = c(1, 2, 1),
                    beta = c(-1, 0.5, 0.3))
esf <- kits_esf(parms)
esf
esf$prob

# The language calibration of kitm03; bk03 is the form of 12 to 24 months
item <- kitm03$responses |>
  dplyr::filter(domain == "lan") |>
  kits_resp() |>
  kits_item(scale = "lan M03")
esf <- kits_esf(item, pattern_id = "bk03")
esf
p <- plot(esf)
if (interactive()) p

Description

Every main result of kits records how it was made: the call (object names only; data given by value show as ⁠<data>⁠), the kits version, the settings, and a fingerprint of the data (counts, item ids, md5 hashes of the sorted ids and responses). The record holds no data and no time stamp, so a result can be shared and the same input gives an identical object.

Usage

kits_info(x)

## S3 method for class 'kits_info'
print(x, ...)

Arguments

Value

A kits_info list (printed briefly): call, version, settings, data, and, when they apply:

• reference: the fixed parameters; item_data: the data the item parameters came from;

• persons: a fingerprint of the person information (persons of kits_subj(), or wave_m);

• input: the name and form of a data.frame or kits_subj() given as data;

• conversions (links applied by kits_convert()) and links (their intercept, slope).

Examples

betas <- list(a1 = c(-1, 0), a2 = c(0, 1), a3 = 0.5, a4 = -0.5)
X <- kits_sim(seq(-3, 3, length.out = 300), betas, seed = 1)
item <- kits_item(X, scale = "demo")
kits_info(item)
identical(kits_item(X, scale = "demo"), item)

# Person information given to kits_subj() is fingerprinted too
s <- kits_subj(X, item, persons = data.frame(visit_id = rownames(X), wave_m = 12))
kits_info(s)

Description

Each returns a function of theta for a set of items: kits_information() the test information I(theta) = sum_i Var(X_i | theta) under the PCM, and kits_expected_score() the expected raw score sum_i E(X_i | theta) (the test characteristic curve). theta is on the calibration scale of the step parameters (beta).

Usage

kits_information(item, ...)

## Default S3 method:
kits_information(item, items = NULL, pattern_id = NULL, ...)

## S3 method for class 'kits_item'
kits_information(item, items = NULL, pattern_id = NULL, ...)

## S3 method for class 'kits'
kits_information(item, ...)

## S3 method for class 'kits_fit'
kits_information(item, items = NULL, pattern_id = NULL, ...)

kits_expected_score(item, ...)

## Default S3 method:
kits_expected_score(item, items = NULL, pattern_id = NULL, ...)

## S3 method for class 'kits_item'
kits_expected_score(item, items = NULL, pattern_id = NULL, ...)

## S3 method for class 'kits'
kits_expected_score(item, ...)

## S3 method for class 'kits_fit'
kits_expected_score(item, items = NULL, pattern_id = NULL, ...)

## S3 method for class 'kits_information'
print(x, ...)

## S3 method for class 'kits_expected_score'
print(x, ...)

Arguments

Details

Details: kits_algorithm("information") and tutorial_algorithms/06_scale.html; the models tutorial (tutorial_models/kits_models.html), section 1.

Value

A function of theta (a numeric vector), of class kits_information or kits_expected_score, that returns one value per theta. It keeps attr(, "parms") (the betas), attr(, "items") and attr(, "scale").

Examples

betas <- list(a1 = c(-1, 0), a2 = c(0, 1), a3 = 0.5, a4 = -0.5)
X <- kits_sim(seq(-3, 3, length.out = 400), betas, seed = 1)
item <- kits_item(X)
info <- kits_information(item)
info
info(c(-2, 0, 2))
1 / sqrt(info(0))   # the SE of theta at 0

expected <- kits_expected_score(item, items = c("a1", "a2"))
expected(c(-2, 0, 2))

Description

Calibrates the items with the partial credit model by conditional maximum likelihood, then computes the threshold thr of every step: the ability at which P(X >= k) = .5 (RP50). The origin is the sum of all beta = 0, or the fixed items when fixed_params is given. The calibration defines a scale, labelled by scale; the label travels with the results, so that a wrong link stops.

Usage

kits_item(data, ..., scale = NULL)

## S3 method for class 'kits_item'
print(x, digits = 2, n = 6, ...)

## S3 method for class 'kits_item'
coef(object, rp = 0.5, ...)

## S3 method for class 'kits_item'
plot(
  x,
  type = c("category", "expected", "wright", "fit", "observed"),
  items = NULL,
  theta = NULL,
  scores = NULL,
  data = NULL,
  group = NULL,
  step = 1,
  persons = NULL,
  ...
)

Arguments

Details

Details: kits_algorithm("cml") and tutorial_algorithms/01_calibration.html; the models tutorial (tutorial_models/kits_models.html), sections 2, 3 and 5.

Value

A kits_item: a list that prints briefly. Its elements:

• thresholds: one row per step: item_id, item_score (the step), beta, beta_se, thr, thr_se. Also returned by coef().

• fit: the CML fit (class kits_fit, see kits_cml()).

• stats: the sufficient statistics of the CML (class kits_stats, see kits_stats()).

• n_persons: the number of person-waves in the calibration.

• left_out: fixed items left out of the calibration (no 0 score, or one score only, and no score above their fixed steps).

• design: the item patterns (pattern_id, item_id), including left-out items.

• scale: the scale label (also attr(coef(x), "scale")).

• itemfit: the conditional item fit on the calibration data, as kits_itemfit() (NULL when it cannot be computed).

• diagnostics: the checks of the calibration (see kits_check()).

• info: the call, settings and data fingerprint (see kits_info()).

Examples

betas <- list(a1 = c(-1, 0), a2 = c(0, 1), a3 = 0.5, a4 = -0.5)
X <- kits_sim(seq(-3, 3, length.out = 400), betas, seed = 1)
item <- kits_item(X, scale = "lan M03")
item
coef(item)

# A new wave: fix the items of the first calibration (the new scale is that of the fixed items)
betas_new <- c(betas, list(a5 = c(0.5, 1.5)))
X_new <- kits_sim(seq(-2, 4, length.out = 400), betas_new, prefix = "n", seed = 2)
item_new <- kits_item(X_new, fixed_params = coef(item))
print(item_new, n = 8)

# One wave at a time: old betas never move and earlier scores are never estimated again.
# In wave 2, a2 drifts (it gets a new version, a2_w2), a3 reaches a score of 2 (step 1 stays
# fixed, step 2 is estimated; the thresholds of a3 change) and a5 is new.
betas_1 <- c(betas, list(a6 = c(-1, 1), a7 = 1))
X_1 <- kits_sim(seq(-3, 3, length.out = 400), betas_1, seed = 1)
bank <- coef(kits_item(X_1, scale = "lan M03"))[c("item_id", "item_score", "beta", "beta_se")]
betas_2 <- c(betas_1[c("a1", "a4", "a6")],
             list(a2 = c(1, 2), a7 = 1, a3 = c(0.5, 2), a5 = c(1, 2)))
X_2 <- kits_sim(seq(-1, 5, length.out = 600), betas_2, prefix = "m", seed = 3)
drift <- kits_drift(X_2, bank)   # stop here when too many common items drift
moved <- drift$items$item_id[drift$items$drift %in% TRUE]
colnames(X_2)[colnames(X_2) %in% moved] <- paste0(moved, "_w2")
item_2 <- kits_item(X_2, fixed_params = drift$fix)
added <- dplyr::anti_join(coef(item_2), bank, by = c("item_id", "item_score"))
bank <- rbind(bank, added[names(bank)])
bank

# Thresholds at RP80: the theta at which P(X >= k) = .8
coef(item, rp = 0.8)

# The probability of each score of each item
p <- plot(item)
p <- plot(item, items = c("a1", "a2"))
# The expected score of each item
p <- plot(item, type = "expected")
# A Wright map: the children beside the thresholds
p <- plot(item, type = "wright", scores = kits_subj(X, item))
# Item fit: infit and outfit of each item (x$itemfit)
p <- plot(item, type = "fit")
# Observed share passing against theta, by a group, beside the model (grey)
p <- plot(item, type = "observed", data = X, group = rep(c("a", "b"), length.out = nrow(X)))
if (interactive()) p

Description

Kreiner's (2011) test of item fit: for each item, the Goodman-Kruskal gamma of item score x rest score (the sum of the other items) is compared with the gamma the PCM implies given the item parameters. Each row is one item in one item pattern with at least min_n persons. gamma_obs below gamma_exp means the item separates persons less than the model implies, above means more (for example local dependence); with large N, look at the size of the difference.

Usage

kits_item_restscore(data, item, min_n = 100, ...)

## S3 method for class 'kits_item_restscore'
print(x, digits = 3, n = 10, ...)

## S3 method for class 'kits_item_restscore'
plot(x, items = NULL, ...)

Arguments

Details

Details: the models tutorial (tutorial_models/kits_models.html), sections 6 and 9.2.

Value

A data.frame (class kits_item_restscore) with one row per item and item pattern:

• item_id, pattern_id (as in kits_subj()), n (persons);

• gamma_obs, gamma_exp: the observed gamma and the gamma expected under the PCM;

• se (asymptotic SE of gamma_obs; Goodman & Kruskal, 1972), z, p (two-sided, normal);

• p_adj: Benjamini-Hochberg (1995) over all rows.

NA when the gamma cannot be computed (the item or the rest score is constant in the pattern). The skipped patterns are in attr(x, "skipped").

References

Kreiner, S. (2011). A note on item-restscore association in Rasch models. Applied Psychological Measurement, 35, 557-561.

Benjamini, Y., & Hochberg, Y. (1995). Controlling the false discovery rate: a practical and powerful approach to multiple testing. Journal of the Royal Statistical Society B, 57, 289-300.

Goodman, L. A., & Kruskal, W. H. (1972). Measures of association for cross classifications, IV: Simplification of asymptotic variances. Journal of the American Statistical Association, 67, 415-421.

See Also

kits_itemfit() for infit, outfit and the item-rest correlation.

Examples

betas <- list(a1 = c(-1, 0), a2 = c(0, 1), a3 = 0.5, a4 = -0.5, a5 = 0)
X <- kits_sim(seq(-3, 3, length.out = 500), betas, seed = 1)
X[, "a5"] <- rep(0:1, 250)   # a5 is unrelated to the others
item <- kits_item(X)
rs <- kits_item_restscore(X, item)
rs

# Observed against expected gamma; off the line = misfit
p <- plot(rs)
if (interactive()) p

Description

kits_item() calibrates in three steps, and each step is also a function: kits_stats() counts the sufficient statistics (n_ig, persons with a score of at least g on item i; n_br, persons with raw score r in item pattern b), kits_cml() maximizes the conditional likelihood of the PCM from these counts, and kits_thresholds() gives the threshold of every step with its SE. They give the numbers of item$stats, item$fit and coef(item).

Usage

kits_stats(data, fixed_params = NULL, ...)

## S3 method for class 'kits_stats'
print(x, n = 6, ...)

kits_cml(stats)

kits_thresholds(fit)

Arguments

Details

Details: kits_algorithm("cml") and tutorial_algorithms/01_calibration.html; the models tutorial (tutorial_models/kits_models.html), sections 2, 3 and 5.

Value

• kits_stats(): a kits_stats, a list that prints briefly. Its elements: items (the items, in the order of sort()); steps (one row per step, item_id, item_score (the step g) and n (n_ig)); ⁠item patterns⁠ (one row per item pattern, pattern_id, items (a list of item ids), n (persons) and max_raw); raw (one row per item pattern and raw score 0 to max_raw, pattern_id, raw and n (n_br)); fixed (the fixed parameters of the items in the counts, or NULL) and left_out (the fixed parameters of the fixed items left out, or NULL); n_persons (the number of person-waves) and info (see kits_info()).

• kits_cml(): a kits_fit, with coef (item_id, item_score, beta, SE_beta), est (beta, acov.beta, nll), inputs (design, method = "CML", n_persons, left_out) and optim (the convergence record).

• kits_thresholds(): a table with one row per step: item_id, item_score, beta, beta_se, thr, thr_se.

See Also

kits_item() (all three steps in one call), kits_algorithm().

Examples

betas <- list(a1 = c(-1, 0), a2 = c(0, 1), a3 = 0.5, a4 = -0.5)
X <- kits_sim(seq(-3, 3, length.out = 400), betas, seed = 1)
X[1:100, "a4"] <- NA   # two item patterns

# 1 the sufficient statistics
stats <- kits_stats(X)
stats
stats$steps

# 2 the CML
fit <- kits_cml(stats)
fit
coef(fit)

# 3 the thresholds
thresholds <- kits_thresholds(fit)
thresholds

# The same numbers are in the calibration
identical(stats$steps, kits_item(X)$stats$steps)

Description

One row per item: the D of its milestone step, the age at which a share of the children pass it, the age at which the norm median reaches its D, its sex DIF and its stem. The table keeps the norm (summary numbers, no child's data), so plot() draws the growth curves with the items (type = "growth", one panel per domain) or the developmental ladder (type = "ladder").

Usage

kits_item_table(
  thr,
  norms = NULL,
  data = NULL,
  dif = NULL,
  stems = NULL,
  rp = 0.5,
  dif_cut = 0.3,
  step = 1
)

## S3 method for class 'kits_item_table'
plot(
  x,
  type = c("growth", "ladder"),
  items = NULL,
  ages = c(3, 6, 9, 12, 18, 24, 36, 48, 60, 72, 84),
  age_ticks = AGE_TICKS,
  y_range = NULL,
  ...
)

Arguments

Details

Details: vignette("kits-advanced", package = "kits"), sections 7.3 to 7.5 and 10.9.

Value

A kits_item_table, a data.frame with one row per item; attr(, "norm") keeps the norm, attr(, "rp") the RP; with data, the diagnostics list the items with perfect separation by age (their age is only known between the oldest child who fails and the youngest who passes). Its columns:

• D: the threshold of the pass step (item_score == step), on the scale of the norm.

• step: the pass step, only when step is not 1 for every item.

• domain, column: the domain of the item and its column of the ladder (default the domain).

• age50 (age75, ... for another rp): the age at which a share rp pass, from data.

• DIF: "none", "favors girls", "favors boys" or "inconsistent", from dif.

• stem: the item stem (any language), from stems; the item id when not given.

• age_reach, below_range, above_range, empirical, x: the place on the growth chart (the empirical age when there is one, else the age at which the norm median reaches D); only with norms.

Examples

set.seed(1)
age <- runif(800, 3, 24)
D <- 20 + 15 * log(age) + rnorm(800, 0, 3)
norm <- kits_norms(D, age, ages = 3:24, degrees = c(3, 2, 1, 1),
                   by = data.frame(domain = rep("lan", 800)))
thr <- data.frame(item_id = c("a1", "a2", "a3", "a4"), item_score = 1, thr = c(40, 55, 65, 60),
                  domain = "lan")
pass <- sapply(c(40, 55, 65, 60), \(b) rbinom(800, 1, plogis((D - b) / 3)))
colnames(pass) <- thr$item_id
resp <- data.frame(visit_id = 1:800, age_m = age, wave_m = round(age), pass)
dif <- data.frame(item_id = c("a2", "a3", "a4"),
                  DIF = c("favors girls", "favors boys", "inconsistent"))
stems <- c(a1 = "Lifts head", a2 = "Says two words", a3 = "Names colours",
           a4 = "Points to pictures")
item_tab <- kits_item_table(thr, norm, data = resp, dif = dif, stems = stems)
item_tab

# A 0-4 item whose pass is a score of 3 or more
thr4 <- rbind(thr, data.frame(item_id = "a5", item_score = 1:4, thr = c(30, 45, 58, 70),
                              domain = "lan"))
kits_item_table(thr4, norm, step = c(a5 = 3))

# No norm: D and the observed pass ages from the responses only
kits_item_table(thr, data = resp)
p <- plot(item_tab)
p <- plot(item_tab, type = "ladder", ages = c(6, 12, 18))
if (interactive()) p

Description

For each item, the infit and outfit mean squares of the residuals under the PCM (expected value 1; above 1 more random, below 1 more predictable than the model expects) and the item-rest correlation rir (weighted mean over item patterns). By default the residuals are conditional on the raw score within the item pattern (Christensen, Kreiner & Mesbah, 2013), so no ability estimate is needed; persons with a zero or a perfect score are left out.

Usage

kits_itemfit(data, item, type = c("conditional", "wle"), ...)

## S3 method for class 'kits_itemfit'
plot(
  x,
  type = c("both", "infit", "outfit"),
  items = NULL,
  range = c(0.6, 1.4),
  ...
)

Arguments

Details

Details: tutorial_algorithms/05_checks.html.

Value

A data.frame (class kits_itemfit) with one row per item: item_id, n (responses used), pvalue (the mean score as a share of the maximum), rir, infit, outfit, and flag, against the range 0.6 to 1.4 (Wright & Linacre, 1994):

• "underfit": infit or outfit above 1.4 (it wins when an item is also below 0.6).

• "overfit": otherwise, infit or outfit below 0.6.

• "ok": both within 0.6 to 1.4, the limits included; NA when infit and outfit are NA.

References

Christensen, K. B., Kreiner, S., & Mesbah, M. (Eds.). (2013). Rasch models in health. ISTE and Wiley.

Wright, B. D., & Linacre, J. M. (1994). Reasonable mean-square fit values. Rasch Measurement Transactions, 8(3), 370.

Examples

betas <- list(a1 = c(-1, 0), a2 = c(0, 1), a3 = 0.5, a4 = -0.5, a5 = 0)
X <- kits_sim(seq(-3, 3, length.out = 400), betas, seed = 1)
X[, "a5"] <- sample(0:1, 400, replace = TRUE)   # a5 is pure noise
item <- kits_item(X)
fit <- kits_itemfit(X, item)
fit
identical(fit$infit, item$itemfit$infit)   # kits_item() keeps the same table

# At each person's WLE: lower on short forms
kits_itemfit(X, item, type = "wle")

# Infit and outfit of each item, the acceptable range shaded
p <- plot(fit)
p <- plot(fit, type = "outfit", range = c(0.5, 1.5))
if (interactive()) p

Description

Estimates a cohort link in two ways that do not use the screened common items, and compares the converted values at chosen theta with the main link (Kolen & Brennan, 2014): same-age groups at the shared waves (a latent normal per cohort and wave, item parameters fixed), and a concurrent CML calibration of the stacked data of both cohorts. Details: the models tutorial (tutorial_models/kits_models.html), section 7, and vignette("kits-advanced", package = "kits"), section 10.7.

Usage

kits_link_check(
  link,
  item_from,
  item_to,
  X_from,
  X_to,
  persons = NULL,
  theta = NULL,
  tol = 0.2,
  persons_from = NULL,
  persons_to = NULL
)

## S3 method for class 'kits_link_check'
print(x, digits = 2, ...)

Arguments

Value

A kits_link_check: a list with

• methods: one row per method: method, intercept, slope, basis (what it rests on).

• at: one row per method and theta: theta, method, value, diff, se_method, and with draws se_link, z and z_both.

• waves: one row per shared wave (NULL when none): n, latent mean, sd and their SEs of each cohort (⁠_from⁠, ⁠_to⁠), and converged.

• concurrent: the concurrent kits_item(); lines: the lines of the separate calibrations on its scale.

• from_scale, to_scale, settings (tol), diagnostics (see kits_check()) and info (see kits_info()).

References

Kolen, M. J., & Brennan, R. L. (2014). Test equating, scaling, and linking (3rd ed.). Springer. doi:10.1007/978-1-4939-0317-7

Examples

# Two cohorts measured at 36 months; items a4 to a7 are common
betas <- lapply(seq(-3, 3, length.out = 10), function(b) b + c(-0.5, 0.5))
names(betas) <- paste0("a", 1:10)
set.seed(1)
wave <- rep(c(24, 36, 36, 48), each = 400)
theta <- 2 * log(wave / 24) + rnorm(1600)
young <- kits_sim(theta[1:800], betas[1:7], prefix = "y", seed = 1)
old <- kits_sim(theta[801:1600], betas[4:10], prefix = "o", seed = 2)
persons <- data.frame(visit_id = c(rownames(young), rownames(old)), wave_m = wave)
item_young <- kits_item(young, scale = "young")
item_old <- kits_item(old, scale = "old")
link <- kits_linking(item_old, item_young, n_boot = 100)
chk <- kits_link_check(link, item_old, item_young, old, young, persons = persons)
chk

Description

The four steps of kits_linking() as functions of their own: kits_link_points() (the points), kits_link_screen() (one round of screening), kits_link_line() (the mean/sigma line) and kits_link_error() (the item-resampling linking error). Piped in this order they give the same link as kits_linking(..., n_boot = ). Details: kits_algorithm("link") and tutorial_algorithms/03_linking.html.

Usage

kits_link_points(from, to, step = NULL, to_scale = NULL)

kits_link_screen(
  points,
  cut = 2,
  spread = c("sd", "mad", "se"),
  unit = c("step", "item"),
  from_scale = NULL,
  to_scale = NULL
)

kits_link_line(screened)

kits_link_error(link, n_boot = 200, seed = 1)

Arguments

Value

• kits_link_points(): a kits_link_points, one row per point, id, item, from, to (and step, domain, se_from, se_to when available).

• kits_link_screen(): a kits_link_screen, the points with resid, z, flagged and dropped.

• kits_link_line(): a kits_link (see kits_linking()) with NA linking errors.

• kits_link_error(): the link with intercept_error, slope_error, n_failed, draws and vcov.

See Also

kits_linking() (all four steps in one call), kits_convert().

Examples

# Two calibrations with common items a3, a4, a5
betas <- list(a1 = -2, a2 = -1, a3 = c(-0.5, 0.5), a4 = 0, a5 = c(0.5, 1.5), a6 = 2, a7 = 3)
young <- kits_sim(rnorm(500, 0), betas[1:5], seed = 1)
old <- kits_sim(rnorm(500, 2), betas[3:7], prefix = "q", seed = 2)
item_young <- kits_item(young, scale = "young cohort")
item_old <- kits_item(old, scale = "old cohort")

points <- kits_link_points(item_old, item_young)   # 1 the points
screened <- kits_link_screen(points)               # 2 one round of screening
link <- kits_link_line(screened)                   # 3 the line
link <- kits_link_error(link, n_boot = 200, seed = 1)  # 4 the linking error
link

# Your own points: point 8 is shifted and dropped
own <- data.frame(id = paste0("p", 1:8), item = paste0("p", 1:8),
                  from = c(-2, -1, 0, 1, 2, 3, 0.5, 1.5),
                  to = c(-1, 0, 1, 2, 3, 4, 1.5, 5.5))
kits_link_screen(own, from_scale = "x", to_scale = "y", spread = "mad")$dropped

Description

Fits a straight mean/sigma line, new value = intercept + slope x old value, with one round of screening, and (with n_boot > 0) a linking error that resamples whole items. Between two calibrations each common step is one point; to an external scale each anchor item is one point (its pass step on this scale against its tau). Several domains can share one line. The four steps are also functions of their own (kits_link_steps). Details: kits_algorithm("link") and tutorial_algorithms/03_linking.html.

Usage

kits_linking(
  from,
  to,
  step = NULL,
  cut = 2,
  n_boot = 0,
  seed = 1,
  to_scale = NULL,
  spread = c("sd", "mad", "se"),
  unit = c("step", "item")
)

Arguments

Value

A kits_link: a list that prints briefly (print.kits_link()). Its elements:

• intercept, slope: the line after screening (the B and A of Kolen & Brennan, 2014).

• intercept_error, slope_error, n_failed: the linking error (NA when n_boot = 0).

• draws, vcov (only when n_boot > 0): the resampled lines and their 2 x 2 covariance.

• intercept0, slope0: the line before screening.

• n: the number of points.

• dropped: the dropped points.

• points: one row per point: id, item, from, to, resid, resid_final, z, flagged, dropped (and se_from, se_to, step, domain when they apply).

• settings: cut, n_boot, seed, spread, unit, kind, step (and key).

• from_scale, to_scale: the scales the line converts from and to (NA when not given).

• diagnostics: the checks of the link (see kits_check()); info: see kits_info().

• n_items and, between two calibrations, items_total.

• domains (with domains): domain, n, intercept, and the shared slope.

References

Kolen, M. J., & Brennan, R. L. (2014). Test equating, scaling, and linking (3rd ed.). Springer. doi:10.1007/978-1-4939-0317-7

Examples

# Each cohort answers part of the items; a3, a4, a5 are common
betas <- list(a1 = -2, a2 = -1, a3 = c(-0.5, 0.5), a4 = 0, a5 = c(0.5, 1.5), a6 = 2, a7 = 3)
young <- kits_sim(rnorm(500, 0), betas[1:5], seed = 1)
old <- kits_sim(rnorm(500, 2), betas[3:7], prefix = "q", seed = 2)
item_old <- kits_item(old, scale = "old cohort")
item_young <- kits_item(young, scale = "young cohort")
link <- kits_linking(item_old, item_young, n_boot = 200)
link

# The older cohort's theta on the younger cohort's scale
s_old <- kits_subj(old, item_old)
head(kits_convert(s_old, link))

# To D through anchor items, two domains sharing one line
set.seed(1)
steps <- data.frame(item_id = paste0("a", 1:12), item_score = 1, thr = rnorm(12),
                    domain = rep(c("lan", "cog"), each = 6))
anchors <- data.frame(item_id = steps$item_id, tau = 64 + 7 * steps$thr + rnorm(12, 0, 0.5))
d_link <- kits_linking(steps, anchors, n_boot = 200)
d_link
kits_convert(c(-1, 0, 1), d_link, from = "my scale")

Description

The methods of R's own generics, so the usual names work:

• confint(): confidence intervals. For a kits_item(), of each threshold: thr +/- z thr_se (normal; the SE is in coef(item)). For a link (kits_linking()), of the intercept and the slope: with bootstrap draws (n_boot > 0) the quantiles of the draws, otherwise none (NA). For a kits_dif(), of each item's dif: dif +/- z SE, with the SE from the covariances of the two calibrations (attr(, "se")).

• vcov(): the covariance matrix of the step parameters beta of a kits_item() (rows and columns item:score; 0 for fixed steps).

• update(): fit again with some settings changed, for example update(norm, degrees = c(4, 3, 2, 1)) or update(item, scale = "lan M03"). The call recorded in kits_info() is run again in the calling environment, so the data must still be there under the same name (results keep no data); data given by value (recorded as ⁠<data>⁠) cannot be refitted.

• logLik(), nobs(), and so AIC() and BIC(): for a kits_norms(), the log-likelihood of the shash fit (summed over the groups of a norm by group), its number of coefficients and of person-waves; for a kits_item(), the conditional log-likelihood of the CML, the number of free step parameters and of person-waves. Compare only fits of the same data (for example norms of different degrees).

• simulate(): responses from the step parameters of a kits_item() at given theta, as kits_sim() does; kits_sim() needs no calibration.

Usage

## S3 method for class 'kits_item'
confint(object, parm = NULL, level = 0.95, ...)

## S3 method for class 'kits_link'
confint(object, parm = c("intercept", "slope"), level = 0.95, ...)

## S3 method for class 'kits_dif'
confint(object, parm = NULL, level = 0.95, ...)

## S3 method for class 'kits_item'
vcov(object, ...)

## S3 method for class 'kits_item'
logLik(object, ...)

## S3 method for class 'kits_item'
nobs(object, ...)

## S3 method for class 'kits_norms'
logLik(object, ...)

## S3 method for class 'kits_norms'
nobs(object, ...)

## S3 method for class 'kits_item'
simulate(object, nsim = 1, seed = NULL, theta, ...)

## S3 method for class 'kits_norms'
update(object, ...)

## S3 method for class 'kits_item'
update(object, ...)

Arguments

Value

confint(): a data.frame with the estimate, lower and upper. vcov(): a matrix. update(): the new result. logLik(): a logLik object. nobs(): a number. simulate(): a response matrix (a list of them when nsim > 1).

Examples

betas <- list(a1 = c(-1, 0), a2 = c(0, 1), a3 = 0.5, a4 = -0.5)
X <- kits_sim(rnorm(400, 0, 1.5), betas, seed = 1)
item <- kits_item(X, scale = "lan M03")
confint(item)
vcov(item)[1:2, 1:2]
logLik(item)
AIC(item)
X_new <- simulate(item, theta = rnorm(5), seed = 2)
X_new

set.seed(1)
age <- runif(600, 3, 36)
D <- 20 + 15 * log(age) + rnorm(600, 0, 3)
norm <- kits_norms(D, age, ages = 3:36, degrees = c(3, 2, 1, 1))
lower <- update(norm, degrees = c(2, 1, 1, 1))
AIC(norm, lower)
nobs(norm)

Description

From the 1st percentile of age in the first wave to the 99th percentile of age in the last wave, both ends rounded outward to by (by default half a month). Pass only the waves to be normed (screen them first with kits_norm_screen()).

Usage

kits_norm_ages(age_m, wave_m, probs = c(0.01, 0.99), by = 0.5)

Arguments

Details

Details: kits_algorithm("norm_screen") and tutorial_algorithms/04_norms.html.

Value

A vector of ages, which can be passed directly to ages of kits_norms().

Examples

set.seed(1)
age <- c(rnorm(200, 12, 0.6), 7, 8, rnorm(200, 24, 0.6))
wave_m <- c(rep(12, 202), rep(24, 200))
range(kits_norm_ages(age, wave_m))

# The same from a kits_subj with age_m and wave_m columns
X <- kits_sim(rnorm(402), list(a1 = c(-1, 0), a2 = 0.5, a3 = -0.5), seed = 1)
persons <- data.frame(visit_id = rownames(X), age_m = age, wave_m = wave_m)
s <- kits_subj(X, kits_item(X), persons = persons)
range(kits_norm_ages(s))

Description

Computes, for each wave, the percentage of children at the lowest score of that wave (D rounded to 3 decimals), and leaves a wave out of the norms when it reaches cut. Waves piled at the ceiling still go into the norms.

Usage

kits_norm_screen(d, wave_m, cohort = NULL, cut = 20, ...)

## S3 method for class 'kits_norm_screen'
plot(x, ...)

Arguments