Package {boundedHill}

Bayesian bounded logistic regression

Description

The boundedHill package fits Bernoulli and grouped binomial regression models of the form

P(Y_i = 1 \mid x_i) = \delta_0 + (\delta_1 - \delta_0) \operatorname{logit}^{-1}(x_i^\top \beta),

with 0 \leq \delta_0, \delta_1 \leq 1.

Author(s)

Maintainer: Minji Lee leeminji@unist.ac.kr [copyright holder]

Authors:

• Minji Lee leeminji@unist.ac.kr [copyright holder]

• Chang Hyeong Lee [copyright holder]

• Ryung S. Kim [copyright holder]

Beta shapes from a prior mean and standard deviation

Description

Convert a prior mean and standard deviation for an asymptote into the two Beta shape parameters used by bh_prior. With mean m and standard deviation s, the shapes are a = m k and b = (1 - m) k with k = m(1 - m)/s^2 - 1.

Usage

bh_beta_moments(mean, sd)

Arguments

Value

A named numeric vector c(shape1, shape2).

Examples

bh_beta_moments(0.10, 0.12)   # baseline response around 10 percent
bh_beta_moments(0.85, 0.12)   # plateau around 85 percent
bh_prior(delta0 = bh_beta_moments(0.2, 0.1),
         delta1 = bh_beta_moments(0.7, 0.1))

Control Gibbs sampling

Description

Set the number of iterations, warmup, thinning, and chains used by bh_fit.

Usage

bh_control(iter = 4000L, warmup = 2000L, thin = 1L, chains = 4L)

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

Arguments

Value

An object of class bh_control: a list with integer elements iter, warmup, thin and chains. The print method returns its input invisibly.

Examples

bh_control(iter = 2000, warmup = 1000, chains = 2)

Diagnose computation and data-range information

Description

Check MCMC convergence and whether the data identify the bounded logistic curve. Diagnostics use the original, unmodified posterior chains. Endpoints fixed by the prior are excluded from convergence flags. Undefined diagnostics on other parameters are flagged rather than treated as evidence of convergence. Switching of the endpoint labels can give poor diagnostics for the raw parameters even when the fitted probabilities (see predict.bounded_reg) mix well.

Usage

bh_diagnose(object, rhat_threshold = 1.01, ess_threshold = 400)

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

Arguments

Value

An object of class bh_diagnostic: a list with the MCMC summary table (mcmc), the names of fixed and flagged parameters, the design-matrix condition number, posterior quantiles of the logistic gate span and of the endpoint gap delta1 - delta0, the posterior probability that delta0 > delta1, the number of endpoint-order switches per chain, and a character vector of warning messages.

Examples

set.seed(1)
x <- seq(-3, 3, length.out = 60)
y <- rbounded_binom(-0.5 + 1.2 * x, delta0 = 0.1, delta1 = 0.8)
fit <- bh_fit(y ~ x, data = data.frame(x = x, y = y),
              control = bh_control(iter = 400, warmup = 200, chains = 2),
              seed = 1)
bh_diagnose(fit)

Fit Bayesian bounded logistic regression

Description

Fit a bounded logistic regression model to Bernoulli or grouped binomial outcomes using a fully Gibbs posterior sampler. The right-hand side of formula is processed by model.matrix, so continuous predictors, factors, interactions, and standard transformations are supported.

Usage

bh_fit(
  formula,
  data,
  prior = bh_prior(),
  control = bh_control(),
  seed = NULL,
  subset,
  na.action = stats::na.omit,
  contrasts = NULL
)

Arguments

Value

An object of class bounded_reg: a list containing the call, formula, model matrix, response counts, prior, control settings, chain seeds, and the posterior draws (a posterior draws_array in element draws). Use the methods in bounded_reg-methods, plot.bounded_reg and bh_diagnose to work with it.

References

Polson, N. G., Scott, J. G., and Windle, J. (2013). Bayesian inference for logistic models using Polya-Gamma latent variables. Journal of the American Statistical Association, 108(504), 1339–1349. doi:10.1080/01621459.2013.829001

Lee, M., Lee, C. H., and Kim, R. S. A novel Bayesian phase 1/2 design incorporating the Hill equation. Manuscript in preparation.

