Package 'rstanemax'

The 'rstanemax' package.

Description

Perform sigmoidal Emax model fit using Stan without writing Stan model code.

Author(s)

Maintainer: Kenta Yoshida [email protected] (ORCID)

Authors:

• Danielle Navarro [email protected] (ORCID)

Other contributors:

• Trustees of Columbia University (src/init.cpp, tools/make_cc.R, R/stanmodels.R) [copyright holder]

References

Stan Development Team (2018). RStan: the R interface to Stan. R package version 2.18.2. http://mc-stan.org

See Also

Useful links:

• https://github.com/yoshidk6/rstanemax

• https://yoshidk6.github.io/rstanemax/

• Report bugs at https://github.com/yoshidk6/rstanemax/issues

---

Convert stanemax object to a posterior draws object

Description

Convert stanemax object to a posterior draws object

Usage

as_draws(x, ...)

as_draws_list(x, ...)

as_draws_array(x, ...)

as_draws_df(x, ...)

as_draws_matrix(x, ...)

as_draws_rvars(x, ...)

## S3 method for class 'stanemax'
as_draws(x, inc_warmup = FALSE, ...)

## S3 method for class 'stanemaxbin'
as_draws(x, inc_warmup = FALSE, ...)

## S3 method for class 'stanemax'
as_draws_list(x, inc_warmup = FALSE, ...)

## S3 method for class 'stanemaxbin'
as_draws_list(x, inc_warmup = FALSE, ...)

## S3 method for class 'stanemax'
as_draws_array(x, inc_warmup = FALSE, ...)

## S3 method for class 'stanemaxbin'
as_draws_array(x, inc_warmup = FALSE, ...)

## S3 method for class 'stanemax'
as_draws_df(x, inc_warmup = FALSE, ...)

## S3 method for class 'stanemaxbin'
as_draws_df(x, inc_warmup = FALSE, ...)

## S3 method for class 'stanemax'
as_draws_matrix(x, inc_warmup = FALSE, ...)

## S3 method for class 'stanemaxbin'
as_draws_matrix(x, inc_warmup = FALSE, ...)

## S3 method for class 'stanemax'
as_draws_rvars(x, inc_warmup = FALSE, ...)

## S3 method for class 'stanemaxbin'
as_draws_rvars(x, inc_warmup = FALSE, ...)

Arguments

x	An object of class stanemax.
...	Arguments passed to individual methods (if applicable).'
inc_warmup	Should warmup draws be included? Defaults to FALSE.

Value

A draws object of the appropriate subclass

See Also

draws subset_draws

Examples

## Not run: 
data(exposure.response.sample)
fit <- stan_emax(response ~ exposure, exposure.response.sample)
posterior::as_draws_list(fit)
posterior::as_draws_array(fit)
posterior::as_draws_df(fit)
posterior::as_draws_matrix(fit)
posterior::as_draws_rvars(fit)

## End(Not run)

---

Sample simulated data for exposure-response.

Description

Sample simulated data for exposure-response.

Usage

exposure.response.sample

Format

A data frame with columns:

dose

Dose levels used for simulation of pharmacokinetics

exposure

Simulated exposure

response

Simulated pharmacodynamic response

Examples

exposure.response.sample

---

Sample simulated data for exposure-response for binary endpoint

Description

Sample simulated data for exposure-response for binary endpoint

Usage

exposure.response.sample.binary

Format

A data frame with columns:

conc

Simulated exposure

y_logit

Simulated logit(p)

y_prob

Simulated p

y

Simulated event (1 or 0)

y_cov_logit

Simulated logit(p) for model with covariate

y_cov_prob

Simulated p for model with covariate

y_cov

Simulated event (1 or 0) for model with covariate

sex_num

1 or 0

sex

female or male

Examples

exposure.response.sample

---

Sample simulated data for exposure-response with covariates

Description

Sample simulated data for exposure-response with covariates

Usage

exposure.response.sample.with.cov

Format

A data frame with columns:

dose

Dose levels used for simulation of pharmacokinetics

conc

Simulated exposure

resp

Simulated pharmacodynamic response

cov1

Covariate 1 for e0

cov2

Covariate 2 for emax

cov3

Covariate 3 for ec50 (data type factor)

cov3num

Covariate 3 for ec50 (data type numeric)

Examples

exposure.response.sample

---

Extract posterior draws of key parameters

Description

Extract posterior draws of key parameters

Usage

extract_param(object)

Arguments

object

A stanemax class object

Value

A tibble containing posterior draws of key parameters. If covariate(s) are included in the model, posterior draws for different combinations of covariates are supplied in a long format - e.g. if there are posterior draws of 100 samples and 4 levels of the covariates, the returned tibble will have the length of 400

---

Calculate log-likelihoods from posterior samples. Data can be either original data used for model fit or new data.

Description

See rstantools::log_lik for more details.

Usage

log_lik(object, ...)

