Type: Package
Title: Bayesian Estimation and Validation for Small-N Designs with Rater Bias
Version: 0.1.0
Description: Approximate Bayesian inference and Monte Carlo validation for small-N repeated-measures designs with two time points and two raters. The package is intended for applications in which sample size is limited and the observed outcome may be affected by rater-specific bias. User-supplied data are standardised into a common long-format structure. Pre-post effects are analysed using difference scores in a linear model with a rater indicator as covariate. Posterior summaries for the regression coefficients are obtained from a large-sample normal approximation centred at the least-squares estimate with plug-in covariance under a flat improper prior. Evidence for a non-zero pre-post effect, adjusted for rater differences, is summarised using a BIC-based approximation to the Bayes factor for comparison between models with and without the pre-post effect. Monte Carlo validation uses design quantities estimated from the observed data, including sample size, mean pre-post change, and second-rater additive discrepancy, and summarises inferential performance in terms of bias, root mean squared error, credible interval coverage, posterior tail probabilities, and mean Bayes factor values. For background on the BIC approximation and Bayes factors, see Schwarz (1978) <doi:10.1214/aos/1176344136> and Kass and Raftery (1995) <doi:10.1080/01621459.1995.10476572>.
License: GPL-3
Encoding: UTF-8
RoxygenNote: 7.3.3
Depends: R (≥ 4.1.0)
Imports: stats, graphics
Suggests: testthat (≥ 3.0.0), knitr, rmarkdown
Config/testthat/edition: 3
NeedsCompilation: no
Packaged: 2026-04-22 12:33:34 UTC; irene
Author: Irene Gianeselli ORCID iD [aut, cre] (affiliation: Free University of Bozen-Bolzano), Andrea Bosco ORCID iD [aut] (affiliation: University of Bari Aldo Moro), Demis Basso ORCID iD [aut] (affiliation: Free University of Bozen-Bolzano)
Maintainer: Irene Gianeselli <irene.gianeselli@unibz.it>
Repository: CRAN
Date/Publication: 2026-04-23 20:10:09 UTC

Run the babebi workflow on user-supplied data

Description

Fits the babebi model to observed data and, optionally, performs Monte Carlo validation calibrated on the observed design.

Usage

babebi(
  data,
  id,
  time,
  rater,
  outcome,
  time_order = NULL,
  rater_order = NULL,
  validate = TRUE,
  R = 1000,
  N = NULL,
  delta = NULL,
  bias_r2 = NULL,
  n_draws = 4000,
  seed = NULL
)

Arguments

data

A data frame in long format.

id

Unquoted column name identifying subjects or a character string.

time

Unquoted column name identifying time points or a character string.

rater

Unquoted column name identifying raters or a character string.

outcome

Unquoted column name containing the observed score or a character string.

time_order

Optional character vector of length 2 giving the order of the time factor: baseline first, follow-up second.

rater_order

Optional character vector of length 2 giving the order of the rater factor: reference rater first, second rater second.

validate

Logical; if TRUE, run Monte Carlo validation after model fitting.

R

Number of Monte Carlo repetitions when validate = TRUE.

N

Optional override for the sample size used in validation.

delta

Optional override for the pre-post effect used in validation.

bias_r2

Optional override for the additive bias of the second rater used in validation.

n_draws

Number of posterior draws used in model fitting.

seed

Optional integer seed for reproducibility.

Value

A named list containing:

fit

A babebi_fit object returned by fit_model().

validation

A babebi_validation object returned by montecarlo_from_data() when validate = TRUE, otherwise NULL.

call

The original function call.

Examples

dat <- data.frame(
  id = rep(1:4, each = 4),
  time = rep(c("pre", "pre", "post", "post"), times = 4),
  rater = rep(c("r1", "r2"), times = 8),
  y = c(
    3.0, 3.2, 3.8, 4.0,
    2.9, 3.1, 3.5, 3.7,
    3.4, 3.6, 4.0, 4.1,
    3.1, 3.3, 3.9, 4.0
  )
)

res <- babebi(
  data = dat,
  id = id,
  time = time,
  rater = rater,
  outcome = y,
  time_order = c("pre", "post"),
  rater_order = c("r1", "r2"),
  validate = TRUE,
  R = 100,
  n_draws = 500,
  seed = 123
)

