
Analyze Multiple Exposure Realizations
ameras.RdFit regression models that account for exposure uncertainty using multiple exposure realizations. Supported outcome models are Gaussian, binomial, Poisson, proportional hazards, multinomial, and conditional logistic regression. Estimation methods include regression calibration (RC), extended regression calibration (ERC), Monte Carlo maximum likelihood (MCML), frequentist model averaging (FMA), and Bayesian model averaging (BMA).
Usage
ameras(formula, data, family="gaussian", methods="RC",
transform=NULL,
transform.jacobian=NULL, inpar=NULL, loglim=1e-30, MFMA=100000,
future.chunk.size.FMA=NULL,
prophaz.numints.BMA=10, ERRprior.BMA="doubleexponential", nburnin.BMA=5000,
niter.BMA=20000, nchains.BMA=2, thin.BMA=10, included.realizations.BMA=NULL,
optim.method="Nelder-Mead", control=NULL,
keep.data=TRUE, na.action=getOption("na.action"), ... )Arguments
- formula
an object of class
"formula"containing the model specification. See Details.- data
input data frame.
- family
outcome model family:
"gaussian","binomial","poisson","prophaz","multinomial"or"clogit"(default"gaussian").- methods
character vector of one or multiple methods to apply. Options:
"RC","ERC","MCML","FMA","BMA"(default"RC").- transform
function for parameter transformation during optimization (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
log(max(x, loglim))(default1e-30).- MFMA
number of samples for
"FMA"to compute estimates and CIs (default 100,000).- future.chunk.size.FMA
optional positive number controlling the average number of FMA dose realizations per future. When
NULL(the default), approximately one future per available worker is used. Parallel execution is controlled by the user's currentfuture::plan(); the default plan is sequential.- prophaz.numints.BMA
for
methods="BMA"withfamily="prophaz", the number of subintervals with constant baseline hazard (default 10). Cut points are determined based on quantiles of the event time distribution among cases.- ERRprior.BMA
prior for dose-related parameters when
doseRRmod="ERR"or"LINEXP"andmethods="BMA". Options:"truncated_normal","truncated_horseshoe","truncated_doubleexponential","normal","horseshoe","doubleexponential", see Details (default"doubleexponential").- 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).
- optim.method
method used for optimization by
optim. Options are"Nelder-Mead"and"BFGS". When using Nelder-Mead, a second optimization with BFGS is normally run to refine the fit. If this automatic BFGS refinement fails because its finite-difference evaluations are non-finite, the Nelder-Mead solution is retained and checked using the usual Hessian and convergence diagnostics. A warning is emitted if the selected final optimizer result has a nonzero convergence code.- control
control list passed to
optim(defaultlist(reltol=1e-10)).- keep.data
whether to attach data to the output object (default
TRUE). When the data object is large,keep.datacan be set toFALSEto preserve memory. The attached data is used to compute profile likelihood confidence intervals, but can also be supplied separately whenkeep.data=FALSE. Seeconfint.- na.action
function or function name controlling missing-value handling for model inputs after formula terms have been expanded. By default,
getOption("na.action")is used, typicallyna.omit. Usena.failto reject missing model inputs explicitly, orna.passto skip row removal; missing model inputs left byna.passwill generally cause an error during input checks or model fitting.na.excludeis accepted for fitting, but residuals and diagnostic plots are returned for the fitted rows rather than padded back to the originally supplied row count.- ...
other arguments, passed to functions such as
transform.
Formula Syntax
Models are specified through formulas of the form
Y ~ dose(dose_expression, model="ERR", deg=1, modifier=~M1+M2) + X1 + X2.
Exactly one dose() term is required. It must be a standalone additive
term rather than part of an interaction or transformation. Its unnamed
dose_expression argument selects the exposure realization columns using
eval_select syntax. For example, use
D1:D1000 for sequentially named columns or
all_of(dosevars) for a character vector of column names.
The recognized named arguments inside dose() are model,
deg, and modifier; their names must be written exactly. Unknown
or duplicated named arguments produce an error. For
non-Gaussian families, model selects the exponential relative risk
model ("EXP"), linear-exponential model ("LINEXP"), or linear
excess relative risk model ("ERR", the default). For exponential and
linear ERR models, deg=1 fits a linear exposure effect and deg=2
adds a quadratic term.
The optional modifier argument uses a one-sided formula. Use
modifier=~M for reference-plus-contrast coding and
modifier=~0+M or modifier=~M-1 for subgroup-specific dose
coefficients. Modifier variables may be binary numeric, logical, or
factor with the first level used as the reference category. Interactions,
transformed modifier terms, continuous numeric modifiers, character modifiers,
and no-intercept coding with multiple modifier variables are not supported.
The special terms are parsed more narrowly than ordinary model-formula terms.
For non-survival models, the response must be a single, untransformed data
column. The argument to strata() for conditional logistic regression
and the argument to offset() for Poisson regression must each be one
untransformed data column. Proportional hazards models require
Surv(exit, status) or Surv(entry, exit, status), with each
argument naming a data column. Expressions such as
offset(log(person_time)) or
strata(interaction(center, set)) are therefore not supported; create
the derived column in data first. Exactly one strata() term is
required for conditional logistic models, while an optional offset()
term may occur at most once in Poisson models. These terms are not supported
for other outcome families.
Additional right-hand-side covariates are expanded with
model.matrix and may use standard formula features such as
factor contrasts, interactions, I() terms, and basis functions. For
example, X1*X2, I(age^2), splines::ns(age, df=3), and
splines::bs(age, df=4) are supported. These terms must preserve one
value per input row; terms that drop rows internally, such as
stats::na.omit(X), are not supported. Removing the overall intercept
with -1 or +0 is also not supported.
Supported Outcome Models
For the Gaussian family, $$Y_i \sim N(\mu_i, \sigma^2),$$ with $$\mu_i = \alpha_0 + \bm X_i^T \bm \alpha + \beta_1 D_i + \beta_2 D_i^2 + \bm M_i^T \bm \beta_{m1}D_i + \bm M_i^T \bm \beta_{m2}D_i^2.$$ Here \(\bm X_i\) are covariates, \(D_i\) is the exposure with measurement error, and \(\bm M_i\) are effect modifier design columns. The quadratic exposure terms and effect modification are optional.
For non-Gaussian families, the supported main-exposure relative risk models are the exponential model $$RR_i=\exp(\beta_1 D_i+\beta_2 D_i^2+ \bm M_i^T \bm \beta_{m1}D_i + \bm M_i^T \bm \beta_{m2}D_i^2),$$ the linear excess relative risk (ERR) model $$RR_i=1+\beta_1 D_i+\beta_2 D_i^2+ \bm M_i^T \bm \beta_{m1}D_i + \bm M_i^T \bm \beta_{m2}D_i^2,$$ and the linear-exponential model $$RR_i=1+(\beta_1+\bm M_i^T \bm \beta_{m1})D_i \exp\{(\beta_2+\bm M_i^T \bm \beta_{m2})D_i\}.$$ Quadratic and effect modification terms are optional where applicable.
For binary outcomes, logistic regression uses $$p_i/(1-p_i)=RR_i\exp(\alpha_0+\bm X_i^T \bm \alpha).$$
For counts, Poisson regression uses $$Y_i \sim \text{Poisson}(\mu_i), \qquad \mu_i=RR_i\exp(\alpha_0+\bm X_i^T \bm \alpha)\times \text{offset}_i,$$ with an optional offset.
For time-to-event outcomes, proportional hazards regression uses $$h(t)=h_0(t)RR_i\exp(\bm X_i^T \bm \alpha),$$ where \(h_0\) is the baseline hazard.
For a categorical outcome with \(Z>2\) categories, multinomial logistic regression uses the last category as the referent (\(\alpha_{0,Z}=\bm \alpha_Z=\beta_{1,Z}=\beta_{2,Z}= \bm \beta_{m1,Z}=\bm \beta_{m2,Z}=0\)): $$P(Y_i=z)=\frac{RR_i\exp(\alpha_{0,z}+\bm X_i^T \bm \alpha_z)} {1+\sum_{s=1}^{Z-1}RR_i\exp(\alpha_{0,s}+\bm X_i^T \bm \alpha_s)}.$$
For matched case-control data, conditional logistic regression uses $$P\left(Y_i=1, Y_k=0\ \forall k\ne i\ \bigg|\ \sum_{i\in\mathcal R}Y_i=1\right)= \frac{RR_i\exp(\bm X_i^T \bm \alpha)} {\sum_{k\in\mathcal R}RR_k\exp(\bm X_k^T \bm \alpha)},$$ where \(\mathcal R\) is the matched set containing individual \(i\).
The estimation methods are described by Carroll et al. (2006) doi:10.1201/9781420010138 for RC, Little et al. (2023) doi:10.1038/s41598-023-42283-y for ERC, Stayner et al. (2007) doi:10.1667/RR0677.1 for MCML, Kwon et al. (2023) doi:10.1371/journal.pone.0290498 for FMA, and Kwon et al. (2016) doi:10.1002/sim.6635 for BMA.
Value
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 used for fitting after applying
na.action and any family-specific filtering), num.rows.original (the
number of rows supplied before applying na.action), na.action (the
omitted-row object returned by the missing-value action, when applicable),
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, including model$data, which is either the data frame used for
model fitting when keep.data=TRUE or NULL otherwise), and
CI.computed (logical, whether confidence intervals have been attached by
add_confint).
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.
- timing
list with CPU and elapsed timings for fitting, confidence interval computation, and their total. CPU time is used for printed runtime summaries.
For RC, ERC, and MCML the following additional output is included:
- optim
a list object with results returned by optim. Components are
par(raw parameters before applying a transformation if applicable),hessian(Hessian matrix forpar),convergence(convergence code with 0 indicating convergence and a nonzero value indicating that the optimizer did not converge; code 1 indicates that the maximal number of iterations was reached), andcounts(the number of likelihood function evaluations used during optimization).- loglik
log-likelihood value at the optimum.
For RC and ERC, the output additionally contains:
- ERC
logical, whether the output is for ERC (
ERC=TRUE) or RC (ERC=FALSE).
For BMA the output additionally contains:
- samples
MCMC posterior samples, as obtained from
nimble. Withnchains.BMA > 1, this is a list withnchains.BMAcomponents, each a named matrix with the samples from one chain in its rows and columns corresponding to model parameters. Withnchains.BMA = 1, this is a single named matrix.- Rhat
data frame with two columns,
Rhatandn.eff. The first column contains the Gelman-Rubin statistics \(\hat R \geq 1\) that can be used to assess convergence of MCMC chains. A value of 1 indicates good convergence and values \(>1.05\) indicate poor convergence. The effective sample sizen.effis a measure of how many independent samples the auto-correlated MCMC samples correspond to. A low effective sample size indicates high correlations and/or poor mixing. For single-chain BMA fits, these diagnostics cannot be estimated and are returned asNA.- included.realizations
indices of realization exposures that were included to obtain the results.
- prophaz.timepoints
for
family="prophaz", time points defining the intervals on which the estimated baseline hazard is constant; these areprophaz.numints.BMA + 1time points covering the interval(min(entry), max(exit)), based on quantiles among observed event times. See Details.
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.
- weights
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
add_confint, print,
coef, nobs,
confint,
summary,
vcov,
residuals,
plot, traceplot,
convergence,
Rhat, and
included_realizations.
Details
Missing values in model inputs are handled by na.action after formula
terms have been expanded. Thus missing values in raw variables and in derived
covariate columns, such as factor contrasts, interactions, and spline bases,
are handled consistently before model fitting. The omitted-row action is stored
on the fitted object. When keep.data=FALSE and data are supplied later to
methods such as confint(), add_confint(), residuals(),
and plot(), the
same missing-value policy is reapplied. Unlike
lm and glm, na.exclude does not
pad residuals or diagnostic plots back to the originally supplied row count;
those outputs are computed on the fitted rows.
When keep.data=FALSE, later calls that use supplied data apply the same
expanded covariate columns as the original fit. If covariates appear poorly
scaled or ill-conditioned, ameras emits a diagnostic warning; centering or
scaling continuous covariates such as calendar year can improve numerical
optimization.
For conditional logistic regression, matched sets of size 1 and matched sets
with no cases are excluded, and matched sets with more than one case are not
currently supported. For proportional hazards regression with entry times,
rows with entry == exit are excluded because they have zero follow-up
time under the entry < t <= exit risk-set convention.
A transformation can be used to reparametrize parameters for optimization, such that the likelihoods are evaluated at transform(parameters), where parameters are unconstrained. This 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: \(\alpha_0, \bm \alpha, \beta_1, \beta_2, \bm \beta_{m1}, \bm \beta_{m2}, \sigma\), where \(\bm \alpha\), \(\bm\beta_{m1}\) and \(\bm \beta_{m2}\) can be vectors, with lengths matching \(\bm X\) and \(\bm M\), respectively. \(\sigma\) 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 \(Z-1\) parameter vectors in the order as given above, where \(Z\) 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 \(\beta_1\) and \(\beta_2\) by default, with lower limits \(-1/max(D)\) for \(\beta_1\) in the linear dose-response and \((0,-1/max(D^2))\) for \((\beta_1,\beta_2)\) in the linear-quadratic dose-response, respectively. For the linear-exponential model, a lower limit of 0 is used for \(\beta_1\), and no transformation is used for \(\beta_2\). If reference-plus-contrast effect modifiers are specified, no transformation is used for modifier contrast parameters. With subgroup-specific modifier coding, the default transformation is applied to the subgroup dose-effect parameters. For ERR and linear-exponential models with effect modifiers, subgroup-specific coding can therefore be more numerically robust than reference-plus-contrast coding, because bounds are applied directly to each subgroup dose-effect parameter. 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 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, horseshoe, and double exponential priors, and the same priors truncated at 0 to yield positive values. In particular:
Normal: \(\beta_j \sim N(0,1000)\) for all exposure-response parameters \(\beta_j\)
Horseshoe (shrinkage prior): \(\tau \sim \text{Cauchy}(0,1)^+; \lambda_j \sim \text{Cauchy}(0,1)^+; \beta_j \sim N(0, \tau^2 \lambda_j^2)\). Here \(\tau\) is shared across all parameters
Double exponential (shrinkage prior): \(\lambda_j \sim \text{Cauchy}(0,1)^+; \beta_j \sim \text{DoubleExponential}(0,\lambda_j)\)
For all other parameters, and when using the exponential exposure-response model or the Gaussian outcome family, the prior is \(N(0, 1000)\). For the parameter \(\sigma\) in the Gaussian family, this prior is truncated at 0. When subgroup-specific modifier coding is used in BMA, priors and MCMC sampling remain on the internal reference-plus-contrast scale; reported coefficients, variance matrices, samples, diagnostics, and sample-based intervals are converted to the subgroup-specific scale.
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.
See also
confint for returning confidence intervals,
add_confint for attaching confidence intervals,
summary for a summary of the fitted model
including confidence intervals if computed, coef
for extracting coefficients, nobs for the number
of observations used for fitting, vcov for extracting
variance-covariance matrices, and included_realizations
for inspecting which realizations contributed to model averaging.
For extended examples, see
vignette("modelfitting", package="ameras") for the general workflow,
vignette("relativeriskmodels", package="ameras") for relative risk
models, vignette("effectmodification", package="ameras") for effect
modification, and vignette("confidenceintervals", package="ameras")
for confidence and credible intervals.
References
Roberti, S., Kwon D., Wheeler W., Pfeiffer R. (in preparation). ameras: An R Package to Analyze Multiple Exposure Realizations in Association Studies
Examples
## Fit a Gaussian regression-calibration model using ten exposure realizations
example_data <- ameras_simulated[1:500, ]
fit <- ameras(
Y.gaussian ~ dose(V1:V10) + X1 + X2,
data = example_data,
family = "gaussian",
methods = "RC"
)
#> Fitting RC
## Extract estimates
coef(fit)
#> (Intercept) X1 X2 dose sigma
#> -1.4325161 0.5776954 -0.5216418 1.1596141 1.1238400
## Add Wald confidence intervals and display a detailed summary
fit <- add_confint(fit, type = "wald.orig", print = FALSE)
summary(fit)
#> Call:
#> ameras(formula = Y.gaussian ~ dose(V1:V10) + X1 + X2, data = example_data,
#> family = "gaussian", methods = "RC")
#>
#> Rows: 500
#>
#> Total CPU runtime: 0.1 seconds
#>
#> CPU runtime in seconds by method:
#>
#> Method Fit CI Total
#> RC 0.128 0.0 0.128
#>
#> Summary of coefficients by method:
#>
#> Method Term Estimate SE CI.lower CI.upper
#> RC (Intercept) -1.4325 0.09084 -1.611 -1.2545
#> RC X1 0.5777 0.10087 0.380 0.7754
#> RC X2 -0.5216 0.12672 -0.770 -0.2733
#> RC dose 1.1596 0.05252 1.057 1.2625
#> RC sigma 1.1238 0.03554 1.054 1.1935
#>