Lee, M., Lee, C. H., and Kim, R. S. boundedHill: Bayesian logistic regression with lower and upper asymptotes in R. Manuscript in preparation.

Examples

set.seed(1)
x <- seq(-3, 3, length.out = 60)
y <- rbounded_binom(-0.5 + 1.2 * x, delta0 = 0.1, delta1 = 0.8)
fit <- bh_fit(y ~ x, data = data.frame(x = x, y = y),
              control = bh_control(iter = 400, warmup = 200, chains = 2),
              seed = 1)
summary(fit)

# Grouped binomial data
grouped <- data.frame(dose = c(50, 100, 150, 200, 250),
                      resp = c(2, 11, 14, 15, 14), n = c(15, 20, 21, 22, 20))
fit2 <- bh_fit(cbind(resp, n - resp) ~ log(dose / 150), data = grouped,
               control = bh_control(iter = 400, warmup = 200, chains = 2),
               seed = 2)
coef(fit2)

Pointwise log-likelihood draws

Description

Compute the binomial log likelihood of each observation under each posterior draw, for example for use with the loo package.

Usage

bh_log_lik(object, newdata = NULL)

Arguments

Value

A numeric matrix with posterior draws in rows and observations in columns.

Examples

set.seed(1)
x <- seq(-3, 3, length.out = 60)
y <- rbounded_binom(-0.5 + 1.2 * x, delta0 = 0.1, delta1 = 0.8)
fit <- bh_fit(y ~ x, data = data.frame(x = x, y = y),
              control = bh_control(iter = 400, warmup = 200, chains = 2),
              seed = 1)
ll <- bh_log_lik(fit)
dim(ll)

Extract posterior draws

Description

Extract posterior draws

Usage

bh_posterior_draws(object, format = c("draws_array", "matrix", "data.frame"))

Arguments

Value

Posterior draws in the requested format, with the asymptotes delta0, delta1 and the regression coefficients beta_* as variables.

Examples

set.seed(1)
x <- seq(-3, 3, length.out = 60)
y <- rbounded_binom(-0.5 + 1.2 * x, delta0 = 0.1, delta1 = 0.8)
fit <- bh_fit(y ~ x, data = data.frame(x = x, y = y),
              control = bh_control(iter = 400, warmup = 200, chains = 2),
              seed = 1)
draws <- bh_posterior_draws(fit, format = "matrix")
dim(draws)

Draw from the posterior predictive distribution

Description

Draw from the posterior predictive distribution

Usage

bh_posterior_predict(
  object,
  newdata = NULL,
  trials = NULL,
  ndraws = 100L,
  seed = NULL
)

Arguments

Value

An integer matrix with predictive draws in rows and observations in columns.

Examples

set.seed(1)
x <- seq(-3, 3, length.out = 60)
y <- rbounded_binom(-0.5 + 1.2 * x, delta0 = 0.1, delta1 = 0.8)
fit <- bh_fit(y ~ x, data = data.frame(x = x, y = y),
              control = bh_control(iter = 400, warmup = 200, chains = 2),
              seed = 1)
yrep <- bh_posterior_predict(fit, ndraws = 10, seed = 4)
dim(yrep)

Specify priors for bounded logistic regression

Description

Construct independent Beta priors for the two endpoints and a multivariate normal prior for regression coefficients. No ordering constraint is imposed. A scalar fixes an endpoint; two positive values specify Beta shapes, which can be obtained from a prior mean and standard deviation with bh_beta_moments. The defaults put the baseline response (delta0) at mean 0.10 and the plateau (delta1) at mean 0.85, both with standard deviation 0.12, and give each regression coefficient an independent normal prior with mean 0 and standard deviation 2.

Usage

bh_prior(
  delta0 = bh_beta_moments(0.1, 0.12),
  delta1 = bh_beta_moments(0.85, 0.12),
  beta_mean = 0,
  beta_sd = 2,
  beta_cov = NULL
)

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

Arguments

Details

delta0 and delta1 are the limits as the linear predictor tends to minus and plus infinity, respectively; they need not be the lower and upper probability bounds. Swapping the endpoints and negating beta leaves the likelihood unchanged, so symmetric priors produce a label-symmetric posterior. Asymmetric priors fix the labels.

