| Title: | Analyze Multiple Exposure Realizations in Association Studies |
|---|---|
| Description: | Analyze association studies with multiple realizations of a noisy or uncertain exposure. These can be obtained from e.g. a two-dimensional Monte Carlo dosimetry system (Simon et al 2015 <doi:10.1667/RR13729.1>) to characterize exposure uncertainty. The implemented methods are regression calibration (Carroll et al. 2006 <doi:10.1201/9781420010138>), extended regression calibration (Little et al. 2023 <doi:10.1038/s41598-023-42283-y>), Monte Carlo maximum likelihood (Stayner et al. 2007 <doi:10.1667/RR0677.1>), frequentist model averaging (Kwon et al. 2023 <doi:10.1371/journal.pone.0290498>), and Bayesian model averaging (Kwon et al. 2016 <doi:10.1002/sim.6635>). Supported model families are Gaussian, binomial, multinomial, Poisson, proportional hazards, and conditional logistic. |
| Authors: | Sander Roberti [aut, cre] (ORCID: <https://orcid.org/0000-0002-6275-7442>), William Wheeler [aut], Deukwoo Kwon [aut] (ORCID: <https://orcid.org/0000-0001-5376-5320>), Ruth Pfeiffer [ctb] (ORCID: <https://orcid.org/0000-0001-7791-2698>), NCI [cph, fnd] |
| Maintainer: | Sander Roberti <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.4.0.9000 |
| Built: | 2026-06-02 18:47:01 UTC |
| Source: | https://github.com/sanderroberti/ameras |
Analyze association studies with multiple realizations of a noisy or uncertain exposure. These can be obtained from e.g. a two-dimensional Monte Carlo dosimetry system (Simon et al 2015 <doi:10.1667/RR13729.1>) to characterize exposure uncertainty. Methods include regression calibration (Carroll et al. 2006 doi:10.1201/9781420010138), extended regression calibration (Little et al. 2023 doi:10.1038/s41598-023-42283-y), Monte Carlo maximum likelihood (Stayner et al. 2007 doi:10.1667/RR0677.1), frequentist model averaging (Kwon et al. 2023 doi:10.1371/journal.pone.0290498), and Bayesian model averaging (Kwon et al. 2016 doi:10.1002/sim.6635). Supported model families are Gaussian, binomial, multinomial, Poisson, proportional hazards, and conditional logistic.
The function used to fit models is ameras. To attach confidence/credible intervals, use the method confint. To visualize the exposure uncertainty in the dose realizations, use ecdfplot.
Sander Roberti <[email protected]>, William Wheeler <[email protected]>, Ruth Pfeiffer <[email protected]>, and Deukwoo Kwon <[email protected]
Roberti, S., Kwon D., Wheeler W., Pfeiffer R. (in preparation). ameras: An R Package to Analyze Multiple Exposure Realizations in Association Studies
Fit regression models accounting for exposure uncertainty using multiple Monte Carlo exposure realizations. Six outcome model families are supported. The first is the Gaussian family for continuous outcomes,
with . Here are covariates, is the exposure with measurement error, and are binary effect modifiers. The quadratic exposure terms and effect modification are optional.
For non-Gaussian families, three relative risk models for the main exposure are supported, the usual exponential and the linear excess relative risk (ERR) model , where the quadratic and effect modification terms are optional. Finally, the linear-exponential relative risk model is supported.
The second supported family is logistic regression for binary outcomes, with probabilities
Third is Poisson regression for counts,
where with optional offset.
Fourth is proportional hazards regression for time-to-event data, with hazard function
with the baseline hazard.
Fifth is multinomial logistic regression for a categorical outcome with outcome categories, with the last category as the referent category (i.e., ):
Sixth is conditional logistic regression for matched case control data, for which
where is the matched set corresponding to individual .
Methods include regression calibration (Carroll et al. 2006 doi:10.1201/9781420010138), extended regression calibration (Little et al. 2023 doi:10.1038/s41598-023-42283-y), Monte Carlo maximum likelihood (Stayner et al. 2007 doi:10.1667/RR0677.1), frequentist model averaging (Kwon et al. 2023 doi:10.1371/journal.pone.0290498), and Bayesian model averaging (Kwon et al. 2016 doi:10.1002/sim.6635).
ameras(formula=NULL, data, family="gaussian", methods="RC", Y=NULL, dosevars=NULL, doseRRmod=NULL, deg=NULL, M=NULL, X=NULL, offset=NULL, entry=NULL, exit=NULL, setnr=NULL, CI=NULL, params.profCI=NULL, maxit.profCI=NULL, tol.profCI=NULL, transform=NULL, transform.jacobian=NULL, inpar=NULL, loglim=1e-30, MFMA=100000, prophaz.numints.BMA=10, ERRprior.BMA="doubleexponential", nburnin.BMA=5000, niter.BMA=20000, nchains.BMA=2, thin.BMA=10, included.realizations.BMA=NULL, included.replicates.BMA=NULL, optim.method="Nelder-Mead", control=NULL, keep.data=TRUE, ... )ameras(formula=NULL, data, family="gaussian", methods="RC", Y=NULL, dosevars=NULL, doseRRmod=NULL, deg=NULL, M=NULL, X=NULL, offset=NULL, entry=NULL, exit=NULL, setnr=NULL, CI=NULL, params.profCI=NULL, maxit.profCI=NULL, tol.profCI=NULL, transform=NULL, transform.jacobian=NULL, inpar=NULL, loglim=1e-30, MFMA=100000, prophaz.numints.BMA=10, ERRprior.BMA="doubleexponential", nburnin.BMA=5000, niter.BMA=20000, nchains.BMA=2, thin.BMA=10, included.realizations.BMA=NULL, included.replicates.BMA=NULL, optim.method="Nelder-Mead", control=NULL, keep.data=TRUE, ... )
formula |
an object of class |
data |
input data frame. |
family |
outcome model family: |
methods |
character vector of one or multiple methods to apply. Options: |
Y |
Deprecated. Use the formula interface instead. Name or column index of the outcome variable for linear, binomial, Poisson, multinomial and conditional logistic models, or event indicator variable for the proportional hazards model. |
dosevars |
Deprecated. Use the formula interface instead. Names or column indices of exposure realization vectors. |
doseRRmod |
Deprecated. Use the formula interface instead. The functional form of the dose-response relationship; options are exponential RR ( |
deg |
Deprecated. Use the formula interface instead. For |
M |
Deprecated. Use the formula interface instead. Names or column indices of binary effect modifying variables (optional). |
X |
Deprecated. Use the formula interface instead. Names or column indices of other covariates (optional). |
offset |
Deprecated. Use the formula interface instead. Name or column index of offset variable for Poisson regression (optional). |
entry |
Deprecated. Use the formula interface instead. Name or column index of left truncation time variable for proportional hazards regression (optional). |
exit |
Deprecated. Use the formula interface instead. Name or column index of exit time variable, required when |
setnr |
Deprecated. Use the formula interface instead. Name or column index of integer-valued matched set variable, required when |
CI |
Deprecated. Use confint() to compute confidence intervals instead. Method for calculation of 95% confidence or credible intervals (see Details).
For RC, ERC, and MCML, options are |
params.profCI |
Deprecated. Use confint() to compute confidence intervals instead. When |
maxit.profCI |
Deprecated. Use confint() to compute confidence intervals instead. Maximum iterations for determining profile-likelihood CIs; passed to |
tol.profCI |
Deprecated. Use confint() to compute confidence intervals instead. Tolerance for determining profile-likelihood CIs; passed to |
transform |
function for internal parameter transformation (see Details). |
transform.jacobian |
Jacobian of the transformation function (see Details). |
inpar |
vector of initial values for log-likelihood optimization (optional). |
loglim |
parameter used in likelihood computations to avoid taking the log of very small or negative numbers via |
MFMA |
number of samples for |
prophaz.numints.BMA |
for |
ERRprior.BMA |
prior for dose-related parameters when |
nburnin.BMA |
number of MCMC burn-in iterations for BMA (default 5,000). |
niter.BMA |
number of MCMC iterations per chain for BMA (default 20,000). |
nchains.BMA |
number of MCMC chains for BMA (default 2). |
thin.BMA |
thinning rate for BMA (default 10). |
included.realizations.BMA |
indices of exposure realizations used in BMA (defaults to all realizations). |
included.replicates.BMA |
Deprecated. Use |
optim.method |
method used for optimization by |
control |
control list passed to |
keep.data |
whether to attach data to the output object (default |
... |
other arguments, passed to functions such as |
Models are specified through formulas of the form Y~dose(dose_expression, model="ERR", deg=1, modifier=M1+M2)+X1+X2. Here dose_expression specifies the dose realization columns and is parsed by eval_select from the tidyselect package. Useful examples are D1:D1000 if the doses are in a sequence of columns with sequential names such as D1-D1000, and all_of(dosevars) where dosevars is a vector with the names of all dose columns. Further, model specifies, for non-Gaussian families, whether to use the exponential dose-response model (model="EXP"), the linear-exponential model (model="LINEXP") or the linear ERR model (model="ERR"). Next, deg is used to specify whether a quadratic dose term should (deg=2) or should not (deg=1) be estimated for the exponential or linear ERR dose-response model. The modifier term is optional and used to specify binary effect modification variables. Note that interactions in the modifier term are not allowed, e.g. M1*M2. When deg, modifier, and model are not supplied, the defaults are deg=1, no effect modifiers, and model="ERR". Finally, X1 and X2 above represent optional additional covariates, which can include factor variables and interactions such as X1*X2. The matched set variable setnr required for conditional logistic regression is specified on the right-hand side of the formula through a term strata(setnr), and an optional offset variable offset for Poisson regression similarly through a term offset(offset). For proportional hazards regression, the left-hand side of the formula should have the form Surv(exit, status) or Surv(entry, exit, status).
A transformation can be used to reparametrize parameters internally (i.e., such that the likelihoods are evaluated at transform(parameters), where parameters are unconstrained), and should be specified when fitting linear excess relative risk and linear-exponential models to ensure nonnegative odds/risk/hazard. The included function transform1 applies an exponential transformation to the desired parameters, see ?transform1. When supplying a function to transform, this should be a function of the full parameter vector, returning a full (transformed) parameter vector. In particular, the full parameter vector contains parameters in the following order: , where , and can be vectors, with lengths matching and , respectively. is only included for the linear model (Gaussian family), and no intercept is included for the proportional hazards and conditional logistic models. For the multinomial model, the full parameter vector is the concatenation of parameter vectors in the order as given above, where is the number of outcome categories, with the last category chosen as the referent category. See vignette("transformations", package="ameras") for an example of how to specify a custom transformation function.
When no transformation is specified and the linear ERR model is used, transform1 is used for ERR parameters and by default, with lower limits for in the linear dose-response and for in the linear-quadratic dose-response, respectively. For the linear-exponential model, a lower limit of 0 is used for , and no transformation is used for . If effect modifiers M are specified, no transformation is used for those parameters. When negative RRs are obtained during optimization, an error will be generated and a different transformation or bounds should be used. All output is returned in the original parametrization. The Jacobian of the transformation (transform.jacobian) is required when using a transformation. For transform1, the Jacobian is given by transform1.jacobian. No transformations are used in BMA, and FMA is applied on the parameters using the parametrization as given in above with variances obtained using the delta method with the provided Jacobian function.
For BMA, a prior distribution for exposure-response parameters can be chosen when using linear or linear-exponential exposure-response model. The options are normal, horshoe, and double exponential priors, and the same priors truncated at 0 to yield positive values. In particular:
Normal: for all exposure-response parameters
Horseshoe (shrinkage prior): . Here is shared across all parameters
Double exponential (shrinkage prior):
For all other parameters, and when using the exponential exposure-response model or the Gaussian outcome family, the prior is . For the parameter in the Gaussian family, this prior is truncated at 0.
Because the proportional hazards model is not available in nimble, ameras uses a piecewise constant baseline hazard for Bayesian model averaging. The interval min(entry), max(exit)) is divided into prophaz.numints.BMA subintervals with cutpoints obtained as quantiles of the distribution of event times among cases, and a baseline hazard parameter is estimated for each subinterval.
The output is an object of class amerasfit. General components are call
(the function call to ameras), formula (the formula object specifying
the model), num.rows (the number of rows in data), num.realizations
(the number of dose realizations provided), transform (the used transformation
function, if applicable), transform.jacobian (the used Jacobian function for
the transformation, if applicable), other.args (any other arguments passed to
...), model (a list containing the specified model components parsed from
the formula), CI.computed (logical, whether confidence intervals have been
attached by confint), and data (either the
data frame used for model fitting when keep.data=TRUE or NULL otherwise).
For each method supplied to methods, the output contains a list with components:
coefficients |
named vector of model coefficients. |
sd |
named vector of standard deviations. |
vcov |
covariance matrix for the full parameter vector. Based on the observed information (negative second derivative of log-likelihood) for RC, ERC, and MCML, and on the obtained samples for FMA and BMA. |
runtime |
string with the runtime in seconds. |
For RC, ERC, and MCML the following additional output is included:
optim |
a list object with results returned by optim. Components are |
loglik |
log-likelihood value at the optimum. |
For RC and ERC, the output additionally contains:
ERC |
logical, whether the output is for ERC ( |
For BMA the output additionally contains:
samples |
MCMC posterior samples, as obtained from |
Rhat |
data frame with two columns, |
included.realizations |
indices of realization exposures that were included to obtain the results. |
prophaz.timepoints |
for |
Finally, for FMA the output additionally contains:
samples |
data frame with samples generated from the normal distributions associated with parameters estimated for each dose realization. |
weigths |
vector of weights corresponding to the models fit to each included realization |
included.samples |
the total number of samples included. |
included.realizations |
indices of realization exposures that were included to obtain results. Fits without a valid variance estimate (i.e., non-invertible Hessian or inverse that is not positive definite) or that reach the maximal number of iterations without convergence are filtered out and not used to obtain results. |
The class amerasfit supports the methods print, coef, confint, summary, and traceplot.
Roberti, S., Kwon D., Wheeler W., Pfeiffer R. (in preparation). ameras: An R Package to Analyze Multiple Exposure Realizations in Association Studies
confint for computing confidence intervals,
summary for a summary of the fitted model
including confidence intervals if computed, coef
for extracting coefficients.
data(data, package="ameras") ameras(Y.gaussian~dose(V1:V10, modifier=M1+M2)+X1+X2, data=data, family="gaussian")data(data, package="ameras") ameras(Y.gaussian~dose(V1:V10, modifier=M1+M2)+X1+X2, data=data, family="gaussian")
Returns a data frame with all the parameters of a fitted
amerasfit object. The resulting object has a column
for every method supplied to 'methods' when calling 'ameras',
with rows corresponding to parameters.
## S3 method for class 'amerasfit' coef(object, ...)## S3 method for class 'amerasfit' coef(object, ...)
object |
A fitted model object of class |
... |
Additional arguments, currently unused. |
Data frame with estimated model parameters. Column names correspond to the 'methods' used in the 'ameras' call, and row names correspond to parameter names.
ameras for model fitting,
summary for a summary of the fitted model
including confidence intervals if computed.
data("data", package = "ameras") dosevars <- paste0("V", 1:10) ## Fit the model fit <- ameras(Y.binomial~dose(V1:V10, model="ERR"), data = data, family = "binomial", methods = c("RC","ERC")) ## Full matrix coef(fit) ## Vector with RC parameters coef(fit)$RCdata("data", package = "ameras") dosevars <- paste0("V", 1:10) ## Fit the model fit <- ameras(Y.binomial~dose(V1:V10, model="ERR"), data = data, family = "binomial", methods = c("RC","ERC")) ## Full matrix coef(fit) ## Vector with RC parameters coef(fit)$RC
Computes and/or prints confidence intervals for the parameters of a fitted
amerasfit object. This is a separate step from model fitting,
i.e., ameras fits the model and confint computes
intervals, attaches them to the fitted object, and prints them. If
confint is called a second time on the same object, intervals
are only printed and not recomputed, unless force=TRUE.
## S3 method for class 'amerasfit' confint(object, parm="dose", level=0.95, type=c("proflik","percentile"), maxit.profCI=20, tol.profCI=1e-2, data=NULL, force=FALSE, print=TRUE, digits = max(3, getOption("digits") - 3), ...)## S3 method for class 'amerasfit' confint(object, parm="dose", level=0.95, type=c("proflik","percentile"), maxit.profCI=20, tol.profCI=1e-2, data=NULL, force=FALSE, print=TRUE, digits = max(3, getOption("digits") - 3), ...)
object |
A fitted model object of class |
parm |
Either |
level |
The confidence level (default |
type |
The type(s) of confidence intervals to determine. For RC, ERC, and MCML, this can be one of:
For FMA and BMA, confidence intervals are based on the generated samples and possible confidence interval types are:
If |
maxit.profCI |
Maximum number of iterations for the root-finding algorithm used to
locate profile likelihood interval bounds. Only used when
|
tol.profCI |
Tolerance for the root-finding algorithm. Only used when
|
data |
The original data frame used for fitting. Only required when
|
force |
Logical. If |
print |
Logical. If |
digits |
Number of significant digits to be printed. Default is 'max(3, getOption("digits") - 3)' |
... |
Additional arguments, currently unused. |
For (extended) regression calibration and Monte Carlo maximum likelihood,
Wald and profile likelihood intervals can be obtained. When a parameter
transformation is used, type="wald.transformed"
yields the CI at significance level of
where is the -quantile of the standard normal distribution and is the vector
of standard deviations estimated using the inverse Hessian matrix,
and type="wald.orig" uses the delta method to obtain the CI
where is the vector of
standard deviations estimated using with the
Jacobian of the transformation and is the Hessian. When no
transformation is used, type="wald.orig" should be used.
The third option is proflik, which uses the profile likelihood to
compute confidence bounds.
For FMA and BMA, the options for
confidence/credible intervals are type="percentile" which uses
percentiles, and type="hpd" which computes highest posterior density
intervals using HPDinterval from the coda package, both using
the FMA samples or Bayesian posterior samples.
Profile likelihood intervals (type="proflik") require
re-evaluating the likelihood repeatedly and can be time-consuming.
The parm argument can be used to restrict computation to dose
parameters only (the default) when intervals for the other parameters are
not of interest.
When the model was fitted with keep.data=FALSE and
type="proflik" is used for confint, the original data must be
supplied via the data argument. Wald intervals do not require the
data and can always be computed from the stored Hessian and parameter
estimates alone.
The original amerasfit object with a CI element added to
each fitted method result. For RC, ERC, and MCML the CI element
is a data frame with columns:
lowerLower confidence bound.
upperUpper confidence bound.
When type = "proflik", four additional columns are included:
pval.lowerP-value at the lower bound, should be close to
level.
pval.upperP-value at the upper bound, should be close to
level.
iter.lowerNumber of iterations used by the root-finding algorithm for the lower bound.
iter.upperNumber of iterations used by the root-finding algorithm for the upper bound.
For FMA and BMA the CI element is a data frame with columns
lower and upper.
ameras for model fitting,
summary for a summary of the fitted model
including confidence intervals if computed,
confint for the generic function.
data("data", package = "ameras") ## Fit the model fit <- ameras(Y.binomial~dose(V1:V10, model="ERR"), data = data, family = "binomial", methods = "RC") ## Wald intervals (fast) fit <- confint(fit, type = "wald.orig") summary(fit) ## Profile likelihood intervals for dose parameters only (slower) fit <- confint(fit, type = "proflik", parm = "dose") summary(fit) ## With keep.data = FALSE, supply data explicitly for proflik fit2 <- ameras(Y.binomial~dose(V1:V10, model="ERR"), data = data, family = "binomial", methods = "RC", keep.data = FALSE) fit2 <- confint(fit2, type = "proflik", data = data) ## FMA and BMA with percentile intervals fit3 <- ameras(Y.binomial~dose(V1:V10, model="ERR"), data = data, family = "binomial", methods = c("FMA", "BMA")) fit3 <- confint(fit3, type = "percentile") summary(fit3)data("data", package = "ameras") ## Fit the model fit <- ameras(Y.binomial~dose(V1:V10, model="ERR"), data = data, family = "binomial", methods = "RC") ## Wald intervals (fast) fit <- confint(fit, type = "wald.orig") summary(fit) ## Profile likelihood intervals for dose parameters only (slower) fit <- confint(fit, type = "proflik", parm = "dose") summary(fit) ## With keep.data = FALSE, supply data explicitly for proflik fit2 <- ameras(Y.binomial~dose(V1:V10, model="ERR"), data = data, family = "binomial", methods = "RC", keep.data = FALSE) fit2 <- confint(fit2, type = "proflik", data = data) ## FMA and BMA with percentile intervals fit3 <- ameras(Y.binomial~dose(V1:V10, model="ERR"), data = data, family = "binomial", methods = c("FMA", "BMA")) fit3 <- confint(fit3, type = "percentile") summary(fit3)
Data includes outcomes of all six supported types in the appropriately named columns. For proportional hazards regression, the observed exit time is time and event status is event. For conditional logistic regression, the matched set variable is setnr. The data has 10 exposure realizations in columns V1-V10.
data(data, package="ameras") # Display a few rows of the data data[1:5, ]data(data, package="ameras") # Display a few rows of the data data[1:5, ]
Create a descriptive figure to visualize the distribution of dose and its uncertainty.
ecdfplot(data, dosevars, xlab="Dose", ylab="Cumulative distribution", show.mean=TRUE, log.xaxis=TRUE)ecdfplot(data, dosevars, xlab="Dose", ylab="Cumulative distribution", show.mean=TRUE, log.xaxis=TRUE)
data |
data frame containing columns with dose vectors |
dosevars |
names or column indices of dose vectors. |
xlab |
label for the x-axis, default |
ylab |
label for the y-axis, default |
show.mean |
logical, whether to plot the cumulative distribution of the mean dose across realizations and across individuals, default |
log.xaxis |
logical, whether to use a log-scale for the dose axis (default |
In the left panel, the empirical cumulative distribution function (ECDF) is
plotted for each dose realization. In other words, each curve shows one distribution
of dose across individuals. The spread within individual curves reflects the dose range
across individuals, while the spread between curves reflects between-realization variation
on the cohort level. If show.mean=TRUE, the solid black curve is the cumulative
distribution of the mean dose for each individual.
In the right panel, ECDFs are plotted for each individual,
showing distributions within individuals. A wide spread within individual curves
is indicative of large within-individual variation, while the spread between
curves reflects between-individual variation. If show.mean=TRUE, the solid
black curve is the cumulative distribution of the mean for each dose realization.
When using a log-scale for the x-axis, any zero dose values are excluded before plotting.
if (requireNamespace("ggplot2", quietly = TRUE)) { data(data, package="ameras") ecdfplot(data, dosevars=paste0("V", 1:10)) }if (requireNamespace("ggplot2", quietly = TRUE)) { data(data, package="ameras") ecdfplot(data, dosevars=paste0("V", 1:10)) }
Extracts the indices of dose realizations included in model averaging
for FMA and/or BMA results of a fitted amerasfit object.
Realizations are excluded from FMA if the optimization did not converge or
the Hessian was not positive definite.
included_realizations(x, ...) ## S3 method for class 'amerasfit' included_realizations(x, methods = c("FMA", "BMA"), ...)included_realizations(x, ...) ## S3 method for class 'amerasfit' included_realizations(x, methods = c("FMA", "BMA"), ...)
x |
A fitted model object of class |
methods |
Character vector specifying which method(s) to extract included
realizations for. One or both of |
... |
Additional arguments, currently unused. |
For FMA, realizations are excluded if the optimization did not converge or the Hessian was not invertible or not positive definite. If more than 20% of realizations are excluded, a warning is issued during fitting.
For BMA, all realizations are included by default. A subset of
realizations can be specified via the included.replicates.BMA
argument to ameras, for example by passing the indices
returned by included_realizations(fit, methods="FMA") from a
prior FMA fit.
If a single method is requested or only one method was run, an
integer vector of indices of the included dose realizations. If both
FMA and BMA results are present and both are requested, a named list
with elements FMA and BMA, each containing an integer
vector of included realization indices.
data("data", package="ameras") dosevars <- paste0("V", 1:10) ## FMA only fit <- ameras(Y.binomial ~ dose(all_of(dosevars), model="ERR"), data=data, family="binomial", methods="FMA") included_realizations(fit) length(included_realizations(fit)) ## Both FMA and BMA fit2 <- ameras(Y.binomial ~ dose(all_of(dosevars), model="ERR"), data=data, family="binomial", methods=c("FMA", "BMA")) included_realizations(fit2) included_realizations(fit2, methods="FMA") included_realizations(fit2, methods="BMA")data("data", package="ameras") dosevars <- paste0("V", 1:10) ## FMA only fit <- ameras(Y.binomial ~ dose(all_of(dosevars), model="ERR"), data=data, family="binomial", methods="FMA") included_realizations(fit) length(included_realizations(fit)) ## Both FMA and BMA fit2 <- ameras(Y.binomial ~ dose(all_of(dosevars), model="ERR"), data=data, family="binomial", methods=c("FMA", "BMA")) included_realizations(fit2) included_realizations(fit2, methods="FMA") included_realizations(fit2, methods="BMA")
Produces diagnostic plots for a fitted amerasfit object,
including residuals versus fitted values and normal Q-Q plots.
Plots are produced for each estimation method present in the fitted
object.
## S3 method for class 'amerasfit' plot(x, methods = c("RC", "ERC", "MCML", "FMA", "BMA"), which = NULL, type = NULL, dose.col = NULL, add.smooth = getOption("add.smooth", TRUE), qqline = TRUE, id.n = 3, ask = NULL, data = NULL, ...)## S3 method for class 'amerasfit' plot(x, methods = c("RC", "ERC", "MCML", "FMA", "BMA"), which = NULL, type = NULL, dose.col = NULL, add.smooth = getOption("add.smooth", TRUE), qqline = TRUE, id.n = 3, ask = NULL, data = NULL, ...)
x |
A fitted model object of class |
methods |
Character vector specifying which estimation methods to produce
plots for. One or more of |
which |
Character vector specifying which plots to produce. For non- |
type |
The type of residuals to use. One of |
dose.col |
The dose realization to use for computation of residuals. If
|
add.smooth |
Logical. If |
qqline |
Logical. If |
id.n |
Integer. The number of extreme residuals to label in residuals vs fitted
and normal Q-Q plots. Labels show the row index of the observation. Defaults to
|
ask |
Logical. If |
data |
The original data frame used for fitting. Only required when the
model was fitted with |
... |
Additional graphical arguments passed to |
If not otherwise specified, the dose realization used to compute fitted values is selected for each estimation method as follows. For RC and ERC the mean dose across realizations is used. For MCML and FMA the realization yielding the largest likelihood at the final parameter estimates is used (which for FMA corresponds to the highest model averaging weight). For BMA the realization most frequently selected by the MCMC sampler is used. The selected dose column is shown in the plot title.
For the "residuals-vs-fitted" plot, the smooth line is added
via panel.smooth using a loess smoother when add.smooth=TRUE.
For the "qq" plot, the residuals are plotted against the
theoretical quantiles of the normal distribution when qqline=TRUE. For both plots,
the id.n most extreme residuals are labeled. For family="multinomial",
one panel is produced per non-reference outcome category.
For proportional hazards models, scaled Schoenfeld residuals are drawn
against the observed event times to assess the proportional hazards assumption.
Under proportional hazards, the residuals should fluctuate randomly around
zero with no systematic trend over time. Systematic patterns or smooth
trends may indicate time-varying covariate effects and violation of the
proportional hazards assumption. Note that the implementation here corresponds
to using transform = "identity" in cox.zph,
in contrast to the default setting for that function which applies a
Kaplan–Meier transformation of time.
The data must either be stored on the object (keep.data=TRUE in
ameras, the default) or supplied via the data argument.
The amerasfit object x is returned invisibly.
residuals.amerasfit for computing residuals,
ameras for model fitting,
confint for confidence intervals,
plot.lm for the equivalent method for linear models.
data("data", package="ameras") dosevars <- paste0("V", 1:10) ## Binomial model fit <- ameras(Y.binomial ~ dose(all_of(dosevars), model="ERR"), data=data, family="binomial", methods="RC") ## Both diagnostic plots for RC plot(fit) ## Residuals vs fitted only plot(fit, which="residuals-vs-fitted") ## Deviance residuals plot(fit, type="deviance") ## Multiple methods fit2 <- ameras(Y.binomial ~ dose(all_of(dosevars), model="ERR"), data=data, family="binomial", methods=c("RC", "ERC")) plot(fit2) ## With keep.data=FALSE, supply data explicitly fit3 <- ameras(Y.binomial ~ dose(all_of(dosevars), model="ERR"), data=data, family="binomial", methods="RC", keep.data=FALSE) plot(fit3, data=data) ## Schoenfeld residual plot fit4 <- ameras(Surv(time, status) ~ dose(all_of(dosevars), model = "ERR"), data = data, family = "prophaz", methods = "RC") plot(fit4)data("data", package="ameras") dosevars <- paste0("V", 1:10) ## Binomial model fit <- ameras(Y.binomial ~ dose(all_of(dosevars), model="ERR"), data=data, family="binomial", methods="RC") ## Both diagnostic plots for RC plot(fit) ## Residuals vs fitted only plot(fit, which="residuals-vs-fitted") ## Deviance residuals plot(fit, type="deviance") ## Multiple methods fit2 <- ameras(Y.binomial ~ dose(all_of(dosevars), model="ERR"), data=data, family="binomial", methods=c("RC", "ERC")) plot(fit2) ## With keep.data=FALSE, supply data explicitly fit3 <- ameras(Y.binomial ~ dose(all_of(dosevars), model="ERR"), data=data, family="binomial", methods="RC", keep.data=FALSE) plot(fit3, data=data) ## Schoenfeld residual plot fit4 <- ameras(Surv(time, status) ~ dose(all_of(dosevars), model = "ERR"), data = data, family = "prophaz", methods = "RC") plot(fit4)
Prints a simple summary of a fitted amerasfit object.
## S3 method for class 'amerasfit' print(x, digits = max(3, getOption("digits") - 3), ...)## S3 method for class 'amerasfit' print(x, digits = max(3, getOption("digits") - 3), ...)
x |
A fitted model object of class |
digits |
Number of significant digits to be printed. Default is 'max(3, getOption("digits") - 3)' |
... |
Additional arguments, currently unused. |
Prints the 'ameras' call, number of rows and dose realizations in the data, runtime, and model coefficients.
ameras for model fitting,
summary for a more detailed summary of the fitted models
including confidence intervals if computed.
data("data", package = "ameras") ## Fit the model fit <- ameras(Y.binomial~dose(V1:V10, model="ERR"), data = data, family = "binomial", methods = c("RC","ERC")) ## Default print fit print(fit) ## More digits print(fit, digits=5)data("data", package = "ameras") ## Fit the model fit <- ameras(Y.binomial~dose(V1:V10, model="ERR"), data = data, family = "binomial", methods = c("RC","ERC")) ## Default print fit print(fit) ## More digits print(fit, digits=5)
Computes residuals for a fitted amerasfit object.
## S3 method for class 'amerasfit' residuals(object, method = "RC", type = NULL, data = NULL, dose.col = NULL, scaled.schoenfeld = TRUE, ...)## S3 method for class 'amerasfit' residuals(object, method = "RC", type = NULL, data = NULL, dose.col = NULL, scaled.schoenfeld = TRUE, ...)
object |
A fitted model object of class |
method |
Character string specifying which estimation method to compute
residuals for. One of |
type |
The type of residuals to compute. Defaults to
|
data |
The original data frame used for fitting. Only required when the
model was fitted with |
dose.col |
Character string specifying the dose column to use when computing
fitted values. If |
scaled.schoenfeld |
Logical. If |
... |
Additional arguments, currently unused. |
Fitted values are computed using the dose column specified by
dose.col.
For family="clogit", fitted values are the
conditional probabilities of being a case within each matched set,
computed as where
is the relative risk for individual and the sum
is over all individuals in the same matched set.
For family="prophaz" and type="schoenfeld", the
Schoenfeld residual for the individual failing at time is:
where is the observed covariate vector for the failing
individual and
is the weighted mean covariate vector in the risk set
at time , with weights equal to the
relative risks . Ties in event times are handled using the
Breslow approximation.
For families "gaussian", "binomial",
"poisson", and "clogit", a numeric vector of
length containing the residuals.
For family="multinomial", a numeric matrix of dimension
where is the number of outcome
categories. Column names correspond to the factor levels.
Note that when plotting via plot, the
reference category is excluded since its residuals are a
linear combination of the other categories.
For family="prophaz" with type="schoenfeld", a data
frame with columns id (row index of the event), time
(event time), and one additional column per model parameter
containing the Schoenfeld residuals. Only rows corresponding to
events (status=1) are included.
Schoenfeld, D. (1982). Partial residuals for the proportional hazards regression model. Biometrika, 69(1), 239–241. doi:10.1093/biomet/69.1.239
Grambsch, P. M. and Therneau, T. M. (1994). Proportional hazards tests and diagnostics based on weighted residuals. Biometrika, 81(3), 515–526. doi:10.1093/biomet/81.3.515
plot for diagnostic plots using these
residuals,
ameras for model fitting,
residuals for the generic function.
data("data", package="ameras") dosevars <- paste0("V", 1:10) fit <- ameras(Y.binomial ~ dose(all_of(dosevars), model="ERR"), data=data, family="binomial", methods="RC") ## Pearson residuals (default) res <- residuals(fit) summary(res) ## Deviance residuals res_dev <- residuals(fit, type="deviance") ## Response residuals res_raw <- residuals(fit, type="response") ## Specific dose column res_v1 <- residuals(fit, dose.col="V1") ## Multiple methods fit2 <- ameras(Y.binomial ~ dose(all_of(dosevars), model="ERR"), data=data, family="binomial", methods=c("RC", "ERC")) res_erc <- residuals(fit2, method="ERC") ## With keep.data=FALSE fit3 <- ameras(Y.binomial ~ dose(all_of(dosevars), model="ERR"), data=data, family="binomial", methods="RC", keep.data=FALSE) res <- residuals(fit3, data=data) ## Schoenfeld residuals for proportional hazards model fit4 <- ameras(Surv(time, status) ~ dose(all_of(dosevars), model="ERR"), data=data, family="prophaz", methods="RC") res_sch <- residuals(fit4) res_raw_sch <- residuals(fit4, scaled.schoenfeld=FALSE)data("data", package="ameras") dosevars <- paste0("V", 1:10) fit <- ameras(Y.binomial ~ dose(all_of(dosevars), model="ERR"), data=data, family="binomial", methods="RC") ## Pearson residuals (default) res <- residuals(fit) summary(res) ## Deviance residuals res_dev <- residuals(fit, type="deviance") ## Response residuals res_raw <- residuals(fit, type="response") ## Specific dose column res_v1 <- residuals(fit, dose.col="V1") ## Multiple methods fit2 <- ameras(Y.binomial ~ dose(all_of(dosevars), model="ERR"), data=data, family="binomial", methods=c("RC", "ERC")) res_erc <- residuals(fit2, method="ERC") ## With keep.data=FALSE fit3 <- ameras(Y.binomial ~ dose(all_of(dosevars), model="ERR"), data=data, family="binomial", methods="RC", keep.data=FALSE) res <- residuals(fit3, data=data) ## Schoenfeld residuals for proportional hazards model fit4 <- ameras(Surv(time, status) ~ dose(all_of(dosevars), model="ERR"), data=data, family="prophaz", methods="RC") res_sch <- residuals(fit4) res_raw_sch <- residuals(fit4, scaled.schoenfeld=FALSE)
Extracts the Gelman-Rubin convergence diagnostics from the BMA
results of a fitted amerasfit object.
Rhat(x, ...) ## S3 method for class 'amerasfit' Rhat(x, ...)Rhat(x, ...) ## S3 method for class 'amerasfit' Rhat(x, ...)
x |
A fitted model object of class |
... |
Additional arguments, currently unused. |
A data frame with columns Rhat and n.eff, containing
the Gelman-Rubin statistic and effective sample size for each
parameter. Values of Rhat substantially above 1.05 indicate
potential convergence problems, in which case longer chains via
niter.BMA and nburnin.BMA are recommended.
ameras,
summary.amerasfit,
included_realizations.amerasfit
data("data", package="ameras") dosevars <- paste0("V", 1:10) fit <- ameras(Y.binomial ~ dose(all_of(dosevars), model="ERR"), data=data, family="binomial", methods="BMA") Rhat(fit)data("data", package="ameras") dosevars <- paste0("V", 1:10) fit <- ameras(Y.binomial ~ dose(all_of(dosevars), model="ERR"), data=data, family="binomial", methods="BMA") Rhat(fit)
Produces a summary of a fitted amerasfit object, including
parameter estimates, standard errors, and confidence intervals if
computed via confint.
## S3 method for class 'amerasfit' summary(object, ...) ## S3 method for class 'amerasfit' summary_table(object, ...) ## S3 method for class 'summary.amerasfit' print(x, digits = max(3, getOption("digits") - 3), ...)## S3 method for class 'amerasfit' summary(object, ...) ## S3 method for class 'amerasfit' summary_table(object, ...) ## S3 method for class 'summary.amerasfit' print(x, digits = max(3, getOption("digits") - 3), ...)
object |
A fitted model object of class |
x |
An object of class |
digits |
The number of significant digits to use. Defaults to
|
... |
Additional arguments, currently unused. |
summary.amerasfit collects results from all estimation methods
present in the fitted object into a single summary table. Columns for
confidence intervals are only printed if they have been computed by
confint. When BMA results are present
in the fitted object, the summary table includes columns Rhat and
n.eff, with NA values for all other methods.
Printing the summary prints the original call to ameras, the runtime
(total and by method), and the table described above. This table can also
be accessed directly (i.e., to retrieve confidence intervals) using
summary_table.
summary.amerasfit returns an object of class
summary.amerasfit, which is a list containing the following
elements:
callThe matched call from the original call to ameras.
summary_tableA data frame with one row per parameter per method, containing columns:
MethodThe estimation method (RC, ERC, MCML, FMA, or BMA).
TermThe parameter name.
EstimateThe parameter estimate.
SEThe standard error.
CI.lowerThe lower confidence bound, if confidence intervals have been
computed via confint.
CI.upperThe upper confidence bound, if confidence intervals have been
computed via confint.
pval.lowerp-value associated with the lower bound of the profile likelihood
CI, the assess validity of the obtained bound. Only included if
profile likelihood confidence intervals were computed via
confint.
pval.upperp-value associated with the upper bound of the profile likelihood
CI, the assess validity of the obtained bound. Only included if
profile likelihood confidence intervals were computed via
confint.
RhatThe Gelman-Rubin convergence diagnostic, included only when BMA results are present. Values above 1.05 indicate potential convergence problems.
n.effThe effective sample size, included only when BMA results are present.
runtime_tableA data frame with columns Method and Runtime,
reporting the computation time in seconds for each method.
total_runtime_secondsThe total computation time in seconds across all methods.
CI.computedLogical. TRUE if confidence intervals have been computed
via confint, FALSE
otherwise.
ameras for model fitting,
confint for computing confidence
intervals,
print for a shorter printed summary,
coef for extracting coefficients.
data("data", package = "ameras") ## Fit the model fit <- ameras(Y.binomial~dose(V1:V10, model="ERR"), data = data, family = "binomial", methods = "RC") ## Summary without confidence intervals summary(fit) ## Summary with confidence intervals fit <- confint(fit, method = "wald.orig") summary(fit) ## Access the summary table directly s <- summary_table(fit) ## Multiple methods fit2 <- ameras(Y.binomial~dose(V1:V10, model="ERR"), data = data, family = "binomial", methods = c("RC", "ERC", "MCML")) fit2 <- confint(fit2, method = "wald.orig") summary(fit2)data("data", package = "ameras") ## Fit the model fit <- ameras(Y.binomial~dose(V1:V10, model="ERR"), data = data, family = "binomial", methods = "RC") ## Summary without confidence intervals summary(fit) ## Summary with confidence intervals fit <- confint(fit, method = "wald.orig") summary(fit) ## Access the summary table directly s <- summary_table(fit) ## Multiple methods fit2 <- ameras(Y.binomial~dose(V1:V10, model="ERR"), data = data, family = "binomial", methods = c("RC", "ERC", "MCML")) fit2 <- confint(fit2, method = "wald.orig") summary(fit2)
Produce MCMC traceplots for amerasfit objects.
traceplot(object, ...) ## S3 method for class 'amerasfit' traceplot(object, iter = 5000, Rhat = TRUE, n.eff = TRUE, pdf = FALSE, ...)traceplot(object, ...) ## S3 method for class 'amerasfit' traceplot(object, iter = 5000, Rhat = TRUE, n.eff = TRUE, pdf = FALSE, ...)
object |
a |
iter |
number of iterations to include in the traceplot (defaults to last 5000) |
Rhat |
logical; whether to include R-hat diagnostics in the plot (default TRUE) |
n.eff |
logical; whether to include effective sample size in the plot (default TRUE) |
pdf |
logical; whether to save the output as a PDF (default FALSE) |
... |
additional arguments passed to |
Wrapper for MCMCvis::MCMCtrace to produce MCMC diagnostic plots. See ?MCMCtrace for more plotting options that can be provided through ....
Traceplots and posterior density plots.
data(data, package="ameras") fit <- ameras(Y.gaussian~dose(V1:V10), data, methods="BMA") traceplot(fit)data(data, package="ameras") fit <- ameras(Y.gaussian~dose(V1:V10), data, methods="BMA") traceplot(fit)
Applies exponential transformation to one or multiple components of parameter vector , where are lower limits that can be different for each component
transform1(params, index.t=1:length(params), lowlimit=rep(0,length(index.t)), boundcheck=FALSE, boundtol=1e-3, ... )transform1(params, index.t=1:length(params), lowlimit=rep(0,length(index.t)), boundcheck=FALSE, boundtol=1e-3, ... )
params |
full input parameter vector |
index.t |
indices of parameters to be transformed (default all) |
lowlimit |
lower limits to be applied (default zero), where the k-th component of |
boundcheck |
whether to produce a warning when any of the transformed parameters are within |
boundtol |
tolerance for producing a warning for reaching the boundary |
... |
not used |
Transformed parameter vector.
params <- c(.1, .5, 1) transform1(params, lowlimit=c(0, -1, 1))params <- c(.1, .5, 1) transform1(params, lowlimit=c(0, -1, 1))
Inverse of transform1 for the purpose of deriving initial values.
transform1.inv(params, index.t=1:length(params), lowlimit=rep(0,length(index.t)), ... )transform1.inv(params, index.t=1:length(params), lowlimit=rep(0,length(index.t)), ... )
params |
full input parameter vector |
index.t |
indices of parameters to be transformed (default all) |
lowlimit |
lower limits to be applied (default zero), where the k-th component of |
... |
not used |
Transformed parameter vector.
params <- c(.1, .5, 1) # Desired initial values on original scale transform1.inv(params, lowlimit=c(0, -1, 1)) # Initial values to use on transformed scaleparams <- c(.1, .5, 1) # Desired initial values on original scale transform1.inv(params, lowlimit=c(0, -1, 1)) # Initial values to use on transformed scale
Computes the Jacobian matrix of transform1. Note that lower limits do not need to be specified as the Jacobian is independent of those
transform1.jacobian(params, index.t=1:length(params), ... )transform1.jacobian(params, index.t=1:length(params), ... )
params |
input parameter vector (before transformation) to evaluate the Jacobian at |
index.t |
indices of parameters to be transformed (default all) |
... |
not used |
Jacobian matrix.
params <- c(.1, .5, 1) transform1.jacobian(params)params <- c(.1, .5, 1) transform1.jacobian(params)
Extracts the variance-covariance matrices of the parameter estimates
from a fitted amerasfit object.
## S3 method for class 'amerasfit' vcov(object, methods = c("RC", "ERC", "MCML", "FMA", "BMA"), ...)## S3 method for class 'amerasfit' vcov(object, methods = c("RC", "ERC", "MCML", "FMA", "BMA"), ...)
object |
A fitted model object of class |
methods |
Character vector specifying which estimation methods to extract
variance-covariance matrices for. One or more of |
... |
Additional arguments, currently unused. |
If a single method is requested or only one method was run, a named numeric matrix with rows and columns corresponding to model parameters. If multiple methods are requested and multiple methods were run, a named list of such matrices, one per method.
Note that for FMA and BMA the variance-covariance matrix is based
on the generated samples rather than a Hessian-based
approximation, and may differ in interpretation from the RC, ERC,
and MCML variance-covariance matrices. For BMA, the reliability of
the variance-covariance matrix depends on MCMC convergence as indicated by Rhat.
ameras for model fitting,
coef for extracting coefficients,
summary.amerasfit for a summary including standard
errors,
vcov for the generic function.
data("data", package="ameras") dosevars <- paste0("V", 1:10) fit <- ameras(Y.binomial ~ dose(all_of(dosevars), model="ERR"), data=data, family="binomial", methods=c("RC", "ERC")) ## Extract vcov for all available methods vcov(fit) ## Extract vcov for a single method, returns a matrix vcov(fit, methods="RC") ## Extract vcov for multiple methods, returns a named list vcov(fit, methods=c("RC", "ERC"))data("data", package="ameras") dosevars <- paste0("V", 1:10) fit <- ameras(Y.binomial ~ dose(all_of(dosevars), model="ERR"), data=data, family="binomial", methods=c("RC", "ERC")) ## Extract vcov for all available methods vcov(fit) ## Extract vcov for a single method, returns a matrix vcov(fit, methods="RC") ## Extract vcov for multiple methods, returns a named list vcov(fit, methods=c("RC", "ERC"))