Package 'babebi'

Title: Bayesian Estimation and Validation for Small-N Designs with Rater Bias
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>.
Authors: Irene Gianeselli [aut, cre] (ORCID: <https://orcid.org/0000-0002-8689-3035>, affiliation: Free University of Bozen-Bolzano), Andrea Bosco [aut] (ORCID: <https://orcid.org/0000-0002-9458-3993>, affiliation: University of Bari Aldo Moro), Demis Basso [aut] (ORCID: <https://orcid.org/0000-0002-4595-3513>, affiliation: Free University of Bozen-Bolzano)
Maintainer: Irene Gianeselli <[email protected]>
License: GPL-3
Version: 0.1.0
Built: 2026-05-23 09:26:43 UTC
Source: https://github.com/cran/babebi

Help Index

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)

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.

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.

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.