Release Notes for Pumas 2.7.0

Pumas

Features and improvements

  • Add the parallel absorption two compartment model Depots2Central1Periph1
  • Add the three compartment model Central1Periph2
  • Add steady state options to diffeq_options to set tolerances for steady state calculations.
  • Allow for init_randeffs input in empirical_bayes to choose initial estimates.
  • Allow user to pass init_randeffs to JointMAP as a vector of NamedTuples.
  • Support deconstruction of variables in @pre such as η₁, η₂ = η to unpack and provide elementwise names to a multidimensional random effect.
  • Require the number of samples to be set when using simobs with only a model/bayesresult and subject/population input to avoid the confusing default of 10 samples.
  • Print convergence measure instead of Successful Minimization: true/false in fit output.
  • Introduce sample_params for inference to enable simulation with uncertainty in a more controlled way.
  • Introduce center_randeffs for more appropriate initialization of random effects in the non-Gaussian case. The choice of "center" for each distribution can be found by calling Pumas.center_stat(dist) for a given distribution dist.
  • Make input order consistent for center_randeffs, init_randeffs, zero_randeffs, and sample_randeffs (see deprecations at the bottom of this page).
  • Use the same solver and tolerances between simobs and fit.
  • Extend StatsAPI.pvalue to be used with the output of lrtest.
  • Make icoefs more useful in the DataFrame based on inspect. Previously icoefs would only be populated at covariate times, but now they will be populated at all times in the DataFrame output.
  • Make constant covariates available in @random to enable more flexible random effects definitions.
  • Use Optim.LBFGS as default optimization algorithm for JointMAP due to the large number of parameters to be optimized.
  • Only support whitelisted diffeq_options settings to avoid users from setting options that might not be compatible with the internal handling of integrator options used in Pumas. Supported options are: :alg, :abstol, :reltol, :maxiters, :continuity, :ss_abstol, :ss_reltol, :ss_maxiters.
  • Add symbolic_jacobian (default: false) to @options to enable symbolic calculation of the Jacobian of the ODE system.
  • Show what's fixed and optimized in tables derived from fit calls.
  • Support events with zero bolus doses (amt = 0).
  • Restrict eta shrinkage computation to Normal and MvNormal to avoid inappropriately calculating shrinkage for non-Gaussian random effects where the interpretation is unclear.
  • Allow for ensemblealg input in icoef when empirical bayes estimates will be computed.
  • Made the gradient calculation slightly more efficient by changing the order of the linear algebra operations.
  • Reordered some checks for finite likelihood and gradients to not evaluate the initial likelihood several times when fitting.
  • Support a zero Matrix in PDiagDomain such that zero(n,n) can be used in the parameter NamedTuple when simulating.