print(res$fit)
summary(res$fit)
plot(res$fit)
print(res$validation)

Extract design parameters for Monte Carlo calibration

Description

Internal helper used to estimate sample size, mean pre-post change, and second-rater additive discrepancy from standardised user-supplied data for Monte Carlo calibration.

Usage

extract_design(data)

Arguments

data

A data frame returned by prepare_data, with columns id, time, rater, and y.

Value

A named list containing:

N

Number of unique subjects.

delta

Estimated mean pre-post change, averaged across raters.

bias_r2

Estimated mean additive discrepancy of the second rater relative to the reference rater, averaged across subjects and time points.

time_levels

The two ordered time levels used in the data.

rater_levels

The two ordered rater levels used in the data.

Fit the babebi model to observed data

Description

Fits the current babebi model to a fully observed 2 (time) x 2 (rater) repeated-measures dataset. Estimation is based on difference scores and a linear model including a rater indicator as covariate.

Usage

fit_model(
  data,
  id,
  time,
  rater,
  outcome,
  time_order = NULL,
  rater_order = NULL,
  n_draws = 4000,
  seed = NULL
)

Arguments

data

A data frame in long format.

id

Unquoted column name identifying subjects or a character string.

time

Unquoted column name identifying time points or a character string.

rater

Unquoted column name identifying raters or a character string.

outcome

Unquoted column name containing the observed score or a character string.

time_order

Optional character vector of length 2 giving the order of the time factor: baseline first, follow-up second.

rater_order

Optional character vector of length 2 giving the order of the rater factor: reference rater first, second rater second.

n_draws

Number of posterior draws used for approximation.

seed

Optional integer seed used to initialise the random-number generator for posterior sampling.

Details

Posterior draws are obtained from a large-sample normal approximation to the posterior of the regression coefficients under an improper flat prior.

Value

A named list of class babebi_fit.

Examples

dat <- data.frame(
  id = rep(1:4, each = 4),
  time = rep(c("pre", "pre", "post", "post"), times = 4),
  rater = rep(c("r1", "r2"), times = 8),
  y = c(
    3.0, 3.2, 3.8, 4.0,
    2.9, 3.1, 3.5, 3.7,
    3.4, 3.6, 4.0, 4.1,
    3.1, 3.3, 3.9, 4.0
  )
)

fit <- fit_model(
  data = dat,
  id = id,
  time = time,
  rater = rater,
  outcome = y,
  time_order = c("pre", "post"),
  rater_order = c("r1", "r2"),
  n_draws = 500,
  seed = 123
)

print(fit)
summary(fit)
plot(fit)

Run Monte Carlo calibration from user-supplied data

Description

Uses observed data to estimate the sample size, mean pre-post change, and mean additive discrepancy of the second rater for the Monte Carlo engine, then runs a single Monte Carlo validation cell.

Usage

montecarlo_from_data(
  data,
  id,
  time,
  rater,
  outcome,
  time_order = NULL,
  rater_order = NULL,
  R = 1000,
  N = NULL,
  delta = NULL,
  bias_r2 = NULL,
  seed = NULL
)

Arguments

data

A data frame in long format.

id

Unquoted column name identifying subjects or a character string.

time

Unquoted column name identifying time points or a character string.

rater

Unquoted column name identifying raters or a character string.

outcome

Unquoted column name containing the observed score or a character string.

time_order

Optional character vector of length 2 giving the order of the time factor: baseline first, follow-up second.

rater_order

Optional character vector of length 2 giving the order of the rater factor: reference rater first, second rater second.

R

Number of Monte Carlo repetitions.

N

Optional override for the sample size used in the simulation. Defaults to the observed number of subjects.

delta

Optional override for the pre-post effect used in the simulation. Defaults to the value estimated from the data.

bias_r2

Optional override for the additive bias of the second rater. Defaults to the value estimated from the data.

seed

Optional integer seed used to initialise the random-number generator for simulation.

Value

A one-row data frame of class babebi_validation with Monte Carlo performance summaries. The attributes calibrated_design and call store the design estimated from the observed data and the original call.

