Release Notes for Pumas 2.8.0

Pumas

Features and improvements

Experimental Features

• Add Monte Carlo Expectation Maximization, MCEM, estimation method that works with regular models defined using @model
• Add Variational Expectation Maximization, VEM, estimation method that works with regular models defined using @model
• Add FiniteMarkov distribution to model discrete time finite (state) Markov processes.

Features

• Add ProportionalNormal, CombinedNormal and CombinedCorrelatedNormal to automatically safe guard against negative values and to provide a coherent interface for common error models.

• Add OrderedLogit categorical distributions to simplify modeling of ordered categorical data.

• Add metadata to DataFrame constructed from Pumas output objects. The metadata will automatically be used as labels when using AlgebraOfGraphics.jl based plotting and in some tables from SummaryTables.jl.

• Allow multiple iterations of SIR following www.page-meeting.org/?abstract=2907 and www.page-meeting.org/?abstract=3546.

• Add support for MvNormal with missing values in @derived for LaplaceI and NaivePooled.

• Allow named models such as Central1, Central1Periph1, etc to be used in models that are not possible to solve with closed form solutions by switching to a numerical ODE solver when needed.

• Add support for vcov/infer calculations with ensemblealg set to EnsembleDistribted() or EnsembleSplitThreads().

• Add support for random effects following NormalCanon, JohnsonSU, and MvNormalCanon distributions.

• Add control of the initial empirical bayes estimate value used when finding the mode in inner iterations of FOCE and LaplaceI. Both constructors accept the randeffs_initialization keywoard with possible options being: RandeffsInitialization.Center, RandeffsInitialization.CenterOrPreviousOrth, RandeffsInitialization.PreviousOrth. The default is RandeffsInitialization.PreviousOrth that carries over the estimate from the previous iteration. The description of each option can be found in the docstrings.

• Reexport cor2cov from StatsBase.jl to complement cov2cor for working with conversion between correlation and covariance matrices.

• Reexport dof from StatsAPI.jl and add a method for FittedPumasModel to get the degrees of freedom of the model. Note, the interpretation of degrees of freedom in mixed effects models is not straightforward and this method provides a simple approximation. Please see the following references for more information and what it means for things like test statistic distributions and AIC calculations.

  • https://bbolker.github.io/mixedmodels-misc/glmmFAQ.html#why-doesnt-lme4-display-denominator-degrees-of-freedomp-values-what-other-options-do-i-have
  • https://bbolker.github.io/mixedmodels-misc/glmmFAQ.html#can-i-use-aic-for-mixed-models-how-do-i-count-the-number-of-degrees-of-freedom-for-a-random-effect
  • https://www.jstatsoft.org/article/view/v107i06
  • https://www.sciencedirect.com/science/article/abs/pii/S0167947319300283

• Reexport BlockDiagonal from BlockDiagonals.jl to be used in Pumas when defining block-diagonal covariance matrices.

• Perform bootstrap inference with stratification over several variables at once. The variables must be present in the subjects as covariates and the stratification is specified as a vector of symbols (stratify = [:AGE, :WEIGHT]). All stratification variable must be constant since subjects are sampled as whole units.

• Pumas now run natively on AppleSilicon (M) chips. This improves performance and avoids issues with multi-threading.

Improvements

• Improve performance of @delay by computing normalizing constants only once.
• Improve performance of some derivative computations by combing primal and derivative evaluations.
• Improve the way weighted residuals are computed to reduce unnecessary computations and allocations.
• Improve the sampling in SIR by using log weights and reducing allocations in SIR.
• Ignore non-Gaussian error models in ϵ-shrinkage calculation to allow for proper handling of models with a mix of Gaussian and non-Gaussian error models.
• Reuse ensemble algorithm when re-computation of Empirical Bayes Estimates is necessary with FittedPumasModel as input.

Documentation and error messages

