Skip to contents

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 an amerasfit object is now provided by add_confint(). Both functions always compute the requested intervals, so a new add_confint() call replaces intervals already attached to the returned object. The force, print, and digits arguments have been removed; use summary() to display intervals attached to a fit.
  • coef() now returns a named numeric vector when an amerasfit object 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.amerasfit from summary_table to coefficients and removed the package-specific summary_table() accessor. Use coef(summary(fit)) to retrieve the table. Printed summaries are unchanged.
  • Removed the redundant CI.computed component from fitted objects and summaries. Attached intervals are detected from method-specific CI components.
  • Removed the deprecated direct argument interface to ameras(). Models must now be specified through formula; calls using the former Y, dosevars, doseRRmod, deg, M, X, offset, entry, exit, or setnr arguments fail with migration guidance.
  • Removed the deprecated CI, params.profCI, maxit.profCI, and tol.profCI arguments from ameras(). Confidence intervals must be added after fitting with add_confint().
  • Removed the deprecated included.replicates.BMA alias; use included.realizations.BMA instead.
  • Removed non-formula effect-modifier syntax. Use modifier = ~ M1 + M2 instead of modifier = M1 + M2 inside dose().
  • Renamed the bundled example dataset from data to ameras_simulated.
  • Renamed the proportional hazards BMA output component prophaz_timepoints to prophaz.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 NULL controls are stored as list(reltol = 1e-10), and the same fallback is applied when recomputing intervals for older objects. This can change recomputed profile bounds that previously used optim()’s looser default. Explicit control lists and one-dimensional optimize() tolerances are unchanged.
  • FMA now passes the requested loglim to its realization-specific likelihoods instead of silently using 1e-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 for amerasfit objects 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-6 and maxit.profCI = 100, replacing 1e-2 and 20 to 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 multiple dose() terms, empty dose selections, and special terms used in unsupported positions or outcome families. Non-survival responses and arguments to Surv(), strata(), and offset() now produce targeted errors when they are not plain data-column names.
  • Public amerasfit methods 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: and WARNING: prefixes.
  • The bundled example dataset now loads lazily.

Documentation

  • Expanded ?ameras with 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

Bug fixes

  • Fixed a BMA error when fitting models with a single formula-based effect modifier.
  • Fixed numerical failures that could occur while fitting subgroup-coded effect modifiers, despite valid transformed subgroup effects.
  • FMA now honors the optimizer selected through optim.method.

Changes

  • Newly fitted method results no longer contain the redundant runtime field. Fitting, confidence interval, and total computation times remain available through timing. Fitted objects from earlier versions that contain only runtime remain supported.

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 has entry > exit.
  • Fixed conditional logistic regression fits with strata() terms that use a matched set column name other than setnr.
  • 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.BMA leaves 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 the entry < t <= exit risk-set convention.
  • Profile likelihood confidence intervals now handle unusable Hessian matrices and difficult bounds more robustly. The search uses explicit adaptive bracketing and returns NA with diagnostic warnings when a bound cannot be reliably solved.

New features

  • Added formula-based effect modifier syntax. Use modifier = ~ M for reference-plus-contrast coding and modifier = ~ 0 + M or modifier = ~ M - 1 for subgroup-specific dose-effect parameters. Formula modifiers support binary numeric/logical variables and factors with treatment coding based on the factor level order. The older modifier = M1 + M2 syntax 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 a na.action argument for model-input missing values after formula terms have been expanded. By default it follows getOption("na.action") (typically na.omit), stores the omitted-row action on the fitted object, and reapplies the same policy when data are supplied later for objects fitted with keep.data=FALSE. na.fail and na.pass are also supported. na.exclude is 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 future framework via future.apply when available. Users can enable parallel execution by setting a future plan before calling ameras(), and future.chunk.size.FMA controls the chunk size passed to future.apply::future_lapply().
  • Right-hand-side covariate terms now support namespace-qualified model-matrix basis functions such as splines::ns() and splines::bs(). For keep.data=FALSE fits, later calls that use supplied data apply the same expanded covariate columns as the original fit.
  • Added convergence() for amerasfit objects 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 future framework.

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 by na.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() and confint(): columns pval.lower and pval.upper for 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 runtime field is retained as a compatibility summary and is updated when confint() 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 inpar check in ameras() to generate an error when it should not.
  • Fixed an issue where FMA generated an error instead of returning NULL for generated samples when all individual fits were excluded.
  • Fixed an issue where setting keep.data=FALSE and passing data to confint() 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 isSymmetric check for FMA variance matrices, which caused platform-dependent differences in included realizations due to numerical differences between Cholesky and solve-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. Use force=TRUE to recompute with different settings. confint() now also prints the computed confidence intervals when called with print=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 dosevars variable defined locally (e.g., within a simulation script) through all_of(dosevars) in the formula passed to ameras().

New methods and accessors

  • residuals(): computes Pearson, deviance, and response residuals for all supported families, and Schoenfeld residuals for family="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. For family="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 a summary.amerasfit object 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 replicate with realization, including in names of arguments and output. As a result, the argument included.replicates.BMA is now deprecated and will be removed in version 1.0.0. Use included.realizations.BMA instead.

New features

  • ecdfplot() now has an argument show.mean (default TRUE) 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.lowerbound and CI.upperbound in the summary() output to CI.lower and CI.upper, respectively.

  • Substantially increased ERC computation speed for the clogit and prophaz families.

ameras 0.2.0

CRAN release: 2026-04-26

Breaking changes

  • Confidence intervals are no longer computed inside ameras(). The arguments CI, params.profCI, maxit.profCI, and tol.profCI are deprecated and will be removed in version 1.0.0. Use the new confint() method instead. See ?confint.amerasfit for details.

  • The direct argument interface to ameras() is deprecated and will be removed in version 1.0.0. The arguments Y, dosevars, doseRRmod, deg, M, X, offset, entry, exit, and setnr are deprecated. Please use the new formula interface instead. See ?ameras for details.

New features

  • Implemented a formula interface for ameras(). The dose variable is specified using the special dose() term, which supports tidyselect syntax for selecting dose columns and allows specifying the dose-response model and effect modifiers directly in the formula. See ?ameras for details and examples.

  • Added confint.amerasfit() for computing confidence intervals separately from model fitting. See ?confint.amerasfit for 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 via confint(). Before calling confint(), 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.data added to ameras() (default TRUE). When TRUE, the data are stored on the returned amerasfit object, which is required for profile likelihood confidence interval computation via confint() without re-supplying the data. Set to FALSE to reduce memory usage for large datasets, in which case the data must be supplied to confint() explicitly. See ?ameras and ?confint.amerasfit for details.

ameras 0.1.1

CRAN release: 2026-03-29

  • Initial CRAN submission.