Package 'csemGT'

Title: Conditional Standard Error of Measurement in Generalizability Theory
Description: Estimates the per-person conditional standard error of measurement (CSEM) under the persons-by-items single-facet crossed design of Generalizability Theory, following Brennan (1998) <doi:10.1177/014662169802200401>. Implements three estimators of the relative error variance (full, large_a, uncorrelated) and the closed-form absolute error variance, with both analytical and item-resampling bootstrap sampling variances, quadratic smoothing of CSEMs on observed score, D-study extrapolation, and base-graphics plotting.
Authors: René Gempp [aut, cre, cph] (ORCID: <https://orcid.org/0000-0002-0427-6894>)
Maintainer: René Gempp <[email protected]>
License: GPL (>= 3)
Version: 1.0.0
Built: 2026-06-02 10:39:03 UTC
Source: https://github.com/rgempp/csemgt

Help Index


Coerce a 'csem' object to a data frame

Description

Returns one of the two wide-format tables carried by a 'csem' object: the person-level table ('by = "person"', the default) or the score-level table ('by = "score"').

Usage

## S3 method for class 'csem'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  by = c("person", "score"),
  ...
)

Arguments

x

A 'csem' object.

row.names, optional

Accepted for consistency with the [base::as.data.frame()] generic; both are ignored.

by

One of '"person"' (the default) or '"score"'. '"person"' returns the per-person '$estimates' table; '"score"' returns the '$by_score' table.

...

Currently ignored.

Value

A data frame: '$estimates' when 'by = "person"', '$by_score' when 'by = "score"'.

See Also

[by_score()] for the score-level table through a dedicated accessor; [coef.csem()] for the variance components.

Examples

set.seed(1)
d <- matrix(rbinom(60 * 12, 1, 0.5), nrow = 60)
fit <- csem_gt(d, error_type = "absolute")
head(as.data.frame(fit))                 # by = "person"
head(as.data.frame(fit, by = "score"))

Extract the score-level table from a 'csem' object

Description

'by_score()' returns the score-level summary table of a 'csem' object: one row per distinct observed score, with the estimation columns collapsed to that score. It is the accessor-style equivalent of the '$by_score' component and of 'as.data.frame(x, by = "score")'.

Usage

by_score(x, ...)

## S3 method for class 'csem'
by_score(x, ...)

Arguments

x

A 'csem' object.

...

Currently ignored; present for S3 extensibility.

Value

A data frame with one row per distinct observed score.

See Also

[as.data.frame.csem()] for the person-level and score-level tables through the 'as.data.frame' interface; [coef.csem()] for the variance components.

Examples

set.seed(1)
d <- matrix(rbinom(60 * 12, 1, 0.5), nrow = 60)
fit <- csem_gt(d, error_type = "absolute")
head(by_score(fit))

Extract the variance components of a 'csem' object

Description

Returns the 'variance_components' list of a 'csem' object: the ANOVA table, the person / item / residual variance components, the population-level error variances and SEMs, and the reliability-like coefficients. For the GT paradigm this is the natural set of fitted "coefficients", so it is what 'coef()' returns.

Usage

## S3 method for class 'csem'
coef(object, ...)

Arguments

object

A 'csem' object.

...

Currently ignored.

Value

The 'variance_components' list of 'object'. See [csem_gt()] for its structure.

See Also

[by_score()] and [as.data.frame.csem()] for the estimation tables.

Examples

set.seed(1)
d <- matrix(rbinom(60 * 12, 1, 0.5), nrow = 60)
fit <- csem_gt(d, error_type = "absolute")
coef(fit)$reliability_coefficients

Conditional standard errors of measurement under Generalizability Theory

Description

Estimates conditional standard errors of measurement (CSEMs) for the univariate, single-facet, persons-by-items (p x i) crossed design following Brennan (1998). Returns absolute and relative error variances, three estimators of the relative error variance, closed-form analytical sampling variances, optional item-resampling bootstrap, quadratic smoothing, and D-study extrapolation.

Usage