Value

An object of class bh_prior: a list with elements delta0, delta1, beta_mean, beta_sd and beta_cov. The print method returns its input invisibly.

Examples

bh_prior()
# Asymptotes from mean and SD, wider N(0, 4^2) priors for the logistic part
bh_prior(delta0 = bh_beta_moments(0.15, 0.10),
         delta1 = bh_beta_moments(0.75, 0.10), beta_sd = 4)
# Standard logistic regression: both asymptotes fixed
bh_prior(delta0 = 0, delta1 = 1)

Bounded logistic probabilities

Description

Evaluate delta0 + (delta1 - delta0) * plogis(eta). No ordering of the two endpoints is required.

Usage

bounded_probability(eta, delta0, delta1)

Arguments

Value

A numeric vector of probabilities. Inputs must be scalar or have a common length.

Examples

bounded_probability(c(-2, 0, 2), delta0 = 0.1, delta1 = 0.8)

Plot a bounded logistic regression fit

Description

Draw MCMC trace plots, marginal posterior densities, or fitted probabilities with credible bands against the observed proportions.

Usage

## S3 method for class 'bounded_reg'
plot(x, type = c("fitted", "trace", "density"), variables = NULL, ...)

Arguments

Value

The input object, invisibly. Called for its side effect of drawing a plot.

Examples

set.seed(1)
x <- seq(-3, 3, length.out = 60)
y <- rbounded_binom(-0.5 + 1.2 * x, delta0 = 0.1, delta1 = 0.8)
fit <- bh_fit(y ~ x, data = data.frame(x = x, y = y),
              control = bh_control(iter = 400, warmup = 200, chains = 2),
              seed = 1)
plot(fit)
plot(fit, type = "trace", variables = c("delta0", "delta1"))

Methods for bounded logistic regression fits

Description

Standard S3 methods for objects of class bounded_reg returned by bh_fit: printing, posterior summaries, point estimates, predictions, fitted values, and posterior predictive simulation.

Usage

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

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

## S3 method for class 'summary.bounded_reg'
print(x, digits = 3L, ...)

## S3 method for class 'bounded_reg'
coef(object, statistic = c("mean", "median"), ...)

## S3 method for class 'bounded_reg'
predict(
  object,
  newdata = NULL,
  type = c("response", "linear", "draws"),
  level = 0.95,
  ...
)

## S3 method for class 'bounded_reg'
fitted(object, ...)

## S3 method for class 'bounded_reg'
simulate(object, nsim = 1L, seed = NULL, newdata = NULL, trials = NULL, ...)

Arguments

Value

• print: the input object, invisibly.

• summary: an object of class summary.bounded_reg containing a table of posterior summaries and MCMC diagnostics.

• coef: a named numeric vector containing both asymptotes and the regression coefficients.

• predict: a data frame with columns estimate, median, lower and upper for type = "response" or "linear"; a matrix of posterior probability draws (draws in rows, observations in columns) for type = "draws".

• fitted: a numeric vector of posterior mean probabilities.

• simulate: a data frame with one column per simulation (sim_1, sim_2, ...) and one row per observation.

Examples

set.seed(1)
x <- seq(-3, 3, length.out = 60)
y <- rbounded_binom(-0.5 + 1.2 * x, delta0 = 0.1, delta1 = 0.8)
fit <- bh_fit(y ~ x, data = data.frame(x = x, y = y),
              control = bh_control(iter = 400, warmup = 200, chains = 2),
              seed = 1)
fit
summary(fit)
coef(fit)
predict(fit, newdata = data.frame(x = c(-2, 0, 2)))
head(fitted(fit))
sims <- simulate(fit, nsim = 2, seed = 3)

Generate bounded binomial outcomes

Description

Simulate binomial counts whose success probability follows the bounded logistic curve bounded_probability.

Usage

rbounded_binom(eta, size = 1L, delta0 = 0, delta1 = 1)

Arguments

Value

A numeric vector of integer-valued counts.

Examples

set.seed(1)
rbounded_binom(c(-2, 0, 2), size = 10, delta0 = 0.1, delta1 = 0.8)