Package {gtheoryr}

gtheoryr: Simple Generalizability Theory for R

Description

Small, beginner-friendly helpers for estimating variance components in simple generalizability theory designs. The package currently supports:

• a crossed persons-by-items design via gstudy_pxi()

• generic balanced crossed designs with one or more facets via gstudy_crossed()

• a crossed persons-by-items-by-facet design via gstudy_pxif()

• convenience wrappers for raters and occasions via gstudy_pxir() and gstudy_pxio()

• convenience wrappers for persons-by-items-by-raters-by-occasions designs via gstudy_pxiro()

• a nested items-within-person design via gstudy_nested_ip()

• simple D-studies via dstudy_pxi(), dstudy_crossed(), dstudy_pxif(), dstudy_pxir(), dstudy_pxio(), dstudy_pxiro(), and dstudy_nested_ip()

• table extractors via anova_table(), mean_squares_table(), variance_components_table(), and variance_proportions_table()

Extract Tables from a G-study Object

Description

Convenience extractors for sums of squares, mean squares, and variance components from a "gstudy_gtheoryr" object.

Usage

anova_table(x, ...)

mean_squares_table(x, ...)

variance_components_table(x, ...)

Arguments

Value

A data frame.

Examples

scores <- data.frame(
  person = rep(c("P1", "P2", "P3"), each = 3),
  item = rep(c("I1", "I2", "I3"), times = 3),
  score = c(8, 7, 9, 5, 4, 6, 7, 6, 8)
)

gs <- gstudy_pxi(scores, person = "person", item = "item", score = "score")

anova_table(gs)
mean_squares_table(gs)
variance_components_table(gs)

Parametric Bootstrap Uncertainty for a Crossed G-study

Description

Parametric Bootstrap Uncertainty for a Crossed G-study

Usage

bootstrap_gstudy(
  gstudy,
  B = 1000,
  design_levels = NULL,
  conf = 0.95,
  seed = NULL,
  negative = c("error", "zero")
)

Arguments

Value

A list with percentile intervals (estimate, lower, upper, n_valid), replicate estimates, B, conf, method, adjusted_components and replicate_adjustments. Simulates all random facets at their original sample sizes, then refits ANOVA. Proposed design_levels affect D-study results only. Refit negative components are truncated to zero and counted. Raw variance estimates are retained in replicate output; coefficient estimates use the truncated components. Undefined coefficients remain NA and are counted. This Gaussian parametric method is not the nonparametric bias-corrected procedure described by Tong and Brennan. Coverage is approximate, especially near zero variance boundaries. Simple nested designs are not supported.

References

Tong and Brennan (2007), doi:10.1177/0013164407301533.

Check Data Before Fitting a G-study

Description

Reports missing scores and identifiers, duplicate cells, missing crossed cells and insufficient facet levels without fitting a model or dropping rows.

Usage

check_gstudy_design(
  data,
  person,
  facets,
  score,
  design = c("crossed", "nested")
)

Arguments

Value

A list with valid, issues, level_counts and diagnostic row/cell counts. Missing cells refer to the Cartesian product of observed nonmissing levels.

Examples

d <- data.frame(p = rep(1:3, each = 2), i = rep(1:2, 3), y = 1:6)
check_gstudy_design(d, "p", "i", "y")

Compare a Grid of Candidate D-study Designs

Description

Compare a Grid of Candidate D-study Designs

Usage

dstudy_grid(gstudy, candidates, negative = c("error", "zero"))

Arguments

Value

A data frame with facet counts, observations per person, error variances, G and Phi coefficients and SEMs. At most 100000 combinations. Undefined coefficients (zero universe variance and zero error) are NA.

Design Study for a Nested Items-within-Person Design

Description

Computes a simple reliability summary for a proposed number of nested items per person.

Usage

dstudy_nested_ip(gstudy, n_items = gstudy$n_items)

Arguments

Value

An object of class "dstudy_gtheoryr".

Examples

nested_scores <- data.frame(
  person = c("P1", "P1", "P2", "P2", "P3", "P3"),
  item = c("P1_I1", "P1_I2", "P2_I1", "P2_I2", "P3_I1", "P3_I2"),
  score = c(8, 6, 5, 4, 9, 7)
)