csem_gt(
  data,
  method = c("full", "large_a", "uncorrelated"),
  error_type = c("absolute", "relative"),
  conditioning = "total",
  n_items_D = NULL,
  bootstrap = FALSE,
  R = 1000L,
  bootstrap_type = c("item", "person"),
  ci_method = c("percentile", "basic", "normal", "bca"),
  ci_level = 0.95,
  seed = NULL,
  return_analytical = TRUE,
  smoother = c("polynomial", "none"),
  smoother_args = list(degree = 2),
  exclude_extremes = FALSE,
  cutpoint = NULL,
  truncate_vc = FALSE,
  truncate_negative_error_var = FALSE,
  boot_keep_replicates = FALSE,
  na_action = c("listwise", "fail", "pairwise"),
  verbose = FALSE,
  ...
)

Arguments

data

Matrix or data.frame, N persons by J items, all numeric and complete (the single-facet crossed design requires balanced data).

method

Character vector; one or more of '"full"', '"large_a"', '"uncorrelated"'. Default: all three. Only applies when 'error_type' includes '"relative"'.

error_type

Character vector; one or both of '"absolute"', '"relative"'. Default: both.

conditioning

Either '"total"' (the per-person mean over items, i.e. 'rowMeans(data)') or a numeric vector of length N specifying an alternative conditioning variable. Default: '"total"'. In csemGT v1.0 'observed_score' and 'conditioning_value' coincide.

n_items_D

Integer; number of items for D-study extrapolation. Default: the number of observed items in 'data'.

bootstrap

Logical; if 'TRUE', a resampling bootstrap is run. Default: 'FALSE'.

R

Integer; number of bootstrap replications. Default: 1000.

bootstrap_type

One of '"item"' (default) or '"person"'. The item bootstrap is the default following Brennan (1998) and matches the 'gtcsem' Stata package.

ci_method

One of '"percentile"', '"basic"', '"normal"', '"bca"'. Default: '"percentile"'. In csemGT v1.0 the confidence intervals are Wald (normal-approximation) intervals; replicate-based methods are deferred to a later release, and a non-'"normal"' request is satisfied with the normal interval (the requested and effective methods are both recorded).

ci_level

Confidence level. Default: 0.95.

seed

Integer or 'NULL'; seed for the bootstrap. The bootstrap engines restore the prior RNG state on exit, so a non-'NULL' seed does not leak into the caller's session.

return_analytical

Logical; if 'TRUE' (default), analytical SEs are computed even when 'bootstrap = TRUE'.

smoother

One of '"polynomial"' (default) or '"none"'.

smoother_args

List of smoother arguments. Default: 'list(degree = 2)'.

exclude_extremes

Logical; if 'TRUE', floor and ceiling cases are excluded from the smoother fit (their unsmoothed CSEMs remain, but their 'smoothed_csem.*' values are 'NA'). Default: 'FALSE'.

cutpoint

Numeric or 'NULL'; cutpoint lambda for the mastery dependability coefficient Phi(lambda), on the same mean-per-item scale as 'observed_score'. Default: 'NULL' (not computed).

truncate_vc

Logical; truncate negative ANOVA variance components to zero. Default: 'FALSE'.

truncate_negative_error_var

Logical; truncate negative per-person error variances to zero before taking the CSEM square root. Default: 'FALSE'.

boot_keep_replicates

Logical; retain the bootstrap replicate summary in the output. Default: 'FALSE'.

na_action

One of '"listwise"' (default) or '"fail"'. '"pairwise"' is not supported for the GT paradigm.

verbose

Logical; emit progress messages during the bootstrap.

...

Reserved for forward compatibility; currently ignored.

Details

The analytical standard errors returned in the 'se.analytic.*' columns are **original contributions of the csemGT package** (derived in Gempp, 2026); they are not derived in Brennan (1998), which focuses on the point estimators. Users requiring fully verified inferential coverage should prefer the bootstrap standard errors ('bootstrap = TRUE').