## S3 method for class 'stanemax'
log_lik(object, newdata = NULL, ...)

## S3 method for class 'stanemaxbin'
log_lik(object, newdata = NULL, ...)

Arguments

object	A stanemax or stanemaxbin object
...	Currently unused arguments
newdata	New data used for prediction. If NULL, original data is used.

Value

$S$ by $N$ matrix of log-likelihoods, where each row corresponds to a draw from the posterior distribution and each column corresponds to a data point.

---

Outcome prediction from posterior distribution of parameters

Description

Compute outcome predictions using posterior samples. Exposure data for prediction can be either original data used for model fit or new data.

Usage

posterior_predict(object, ...)

posterior_epred(object, ...)

posterior_linpred(object, transform = FALSE, ...)

## S3 method for class 'stanemax'
posterior_predict(
  object,
  newdata = NULL,
  returnType = "matrix",
  newDataType = "raw",
  ...
)

## S3 method for class 'stanemaxbin'
posterior_predict(
  object,
  newdata = NULL,
  returnType = "matrix",
  newDataType = "raw",
  ...
)

## S3 method for class 'stanemax'
posterior_epred(object, newdata = NULL, newDataType = "raw", ...)

## S3 method for class 'stanemaxbin'
posterior_epred(object, newdata = NULL, newDataType = "raw", ...)

## S3 method for class 'stanemax'
posterior_linpred(
  object,
  transform = FALSE,
  newdata = NULL,
  newDataType = "raw",
  ...
)

## S3 method for class 'stanemaxbin'
posterior_linpred(
  object,
  transform = FALSE,
  newdata = NULL,
  newDataType = "raw",
  ...
)

posterior_predict_quantile(
  object,
  newdata = NULL,
  ci = 0.9,
  pi = 0.9,
  newDataType = c("raw", "modelframe")
)

Arguments

object	A stanemax or stanemaxbin object
...	Additional arguments passed to methods. Arguments that can be passed via the dots include ndraws, for compatibility with functions in the tidybayes package
transform	Should the linear predictor be transformed to response scale?
newdata	An optional data frame that contains columns needed for model to run (exposure and covariates). If the model does not have any covariate, this can be a numeric vector corresponding to the exposure metric.
returnType	An optional string specifying the type of return object (one of "matrix", "dataframe", or "tibble")
newDataType	An optional string specifying the type of newdata input, whether in the format of an original data frame ("raw", the default) or a processed model frame ("modelframe"). Mostly used for internal purposes and users can usually leave at default.
ci	Credible interval of the response without residual variability.
pi	Prediction interval of the response with residual variability.

Details

Run vignette("emaxmodel", package = "rstanemax") to see how you can use the posterior prediction for plotting estimated Emax curve.

Value

An object that contain predicted response with posterior distribution of parameters. The default is a matrix containing predicted response for stan_emax() and .epred for stan_emax_binary(). Each row of the matrix is a vector of predictions generated using a single draw of the model parameters from the posterior distribution.

If either dataframe or tibble is specified, the function returns a data frame or tibble object in a long format - each row is a prediction generated using a single draw of the model parameters and a corresponding exposure.

Several types of predictions are generated with this function.

For continuous endpoint model (stan_emax()),

• .linpred & .epred: prediction without considering residual variability and is intended to provide credible interval of "mean" response.

• .prediction: include residual variability in its calculation, therefore the range represents prediction interval of observed response.

• respHat: replaced by .linpred and .epred

• response: replaced by .prediction

For binary endpoint model (stan_emax_binary()),

• .linpred: predicted probability on logit scale

• .epred: predicted probability on probability scale

• .prediction: predicted event (1) or non-event (0)

  The return object also contains exposure and parameter values used for calculation.

With posterior_predict_quantile() function, you can obtain quantiles of respHat and response as specified by ci and pi.

---

Bayesian Emax model fit with Stan

Description

Run sigmoidal Emax model fit with formula notation

Usage

stan_emax(
  formula,
  data,
  gamma.fix = 1,
  e0.fix = NULL,
  emax.fix = NULL,
  priors = NULL,
  param.cov = NULL,
  ...
)

Arguments

formula	a symbolic description of variables for Emax model fit.
data	an optional data frame containing the variables in the model.
gamma.fix	a (positive) numeric or NULL to specify gamma (Hill coefficient) in the sigmoidal Emax model. If NULL, gamma will be estimated from the data. If numeric, gamma is fixed at the number provided. Default = 1 (normal Emax model).
e0.fix	a numeric or NULL to specify E0 in the Emax model. If NULL, E0 will be estimated from the data. If numeric, E0 is fixed at the number provided. Default = NULL (estimate from the data).
emax.fix	a numeric or NULL to specify Emax in the Emax model. If NULL, Emax will be estimated from the data. If numeric, Emax is fixed at the number provided. Default = NULL (estimate from the data).
priors	a named list specifying priors of parameters (ec50, emax, e0, gamma, sigma). Each list item should be length 2 numeric vector, one corresponding to mean and another corresponding to standard deviation. Currently only supports normal distribution for priors.
param.cov	a named list specifying categorical covariates on parameters (ec50, emax, e0). Convert a column into factor if specific order of covariates are needed.
...	Arguments passed to rstan::sampling (e.g. iter, chains).