gs_nested <- gstudy_nested_ip(
  nested_scores,
  person = "person",
  item = "item",
  score = "score"
)
dstudy_nested_ip(gs_nested, n_items = 4)

Design Study for a Crossed Persons-by-Items Design

Description

Computes relative error, absolute error, a generalizability coefficient, and a phi coefficient for a proposed number of items.

Usage

dstudy_pxi(gstudy, n_items = gstudy$n_items)

Arguments

Value

An object of class "dstudy_gtheoryr".

Examples

scores <- data.frame(
  person = rep(c("P1", "P2", "P3"), each = 3),
  item = rep(c("I1", "I2", "I3"), times = 3),
  score = c(8, 7, 9, 5, 4, 6, 7, 6, 8)
)

gs <- gstudy_pxi(scores, person = "person", item = "item", score = "score")
dstudy_pxi(gs, n_items = 6)

Design Study for a Crossed Persons-by-Items-by-Facet Design

Description

Computes relative and absolute error variances, the generalizability coefficient, and the phi coefficient for the current or proposed number of items and levels of a third crossed facet such as raters, occasions, or forms.

Usage

dstudy_pxif(gstudy, n_items = gstudy$n_items, n_facets = gstudy$n_facets)

Arguments

Value

An object of class "dstudy_gtheoryr".

Examples

scores <- expand.grid(
  person = c("P1", "P2", "P3"),
  item = c("I1", "I2"),
  rater = c("R1", "R2"),
  stringsAsFactors = FALSE
)
scores$score <- c(8, 7, 7, 6, 5, 4, 6, 5, 7, 6, 8, 7)

gs <- gstudy_pxif(
  scores,
  person = "person",
  item = "item",
  facet = "rater",
  score = "score",
  facet_name = "rater"
)

dstudy_pxif(gs)

D-study Wrappers for Common Three-Facet Designs

Description

Convenience wrappers around dstudy_pxif() for crossed persons-by-items-by-raters and crossed persons-by-items-by-occasions designs.

Usage

dstudy_pxir(gstudy, n_items = gstudy$n_items, n_raters = gstudy$n_facets)

dstudy_pxio(gstudy, n_items = gstudy$n_items, n_occasions = gstudy$n_facets)

Arguments

Value

An object of class "dstudy_gtheoryr".

Examples

scores_rater <- expand.grid(
  person = c("P1", "P2", "P3"),
  item = c("I1", "I2"),
  rater = c("R1", "R2"),
  stringsAsFactors = FALSE
)
scores_rater$score <- c(8, 7, 7, 6, 5, 4, 6, 5, 7, 6, 8, 7)

gs_rater <- gstudy_pxir(
  scores_rater,
  person = "person",
  item = "item",
  rater = "rater",
  score = "score"
)
dstudy_pxir(gs_rater)

scores_occasion <- expand.grid(
  person = c("P1", "P2", "P3"),
  item = c("I1", "I2"),
  occasion = c("T1", "T2"),
  stringsAsFactors = FALSE
)
scores_occasion$score <- c(8, 8, 7, 7, 5, 5, 6, 6, 7, 7, 8, 8)

gs_occasion <- gstudy_pxio(
  scores_occasion,
  person = "person",
  item = "item",
  occasion = "occasion",
  score = "score"
)
dstudy_pxio(gs_occasion)

Examine Gains from Increasing One Facet at a Time

Description

Examine Gains from Increasing One Facet at a Time

Usage

dstudy_sensitivity(
  gstudy,
  design_levels = NULL,
  increment = 1,
  negative = c("error", "zero")
)

Arguments

Value

One row per facet with old and new counts, added observations per person, new coefficients and changes from the baseline G and Phi. This is a local comparison conditional on the fitted variance components.

Decompose D-study Error by Variance Component

Description

Decompose D-study Error by Variance Component

Usage

error_budget(gstudy, design_levels = NULL, negative = c("error", "zero"))

Arguments

Value

A data frame of component estimates, divisors, and contributions to relative and absolute error variance. All facets are random.

Examples

d <- data.frame(p = rep(1:3, each = 2), i = rep(1:2, 3), y = 1:6)
gs <- gstudy_pxi(d, "p", "i", "y")
error_budget(gs, negative = "zero")

Generic Crossed G-study and D-study Helpers

Description