The 'relative_uncorrelated' estimator is the per-person absolute error variance minus 'sigma^2(i)/I'. When 'sigma^2(Delta_p) < sigma^2(i)/I' the estimated relative error variance is negative and, under the default 'truncate_negative_error_var = FALSE', **its conditional SEM is 'NaN' at that score rather than truncated to zero**. This is expected behaviour, not a defect: it marks scores at which the estimator admits no non-negative variance, typically the extreme scores. Set 'truncate_negative_error_var = TRUE' to clip such variances to zero (the CSEM is then zero at those scores).

Value

An object of class 'csem'. Key components:

'estimates'

Data frame, one row per person, wide format. Identifier columns 'person_id', 'observed_score', 'conditioning_value', 'group_size', 'extreme', followed by 'cov_xim' and the estimation columns 'csem.<estimator>', 'csem_var.<estimator>', 'se.analytic.<estimator>' / 'se.boot.<estimator>', 'ci_low.*' / 'ci_up.*', and 'smoothed_csem.<estimator>'.

'by_score'

Data frame, one row per distinct observed score, the score-level summary of the estimation columns.

'variance_components'

ANOVA table, the three variance components, population-level error variances/SEMs, and the reliability-like coefficients ('erho2', 'phi', 'phi_lambda').

'smooth_fits'

Per-estimator smoother diagnostics, or 'NULL' when 'smoother = "none"'.

'bootstrap'

Bootstrap metadata, or 'NULL' when 'bootstrap = FALSE'.

See ['new_csem'] for the full structure.

References

Brennan, R. L. (1998). Raw-score conditional standard errors of measurement in generalizability theory. Applied Psychological Measurement, 22(4), 307-331. doi:10.1177/014662169802200401

Gempp, R. (2026). Analytical sampling variances for per-person estimators of conditional standard errors of measurement in Generalizability Theory. PsyArXiv working paper. doi:10.31234/osf.io/6qg9r_v1

Examples

set.seed(1)
d <- matrix(rbinom(60 * 12, 1, 0.5), nrow = 60)
fit <- csem_gt(d, error_type = "absolute")
head(fit$estimates)
fit$variance_components$reliability_coefficients

The csemGT colour palette

Description

Returns the package colour palette: one colour per CSEM estimator ('absolute', 'relative_full', 'relative_large_a', 'relative_uncorrelated') plus a neutral 'structural' colour used for grid lines and other non-data elements. The hues are taken from the Okabe-Ito qualitative palette, which is colourblind-safe. [plot.csem()] uses this palette by default; it is exported so the same colours can be reused elsewhere, for example to keep a manuscript figure consistent with the package plots.

Usage

csem_palette(which = NULL)

Arguments

which

Optional character vector of palette entry names to return. If 'NULL' (the default), the full named vector is returned.

Value

A named character vector of hex colour strings.

See Also

[plot.csem()], which uses this palette.

Examples

csem_palette()
csem_palette("relative_full")
csem_palette(c("absolute", "relative_full"))

Simulated ITED-like dichotomous responses (Brennan, 1998)

Description

A simulated person-by-item matrix of dichotomously scored responses built to mimic the summary characteristics of the ITED Vocabulary Test example analysed in Brennan (1998, p. 314; Figure 1, p. 315). It is intended as a self-contained illustration dataset for the single-facet, person-by-item crossed Generalizability Theory design implemented in csem_gt.

Usage

iowa_like

Format

An integer matrix with 3000 rows (persons) and 40 columns (items). Each entry is 0 or 1 (incorrect / correct). Columns are named item01, item02, ..., item40.

Details

These are simulated data, not the original ITED data. The real Iowa Tests of Educational Development Vocabulary data described by Feldt, Forsyth, Ansley, and Alnot (1993, 1994) are not publicly available. iowa_like was generated from a Rasch (1PL) model whose parameters were calibrated so that the ANOVA-based mean absolute and relative error variances reproduce the values Brennan reports: σˉ2(Δ).00514\bar{\sigma}^2(\Delta) \approx .00514 and σˉ2(δ).00475\bar{\sigma}^2(\delta) \approx .00475. The matrix uses A=3000A = 3000 simulated persons, matching Brennan's own use of 3,000 generated examinees for the absolute-error illustration. The full, seeded generation script is in data-raw/make_iowa_like.R.

