Plotting

The PumasUtilities package provides access to the plotting functions available for Pumas.

All the available plotting functions build upon the Makie plotting ecosystem and so are interoperable with any plots created using Makie. You can freely combine individual plots from Pumas-specific functions with those of Makie, or any other plotting functions that build upon it, such as AlgebraOfGraphics.

For in-depth documentation and examples of Makie please refer directly to the documentation for that package. We will cover the basics within this document, but do not aim to give it a thorough treatment since that is best left to the official documentation.

Publication-Quality and Interactivity

By default, the plots created by all the Pumas plotting functions, as well as any produced using Makie directly, will return a Figure object which will display in the "Plot Pane" of your editor if you are using Visual Studio Code while writing your code. The plots that are displayed are for the most part static images.

If you wish to incorporate some level of interactivity while you are performing your analysis you can use the interactive function to convert the Figure into an interactive plot that allows for zooming, panning, and hover details.

julia> figure = observations_vs_time(population) # This will open the plot pane with a static plot.

julia> interactive(figure) # This will open the plot pane with an interactive plot.

Note that the complexity of the plot layout will determine whether interactive is able to produce a suitable interactive version of your plot. The data contained within your plot will by replicated, but the layout may degrade due to the limitations of the plotting library used for displaying the interactive plots. If the result is not to your liking then try to reduce the complexity of the layout by removing subplot axes from your Figure passed to interactive.

Keywords

All the plotting functions discussed in the next sections accept keyword arguments that control the different aspects of their appearance. Do note that currently the underlying Makie library will not throw an error when keyword arguments are incorrectly spelled. Because of this please carefully inspect the spelling of your keyword arguments should any of them appear to not be taking effect within the resulting plot.

Every docstring for the available plotting functions, listed in the next sections, are also available to you from within your editor and REPL, via the ? mode. They all list the possible keyword arguments that can be passed to them.

There are instances with the plotting functions discussed below where the resulting Figure object contains numerous sub-plots rather than just a single plot. This can make creation of these complex plots difficult when very little space is available for each sub-plot.

You have two options with these cases:

Firstly, you can use several of the keywords that some of the plotting functions provide to limit the number of sub-plots. For example, the observations can be used to limit which out of possibly may observations from a model are displayed in Figure. Check the docstring of the particular plotting function for details of the available keywords.
Secondly, all plotting functions provide a paginate keyword that can be set to paginate = true. The effect that this has is to programmatically split the sub-plots over multiple "pages", which are then returned as a Vector{Figure} rather than the default single Figure. The companion keywords that can be used with this in many of the plotting functions are limit, rows, and columns which set the maximum sub-plots per page, number of rows, and number of columns respectively.

Functions

This section covers the Pumas-specific plotting functions. Those for NCA data and results are documented in the NCA plots section.

`Pumas`

Firstly, to make the plotting functions available we must import the modules.

using Pumas
using PumasUtilities

PumasUtilities automatically loads PumasPlots which is Pumas' main plotting package.

To create custom plots using Makie directly you should also import one of it's "backend" packages, such as CairoMakie, with:

using CairoMakie

The following plots are now available:

Note

Except for vpc_plot, the plots discussed in this section only support continuous data models.

For the example plots below we will be using the following Pumas' analysis results:

using Pumas
using PumasUtilities
using PharmaDatasets
using CairoMakie

pkdata = dataset("nlme_sample")

pop = read_pumas(
    pkdata;
    id = :ID,
    time = :TIME,
    amt = :AMT,
    covariates = [:WT, :AGE, :SEX, :CRCL, :GROUP],
    observations = [:DV],
    cmt = :CMT,
    evid = :EVID,
    rate = :RATE,
)

model = @model begin
    @param begin
        """
        Volume of the Central Compartment (L)
        """
        tvvc ∈ RealDomain(; lower = 0)
        """
        Volume of the Peripheral Compartment (L)
        """
        tvvp ∈ RealDomain(; lower = 0)
        """
        Intercompartmental Clearance
        """
        tvq ∈ RealDomain(; lower = 0)
        """
        Hepatic Clearance (L/hr)
        """
        tvcl_hep ∈ RealDomain(; lower = 0)
        """
        Renal Clearance (L/hr)
        """
        tvcl_ren ∈ RealDomain(; lower = 0)
        """
        Components: CL, Vc
        """
        Ω ∈ PDiagDomain(2)
        """
        Additive RUV (SD Scale)
        """
        σ_add ∈ RealDomain(; lower = 0)
        """
        Proportional RUV (SD Scale)
        """
        σ_prop ∈ RealDomain(; lower = 0)
        """
        Exponent of the Power Function of Creatinine on Renal Clearance
        """
        dCRCL ∈ RealDomain()
    end

    @random begin
        η ~ MvNormal(Ω)
    end

    @covariates begin
        """
        Body Weight (kg)
        """
        WT
        """
        Estimated Creatinine Clearance (mL/min)
        """
        CRCL
    end

    @pre begin
        hepCL = tvcl_hep * (WT / 70)^0.75 # hepatic clearance
        renCL = tvcl_ren * (CRCL / 100)^dCRCL # renal clearance
        CL = (hepCL + renCL) * exp(η[1]) # total clearance
        Vc = tvvc * (WT / 70) * exp(η[2])
        Q = tvq
        Vp = tvvp
    end

    @dynamics Central1Periph1

    @derived begin
        cp := @. Central / Vc
        """
        CTMx Concentrations (ng/mL)
        """
        DV ~ @. CombinedNormal(cp, σ_add, σ_prop)
    end
end

fitted_model = fit(model, pop, init_params(model), FOCE())

fitted_model_inspection = inspect(fitted_model)

fitted_model_inspection_npde = inspect(fitted_model; nsim = 1_000)

continuous_vpc = vpc(fitted_model)

sim = simobs(model, pop, init_params(model));

Simulated population (Vector{<:Subject})
  Simulated subjects: 30
  Simulated variables: DV

`convergence_trace`

PumasPlots.convergence_trace — Function

convergence_trace(fit | inspect)
convergence_trace(figpos, fit | inspect)

Plot the fitting trace for a given fit or inspect object. When a SAEM fit is plotted then traces for $μ$, $Ω$, and $σ$ are plotted, otherwise the -Log-Likelihood and Gradient Norm are plotted side-by-side.

Keywords

