Package 'rstanemax'

The 'rstanemax' package.

Description

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

References

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

---

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 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

---

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

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

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

Arguments

object	A stanemax class object
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.
newDataType	An optional string specifying the type of newdata input, whether in the format of an original data frame or a processed model frame. Mostly used for internal purposes and users can usually leave at default.
...	Additional arguments passed to methods.
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. 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.

Two types of predictions are generated with this function. respHat corresponds to the prediction without considering residual variability and is intended to provide credible interval of "mean" response. response include residual variability in its calculation, therefore the range represents prediction interval of observed response.

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)

---

Methods for stanemax objects

Description

Methods for stanemax objects

Usage

## S3 method for class 'stanemax'
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, ...)

Arguments

x	An object of class stanemax
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.

---