Documentation and error messages

  • Improvefindinfluential docstring to cover supported inputs.
  • Add docstring to NaivePooled to clarify how and when to use it.
  • Better error messages for non-sensical Bayesian cross-validation method specifications.
  • Always error if id and time columns are not present in the input to read_pumas and do the same for amt when event_date==true.
  • Add missing backtick in infer-docstring for MarginalMCMC.
  • Throw an error if a block in @emmodel is defined twice.
  • Fix vpc docstring that referenced ensemblealg twice.
  • Avoid tabs in formula printing for PumasEMModel.
  • Fix show method for FittedPumasEMModel that would fail if the model had multiple endpoints with different numbers of parameters.
  • Improve docstrings of closed form models in general.
  • Abort simulation if steady-state computation fails to converge.
  • Improve docstring of MarginalMCMC and inherit likelihood approximation in infer.
  • Add missing docstrings for loglikelihood.
  • Fix typo in warning when using adjust_evid34 and print the warnings only once.
  • Document Pumas definition of eta-shrinkage in docstring of ηshrinkage.
  • Clarify docstring of init_randeffs (see deprecations below).
  • Document the keyword init_randeffs used to initialize the empirical bayes estimate optimization in fits docstring.
  • Fix log message generated by simobs(::BayesMCMCResult)` that would previously throw an error.
  • Throw descriptive error if absorption lag time is negative.
  • Add examples for truncation and censoring in the docstring of censored_latent and truncated_latent.
  • Clarify event_data comment in docstring of read_pumas.
  • Fix typo in error message when ByObservation(allsubjects = true) is used and subjects have different numbers of observations.
  • Add a warning in the docstring for Constrained to clarify that the type should only be used in @param.

Bugs

  • Fix checks for unbounded parameters in gsa such that an appropriate error is thrown.
  • Respect iterations setting in fit continuation with JointMAP.
  • Convert parameters of RealDomains to floating point numbers to support integer input.
  • Forward RNG to AdvancedHMC.find_good_stepsize to ensure reproducibility of bayesian inference.
  • Fix support of NamedTuples of random effects in PumasEMModels.
  • Fix a bug where the order of ODE parameters in PumasEMModels internals would sometimes be wrong causing incorrect model evaluations.
  • Fix show method for fit results if there are Inf values among estimates.
  • Fix simulation with zero omegas used to turn off specific random effects.
  • Fix a bug where user might get the error message ERROR: UndefVarError: terminate! not defined in Pumas.jl when using steady-state.
  • Fix FOCE type inference inefficiencies that could cause a small overhead in some situations.
  • Fix PSDDomain constructor with diagonal matrices.
  • Fix estimation of absorption lag model with non-constant covariates that would throw an error for an unsupported Event constructor.
  • Fix inconsistent covariates_direction in Subject constructor. Previously, it would be :right for subjects constructed from subjects through the Subject(subject;...) constructor.
  • Fix empirical_bayes for MAP(NaivePooled()). Previously, an error would be thrown.
  • Fix conversion of PumasEMModel to PumasModel. Previously, the reported parameters in the model output would not be correct.
  • Fix Subject constructors with missing covariates. Previously, an error would be thrown.
  • Respect likelihood approximation setting in MarginalMCMC.
  • Fix LogitNormal and support MvLogitNormal random effects. Previously, an internal transformation to orthogonal representations would be incorrect.
  • Fix display and analysis of MCMC samples without population parameters.
  • Fix covariates output in DataFrame(::SimulatedObservations). Previously, covariate information would only be added if the subject also had events.
  • Use center_stat(dist) as the random effect value for population predictions instead of zero. This is more appropriate for non-Gaussian random effects.
  • Fix return code of analytical solution that would sometimes return an indication of success even if the solution was not found.
  • Fix inspect DataFrame constructor for parameters defined directly in @random. Previously, an error would be thrown if the parameter defined in @random was used directly in the model later on without being redefined in @pre.
  • Correctly handl constant parameters (instead of ignoring the constantcoef) in simulated stderror and vcov calculations.
  • Fix checks and handling of reserved identifiers :id and :time in read_pumas.
  • Fix a bug in the calculation of the correaltions in correlation_diagnostic.
  • Make linearity detection safer and faster. Previously, linearity detection could fail and an error would be thrown. Some rare edge cases could also lead to a false positive linearity detection.
  • Fix NaivePooled and restrict it to transformed Gaussians.
  • Fix parsing of @covariates in @emmodel.

Deprecations

  • The method simobs(fpm) is deprecate and the full signature should be used instead: simobs(fpm.model, fpm.data, coef(fpm)).
  • Pumas.truncate is deprecated and discard should be used to trim bayesian samples instead
  • zero_randeffs(model, param, population) is deprecated and zero_randeffs(model, population, param) should be used instead
  • init_randeffs is deprecated in favor of center_randeffs.

PumasPlots

Features and improvements

  • Many plotting functions use open circle markers by default now which can be discriminated better than filled circles when overplotting.
  • convergence_trace: Colormaps are not given via color anymore but via the keyword colormap.
  • npde_vs_covariates: The y-label now includes the observation for which the NPDEs are shown because there can be multiple different observations.
  • sim_plot: Color palettes are given via color_palette and markercolor_palette now because otherwise it's not possible to use from_continuous and other helpers known from AoG which are not Symbols.
  • wresiduals_vs_covariates: The type of observation is specified in the row labels, not in separate titles per axis.
  • ridgeline_plot: The first HPDI is not plotted twice anymore.
  • Some Bayesian diagnostic plots have different axis linking defaults, disabling axis linking in one dimension because the variables along that dimension can have very different ranges. trace_plot and cummean_plot disable y-axis linking, density_plot disables x-axis linking.

Deprecations

  • All plots except corner_plot use AlgebraOfGraphics in the backend now and expose the standard keywords from AoG.draw like facet or legend. All keywords that are made obsolete by AoG functionality are deprecated, such as figurelegend, include_legend, combinelabels, combinexlabels, combineylabels, hidelabels, hidexlabels, hideylabels, hideticks, hidexticks, hideyticks.
  • The corner_plot function is deprecated, the third party package PairPlots.jl offers a comprehensive solution for this type of plot.

NCAUtilities

Deprecations

  • All plots use AlgebraOfGraphics in the backend now and expose the standard keywords from AoG.draw like facet or legend. All keywords that are made obsolete by AoG functionality are deprecated, such as figurelegend, include_legend, combinelabels, combinexlabels, combineylabels, hidelabels, hidexlabels, hideylabels, hideticks, hidexticks, hideyticks.

AlgebraOfGraphics

AlgebraOfGraphics is updated from v0.8.3 to v0.10.8 which includes the following breaking changes:

  • paginate now splits facet plots into pages after fitting scales and not before. This means that, e.g., categorical color mappings are consistent across pages where before each page could have a different mapping if some groups were not represented on a given page. This change also makes pagination work with the split X and Y scales feature enabled by version 0.8.14. paginate's return type changes from PaginatedLayers to Pagination because no layers are stored in that type anymore. The interface to use Pagination with draw and other functions doesn't change compared to PaginatedLayers. paginate now also accepts an optional second positional argument which are the scales that are normally passed to draw when not paginating, but which must be available prior to pagination to fit all scales accordingly.
  • The colorbar! function now returns a Vector{Colorbar} with zero or more entries. Before it would return Union{Nothing,Colorbar}, but now it's possible to draw more than one colorbar if there are multiple colorscales.
  • filled_contours does not create a legend by default but a colorbar. The colorbar can be disabled again by setting, e.g., scales(Color = (; colorbar = false)).
  • Changed the behavior of the from_continuous palette in combination with a scale consisting of Bins. Colors will now be sampled relative to the positions of their bins' midpoints, meaning that smaller bins that lie closer together have more similar colors. The previous behavior with colors sampled evenly can be regained by using from_continuous(cmap; relative = false).

PumasUtilities

Features and improvements

  • The report function now uses Typst for PDF rendering instead of LaTeX. This improves performance on large documents while the interface remains unchanged.

Bugs

  • Fix a bug where large inputs to report sometimes caused failure to render a final PDF due to too many subjects.

OptimalDesign

Features and improvements

  • TimeUnitTransform and inv(TimeUnitTransform) to convert time back and forth between Float and DateTime.
  • New function compare_designs to compare designs by their parameters' Cramer-Rao lower bounds.
  • New methods for evaluate_design and crlb.

Bugs

  • Fix subject_multiples keyword argument in evaluate_design to appropriately calculate the population FIM.
  • Fix rounding error in inv(TimeUnitTransform).
  • Improve control over optimization duration.

Bioequivalence

Features and improvements

  • The output of pumas_be now includes marginal means (similar to "least squares means") calculations for all parametric model based designs.
  • The output of detect_design now includes the number of periods and number of formulations.
  • The implementation of the non-parametric test is now a pure Julia efficient computation (it used lookup tables previously).
  • Output of pumas_be via summary tables has a show method for text/html MIME.

Bugs

  • The within subject variability estimation for multi-period parallel designs was previously faulty and is now fixed.

Deprecations

  • FDA is deprecated and is replaced by FDA_HighlyVariable.
  • EMA_CMAX is deperacted and is replaced by EMA_HighlyVariable.