gstudy_crossed() estimates ANOVA mean squares and variance components for a balanced crossed random-effects design with persons as the object of measurement and one or more additional facets.

dstudy_crossed() computes relative and absolute error variances, the generalizability coefficient, and the phi coefficient for the current or proposed levels of the additional facets.

Usage

gstudy_crossed(data, person, facets, score, facet_labels = facets)

dstudy_crossed(gstudy, design_levels = gstudy$design_levels)

Arguments

Value

For gstudy_crossed(), an object of class "gstudy_gtheoryr".

For dstudy_crossed(), an object of class "dstudy_gtheoryr".

Examples

scores <- read.csv(
  system.file("extdata", "crossed_scores_rater_occasion.csv", package = "gtheoryr"),
  stringsAsFactors = FALSE
)

gs <- gstudy_crossed(
  scores,
  person = "person",
  facets = c("item", "rater", "occasion"),
  score = "score",
  facet_labels = c("item", "rater", "occasion")
)
gs
dstudy_crossed(gs)

Estimate Variance Components for a Nested Items-within-Person Design

Description

Estimates ANOVA mean squares and variance components for a simple balanced nested design in which each person has their own set of items.

Usage

gstudy_nested_ip(data, person, item, score)

Arguments

Value

An object of class "gstudy_gtheoryr".

Examples

nested_scores <- data.frame(
  person = c("P1", "P1", "P2", "P2", "P3", "P3"),
  item = c("P1_I1", "P1_I2", "P2_I1", "P2_I2", "P3_I1", "P3_I2"),
  score = c(8, 6, 5, 4, 9, 7)
)

gs_nested <- gstudy_nested_ip(
  nested_scores,
  person = "person",
  item = "item",
  score = "score"
)
gs_nested

Estimate Variance Components for a Crossed Persons-by-Items Design

Description

Estimates ANOVA mean squares and variance components for a fully crossed random-effects persons-by-items design.

Usage

gstudy_pxi(data, person, item, score)

Arguments

Value

An object of class "gstudy_gtheoryr".

Examples

scores <- data.frame(
  person = rep(c("P1", "P2", "P3"), each = 3),
  item = rep(c("I1", "I2", "I3"), times = 3),
  score = c(8, 7, 9, 5, 4, 6, 7, 6, 8)
)

gs <- gstudy_pxi(scores, person = "person", item = "item", score = "score")
gs

Estimate Variance Components for a Crossed Persons-by-Items-by-Facet Design

Description

Estimates ANOVA mean squares and variance components for a fully crossed random-effects design with persons crossed with items and one additional facet such as raters, occasions, or forms.

Usage

gstudy_pxif(data, person, item, facet, score, facet_name = facet)

Arguments

Value

An object of class "gstudy_gtheoryr".

Examples

scores <- expand.grid(
  person = c("P1", "P2", "P3"),
  item = c("I1", "I2"),
  rater = c("R1", "R2"),
  stringsAsFactors = FALSE
)
scores$score <- c(8, 7, 7, 6, 5, 4, 6, 5, 7, 6, 8, 7)

gs <- gstudy_pxif(
  scores,
  person = "person",
  item = "item",
  facet = "rater",
  score = "score",
  facet_name = "rater"
)
gs

Convenience Wrappers for Common Three-Facet Designs

Description

Convenience wrappers around gstudy_pxif() for crossed persons-by-items-by-raters and crossed persons-by-items-by-occasions designs.

Usage

gstudy_pxir(data, person, item, rater, score)

gstudy_pxio(data, person, item, occasion, score)

Arguments

Value

An object of class "gstudy_gtheoryr".

Examples

scores_rater <- expand.grid(
  person = c("P1", "P2", "P3"),
  item = c("I1", "I2"),
  rater = c("R1", "R2"),
  stringsAsFactors = FALSE
)
scores_rater$score <- c(8, 7, 7, 6, 5, 4, 6, 5, 7, 6, 8, 7)

gstudy_pxir(
  scores_rater,
  person = "person",
  item = "item",
  rater = "rater",
  score = "score"
)

scores_occasion <- expand.grid(
  person = c("P1", "P2", "P3"),
  item = c("I1", "I2"),
  occasion = c("T1", "T2"),
  stringsAsFactors = FALSE
)
scores_occasion$score <- c(8, 8, 7, 7, 5, 5, 6, 6, 7, 7, 8, 8)