• Show warning if overlapping steady-state infusions are detected. Users may want to adjust their dosing regimen to avoid situations where infusions overlap in time.
• Fix typo in the optim_options usage section of the fit docstring.
• Fix docstring of Central1Periph2 the incorrectly described the model as a two-compartment model.
• Update the description of obstimes in predict docstring to correctly reflect the way the input is used.
• Improve markdown formatting in several docstrings.
• Use Pumas-specific warnings for the ODE solver and suppress warnings when fitting to avoid writing warnings to the terminal or logs that are irrelevant to the user because the parameter is rejected eventually as part of the estimation process.
• Display a warning if a variable is defined in the @derived block using =.
• Do not treat internal assertion error as numerical errors. Numerical errors are expected during estimation and should not be confused with internal errors that should actually halt the fitting process.
• Improve checks of valid right hand sides in the @derived block and improve error messages.
• Improve checks of valid named on the right hand side of definitions and assignments to avoid confusing errors if the left hand side has invalid characters such as theta-1 that should be theta_1.

Bugs

• Fix handling of reset events with negative time.
• Fix situation where sampling from censored distributions could fail if only one side was censored.
• Respect reset events in distributed @delay.
• Fix support time-varying covariates in @model when used directly in other blocks than @pre.
• Fix CensoredVPC for models with multiple dependent variables where some are non-Censored.
• Correctly throw bounds errors in @pre.
• Use unicode subscript for ebes in DataFrame(simobs(...)) as was already the case in DataFrame(inspect(...)).
• Fix reset-dose events (evid = 4) with absorption lag. Previously, the reset happened at event time + lag time instead of at event time.
• Fix padding of NCA quantities when used in @observed. Previously, some NCA quantities were not padded correctly.

Deprecations

• Deprecate omegas and improve error message for NaivePooled. Instead, users should set the corresponding parameters to zero in constantcoef.
• Deprecate simobs(::FittedPumasModel; kwargs...) in favor of more explicit calls to simobs.
• Deprecate simobs and predict used with BayesMCMCResults in favor of more explicit calls to simobs and predict with model, population, param, and randeffs arguments. This allows for more explicit control over the simulations and predictions and avoids confusion about what is being used as input for the simulations and predictions.

PumasPlots

Features and improvements

• Plot trace of gradient norm in log-scale.
• Show both plots together for censored VPCs in vpc_plot, displaying continuous and discrete components stacked.
• Add RT single sequence cross-over design.

Documentation and error messages

• General improvements to docstrings for pumas_be and run_be.
• Improved error message if covariate based plots are requested but no covariates are present in the data.

Bugs

• Fix vpc to handle observation names with underscores. Previously, underscores caused an error to be thrown.
• Make goodness_of_fit use population weighted residuals and population predictions by default for consistency with npde plots and literature.
• Use dependent variable to correctly set the yaxis in vpc_plot.
• Fix NTID FDA when CVr > CV_max. Previously, this caused an error to be thrown but NTID FDA does not need CV_max.

NCAUtilities

Features and improvements

• Improve handling of LLQ in plots by adding keywords to control how LLQ is displayed and improving docstrings.

Bugs

• Fix subject_fits with paginate=true in report. Previously, an error was thrown.

Bioequivalence

Features and improvements

• Add functionality to use mixed models for 2x2 crossover designs using the keyword custom_model = LinearMixedModel in pumas_be.
• Improved specification of significance levels using level_ keyword arguments. Please see the docstring for pumas_be.

Documentation and error messages

• Improve docstrings for BioequivalenceEndpointOutput.
• Replace -> with :: in docstrings when referring to output types.

Bugs

• Fixed a bug that would cause printed lines to have the wrong width.
• Display "with REML" or "without REML" for Mixed Models in the Model: part of the header of the output.

Deprecations

SummaryTables

Features and improvements

• Added numeric_default and categorical_default keywords to table_one to change the default analyses for all columns in a table at once. These parameters can also be changed globally with defaults!.
• All table functions now use the "label" column metadata as a label by default if it's present. A different key can be set as the default setting label_key, or nothing to disable the feature.
• Added recursive = false keyword to Replace postprocessor which causes it to recurse into SummaryTables' own wrapper types like Concat and Multiline. ReplaceMissing is set to be recursive by default and is considered a bugfix as the intent was always to replace all missings, not just top-level.
• Added global defaults system which allows to override float rounding behavior and annotation label styles, among others.

Bugs