Details

The following structure is used for the Emax model:

$Response = e_0 + e_{max} \times exposure ^{\gamma} / (ec50 ^{\gamma} + exposure ^ {\gamma}) + \epsilon$

$\epsilon \sim N(0, \sigma^2)$

Value

An object of class stanemax

Examples

## Not run: 
data(exposure.response.sample)
fit1 <- stan_emax(response ~ exposure,
  data = exposure.response.sample,
  # the next line is only to make the example go fast enough
  chains = 1, iter = 500, seed = 12345
)
print(fit1)

# Set priors manually, also estimate gamma instead of the default of fix to 1
fit2 <- stan_emax(response ~ exposure,
  data = exposure.response.sample, gamma.fix = NULL,
  priors = list(
    ec50 = c(100, 30), emax = c(100, 30), e0 = c(10, 5),
    gamma = c(0, 3), sigma = c(0, 30)
  ),
  # the next line is only to make the example go fast enough
  chains = 1, iter = 500, seed = 12345
)
print(fit2)

data(exposure.response.sample.with.cov)
# Specify covariates
fit3 <- stan_emax(
  formula = resp ~ conc, data = exposure.response.sample.with.cov,
  param.cov = list(emax = "cov2", ec50 = "cov3", e0 = "cov1"),
  # the next line is only to make the example go fast enough
  chains = 1, iter = 500, seed = 12345
)
print(fit3)

## End(Not run)

---

Bayesian Emax model fit with Stan for binary endpoint

Description

Bayesian Emax model fit with Stan for binary endpoint

Usage

stan_emax_binary(
  formula,
  data,
  gamma.fix = 1,
  e0.fix = NULL,
  emax.fix = NULL,
  priors = NULL,
  param.cov = NULL,
  ...
)

Arguments

formula	a symbolic description of variables for Emax model fit.
data	an optional data frame containing the variables in the model.
gamma.fix	a (positive) numeric or NULL to specify gamma (Hill coefficient) in the sigmoidal Emax model. If NULL, gamma will be estimated from the data. If numeric, gamma is fixed at the number provided. Default = 1 (normal Emax model).
e0.fix	a numeric or NULL to specify E0 in the Emax model. If NULL, E0 will be estimated from the data. If numeric, E0 is fixed at the number provided. Default = NULL (estimate from the data).
emax.fix	a numeric or NULL to specify Emax in the Emax model. If NULL, Emax will be estimated from the data. If numeric, Emax is fixed at the number provided. Default = NULL (estimate from the data).
priors	a named list specifying priors of parameters (ec50, emax, e0, gamma, sigma). Each list item should be length 2 numeric vector, one corresponding to mean and another corresponding to standard deviation. Currently only supports normal distribution for priors.
param.cov	a named list specifying categorical covariates on parameters (ec50, emax, e0). Convert a column into factor if specific order of covariates are needed.
...	Arguments passed to rstan::sampling (e.g. iter, chains).

Examples

## Not run: 
data(exposure.response.sample.binary)
fit1 <- stan_emax_binary(
  y ~ conc,
  data = exposure.response.sample.binary,
  # the next line is only to make the example go fast enough
  chains = 2, iter = 500, seed = 12345
)
print(fit1)

# Specify covariates
fit2 <- stan_emax_binary(
  formula = y ~ conc, data = exposure.response.sample.binary,
  param.cov = list(emax = "sex"),
  # the next line is only to make the example go fast enough
  chains = 2, iter = 500, seed = 12345
)
print(fit2)

## End(Not run)

---

Methods for stanemax objects

Description

Methods for stanemax objects

Usage

## S3 method for class 'stanemax'
print(x, digits_summary = 2, ...)

## S3 method for class 'stanemaxbin'
print(x, digits_summary = 2, ...)

extract_stanfit(x)

extract_obs_mod_frame(x)

## S3 method for class 'stanemax'
plot(x, show.ci = TRUE, show.pi = FALSE, ci = 0.9, pi = 0.9, ...)

## S3 method for class 'stanemaxbin'
plot(x, show.ci = TRUE, show.pi = FALSE, ci = 0.9, pi = 0.9, ...)

Arguments

x	An object of class stanemax or stanemaxbin
digits_summary	The number of significant digits to use when printing the summary, defaulting to 2. Applies to the quantities other than the effective sample size, which is always rounded to the nearest integer.
...	Additional arguments passed to methods.
show.ci	An logical specifying if the output figure include credible interval of posterior prediction. Default TRUE.
show.pi	An logical specifying if the output figure include prediction interval. Default FALSE.
ci	Credible interval range.
pi	Prediction interval range.

---