ameras (development version)
Breaking changes
-
confint()now follows the standard extractor convention: it returns a two-column matrix for a fit containing one method and a named list of such matrices for a fit containing multiple methods. The former behavior of attaching intervals and their diagnostics to anamerasfitobject is now provided byadd_confint(). Both functions always compute the requested intervals, so a newadd_confint()call replaces intervals already attached to the returned object. Theforce,print, anddigitsarguments have been removed; usesummary()to display intervals attached to a fit. -
coef()now returns a named numeric vector when anamerasfitobject contains one fitted method. Objects containing multiple methods continue to return a data frame with one column per method. - Renamed the coefficient table in
summary.amerasfitfromsummary_tabletocoefficientsand removed the package-specificsummary_table()accessor. Usecoef(summary(fit))to retrieve the table. Printed summaries are unchanged. - Removed the redundant
CI.computedcomponent from fitted objects and summaries. Attached intervals are detected from method-specificCIcomponents. - Removed the deprecated direct argument interface to
ameras(). Models must now be specified throughformula; calls using the formerY,dosevars,doseRRmod,deg,M,X,offset,entry,exit, orsetnrarguments fail with migration guidance. - Removed the deprecated
CI,params.profCI,maxit.profCI, andtol.profCIarguments fromameras(). Confidence intervals must be added after fitting withadd_confint(). - Removed the deprecated
included.replicates.BMAalias; useincluded.realizations.BMAinstead. - Removed non-formula effect-modifier syntax. Use
modifier = ~ M1 + M2instead ofmodifier = M1 + M2insidedose(). - Renamed the bundled example dataset from
datatoameras_simulated. - Renamed the proportional hazards BMA output component
prophaz_timepointstoprophaz.timepoints, matching the documented name and vignette examples. - User-supplied parameter transformations must now be componentwise and strictly monotone: each reported parameter may depend only on its matching optimizer parameter. Initial checks inspect the starting values and coordinate perturbations. Increasing and decreasing transformations are supported; directions are determined locally when obtaining transformed Wald or profile likelihood intervals.
Bug fixes
- HPD intervals for FMA and BMA now honor
level; previously they always used 95% even when the returned column labels showed a different requested level. - Schoenfeld residuals and diagnostic plots now use the fitted factor and subgroup modifier names and designs, avoiding covariance-indexing errors.
- Transformed Wald and profile likelihood intervals now order decreasing transformations correctly, including profile diagnostics and one-sided failures.
- Profile nuisance optimizations now use the effective fitting controls. Omitted or
NULLcontrols are stored aslist(reltol = 1e-10), and the same fallback is applied when recomputing intervals for older objects. This can change recomputed profile bounds that previously usedoptim()’s looser default. Explicit control lists and one-dimensionaloptimize()tolerances are unchanged. - FMA now passes the requested
loglimto its realization-specific likelihoods instead of silently using1e-30. - BMA-only calls no longer require a Jacobian for a supplied transformation, which BMA does not apply. Calls with methods including a frequentist method still require a Jacobian.
- RC, ERC, and MCML fits now warn when the selected final optimizer result returns a nonzero convergence code. For automatic Nelder-Mead plus BFGS fitting, the warning is based on the BFGS result when refinement completes and on the retained Nelder-Mead result when refinement fails.
- A failure of the automatic BFGS refinement due to non-finite finite-difference evaluations no longer aborts a valid Nelder-Mead fit. The Nelder-Mead solution is retained and assessed using the usual Hessian and convergence diagnostics.
New features
- Added an
nobs()method foramerasfitobjects that returns the number of observations used for fitting after missing-value and family-specific exclusions.
Improvements
- Profile likelihood intervals now default to
tol.profCI = 1e-6andmaxit.profCI = 100, replacing1e-2and20to improve accuracy for narrow intervals. Larger tolerances can still be requested to reduce computation time, especially for ERC and MCML; the p-value accuracy check is unchanged. Warnings now suggest decreasing the tolerance for inaccurate roots or increasing the iteration limit when reached, retain root-finding warning details, and give separate guidance for bracketing failures. - Formula parsing now requires a two-sided formula and rejects unknown or duplicated named arguments in
dose(), invalid model or degree values, missing or multipledose()terms, empty dose selections, and special terms used in unsupported positions or outcome families. Non-survival responses and arguments toSurv(),strata(), andoffset()now produce targeted errors when they are not plain data-column names. - Public
amerasfitmethods now warn about unused arguments passed through..., helping detect misspelled or unsupported arguments. - Improved validation messages, including correcting factor-validation errors and removing redundant
ERROR:andWARNING:prefixes. - The bundled example dataset now loads lazily.
Documentation
- Expanded
?ameraswith dedicated formula-syntax and outcome-model sections, documented restrictions on special formula terms, and added a more complete example with links to the relevant vignettes. - Updated the README and vignettes for the revised confidence-interval and coefficient-summary interfaces, including the benefits of attaching expensive profile likelihood intervals with
add_confint()for reuse in summaries. Expanded documentation of the simulated example data.
ameras 0.5.2
CRAN release: 2026-07-28
ameras 0.5.1
CRAN release: 2026-07-16
Bug fixes
- Fixed an issue where large differences in AIC values between dose realizations could cause FMA weights to become
NaN, resulting in an error. - Fixed an issue where a subsequent call to
confint()would print intervals for dose-related parameters only.confint()now prints intervals for all parameters. - Fixed validation for proportional hazards models specified with
Surv(entry, exit, status).ameras()now checks the observed entry and exit time values and errors when any subject hasentry > exit. - Fixed conditional logistic regression fits with
strata()terms that use a matched set column name other thansetnr. - Fixed BMA handling for models with a single sampled model parameter, including during sample-based confidence interval construction.
- Fixed an issue where an FMA realization with a finite fitted Hessian but non-finite sampling covariance could trigger a low-level
rmvnorm()error. Such realizations are now excluded with a warning before FMA weights and samples are computed. - BMA now errors clearly if
included.realizations.BMAleaves fewer than two dose realizations, since one-realization analyses should use RC. - Conditional logistic regression now explicitly excludes matched sets of size 1 and matched sets with no cases, and errors for matched sets with more than one case.
- Proportional hazards regression now explicitly excludes rows with
entry == exit, which have zero follow-up time under theentry < t <= exitrisk-set convention. - Profile likelihood confidence intervals now handle unusable Hessian matrices and difficult bounds more robustly. The search uses explicit adaptive bracketing and returns
NAwith diagnostic warnings when a bound cannot be reliably solved.
New features
- Added formula-based effect modifier syntax. Use
modifier = ~ Mfor reference-plus-contrast coding andmodifier = ~ 0 + Mormodifier = ~ M - 1for subgroup-specific dose-effect parameters. Formula modifiers support binary numeric/logical variables and factors with treatment coding based on the factor level order. The oldermodifier = M1 + M2syntax is deprecated. - BMA now supports subgroup-specific formula modifiers. Priors and MCMC sampling remain on the internal reference-plus-contrast scale, while reported summaries, stored samples, diagnostics, and sample-based intervals use the subgroup-specific scale.
-
ameras()now supports ana.actionargument for model-input missing values after formula terms have been expanded. By default it followsgetOption("na.action")(typicallyna.omit), stores the omitted-row action on the fitted object, and reapplies the same policy when data are supplied later for objects fitted withkeep.data=FALSE.na.failandna.passare also supported.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. - FMA realization-specific fits can now use the
futureframework viafuture.applywhen available. Users can enable parallel execution by setting afutureplan before callingameras(), andfuture.chunk.size.FMAcontrols the chunk size passed tofuture.apply::future_lapply(). - Right-hand-side covariate terms now support namespace-qualified model-matrix basis functions such as
splines::ns()andsplines::bs(). Forkeep.data=FALSEfits, later calls that use supplied data apply the same expanded covariate columns as the original fit. - Added
convergence()foramerasfitobjects to extract or recompute optimizer gradient diagnostics for RC, ERC, and MCML fits. - Added
dose_lrt()for global and individual likelihood-ratio tests of dose-related parameters in RC, ERC, and MCML fits. - Added vignettes for standard analyses with one dose realization, effect modification, manual FMA from realization-specific RC fits, and parallel FMA with the
futureframework.
Improvements
- FMA now always reports the number of excluded realizations, rather than warning only when more than 20% of realizations are excluded.
- FMA no longer assigns a minimum sample size of 1 to every realization. Realizations with model-averaging weights that round to 0 samples are excluded, and the number excluded for this reason is reported with a message.
- FMA now warns when results are based on only 1 or 2-5 realizations after exclusions.
- Added numerical diagnostics that warn when right-hand-side covariates appear poorly scaled or ill-conditioned, and when
optim()reports convergence but optimizer diagnostics suggest the solution may not be fully stationary. When the Hessian is usable, the optimizer warning uses the approximate remaining objective improvement on both absolute and relative scales. -
summary()now reports row counts in the order applied during fitting: supplied rows, nonzero omissions byna.action, nonzero family-specific exclusions, and rows used for fitting when this differs from the supplied row count. For conditional logistic regression, it reports rows excluded because they belong to uninformative matched sets. For proportional hazards regression with entry times, it reports rows excluded because they have zero follow-up time. - Streamlined information printed by
summary()andconfint(): columnspval.lowerandpval.upperfor profile likelihood intervals are no longer printed. They are still accessible within the fit object, and warnings are still printed in case an inaccurate profile likelihood bound is suspected. - Added structured timing information to fitted method results, separating fitting time, confidence interval computation time, and total time. Printed runtime summaries now use CPU time, so time spent while the computer is asleep is not counted. The existing
runtimefield is retained as a compatibility summary and is updated whenconfint()adds confidence interval timing. - Added validation to reject input data containing the reserved ameras column name
rcdose_ameras.
ameras 0.4.0
CRAN release: 2026-05-29
Bug fixes
- Fixed a bug causing the
inparcheck inameras()to generate an error when it should not. - Fixed an issue where FMA generated an error instead of returning
NULLfor generated samples when all individual fits were excluded. - Fixed an issue where setting
keep.data=FALSEand passing data toconfint()failed a validation check when effect modifiers were present. - Fixed an issue where profile likelihood confidence intervals for the ERC method of the proportional hazards family were computed using the non-ERC likelihood, silently ignoring the measurement error correction.
- Removed the
isSymmetriccheck for FMA variance matrices, which caused platform-dependent differences in included realizations due to numerical differences between Cholesky andsolve-based computations. The Cholesky-based variance computation now used guarantees exact symmetry without an explicit check.
Improvements
- Reduced memory usage and improved computation speed for large datasets: removed the use of N x N matrices for ERC for the proportional hazards family, and precomputed centered dose matrices for ERC are now stored and reused across likelihood evaluations rather than recomputed at each call.
-
confint()no longer recomputes confidence intervals by default if they have already been computed. Useforce=TRUEto recompute with different settings.confint()now also prints the computed confidence intervals when called withprint=TRUE(default). - FMA and BMA output now includes a variance-covariance matrix
vcov, computed from the model-averaged posterior samples. - It is now possible to use a
dosevarsvariable defined locally (e.g., within a simulation script) throughall_of(dosevars)in the formula passed toameras().
New methods and accessors
-
residuals(): computes Pearson, deviance, and response residuals for all supported families, and Schoenfeld residuals forfamily="prophaz", supporting both raw and scaled versions following Grambsch and Therneau (1994). -
plot(): diagnostic plots including residuals versus fitted values and normal Q-Q plots. Forfamily="prophaz", Schoenfeld residual plots are produced to assess the proportional hazards assumption. -
vcov(): extracts the variance-covariance matrix of parameter estimates for one or more estimation methods. -
included_realizations(): returns the indices of realizations included in FMA and BMA model averaging. -
Rhat(): returns the Gelman-Rubin convergence diagnostics and effective sample sizes for BMA results. -
summary_table(): extracts the summary table from asummary.amerasfitobject as a data frame, for programmatic access to parameter estimates, standard errors, and confidence intervals.
ameras 0.3.0
CRAN release: 2026-05-07
Breaking changes
- Replaced all occurrences of
replicatewithrealization, including in names of arguments and output. As a result, the argumentincluded.replicates.BMAis now deprecated and will be removed in version 1.0.0. Useincluded.realizations.BMAinstead.
New features
-
ecdfplot()now has an argumentshow.mean(defaultTRUE) to toggle whether to plot curves for the distribution of the mean doses across realizations and individuals.
Minor improvements and fixes
Shortened column names
CI.lowerboundandCI.upperboundin thesummary()output toCI.lowerandCI.upper, respectively.Substantially increased ERC computation speed for the
clogitandprophazfamilies.
ameras 0.2.0
CRAN release: 2026-04-26
Breaking changes
Confidence intervals are no longer computed inside
ameras(). The argumentsCI,params.profCI,maxit.profCI, andtol.profCIare deprecated and will be removed in version 1.0.0. Use the newconfint()method instead. See?confint.amerasfitfor details.The direct argument interface to
ameras()is deprecated and will be removed in version 1.0.0. The argumentsY,dosevars,doseRRmod,deg,M,X,offset,entry,exit, andsetnrare deprecated. Please use the new formula interface instead. See?amerasfor details.
New features
Implemented a formula interface for
ameras(). The dose variable is specified using the specialdose()term, which supports tidyselect syntax for selecting dose columns and allows specifying the dose-response model and effect modifiers directly in the formula. See?amerasfor details and examples.Added
confint.amerasfit()for computing confidence intervals separately from model fitting. See?confint.amerasfitfor details.Added function
ecdfplot()for exploratory visualization of the dose realizations before model fitting.
General improvements
-
Reduced memory usage for large datasets.
- Removed the use of an N x N matrix for ERC for the Poisson family, improving both memory and computation speed.
- Removed duplicate data storage for RC and ERC for all families.
summary.amerasfit()now only includes confidence interval columns after they have been computed viaconfint(). Before callingconfint(), a note is printed directing the user to compute confidence intervals.Profile likelihood confidence interval bounds now include p-values in the summary table, making it easier to assess the accuracy of the root-finding algorithm.
Removed memoization of the profile likelihood function as it was causing issues and likely not providing much benefit.
New arguments
-
keep.dataadded toameras()(defaultTRUE). WhenTRUE, the data are stored on the returnedamerasfitobject, which is required for profile likelihood confidence interval computation viaconfint()without re-supplying the data. Set toFALSEto reduce memory usage for large datasets, in which case the data must be supplied toconfint()explicitly. See?amerasand?confint.amerasfitfor details.