trace: select which trace to plot. When plotting into a figure position or axis then only a single trace is plotted, otherwise several can be plotted. Available trace names are as follows:
- @model-based: :loglikelihood and :gradientnorm, or their abbreviations :ll and :gn.
- @emmodel-based: :μ, :Ω, and :σ, or their fullnames :mu, :Omega, and :sigma.
paginate: (default false) When true sets the return type of a plot to a Vector{AlgebraOfGraphics.FigureGrid} rather than a single AlgebraOfGraphics.FigureGrid, splitting the returned plot over several "pages" if there are too many to fit on a single figure comfortably. See also limit, rows, and columns for controlling page size and grid shape.
limit: Sets the maximum number of axes that can be plotted per page when pagination is active. Cannot be combined with rows and columns.
rows: Sets the number of rows per page when pagination is active. For plots with a layout scale, must be specified together with columns. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
columns: Sets the number of columns per page when pagination is active. For plots with a layout scale, must be specified together with rows. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
axis: A key-value object with axis options that gets passed to the underlying AlgebraOfGraphics.draw call.
figure: A key-value object with figure options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)
legend: A key-value object with legend options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.) A legend will be drawn automatically unless legend = (; show = false) is set.
facet: A key-value object with facet options that gets passed to the underlying AlgebraOfGraphics.draw call.
colorbar: A key-value object with colorbar options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)

Supported Style Keywords

color
colormap
linewidth
linestyle

For the fitted_model_inspection variable above the following syntax is used to generate the plot below:

convergence_trace(fitted_model_inspection)

`covariates_dist`

PumasPlots.covariates_dist — Function

covariates_dist([model,], subject | population | fit | inspect)
covariates_dist(figpos, [model,], subject | population | fit | inspect)

Plot the distribution of covariates for the given population. An optional associated model may be passed in as the first argument which will be used to provide more detailed axis labels based on the metadata and descriptions provided in the model definition, if any. A single fit or inspect object may also be used in place of the model and population arguments.

Each subject contributes a single value per covariate. For time-varying covariates, the baseline (first) value of each subject is used.

Keywords

covariates: The covariates to be plotted. When not specified then all covariates for the given model will be shown. A subset of covariates can be plotted by providing a Symbol or Vector{Symbol} of covariate names.
categorical: Select which of the variables should be interpreted as categorical. Provide a vector of symbols corresponding to the names of the categorical variables. By default all variables are treated as continuous.
paginate: (default false) When true sets the return type of a plot to a Vector{AlgebraOfGraphics.FigureGrid} rather than a single AlgebraOfGraphics.FigureGrid, splitting the returned plot over several "pages" if there are too many to fit on a single figure comfortably. See also limit, rows, and columns for controlling page size and grid shape.
limit: Sets the maximum number of axes that can be plotted per page when pagination is active. Cannot be combined with rows and columns.
rows: Sets the number of rows per page when pagination is active. For plots with a layout scale, must be specified together with columns. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
columns: Sets the number of columns per page when pagination is active. For plots with a layout scale, must be specified together with rows. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
axis: A key-value object with axis options that gets passed to the underlying AlgebraOfGraphics.draw call.
figure: A key-value object with figure options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)
legend: A key-value object with legend options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.) A legend will be drawn automatically unless legend = (; show = false) is set.
facet: A key-value object with facet options that gets passed to the underlying AlgebraOfGraphics.draw call.
colorbar: A key-value object with colorbar options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)

Supported Style Keywords

color
strokecolor
strokewidth

For the model and pop variables above the following syntax is used to generate the plot below:

covariates_dist(model, pop; categorical = [:SEX, :GROUP])

`empirical_bayes_dist`

PumasPlots.empirical_bayes_dist — Function

empirical_bayes_dist(inspect)
empirical_bayes_dist(figpos, inspect)

Plot the distribution of random effects for the given inspect object. Axis label will be based on the metadata and descriptions provided in the model's definition, if any.

Keywords

ebes: Select which variable, as a Symbol, to plot. By default plots all available. Provide a Vector{Symbol} to plot a subset of all available variables.
zeroline: Include a zeroline in the plot. Default is false.
paginate: (default false) When true sets the return type of a plot to a Vector{AlgebraOfGraphics.FigureGrid} rather than a single AlgebraOfGraphics.FigureGrid, splitting the returned plot over several "pages" if there are too many to fit on a single figure comfortably. See also limit, rows, and columns for controlling page size and grid shape.
limit: Sets the maximum number of axes that can be plotted per page when pagination is active. Cannot be combined with rows and columns.
rows: Sets the number of rows per page when pagination is active. For plots with a layout scale, must be specified together with columns. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
columns: Sets the number of columns per page when pagination is active. For plots with a layout scale, must be specified together with rows. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
axis: A key-value object with axis options that gets passed to the underlying AlgebraOfGraphics.draw call.
figure: A key-value object with figure options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)
legend: A key-value object with legend options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.) A legend will be drawn automatically unless legend = (; show = false) is set.
facet: A key-value object with facet options that gets passed to the underlying AlgebraOfGraphics.draw call.
colorbar: A key-value object with colorbar options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)

Supported Style Keywords

color
strokecolor
strokewidth
zeroline_color
zeroline_linestyle
zeroline_linewidth

For the fitted_model_inspection variable above the following syntax is used to generate the plot below:

empirical_bayes_dist(fitted_model_inspection)

`empirical_bayes_vs_covariates`

PumasPlots.empirical_bayes_vs_covariates — Function

empirical_bayes_vs_covariates(inspect)
empirical_bayes_vs_covariates(figpos, inspect)

Plot the random effects versus covariates for the given inspect object. Axis label will be based on the metadata and descriptions provided in the model's definition, if any. Reports the Pearson correlation coefficient r.

Since the empirical bayes estimates are constant within each subject, the data is reduced to one row per subject before plotting, so subjects contribute equally regardless of their number of observations. For time-varying covariates, the baseline (first) value of each subject is used, so a covariate that is identical for all subjects at baseline is plotted without a correlation coefficient.

Keywords

categorical: Select which of the variables should be interpreted as categorical. Provide a vector of symbols corresponding to the names of the categorical variables. By default all variables are treated as continuous.
covariates: The covariates to be plotted. When not specified then all covariates for the given model will be shown. A subset of covariates can be plotted by providing a Symbol or Vector{Symbol} of covariate names.
ebes: Select which variable, as a Symbol, to plot. By default plots all available. Provide a Vector{Symbol} to plot a subset of all available variables.
loess: Add a loess fit line to the plot. Default is true.
zeroline: Include a zeroline in the plot. Default is false.
paginate: (default false) When true sets the return type of a plot to a Vector{AlgebraOfGraphics.FigureGrid} rather than a single AlgebraOfGraphics.FigureGrid, splitting the returned plot over several "pages" if there are too many to fit on a single figure comfortably. See also limit, rows, and columns for controlling page size and grid shape.
limit: Sets the maximum number of axes that can be plotted per page when pagination is active. Cannot be combined with rows and columns.
rows: Sets the number of rows per page when pagination is active. For plots with a layout scale, must be specified together with columns. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
columns: Sets the number of columns per page when pagination is active. For plots with a layout scale, must be specified together with rows. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
axis: A key-value object with axis options that gets passed to the underlying AlgebraOfGraphics.draw call.
figure: A key-value object with figure options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)
legend: A key-value object with legend options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.) A legend will be drawn automatically unless legend = (; show = false) is set.
facet: A key-value object with facet options that gets passed to the underlying AlgebraOfGraphics.draw call.
colorbar: A key-value object with colorbar options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)