• Corrected the docstring of table_one which erroneously listed show_testnames and not show_tests.
• Fixed inconsistent classification of categorical data, now the rules are the same for table_one and overview_table. A numeric column is a column with some non-missing values, all of which are subtypes of Real but not Bool. All other columns are categorical.
• Simplified typst escaping, all custom rules were removed and text is simply wrapped in "" with \" as the only escaped character. This avoids bugs where some text is interpreted as special typst markup.
• Fixed internal alignment of Multiline in the LaTeX backend so that it matches the cell alignment.
• Fixed unintended enumeration markup in overview_table rendered with Typst.
• Fixed rendering of concat/styled annotations and footnotes in docx.

AlgebraOfGraphics

Behavior change

• As Makie 0.23 split up Arrows in Arrows2D and Arrows3D, visual(Arrows2D) needs to be specified explicitly now in AlgebraOfGraphics. As Arrows2D plots polygon shapes now and not a mixture of scatters and lines, the categorical arrowhead marker aesthetic had to be removed.
• The internal LinesFill recipe was removed. This had been used for linear and density transformations. Instead, both transformations now create ProcessedLayers with Bands and Lines layers. This means that certain visuals multiplied with those transformations may lead to incompatible attribute errors now when calling draw if they use attributes that Band and Lines do not share. On the other hand, you can style layers completely independently with subvisual now. To replace density() * visual(direction = :y) you can now do density(direction = :y) directly.
• Added a confidence interval layer to smooth which is enabled by default and can be disabled with interval = nothing. This will cause breakage where smooth() * visual(...) was used with attributes that Band does not know. You can use smooth() * You can usesmooth() * subvisual(:ci/:prediction, ...)` to target the components specifically. Note that Loess confidence intervals have quadratic memory scaling so they should not be used with very large numbers of observations.

Experimental Features

• Added the experimental draw_to_spec function. This can be used as an alternative to draw to create a Makie.SpecApi spec that can be updated interactively using observables.

Features and improvements

• Added the show_aesthetics function which can be used to print information about the aesthetic mappings supported for a given Makie plot type.
• Make the visuals BarPlot, BoxPlot, Density and CrossBar aware of the strokecolor aesthetic. Note that, for some visuals, it is necessary to specify a strokewidth strictly larger than 0 to appreciate the effect of the strokecolor mapping. Note also that the strokecolor aesthetic in itself was already available, and it is defined so that it behaves as the Color aesthetic (for example, in terms of scales). Indeed, the visuals Scatter, ScatterLines and Hist were already aware of strokecolor. There are other visuals that also could use strokecolor (for example, violin plots), but implementing strokecolor for all of them is left for later.
• Added subvisual which is a version of visual that restricts its effect to only those layers specified by a target argument. Intended for the styling of transformations creating multiple plot layers. subvisual(:ci/:prediction, ...) to target the components specifically. Note that Loess confidence intervals have quadratic memory scaling so they should not be used with very large numbers of observations.
• Added an auto-label mechanism when using dims which picks up the column labels from the positional arguments of mapping and assigns them to the categorical values created by dims. Slightly breaking in that the categorical scale now does not consist of CartesianIndex values anymore but the custom type DimsIndex that contains information about which dims were requested.
• Added QQPlot and QQNorm aesthetics for use with Makie 0.24.7 and up. QQPlot can take one positional argument and a distribution keyword from that version on which makes it compatible with AlgebraOfGraphics.
• Added singlexlabel and singleylabel keywords to draw(facet = (; ...)) with which the behavior can be disabled where the same label across multiple axes is replaced with a single spanning one.
• Added scale to AesColor scale properties which allows to transform continuous colors with functions such as log10.
• Always treat layout, row, col and group mappings as categorical to simplify common scenarios where grouping information is stored as integers.
• Make mapping(key = (:col1, :col2)) work automatically, equivalent to (:col1, :col2) => tuple.
• Added the ability to set scale, ticks and tickformat for continuous X, Y and Z scales via the scales options which allows to set these in multi-scale facet scenarios.
• Added support for Makie's new TextLabel recipe.

Documentation and error messages

• Improved error message when two layers with incompatible continuous data are combined.

Bugs

• Improved handling of all-missing subgroups in some cases.
• Fixed a bug where adding a layer without layout mapping could result in layout facets that should not have been visible at all.

PumasAide

Initial release of PumasAide, which allows connecting coding agents directly to Pumas sessions.