Source

Simulated to match the summary statistics of the ITED Vocabulary Test example in Brennan, R. L. (1998). Raw-score conditional standard errors of measurement in generalizability theory. Applied Psychological Measurement, 22(4), 307-331. The underlying instrument is described in Feldt, L. S., Forsyth, R. A., Ansley, T. N., & Alnot, S. D. (1993, 1994). Iowa Tests of Educational Development. Riverside.

References

Brennan, R. L. (1998). Raw-score conditional standard errors of measurement in generalizability theory. Applied Psychological Measurement, 22(4), 307-331.

Examples

data(iowa_like)
dim(iowa_like)
iowa_like[1:5, 1:6]

## Relative conditional SEM, 'full' estimator (the default),
## reproducing the kind of dispersion seen in Brennan (1998),
## Figure 1b/1d.

fit <- csem_gt(iowa_like, error_type = "relative", method = "full")
fit
plot(fit)

Simulated IPIP-10-like Likert responses

Description

A simulated person-by-item matrix of Likert-scaled (1-5) responses built to mimic the qualitative features of a short, positively oriented Big-Five Conscientiousness subscale – in particular, the Conscientiousness items of the IPIP-50 inventory (Goldberg, 1992; Goldberg et al., 2006). It is intended as a self-contained illustration dataset for the polytomous Likert use case in the single-facet, person-by-item crossed Generalizability Theory design implemented in csem_gt.

Usage

ipip_like

Format

An integer matrix with 2000 rows (persons) and 10 columns (items). Each entry is an integer in {1,2,3,4,5}\{1, 2, 3, 4, 5\}. Columns are named item01, item02, ..., item10.

Details

These are simulated data, not real IPIP-50 responses. ipip_like was generated by drawing independent normal person, item, and residual effects under the random-effects model that Generalizability Theory assumes for the p×ip \times i design, and then rounding and clipping the resulting scores to the 1-5 Likert metric. The pre-truncation variance components are inflated to absorb the contraction induced by the clip-and-round step, so that the post-truncation ANOVA estimates approximate the targets σ2(p)0.434\sigma^2(p) \approx 0.434, σ2(i)0.136\sigma^2(i) \approx 0.136, and σ2(pi)1.000\sigma^2(pi) \approx 1.000, with generalizability coefficient Eρ20.81E\rho^2 \approx 0.81. These targets are representative of the Conscientiousness subscale of the IPIP-50 dataset distributed by the Open-Source Psychometrics Project (n.d.) and can be reproduced by any user with access to that public dataset via a one-way p×ip \times i ANOVA. The matrix uses A=2,000A = 2{,}000 simulated persons and I=10I = 10 items, with all items oriented positively (any reverse-keying is assumed already applied so that higher scores indicate higher Conscientiousness). The full, seeded generation script is in data-raw/make_ipip_like.R.

Source