Supported Style Keywords

color
loess_color
loess_linestyle
loess_linewidth
marker
markersize
zeroline_color
zeroline_linestyle
zeroline_linewidth

For the fitted_model_inspection variable above the following syntax is used to generate the plot below:

empirical_bayes_vs_covariates(fitted_model_inspection; categorical = [:SEX, :GROUP])

`goodness_of_fit`

PumasPlots.goodness_of_fit — Function

goodness_of_fit(inspect)

Plot a 2-by-2 grid of subplots for each observation associated with the inspect object. The plots included are:

observations_vs_predictions
observations_vs_ipredictions
wresiduals_vs_time (or npde_vs_time)
wresiduals_vs_predictions (or npde_vs_predictions)

Axis label will be based on the metadata and descriptions provided in the model's definition, if any.

Keywords

loess: Add a loess fit line to the plot. Default is true.
ols: Add an OLS fit line to the plot. Default is false.
observations: The observations to be plotted. When not specified then all observations for the given model will be shown. A subset of observations can be plotted by providing a Symbol or Vector{Symbol} of observation names.
paginate: (default false) When true sets the return type of a plot to a Vector{AlgebraOfGraphics.FigureGrid} rather than a single AlgebraOfGraphics.FigureGrid, splitting the returned plot over several "pages" if there are too many to fit on a single figure comfortably. See also limit, rows, and columns for controlling page size and grid shape.
limit: Sets the maximum number of axes that can be plotted per page when pagination is active. Cannot be combined with rows and columns.
rows: Sets the number of rows per page when pagination is active. For plots with a layout scale, must be specified together with columns. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
columns: Sets the number of columns per page when pagination is active. For plots with a layout scale, must be specified together with rows. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
axis: A key-value object with axis options that gets passed to the underlying AlgebraOfGraphics.draw call.
figure: A key-value object with figure options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)
legend: A key-value object with legend options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.) A legend will be drawn automatically unless legend = (; show = false) is set.
facet: A key-value object with facet options that gets passed to the underlying AlgebraOfGraphics.draw call.
colorbar: A key-value object with colorbar options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)

Supported Style Keywords

loess_color
loess_linestyle
loess_linewidth
ols_color
ols_linestyle
ols_linewidth
marker
markercolor
markersize

For the fitted_model_inspection variable above the following syntax is used to generate the plot below:

goodness_of_fit(fitted_model_inspection)

`iwresiduals_vs_ipredictions`

PumasPlots.iwresiduals_vs_ipredictions — Function

iwresiduals_vs_ipredictions(inspect | [model], wresiduals, predict)
iwresiduals_vs_ipredictions(figpos, inspect | [model], wresiduals, predict)

Plot the weighted individual residuals versus individual predictions for the given inspect object, or the combination of an optional model and the results of wresiduals and predict.

Axis label will be based on the metadata and descriptions provided in the model's definition, if any.

Keywords

loess: Add a loess fit line to the plot. Default is true.
ols: Add an OLS fit line to the plot. Default is false.
observations: The observations to be plotted. When not specified then all observations for the given model will be shown. A subset of observations can be plotted by providing a Symbol or Vector{Symbol} of observation names.
zeroline: Include a zeroline in the plot. Default is false.
labels: The custom name to use for each individual series within in the plot such as a scatter or line. Provide a NamedTuple with any of the following keys and your custom label string: loess, ols, and observed.
paginate: (default false) When true sets the return type of a plot to a Vector{AlgebraOfGraphics.FigureGrid} rather than a single AlgebraOfGraphics.FigureGrid, splitting the returned plot over several "pages" if there are too many to fit on a single figure comfortably. See also limit, rows, and columns for controlling page size and grid shape.
limit: Sets the maximum number of axes that can be plotted per page when pagination is active. Cannot be combined with rows and columns.
rows: Sets the number of rows per page when pagination is active. For plots with a layout scale, must be specified together with columns. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
columns: Sets the number of columns per page when pagination is active. For plots with a layout scale, must be specified together with rows. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
axis: A key-value object with axis options that gets passed to the underlying AlgebraOfGraphics.draw call.
figure: A key-value object with figure options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)
legend: A key-value object with legend options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.) A legend will be drawn automatically unless legend = (; show = false) is set.
facet: A key-value object with facet options that gets passed to the underlying AlgebraOfGraphics.draw call.
colorbar: A key-value object with colorbar options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)

Supported Style Keywords

loess_color
loess_linestyle
loess_linewidth
ols_color
ols_linestyle
ols_linewidth
zeroline_color
zeroline_linestyle
zeroline_linewidth
marker
markercolor
markersize

For the fitted_model_inspection variable above the following syntax is used to generate the plot below:

iwresiduals_vs_ipredictions(fitted_model_inspection)

`iwresiduals_vs_time`

PumasPlots.iwresiduals_vs_time — Function

iwresiduals_vs_time(inspect | [model], wresiduals)
iwresiduals_vs_time(figpos, inspect | [model], wresiduals)

Plot the weighted individual residuals versus time for the given inspect object, or the combination of an optional model and the result of wresiduals.

Axis label will be based on the metadata and descriptions provided in the model's definition, if any.

Keywords

loess: Add a loess fit line to the plot. Default is true.
ols: Add an OLS fit line to the plot. Default is false.
observations: The observations to be plotted. When not specified then all observations for the given model will be shown. A subset of observations can be plotted by providing a Symbol or Vector{Symbol} of observation names.
zeroline: Include a zeroline in the plot. Default is false.
labels: The custom name to use for each individual series within in the plot such as a scatter or line. Provide a NamedTuple with any of the following keys and your custom label string: loess, ols, and observed.
paginate: (default false) When true sets the return type of a plot to a Vector{AlgebraOfGraphics.FigureGrid} rather than a single AlgebraOfGraphics.FigureGrid, splitting the returned plot over several "pages" if there are too many to fit on a single figure comfortably. See also limit, rows, and columns for controlling page size and grid shape.
limit: Sets the maximum number of axes that can be plotted per page when pagination is active. Cannot be combined with rows and columns.
rows: Sets the number of rows per page when pagination is active. For plots with a layout scale, must be specified together with columns. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
columns: Sets the number of columns per page when pagination is active. For plots with a layout scale, must be specified together with rows. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
axis: A key-value object with axis options that gets passed to the underlying AlgebraOfGraphics.draw call.
figure: A key-value object with figure options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)
legend: A key-value object with legend options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.) A legend will be drawn automatically unless legend = (; show = false) is set.
facet: A key-value object with facet options that gets passed to the underlying AlgebraOfGraphics.draw call.
colorbar: A key-value object with colorbar options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)