Examples

dat <- data.frame(
  id = rep(1:4, each = 4),
  time = rep(c("pre", "pre", "post", "post"), times = 4),
  rater = rep(c("r1", "r2"), times = 8),
  y = c(
    3.0, 3.2, 3.8, 4.0,
    2.9, 3.1, 3.5, 3.7,
    3.4, 3.6, 4.0, 4.1,
    3.1, 3.3, 3.9, 4.0
  )
)

mc <- montecarlo_from_data(
  data = dat,
  id = id,
  time = time,
  rater = rater,
  outcome = y,
  time_order = c("pre", "post"),
  rater_order = c("r1", "r2"),
  R = 100,
  seed = 123
)

print(mc)

Plot a babebi fit object

Description

Plot a babebi fit object

Usage

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

Arguments

x

An object of class babebi_fit.

...

Further arguments passed to or from other methods.

Value

No return value, called for its side effects.

Standardise user data for babebi

Description

Internal helper used to convert user-supplied data into the format required by the estimation and Monte Carlo engine.

Usage

prepare_data(
  data,
  id,
  time,
  rater,
  outcome,
  time_order = NULL,
  rater_order = NULL
)

Arguments

data

A data frame in long format.

id

Unquoted column name identifying subjects or a character string.

time

Unquoted column name identifying time points or a character string.

rater

Unquoted column name identifying raters or a character string.

outcome

Unquoted column name containing the observed score or a character string.

time_order

Optional character vector of length 2 specifying the order of the time factor (e.g., c("pre", "post")).

rater_order

Optional character vector of length 2 specifying the order of the rater factor (reference rater first).

Details

The function assumes a fully observed 2 (time) × 2 (rater) repeated-measures design. Each subject must contribute exactly one observation for each combination of time point and rater.

If time_order or rater_order are not provided, the ordering of factor levels follows the order of appearance in the data. Users are encouraged to specify these arguments explicitly when the ordering carries substantive meaning (e.g., pre vs post).

Value

A data frame with four standardised columns: id, time, rater, and y.

Print a babebi fit object

Description

Print a babebi fit object

Usage

## S3 method for class 'babebi_fit'
print(x, digits = 3, ...)

Arguments

x

An object of class babebi_fit.

digits

Number of digits to print.

...

Further arguments passed to or from other methods.

Value

The input object, invisibly.

Print a babebi validation object

Description

Print a babebi validation object

Usage

## S3 method for class 'babebi_validation'
print(x, digits = 3, ...)

Arguments

x

An object of class babebi_validation.

digits

Number of digits to print.

...

Further arguments passed to or from other methods.

Value

The input object, invisibly.

Print a summary of a babebi fit object

Description

Print a summary of a babebi fit object

Usage

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

Arguments

x

An object of class summary.babebi_fit.

...

Further arguments passed to or from other methods.

Value

The input object, invisibly.

Resolve a column name supplied as symbol or character string

Description

Internal helper for functions that accept either unquoted column names or character strings.

Usage

resolve_colname(expr, env = parent.frame())

Arguments

expr

A captured expression representing a column name.

env

The environment in which the expression should be resolved.

Value

A character string of length 1.

Run one Monte Carlo validation cell

Description

Internal helper used to evaluate the analytical babebi model under a single simulation condition defined by sample size, pre-post effect, and rater bias.

Usage

run_cell(N, delta, bias_r2, R)

Arguments

N

Integer sample size.

delta

Numeric pre-post effect for the reference rater.

bias_r2

Numeric additive discrepancy for the second rater.

R

Integer number of Monte Carlo repetitions.

Details

The current implementation simulates pre-post difference scores directly for the reference rater and the second rater, then applies the same analytical linear-model logic used in fit_model().

Value

A one-row data frame with columns N, delta, bias_r2, bias, rmse, coverage, ppos_mean, and bf_mean.

Summarise a babebi fit object

Description

Summarise a babebi fit object

Usage

## S3 method for class 'babebi_fit'
summary(object, digits = 3, ...)

Arguments

object

An object of class babebi_fit.

digits

Number of digits to print.

...

Further arguments passed to or from other methods.

Value

An object of class summary.babebi_fit.