Simulated to be broadly comparable to the Conscientiousness subscale of the IPIP-50 inventory, as administered in the public dataset of the Open-Source Psychometrics Project (https://openpsychometrics.org/_rawdata/). The underlying instrument is described in Goldberg, L. R. (1992) and Goldberg, L. R., Johnson, J. A., Eber, H. W., Hogan, R., Ashton, M. C., Cloninger, C. R., & Gough, H. G. (2006).

References

Goldberg, L. R. (1992). The development of markers for the Big-Five factor structure. Psychological Assessment, 4(1), 26-42.

Goldberg, L. R., Johnson, J. A., Eber, H. W., Hogan, R., Ashton, M. C., Cloninger, C. R., & Gough, H. G. (2006). The International Personality Item Pool and the future of public-domain personality measures. Journal of Research in Personality, 40(1), 84-96.

Open-Source Psychometrics Project. (n.d.). Raw data. https://openpsychometrics.org/_rawdata/

Examples

data(ipip_like)
dim(ipip_like)
ipip_like[1:5, 1:6]


fit <- csem_gt(ipip_like, error_type = "relative", method = "full",
               smoother = "polynomial")
fit
plot(fit, plot_type = "both", cibands = "model")

Test whether an object is a 'csem' object

Description

Test whether an object is a 'csem' object

Usage

is.csem(x)

Arguments

x

Any R object.

Value

'TRUE' if 'x' inherits from '"csem"', 'FALSE' otherwise.

Examples

set.seed(1)
d <- matrix(rbinom(80 * 15, 1, 0.5), nrow = 80)
fit <- suppressMessages(csem_gt(d, error_type = "absolute"))
is.csem(fit)
is.csem(list())

Plot a 'csem' object

Description

Draws a Brennan-style plot of the per-person conditional standard error of measurement against the observed score, in base graphics, following the layout of the 'gtcsem_plot' Stata command. The per-person scatter is drawn from the '$estimates' table – one point per person, so that the within-score spread of the CSEM is visible – and the optional quadratic-smoother curve from the '$by_score' table.

Usage

## S3 method for class 'csem'
plot(
  x,
  plot_type = c("csem", "ci", "both"),
  error_types = NULL,
  method = NULL,
  show_smooth = TRUE,
  compare_methods = FALSE,
  compare_points = FALSE,
  cibands = c("person", "model"),
  asemethod = c("analytical", "bootstrap"),
  ci_level = NULL,
  theme = c("csem"),
  col = NULL,
  pch = 16,
  cex = NULL,
  lwd = 2,
  lty = 1,
  alpha = NULL,
  main = NULL,
  sub = NULL,
  xlab = NULL,
  ylab = NULL,
  ylim = NULL,
  xlim = NULL,
  add = FALSE,
  ...
)

Arguments

x

A 'csem' object.

plot_type

One of '"csem"' (the per-person scatter, the default), '"ci"' (confidence bands only), or '"both"'. Not used by the compare layout.

error_types

Character vector selecting the error type(s) to plot: '"absolute"', '"relative"', or both. Two error types are drawn as a side-by-side pair of panels. Defaults to the error types carried by 'x'.

method

Relative-error estimator to plot when 'error_types' includes '"relative"': '"full"', '"large_a"', or '"uncorrelated"'. Defaults to the first method carried by 'x'.

show_smooth

Logical; overlay the quadratic-smoother curve when it is available. Defaults to 'TRUE'.

compare_methods

Logical; overlay the three relative-error estimators on one panel with a legend. Defaults to 'FALSE'.

compare_points

Logical; in the compare layout ('compare_methods = TRUE'), also draw the per-person scatter for each estimator. Defaults to 'FALSE', which overlays the smoother curves alone.

cibands

Source of the confidence bands when 'plot_type' is '"ci"' or '"both"': '"person"' (per-person intervals collapsed to the score level) or '"model"' (a band around the quadratic fit).

asemethod

Sampling-variance source for the '"person"' bands: '"analytical"' or '"bootstrap"'. Ignored when 'cibands = "model"'.

ci_level

Confidence level for the bands. Defaults to the level stored in 'x'.

theme

Plot theme. csemGT ships a single own theme, '"csem"'.

col

Override colour for the plotted series. 'NULL' uses the theme palette. Not applied in the compare layout.

pch, cex, lwd, lty

Graphical parameters for the scatter points ('pch', 'cex') and the smoother curve ('lwd', 'lty').

alpha

Point transparency in '[0, 1]'. 'NULL' calibrates it to the number of plotted persons.

main, sub, xlab, ylab

Title, subtitle and axis labels. 'NULL' selects a sensible default; for 'plot_type' '"ci"' / '"both"' the default subtitle reports the confidence level and band source. In the side-by-side layout 'main' is not applied (each panel keeps its own title).

ylim, xlim

Axis limits. 'NULL' selects a sensible default; the side-by-side and compare layouts share one 'ylim' across series.

add

Logical; if 'TRUE', draw onto the current plot instead of opening a new one. Not supported with the side-by-side or compare layouts.

...

Additional graphical parameters passed to the underlying 'plot()' call.

Details

When 'plot_type' is '"ci"' or '"both"' a confidence-band ribbon is added. Two band sources are available through 'cibands':

* '"person"' (the default) draws csem^±zse^\widehat{csem} \pm z\, \widehat{se} around the by-score CSEM curve, using the per-person sampling SE of the CSEM. 'asemethod' selects whether that SE is the analytical or the bootstrap one; the bootstrap SE is only available when 'csem_gt()' was run with 'bootstrap = TRUE'. * '"model"' draws a band around the quadratic smoother. The per-person error variance is refit on the observed score and its square, and the SE of the mean fit is converted to the CSEM scale by the delta method. 'asemethod' is ignored for this source.

The confidence level is 'ci_level' (defaulting to the level stored in 'x'), so a level different from the one used at fitting time can be requested at plot time. The lower edge of every band is truncated at zero.

When two error types are requested ('error_types = c("absolute", "relative")') the two are drawn as a pair of panels sharing one y-axis, so the absolute and relative CSEMs are read on a common scale. Each panel keeps its own title; a user-supplied 'main' is not applied in this layout, and 'add = TRUE' is not supported.

When 'compare_methods = TRUE' the three relative-error estimators are overlaid on one panel with a legend, to compare their smoother curves directly. The per-person scatter is omitted by default – three clouds would not be legible – and added for every estimator by 'compare_points = TRUE'. Confidence bands are not available in this layout, 'add = TRUE' is not supported, and 'col' is not applied (each estimator keeps its palette colour).

Value

'x', invisibly.

See Also

[csem_palette()] for the colours used; [by_score()] and [as.data.frame.csem()] for the tables the plot is built from.

Examples

set.seed(1)
d <- matrix(rbinom(100 * 14, 1, 0.5), nrow = 100)
fit <- csem_gt(d, error_type = "absolute")
plot(fit)
plot(fit, plot_type = "both")

Print a 'csem' object

Description

Displays a 'csem' object as a sequence of console blocks mirroring the output of the 'gtcsem' Stata command: a header summarising the design, the ANOVA table, the D-study population error variances and standard errors of measurement, the reliability-like coefficients, the quadratic smoothing fits (when smoothing was applied), and the mean sampling variance of each estimator across persons.

Usage

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

Arguments

x

A 'csem' object.

...

Currently ignored; present for S3 consistency.

Value

'x', invisibly.

See Also

[summary.csem()] for the score-level table and global statistics; [coef.csem()] and [by_score()] for programmatic access to the underlying components.

Examples

set.seed(1)
d <- matrix(rbinom(80 * 15, 1, 0.5), nrow = 80)
fit <- csem_gt(d, cutpoint = 0.5)
print(fit)

Summarise a 'csem' object

Description

Produces a score-level summary of a 'csem' object. The returned object carries the full 'by_score' table augmented with two columns, 'cum_freq' (the cumulative proportion of persons at or below each observed score) and 'percentile' ('100 * cum_freq'), together with the population-level global statistics: the relative and absolute standard errors of measurement and their companion reliability-like coefficients (the generalizability coefficient 'E rho^2' and the dependability coefficient 'Phi').

Usage

## S3 method for class 'csem'
summary(object, ...)

Arguments

object

A 'csem' object.

...

Currently ignored; present for S3 consistency.

Details

The returned object retains every column of the original 'by_score' table; [print.summary.csem()] displays a curated subset.

Value

An object of class 'summary.csem': a list with components 'call', 'paradigm', 'methods', 'error_types', 'n_persons', 'n_items', 'global_stats' (a list with 'relative_sem', 'erho2', 'absolute_sem', 'phi') and 'by_score_summary' (the augmented 'by_score' table).

See Also

[print.csem()] for the full-object display; [by_score()] and [coef.csem()] for programmatic access to the underlying components.

Examples

set.seed(1)
d <- matrix(rbinom(80 * 15, 1, 0.5), nrow = 80)
fit <- csem_gt(d, error_type = "absolute")
s <- summary(fit)
s$global_stats
head(s$by_score_summary)