Supported Style Keywords

loess_color
loess_linestyle
loess_linewidth
ols_color
ols_linestyle
ols_linewidth
zeroline_color
zeroline_linestyle
zeroline_linewidth
marker
markercolor
markersize

For the fitted_model_inspection variable above the following syntax is used to generate the plot below:

iwresiduals_vs_time(fitted_model_inspection)

`npde_dist`

PumasPlots.npde_dist — Function

npde_dist(inspect)
npde_dist(figpos, inspect)

Keywords

observations: The observations to be plotted. When not specified then all observations for the given model will be shown. A subset of observations can be plotted by providing a Symbol or Vector{Symbol} of observation names.
zeroline: Include a zeroline in the plot. Default is false.
paginate: (default false) When true sets the return type of a plot to a Vector{AlgebraOfGraphics.FigureGrid} rather than a single AlgebraOfGraphics.FigureGrid, splitting the returned plot over several "pages" if there are too many to fit on a single figure comfortably. See also limit, rows, and columns for controlling page size and grid shape.
limit: Sets the maximum number of axes that can be plotted per page when pagination is active. Cannot be combined with rows and columns.
rows: Sets the number of rows per page when pagination is active. For plots with a layout scale, must be specified together with columns. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
columns: Sets the number of columns per page when pagination is active. For plots with a layout scale, must be specified together with rows. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
axis: A key-value object with axis options that gets passed to the underlying AlgebraOfGraphics.draw call.
figure: A key-value object with figure options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)
legend: A key-value object with legend options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.) A legend will be drawn automatically unless legend = (; show = false) is set.
facet: A key-value object with facet options that gets passed to the underlying AlgebraOfGraphics.draw call.
colorbar: A key-value object with colorbar options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)

Supported Style Keywords

color
strokecolor
strokewidth
zeroline_color
zeroline_linestyle
zeroline_linewidth

For the fitted_model_inspection_npde variable above the following syntax is used to generate the plot below:

npde_dist(fitted_model_inspection_npde)

`npde_vs_covariates`

PumasPlots.npde_vs_covariates — Function

npde_vs_covariates(inspect)
npde_vs_covariates(figpos, inspect)

Keywords

categorical: Select which of the variables should be interpreted as categorical. Provide a vector of symbols corresponding to the names of the categorical variables. By default all variables are treated as continuous.
covariates: The covariates to be plotted. When not specified then all covariates for the given model will be shown. A subset of covariates can be plotted by providing a Symbol or Vector{Symbol} of covariate names.
observations: The observations to be plotted. When not specified then all observations for the given model will be shown. A subset of observations can be plotted by providing a Symbol or Vector{Symbol} of observation names.
zeroline: Include a zeroline in the plot. Default is false.
paginate: (default false) When true sets the return type of a plot to a Vector{AlgebraOfGraphics.FigureGrid} rather than a single AlgebraOfGraphics.FigureGrid, splitting the returned plot over several "pages" if there are too many to fit on a single figure comfortably. See also limit, rows, and columns for controlling page size and grid shape.
limit: Sets the maximum number of axes that can be plotted per page when pagination is active. Cannot be combined with rows and columns.
rows: Sets the number of rows per page when pagination is active. For plots with a layout scale, must be specified together with columns. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
columns: Sets the number of columns per page when pagination is active. For plots with a layout scale, must be specified together with rows. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
axis: A key-value object with axis options that gets passed to the underlying AlgebraOfGraphics.draw call.
figure: A key-value object with figure options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)
legend: A key-value object with legend options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.) A legend will be drawn automatically unless legend = (; show = false) is set.
facet: A key-value object with facet options that gets passed to the underlying AlgebraOfGraphics.draw call.
colorbar: A key-value object with colorbar options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)

Supported Style Keywords

color
marker
markersize
zeroline_color
zeroline_linestyle
zeroline_linewidth

For the fitted_model_inspection_npde variable above the following syntax is used to generate the plot below:

npde_vs_covariates(fitted_model_inspection_npde; categorical = [:SEX, :GROUP])

`npde_vs_predictions`

PumasPlots.npde_vs_predictions — Function

npde_vs_predictions(inspect)
npde_vs_predictions(figpos, inspect)

Keywords

loess: Add a loess fit line to the plot. Default is true.
ols: Add an OLS fit line to the plot. Default is false.
observations: The observations to be plotted. When not specified then all observations for the given model will be shown. A subset of observations can be plotted by providing a Symbol or Vector{Symbol} of observation names.
zeroline: Include a zeroline in the plot. Default is false.
labels: The custom name to use for each individual series within in the plot such as a scatter or line. Provide a NamedTuple with any of the following keys and your custom label string: loess, ols, and observed.
paginate: (default false) When true sets the return type of a plot to a Vector{AlgebraOfGraphics.FigureGrid} rather than a single AlgebraOfGraphics.FigureGrid, splitting the returned plot over several "pages" if there are too many to fit on a single figure comfortably. See also limit, rows, and columns for controlling page size and grid shape.
limit: Sets the maximum number of axes that can be plotted per page when pagination is active. Cannot be combined with rows and columns.
rows: Sets the number of rows per page when pagination is active. For plots with a layout scale, must be specified together with columns. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
columns: Sets the number of columns per page when pagination is active. For plots with a layout scale, must be specified together with rows. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
axis: A key-value object with axis options that gets passed to the underlying AlgebraOfGraphics.draw call.
figure: A key-value object with figure options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)
legend: A key-value object with legend options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.) A legend will be drawn automatically unless legend = (; show = false) is set.
facet: A key-value object with facet options that gets passed to the underlying AlgebraOfGraphics.draw call.
colorbar: A key-value object with colorbar options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)

Supported Style Keywords

loess_color
loess_linestyle
loess_linewidth
ols_color
ols_linestyle
ols_linewidth
zeroline_color
zeroline_linestyle
zeroline_linewidth
marker
markercolor
markersize

For the fitted_model_inspection_npde variable above the following syntax is used to generate the plot below:

npde_vs_predictions(fitted_model_inspection_npde)

`npde_vs_time`

PumasPlots.npde_vs_time — Function

npde_vs_time(inspect)
npde_vs_time(figpos, inspect)

Keywords