gstudy_pxio(
  scores_occasion,
  person = "person",
  item = "item",
  occasion = "occasion",
  score = "score"
)

Helpers for a Crossed Persons-by-Items-by-Raters-by-Occasions Design

Description

Convenience wrappers around gstudy_crossed() and dstudy_crossed() for a design with persons, items, raters, and occasions.

Usage

gstudy_pxiro(data, person, item, rater, occasion, score)

dstudy_pxiro(gstudy, n_items = gstudy$design_levels[["item"]],
  n_raters = gstudy$design_levels[["rater"]],
  n_occasions = gstudy$design_levels[["occasion"]])

Arguments

Value

For gstudy_pxiro(), an object of class "gstudy_gtheoryr".

For dstudy_pxiro(), an object of class "dstudy_gtheoryr".

Examples

scores <- read.csv(
  system.file("extdata", "crossed_scores_rater_occasion.csv", package = "gtheoryr"),
  stringsAsFactors = FALSE
)

gs <- gstudy_pxiro(
  scores,
  person = "person",
  item = "item",
  rater = "rater",
  occasion = "occasion",
  score = "score"
)
gs
dstudy_pxiro(gs)

Find the Least Cost Candidate Meeting a Reliability Target

Description

Find the Least Cost Candidate Meeting a Reliability Target

Usage

optimize_dstudy(
  gstudy,
  candidates,
  target = 0.8,
  coefficient = c("phi", "g"),
  costs = NULL,
  observation_cost = 1,
  budget = Inf,
  negative = c("error", "zero")
)

Arguments

Value

A list with feasible, best (all minimum-cost ties), evaluated and target. Cost equals sum(costs * counts) + observation_cost * prod(counts), expressed per person. Without costs, cost is the number of observations. The optimum is only over the supplied candidate grid. No feasible design returns a zero-row best table rather than an invented recommendation.

References

Meyer, Liu and Mashburn (2014), doi:10.1177/0013164413508774.

Construct Approximate Measurement Intervals Around Mean Scores

Description

Construct Approximate Measurement Intervals Around Mean Scores

Usage

score_interval(
  gstudy,
  scores,
  design_levels = NULL,
  decision = c("absolute", "relative"),
  conf = 0.95,
  negative = c("error", "zero")
)

Arguments

Value

A data frame with score, sem, lower and upper. Normal-theory intervals use a common SEM and treat estimated variance components as known. They are not conditional SEMs, prediction intervals or coefficient confidence intervals. Relative intervals exclude systematic facet effects and should not be used for absolute cut-score decisions. Bounds are not clipped.

Report Relative and Absolute Standard Errors of Measurement

Description

Report Relative and Absolute Standard Errors of Measurement

Usage

sem_gtheory(gstudy, design_levels = NULL, negative = c("error", "zero"))

Arguments

Value

A two-row data frame with decision, error_variance and sem, on the mean-score scale. SEM is the square root of the corresponding D-study error variance, not the sampling standard error of a reliability coefficient.

Simulate a Balanced Gaussian Crossed G-study

Description

Simulate a Balanced Gaussian Crossed G-study

Usage

simulate_gstudy(
  n_persons,
  design_levels,
  variance_components,
  mean = 0,
  seed = NULL
)

Arguments

Value

A long-format data frame with person, facet columns and score. Independent Gaussian effects are shared by observations with the same factor combination. The highest interaction and cell error are confounded. Scores are continuous and unbounded; no ordinal or binary model is implied.

Examples

d <- simulate_gstudy(20, c(item = 4),
                     c(person = 2, item = 0.2, residual = 1), seed = 42)
gstudy_crossed(d, "person", "item", "score")

Variance Component Proportions from a G-study

Description

Returns the estimated variance components together with their proportion of the sum of estimated variance components.

Usage

variance_proportions_table(x, ...)

Arguments

Value

A data frame.

Examples

scores <- read.csv(
  system.file("extdata", "crossed_scores_rater_occasion.csv", package = "gtheoryr"),
  stringsAsFactors = FALSE
)

gs <- gstudy_pxiro(
  scores,
  person = "person",
  item = "item",
  rater = "rater",
  occasion = "occasion",
  score = "score"
)

variance_proportions_table(gs)