loess: Add a loess fit line to the plot. Default is true.
ols: Add an OLS fit line to the plot. Default is false.
observations: The observations to be plotted. When not specified then all observations for the given model will be shown. A subset of observations can be plotted by providing a Symbol or Vector{Symbol} of observation names.
zeroline: Include a zeroline in the plot. Default is false.
labels: The custom name to use for each individual series within in the plot such as a scatter or line. Provide a NamedTuple with any of the following keys and your custom label string: loess, ols, and observed.
paginate: (default false) When true sets the return type of a plot to a Vector{AlgebraOfGraphics.FigureGrid} rather than a single AlgebraOfGraphics.FigureGrid, splitting the returned plot over several "pages" if there are too many to fit on a single figure comfortably. See also limit, rows, and columns for controlling page size and grid shape.
limit: Sets the maximum number of axes that can be plotted per page when pagination is active. Cannot be combined with rows and columns.
rows: Sets the number of rows per page when pagination is active. For plots with a layout scale, must be specified together with columns. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
columns: Sets the number of columns per page when pagination is active. For plots with a layout scale, must be specified together with rows. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
axis: A key-value object with axis options that gets passed to the underlying AlgebraOfGraphics.draw call.
figure: A key-value object with figure options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)
legend: A key-value object with legend options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.) A legend will be drawn automatically unless legend = (; show = false) is set.
facet: A key-value object with facet options that gets passed to the underlying AlgebraOfGraphics.draw call.
colorbar: A key-value object with colorbar options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)

Supported Style Keywords

loess_color
loess_linestyle
loess_linewidth
ols_color
ols_linestyle
ols_linewidth
zeroline_color
zeroline_linestyle
zeroline_linewidth
marker
markercolor
markersize

For the fitted_model_inspection_npde variable above the following syntax is used to generate the plot below:

npde_vs_time(fitted_model_inspection_npde)

`observations_vs_ipredictions`

PumasPlots.observations_vs_ipredictions — Function

observations_vs_ipredictions(inspect | [model], predict)
observations_vs_ipredictions(figpos, inspect | [model], predict)

Plot observations versus individual predictions for the given inspect object, or the combination of an optional model and the results of predict.

Axis label will be based on the metadata and descriptions provided in the model's definition, if any.

Keywords

identity: Add an identity line to the plot. Default is false.
loess: Add a loess fit line to the plot. Default is true.
ols: Add an OLS fit line to the plot. Default is false.
observations: The observations to be plotted. When not specified then all observations for the given model will be shown. A subset of observations can be plotted by providing a Symbol or Vector{Symbol} of observation names.
scale: The scale used for both the x and the y axis. Options are :linear (default) and :log. With :log, trend lines are fit on log10-transformed data (an OLS fit then corresponds to a power model) and the axes are log-scaled. Requires strictly positive data. Use this instead of axis = (; xscale, yscale), which transforms only the display and leaves the trend lines fit in linear space.
stratify_by: name of a DataFrame column to colour the points by and to fit the OLS and loess trend lines within (e.g. :subpopulation from a mixture-model inspection). Defaults to nothing (no stratification).
labels: The custom name to use for each individual series within in the plot such as a scatter or line. Provide a NamedTuple with any of the following keys and your custom label string: identity, loess, ols, and observed.
paginate: (default false) When true sets the return type of a plot to a Vector{AlgebraOfGraphics.FigureGrid} rather than a single AlgebraOfGraphics.FigureGrid, splitting the returned plot over several "pages" if there are too many to fit on a single figure comfortably. See also limit, rows, and columns for controlling page size and grid shape.
limit: Sets the maximum number of axes that can be plotted per page when pagination is active. Cannot be combined with rows and columns.
rows: Sets the number of rows per page when pagination is active. For plots with a layout scale, must be specified together with columns. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
columns: Sets the number of columns per page when pagination is active. For plots with a layout scale, must be specified together with rows. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
axis: A key-value object with axis options that gets passed to the underlying AlgebraOfGraphics.draw call.
figure: A key-value object with figure options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)
legend: A key-value object with legend options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.) A legend will be drawn automatically unless legend = (; show = false) is set.
facet: A key-value object with facet options that gets passed to the underlying AlgebraOfGraphics.draw call.
colorbar: A key-value object with colorbar options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)

Supported Style Keywords

identity_color
identity_linewidth
identity_linestyle
loess_color
loess_linestyle
loess_linewidth
ols_color
ols_linestyle
ols_linewidth
marker
markercolor
markersize

For the fitted_model_inspection variable above the following syntax is used to generate the plot below:

observations_vs_ipredictions(fitted_model_inspection)

`observations_vs_predictions`

PumasPlots.observations_vs_predictions — Function

observations_vs_predictions(inspect | [model], predict)
observations_vs_predictions(figpos, inspect | [model], predict)

Plot observations versus population predictions for the given inspect object, or the combination of an optional model and the results of predict.

Axis label will be based on the metadata and descriptions provided in the model's definition, if any.

Keywords

identity: Add an identity line to the plot. Default is false.
loess: Add a loess fit line to the plot. Default is true.
ols: Add an OLS fit line to the plot. Default is false.
observations: The observations to be plotted. When not specified then all observations for the given model will be shown. A subset of observations can be plotted by providing a Symbol or Vector{Symbol} of observation names.
scale: The scale used for both the x and the y axis. Options are :linear (default) and :log. With :log, trend lines are fit on log10-transformed data (an OLS fit then corresponds to a power model) and the axes are log-scaled. Requires strictly positive data. Use this instead of axis = (; xscale, yscale), which transforms only the display and leaves the trend lines fit in linear space.
labels: The custom name to use for each individual series within in the plot such as a scatter or line. Provide a NamedTuple with any of the following keys and your custom label string: identity, loess, ols, and observed.
paginate: (default false) When true sets the return type of a plot to a Vector{AlgebraOfGraphics.FigureGrid} rather than a single AlgebraOfGraphics.FigureGrid, splitting the returned plot over several "pages" if there are too many to fit on a single figure comfortably. See also limit, rows, and columns for controlling page size and grid shape.
limit: Sets the maximum number of axes that can be plotted per page when pagination is active. Cannot be combined with rows and columns.
rows: Sets the number of rows per page when pagination is active. For plots with a layout scale, must be specified together with columns. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
columns: Sets the number of columns per page when pagination is active. For plots with a layout scale, must be specified together with rows. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
axis: A key-value object with axis options that gets passed to the underlying AlgebraOfGraphics.draw call.
figure: A key-value object with figure options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)
legend: A key-value object with legend options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.) A legend will be drawn automatically unless legend = (; show = false) is set.
facet: A key-value object with facet options that gets passed to the underlying AlgebraOfGraphics.draw call.
colorbar: A key-value object with colorbar options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)

Supported Style Keywords

identity_color
identity_linewidth
identity_linestyle
loess_color
loess_linestyle
loess_linewidth
ols_color
ols_linestyle
ols_linewidth
marker
markercolor
markersize

For the fitted_model_inspection variable above the following syntax is used to generate the plot below:

observations_vs_predictions(fitted_model_inspection)

`observations_vs_time`

PlottingUtilities.observations_vs_time — Method

observations_vs_time([model,] subject | population | fit | inspect)
observations_vs_time(figpos, [model,] subject | population | fit | inspect)

Plot observations versus time profiles for the given population. Optionally the associated model can be given as the first argument which can provide more detailed axis labels based on the descriptions and metadata from the model's definition. A single fit or inspect object can be passed in instead of providing the model and population pair.

Keywords

loess: Add a loess fit line to the plot. Default is true.
observations: The observations to be plotted. When not specified then all observations for the given model will be shown. A subset of observations can be plotted by providing a Symbol or Vector{Symbol} of observation names.
separate: Choose whether to overlay all plots or place each in a separate subplot.
labels: The custom name to use for each individual series within in the plot such as a scatter or line. Provide a NamedTuple with any of the following keys and your custom label string: observed, and loess.
paginate: (default false) When true sets the return type of a plot to a Vector{AlgebraOfGraphics.FigureGrid} rather than a single AlgebraOfGraphics.FigureGrid, splitting the returned plot over several "pages" if there are too many to fit on a single figure comfortably. See also limit, rows, and columns for controlling page size and grid shape.
limit: Sets the maximum number of axes that can be plotted per page when pagination is active. Cannot be combined with rows and columns.
rows: Sets the number of rows per page when pagination is active. For plots with a layout scale, must be specified together with columns. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
columns: Sets the number of columns per page when pagination is active. For plots with a layout scale, must be specified together with rows. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
axis: A key-value object with axis options that gets passed to the underlying AlgebraOfGraphics.draw call.
figure: A key-value object with figure options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)
legend: A key-value object with legend options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.) A legend will be drawn automatically unless legend = (; show = false) is set.
facet: A key-value object with facet options that gets passed to the underlying AlgebraOfGraphics.draw call.
colorbar: A key-value object with colorbar options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)

Supported Style Keywords

color
linewidth
linestyle
marker
markercolor
markersize
loess_color
loess_linestyle
loess_linewidth

For the fitted_model_inspection variable above the following syntax is used to generate the plot below:

observations_vs_time(fitted_model_inspection)

`sim_plot`

PumasPlots.sim_plot — Function

sim_plot([model,] simobs)
sim_plot(figpos, [model,] simobs)

Plot simulated model predictions from the result of a simobs call. The model used to simulate may optionally be passed to sim_plot, which is used to provide improved axis labels.

Keywords

ids: Select which subject IDs to display. Can be either a single ID or a Vector of IDs. Note that the type of the ID must match those in the population, i.e. a value 1 is not the same as a "1".
separate: Choose whether to overlay all plots or place each in a separate subplot.
observations: The observations to be plotted. When not specified then all observations for the given model will be shown. A subset of observations can be plotted by providing a Symbol or Vector{Symbol} of observation names.
labels: The custom name to use for each individual series within in the plot such as a scatter or line. Provide a NamedTuple with any of the following keys and your custom label string: simulated, and data.
paginate: (default false) When true sets the return type of a plot to a Vector{AlgebraOfGraphics.FigureGrid} rather than a single AlgebraOfGraphics.FigureGrid, splitting the returned plot over several "pages" if there are too many to fit on a single figure comfortably. See also limit, rows, and columns for controlling page size and grid shape.
limit: Sets the maximum number of axes that can be plotted per page when pagination is active. Cannot be combined with rows and columns.
rows: Sets the number of rows per page when pagination is active. For plots with a layout scale, must be specified together with columns. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
columns: Sets the number of columns per page when pagination is active. For plots with a layout scale, must be specified together with rows. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
axis: A key-value object with axis options that gets passed to the underlying AlgebraOfGraphics.draw call.
figure: A key-value object with figure options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)
legend: A key-value object with legend options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.) A legend will be drawn automatically unless legend = (; show = false) is set.
facet: A key-value object with facet options that gets passed to the underlying AlgebraOfGraphics.draw call.
colorbar: A key-value object with colorbar options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)

Supported Style Keywords

color
linestyle
linewidth
marker
markercolor
markersize

color and markercolor can both be set to the name of a gradient in which case each subject will use a different color based on partitioning the gradient into discrete colors. See Makie.available_gradients() for the full list of supported colors.

For the model and sim variables above the following syntax is used to generate the plot below:

sim_plot(model, sim)

`subject_fits`

PlottingUtilities.subject_fits — Method

subject_fits(inspect | [model], predict)
subject_fits(figpos, inspect | [model], predict)

Plot the population and individual predictions overlaid over observations for the provided observations by ID and the given inspect object, or the combination of a model and the results of predict.

Keywords

ids: Select which subject IDs to display. Can be either a single ID or a Vector of IDs. Note that the type of the ID must match those in the population, i.e. a value 1 is not the same as a "1".
observations: The observations to be plotted. When not specified then all observations for the given model will be shown. A subset of observations can be plotted by providing a Symbol or Vector{Symbol} of observation names.
separate: Choose whether to overlay all plots or place each in a separate subplot.
labels: The custom name to use for each individual series within in the plot such as a scatter or line. Provide a NamedTuple with any of the following keys and your custom label string: data, pred, and ipred.
paginate: (default false) When true sets the return type of a plot to a Vector{AlgebraOfGraphics.FigureGrid} rather than a single AlgebraOfGraphics.FigureGrid, splitting the returned plot over several "pages" if there are too many to fit on a single figure comfortably. See also limit, rows, and columns for controlling page size and grid shape.
limit: Sets the maximum number of axes that can be plotted per page when pagination is active. Cannot be combined with rows and columns.
rows: Sets the number of rows per page when pagination is active. For plots with a layout scale, must be specified together with columns. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
columns: Sets the number of columns per page when pagination is active. For plots with a layout scale, must be specified together with rows. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
axis: A key-value object with axis options that gets passed to the underlying AlgebraOfGraphics.draw call.
figure: A key-value object with figure options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)
legend: A key-value object with legend options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.) A legend will be drawn automatically unless legend = (; show = false) is set.
facet: A key-value object with facet options that gets passed to the underlying AlgebraOfGraphics.draw call.
colorbar: A key-value object with colorbar options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)

Supported Style Keywords

marker
markersize
markercolor
ipred_color
ipred_linewidth
ipred_linestyle
pred_color
pred_linewidth
pred_linestyle

For the fitted_model_inspection variable above the following syntax is used to generate the plot below:

figures = subject_fits(fitted_model_inspection; separate = true, paginate = true)

figures[1]

`vpc_plot`

PumasPlots.vpc_plot — Function

vpc_plot!(axis, [model,] vpc)
vpc_plot(figpos, [model,] vpc)
vpc_plot([model,] vpc)

Keywords

ci_bands::Bool show confidence interval band.
group select which strata to display, as a tuple of Pair{Symbol,Any} entries or a NamedTuple, such as (:DOSE => 75.0,) or (DOSE = 75.0,). Each key must be a stratification variable and each value must equal one of its values. Strata match when they agree on every given key, so naming a subset of the variables selects several.
levels::Union{String,Symbol,Vector} select which levels to display in discrete VPCs.
observations::Bool display a scatter plot of the observations data.
observed_ci::Bool show the observed confidence interval band.
observed_quantiles::Bool show the observed quantiles band.
simquantile_medians::Bool show the simulated quantile median line.
unit_yaxis::Bool set the limits of the y-axis to the unit range, [0, 1].
censored::Symbol either :all (default), :continuous, or :discrete. Controls display of censored VPC pairs: :all shows both stacked, others show only that component.
paginate: (default false) When true sets the return type of a plot to a Vector{Makie.Figure} rather than Makie.Figure which splits the returned plot over several "pages" if there are too many to fit on a single figure comfortably. See also limit, rows, and columns for controlling page size and grid shape.
limit: Sets the maximum number of axes that can be plotted per page when pagination is active. Cannot be combined with rows and columns.
rows: Sets the number of rows per page when pagination is active. For plots with a layout scale, must be specified together with columns. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
columns: Sets the number of columns per page when pagination is active. For plots with a layout scale, must be specified together with rows. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
legend: Either true or a NamedTuple of keyword arguments to pass to the axislegend function for each created Makie.Axis for the plot.
facet: Control the appearance of faceted plots. Off by default. Either true to use default facet settings which hide decorations, ticks, and labels for subplots aside from the left column and bottom row, or a NamedTuple with the following Bool keys:
- hidexlabels, hideylabels, and hidelabels. Default true. Hides labels that are not on the left or bottom edges.
- hidexticks, hideyticks, and hideticks. Default true. Hides ticks and tick labels that are not on the left or bottom edges.
- linkxaxes, linkyaxes, and linkaxes. Default true. Links the limits of the axes along columns/rows.
- combinexlabels, combineylabels, and combinelabels. Default false. Merges unique labels along the left and bottom edges.
labels: The custom name to use for each individual series within in the plot such as a scatter or line. Provide a NamedTuple with any of the following keys and your custom label string: observed, simulated, observed_ci, simulated_ci, and outliers.

Supported Style Keywords

outlier_color
marker
markercolor
markersize
band_color
observed_color
observed_linewidth
observed_linestyle
simulated_color
simulated_linewidth
simulated_linestyle

For the continuous_vpc variable above the following syntax is used to generate the plot below:

vpc_plot(model, continuous_vpc)

The model is optional, and vpc_plot(continuous_vpc) draws the same plot. Passing it labels the time axis with the timeu key of the model's @metadata block and the observation with its docstring.

Discrete and time to event VPCs are plotted with the same call.

`wresiduals_dist`

PumasPlots.wresiduals_dist — Function

wresiduals_dist(inspect | [model], wresiduals)
wresiduals_dist(figpos, inspect | [model], wresiduals)

Plot the distribution of weighted residuals for the given inspect, or the combination of an optional model and the results of wresiduals.

Axis label will be based on the metadata and descriptions provided in the model's definition, if any.

keywords

observations: The observations to be plotted. When not specified then all observations for the given model will be shown. A subset of observations can be plotted by providing a Symbol or Vector{Symbol} of observation names.
type: Select which residuals to plot. Options are :wres and :iwres for weighted population or individual residuals respectively. Default is to plot both.
zeroline: Include a zeroline in the plot. Default is false.
paginate: (default false) When true sets the return type of a plot to a Vector{AlgebraOfGraphics.FigureGrid} rather than a single AlgebraOfGraphics.FigureGrid, splitting the returned plot over several "pages" if there are too many to fit on a single figure comfortably. See also limit, rows, and columns for controlling page size and grid shape.
limit: Sets the maximum number of axes that can be plotted per page when pagination is active. Cannot be combined with rows and columns.
rows: Sets the number of rows per page when pagination is active. For plots with a layout scale, must be specified together with columns. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
columns: Sets the number of columns per page when pagination is active. For plots with a layout scale, must be specified together with rows. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
axis: A key-value object with axis options that gets passed to the underlying AlgebraOfGraphics.draw call.
figure: A key-value object with figure options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)
legend: A key-value object with legend options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.) A legend will be drawn automatically unless legend = (; show = false) is set.
facet: A key-value object with facet options that gets passed to the underlying AlgebraOfGraphics.draw call.
colorbar: A key-value object with colorbar options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)

Supported Style Keywords

color
strokecolor
strokewidth
zeroline_color
zeroline_linestyle
zeroline_linewidth

For the fitted_model_inspection variable above the following syntax is used to generate the plot below:

wresiduals_dist(fitted_model_inspection)

`wresiduals_vs_covariates`

PumasPlots.wresiduals_vs_covariates — Function

wresiduals_vs_covariates(inspect | [model], wresiduals)
wresiduals_vs_covariates(figpos, inspect | [model], wresiduals)

Plot the weighted population residuals versus covariates for the given inspect object, or the combination of an optional model and the results of wresiduals.

Axis label will be based on the metadata and descriptions provided in the model's definition, if any.

Keywords

observations: The observations to be plotted. When not specified then all observations for the given model will be shown. A subset of observations can be plotted by providing a Symbol or Vector{Symbol} of observation names.
categorical: Select which of the variables should be interpreted as categorical. Provide a vector of symbols corresponding to the names of the categorical variables. By default all variables are treated as continuous.
type: Select which residuals to plot. Options are :wres and :iwres for weighted population or individual residuals respectively. Default is to plot both.
covariates: The covariates to be plotted. When not specified then all covariates for the given model will be shown. A subset of covariates can be plotted by providing a Symbol or Vector{Symbol} of covariate names.
zeroline: Include a zeroline in the plot. Default is false.
paginate: (default false) When true sets the return type of a plot to a Vector{AlgebraOfGraphics.FigureGrid} rather than a single AlgebraOfGraphics.FigureGrid, splitting the returned plot over several "pages" if there are too many to fit on a single figure comfortably. See also limit, rows, and columns for controlling page size and grid shape.
limit: Sets the maximum number of axes that can be plotted per page when pagination is active. Cannot be combined with rows and columns.
rows: Sets the number of rows per page when pagination is active. For plots with a layout scale, must be specified together with columns. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
columns: Sets the number of columns per page when pagination is active. For plots with a layout scale, must be specified together with rows. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
axis: A key-value object with axis options that gets passed to the underlying AlgebraOfGraphics.draw call.
figure: A key-value object with figure options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)
legend: A key-value object with legend options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.) A legend will be drawn automatically unless legend = (; show = false) is set.
facet: A key-value object with facet options that gets passed to the underlying AlgebraOfGraphics.draw call.
colorbar: A key-value object with colorbar options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)

Supported Style Keywords

color
marker
markersize
zeroline_color
zeroline_linestyle
zeroline_linewidth

For the fitted_model_inspection variable above the following syntax is used to generate the plot below:

wresiduals_vs_covariates(
    fitted_model_inspection;
    categorical = [:SEX, :GROUP],
    figure = (; fontsize = 12),
)

`wresiduals_vs_predictions`

PumasPlots.wresiduals_vs_predictions — Function

wresiduals_vs_predictions(inspect)
wresiduals_vs_predictions(figpos, inspect)

Plot the weighted residuals versus population predictions for the given inspect object.

Axis label will be based on the metadata and descriptions provided in the model's definition, if any.

Keywords

loess: Add a loess fit line to the plot. Default is true.
ols: Add an OLS fit line to the plot. Default is false.
observations: The observations to be plotted. When not specified then all observations for the given model will be shown. A subset of observations can be plotted by providing a Symbol or Vector{Symbol} of observation names.
zeroline: Include a zeroline in the plot. Default is false.
labels: The custom name to use for each individual series within in the plot such as a scatter or line. Provide a NamedTuple with any of the following keys and your custom label string: loess, ols, and observed.
paginate: (default false) When true sets the return type of a plot to a Vector{AlgebraOfGraphics.FigureGrid} rather than a single AlgebraOfGraphics.FigureGrid, splitting the returned plot over several "pages" if there are too many to fit on a single figure comfortably. See also limit, rows, and columns for controlling page size and grid shape.
limit: Sets the maximum number of axes that can be plotted per page when pagination is active. Cannot be combined with rows and columns.
rows: Sets the number of rows per page when pagination is active. For plots with a layout scale, must be specified together with columns. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
columns: Sets the number of columns per page when pagination is active. For plots with a layout scale, must be specified together with rows. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
axis: A key-value object with axis options that gets passed to the underlying AlgebraOfGraphics.draw call.
figure: A key-value object with figure options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)
legend: A key-value object with legend options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.) A legend will be drawn automatically unless legend = (; show = false) is set.
facet: A key-value object with facet options that gets passed to the underlying AlgebraOfGraphics.draw call.
colorbar: A key-value object with colorbar options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)

Supported Style Keywords

loess_color
loess_linestyle
loess_linewidth
ols_color
ols_linestyle
ols_linewidth
zeroline_color
zeroline_linestyle
zeroline_linewidth
marker
markercolor
markersize

For the fitted_model_inspection variable above the following syntax is used to generate the plot below:

wresiduals_vs_predictions(fitted_model_inspection)

`wresiduals_vs_time`

PumasPlots.wresiduals_vs_time — Function

wresiduals_vs_time(inspect | [model], wresiduals)
wresiduals_vs_time(figpos, inspect | [model], wresiduals)

Plot the weighted residuals versus time for the given inspect object, or the combination of an optional model and the results of wresiduals.

Axis label will be based on the metadata and descriptions provided in the model's definition, if any.

Keywords

loess: Add a loess fit line to the plot. Default is true.
ols: Add an OLS fit line to the plot. Default is false.
observations: The observations to be plotted. When not specified then all observations for the given model will be shown. A subset of observations can be plotted by providing a Symbol or Vector{Symbol} of observation names.
zeroline: Include a zeroline in the plot. Default is false.
labels: The custom name to use for each individual series within in the plot such as a scatter or line. Provide a NamedTuple with any of the following keys and your custom label string: loess, ols, and observed.
paginate: (default false) When true sets the return type of a plot to a Vector{AlgebraOfGraphics.FigureGrid} rather than a single AlgebraOfGraphics.FigureGrid, splitting the returned plot over several "pages" if there are too many to fit on a single figure comfortably. See also limit, rows, and columns for controlling page size and grid shape.
limit: Sets the maximum number of axes that can be plotted per page when pagination is active. Cannot be combined with rows and columns.
rows: Sets the number of rows per page when pagination is active. For plots with a layout scale, must be specified together with columns. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
columns: Sets the number of columns per page when pagination is active. For plots with a layout scale, must be specified together with rows. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
axis: A key-value object with axis options that gets passed to the underlying AlgebraOfGraphics.draw call.
figure: A key-value object with figure options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)
legend: A key-value object with legend options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.) A legend will be drawn automatically unless legend = (; show = false) is set.
facet: A key-value object with facet options that gets passed to the underlying AlgebraOfGraphics.draw call.
colorbar: A key-value object with colorbar options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)

Supported Style Keywords

loess_color
loess_linestyle
loess_linewidth
ols_color
ols_linestyle
ols_linewidth
zeroline_color
zeroline_linestyle
zeroline_linewidth
marker
markercolor
markersize

For the fitted_model_inspection variable above the following syntax is used to generate the plot below:

wresiduals_vs_time(fitted_model_inspection)

Customizing Plots

The provided plotting functions discussed in the previous sections provide numerous customization options in the form of keywords for controlling visual aspects such as line colors and styles, titles, and axis labels. What these keywords do not control is the layout of a Figure in a "global" sense, since they are concerned with the customization of the axis that the plot is contained within.

To create more complex layouts of plots that incorporates the plots discussed above we can make use of Figure objects directly and in particular GridPositions that control where to place individual sub-plots. For a complete treatment of Makie's layout capabilities please refer directly to its documentation since we will only cover the basics here.

In the following example we will create a Figure that contains two different plots as sub-plots. Firstly, we must create a Figure object directly. Ensure that you have called using CairoMakie to import the Figure into your current namespace so that you can use it.

figure = Figure(; fontsize = 12);

Note that Figure takes all the same arguments that you can provide to the figure keyword when creating plots using the previously discussed plotting functions above.

Next we need to select the position within the figure that we would like to place each of our subplots. To do this Figures make use of array-indexing syntax, i.e. [].

observations_vs_time(figure[1, 1], model, pop; observations = :DV)
observations_vs_ipredictions(figure[1, 2], fitted_model_inspection; observations = :DV)
figure

Above we have placed an observations_vs_time plot at row 1 and column 1 and then placed an observations_vs_ipredictions plot at row 1 and column 2, i.e. side-by-side.