Plotting

The PumasUtilities package provides access to the plotting functions available for Pumas and NCA. The subset of functions available for NCA can also be accessed via the NCAUtilities package.

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 your 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 spelt. 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.

Pagination

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

We'll cover NCA- and Pumas-specific plotting functionality separately in the next two sections.

NCA

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

using NCA, NCAUtilities

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 plot functions are now available:

  • groups_check
  • observations_vs_time
  • parameters_dist
  • parameters_vs_group
  • subject_fits
  • summary_observations_vs_time

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

f = CSV.File(HTTP.get("http://bit.ly/painremed").body,
             missingstrings=["", "NA", "."])
pkpain_df = DataFrame(f)
pkpain_noplb_df = filter(x -> !(occursin.("Placebo", x.Dose)), pkpain_df)
#adding route variable
pkpain_noplb_df[!,:route] .= "ev"
# creating an `amt` column
pkpain_noplb_df[!,:Dose] .= parse.(Int,  chop.(pkpain_noplb_df.Dose, tail=3))
pkpain_noplb_df[!,:amt] .= ifelse.(pkpain_noplb_df.Time .== 0, pkpain_noplb_df.Dose, missing)

pkpain_nca = read_nca(pkpain_noplb_df,
                      id = :Subject,
                      time = :Time,
                      amt = :amt,
                      observations = :Conc,
                      group = [:Dose],
                      route = :route)

pk_nca_report = run_nca(pkpain_nca)

groups_check

NCAUtilities.groups_checkFunction
groups_check!(axis, population | report)
groups_check(figpos, population | report)
groups_check(population | report)

Keywords

  • group: Select which group from stratified input data to plot.

  • 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 the limit keyword which can be used to set the limit of figures per page.

  • limit: Sets the maximum number of axes that can be plotted per page when pagination is active.

  • rows: Sets the maximum number of rows of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • columns: Sets the maximum number of columns of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • 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.

Supported Style Keywords

  • color
  • markersize

For the dataset above, the following syntax is used to generate the plot below

groups_check(pkpain_nca, grouplabels = ["Dose (mg)"])

groups_check

observations_vs_time

PlottingUtilities.observations_vs_timeMethod
observations_vs_time!(axis, subject | population | report)
observations_vs_time(figpos, subject | population | report)
observations_vs_time(subject | population | report)

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".

  • 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.

  • 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 the limit keyword which can be used to set the limit of figures per page.

  • limit: Sets the maximum number of axes that can be plotted per page when pagination is active.

  • rows: Sets the maximum number of rows of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • columns: Sets the maximum number of columns of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • 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.

Supported Style Keywords

  • color
  • linestyle
  • linewidth
  • markercolor
  • markersize

For the dataset above, the following syntax is used to generate the plot below

figures =
    observations_vs_time(
        pkpain_nca;
        axis = (
            xlabel = "Time (hours)",
            ylabel = "CTMX Concentration (μg/mL)",
        ),
        paginate = true,
        facet = (combinelabels = true,),
    )

figures[1]

Since there are many subjects within the given data pkpain_nca we paginate the resulting plots such that the maximum number of subplots per page is limited to a reasonable number, 9 in a 3-by-3 grid for observations_vs_time plots. We can also adjust the appearance of the sub-plots by using the facet keyword to combine common axis labels into well-placed multi-axis labels. Notice that we display only figures[1] below while figures contains 14 separate Figure objects containing plots.

observations_vs_time_nca

summary_observations_vs_time

NCAUtilities.summary_observations_vs_timeFunction
summary_observations_vs_time!(axis, population | report)
summary_observations_vs_time(figpos, population | report)
summary_observations_vs_time(population | report)

Keywords

  • statistic: Select whether to use :mean or :geomean for the statistic.

  • errorbars: Set to false to hide error bars.

  • separate: Set to false to overlay all groups on a single axis.

  • group: Select which group from stratified input data to plot.

  • 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 the limit keyword which can be used to set the limit of figures per page.

  • limit: Sets the maximum number of axes that can be plotted per page when pagination is active.

  • rows: Sets the maximum number of rows of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • columns: Sets the maximum number of columns of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • 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.

Supported Style Keywords

  • color
  • linewidth
  • linestyle
  • marker
  • markercolor
  • markersize
  • errorbar_color
  • errorbar_linewidth
  • errorbar_linestyle
  • whiskerwidth

For the dataset above, the following syntax is used to generate the plot below

summary_observations_vs_time(
    pkpain_nca,
    figure = (
        fontsize = 10,
    ),
    axis = (
        xlabel = "Time (hr)",
        ylabel = "CTMX Concentration (μg/mL)",
    ),
    facet = (combinelabels = true,),
)

summary_observations_vs_time

parameters_vs_group

NCAUtilities.parameters_vs_groupFunction
parameters_vs_group!(axis, report)
parameters_vs_group(figpos, report)
parameters_vs_group(report)

Keywords

  • group: Select which group from stratified input data to plot.

  • parameter: The name of the parameter to plot given as a Symbol.

  • 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 the limit keyword which can be used to set the limit of figures per page.

  • limit: Sets the maximum number of axes that can be plotted per page when pagination is active.

  • rows: Sets the maximum number of rows of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • columns: Sets the maximum number of columns of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • 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.

Supported Style Keywords

  • color
  • markersize

For the pk_nca report generated above, the following syntax is used to generate the plot below

parameters_vs_group(pk_nca_report; parameter = :aucinf_obs)

parameters_vs_group

parameters_dist

NCAUtilities.parameters_distFunction
parameters_dist!(axis, report)
parameters_dist(figpos, report)
parameters_dist(report)

Keywords

  • parameter: The name of the parameter to plot given as a Symbol.

  • group: Select which group from stratified input data to plot.

  • 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 the limit keyword which can be used to set the limit of figures per page.

  • limit: Sets the maximum number of axes that can be plotted per page when pagination is active.

  • rows: Sets the maximum number of rows of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • columns: Sets the maximum number of columns of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • 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.

Supported Style Keywords

  • color
  • strokecolor
  • strokewidth

For the pk_nca report generated above, the following syntax is used to generate the plot below

parameters_dist(pk_nca_report; parameter = :aucinf_obs)

parameters_dist

subject_fits

PlottingUtilities.subject_fitsMethod
subject_fits!(axis, subject | population | report)
subject_fits(figpos, subject | population | report)
subject_fits(subject | population | report)

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".

  • 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, cpred, and removed.

  • 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 the limit keyword which can be used to set the limit of figures per page.

  • limit: Sets the maximum number of axes that can be plotted per page when pagination is active.

  • rows: Sets the maximum number of rows of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • columns: Sets the maximum number of columns of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • 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.

Supported Style Keywords

  • cpred_color
  • cpred_linestyle
  • cpred_linewidth
  • removed_color
  • removed_marker
  • removed_markersize
  • markercolor
  • markerstyle

For the pk_nca report generated above, the following syntax is used to generate the plot below

figures = 
    subject_fits(
        pk_nca_report;
        paginate = true,
        separate = true,
        figure = (
            fontsize = 12,
        ),
        axis = (
            xlabel = "Time (hr)",
            ylabel = "CTMX Concentration (μg/mL)"
        ),
        facet = (combinelabels = true,),
    )

figures[1]

The same plot above can be generated using the subject_fits(population) where only the lambdaz fits are computed.

subject_fits_nca

Pumas

As with the NCA plots, we must import the required modules. In this case we import PumasUtilities instead of NCAUtilities.

using Pumas, PumasUtilities

As with the NCA-specific plots in the previous section, we must also import a Makie "backend":

using CairoMakie

The following plots are now available:

  • convergence_trace
  • covariates_check
  • covariates_dist
  • empirical_bayes_dist
  • empirical_bayes_vs_covariates
  • goodness_of_fit
  • iwresiduals_vs_ipredictions
  • iwresiduals_vs_time
  • npde_dist
  • npde_vs_covariates
  • npde_vs_predictions
  • npde_vs_time
  • observations_vs_ipredictions
  • observations_vs_predictions
  • observations_vs_time
  • sim_plot
  • subject_fits
  • vpc_plot
  • wresiduals_dist
  • wresiduals_vs_covariates
  • wresiduals_vs_predictions
  • wresiduals_vs_time
Note

The plots discussed in this section only support continuous data models. Support for discrete data models will be made available soon.

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

data = CSV.read("pkdata_a1.csv", DataFrame; missingstring = ".")
pop = read_pumas(data; observations = [:dv], evid = :evid, covariates = [:formulation, :wt, :age, :racen, :gender])

model = @model begin
    @metadata begin
        timeu = u"hr"
    end
    @param begin
        "Clerance (L/hr)"
        tvcl ∈ RealDomain(lower = 0, init = 3.2)
        "Volume (L)"
        tvv  ∈ RealDomain(lower = 0, init = 16.4)
        "Absorption rate constant (h-1)"
        tvka ∈ RealDomain(lower = 0, init = 3.8)
        "Bioavailability"
        tvbio ∈ RealDomain(lower = 0, init=0.7)
        """
          - ΩCL
          - ΩVc
          - ΩKa
        """
        Ω    ∈ PDiagDomain(init = [0.04,0.04,0.04, 0.04])
        "Proportional RUV"
        σ_p  ∈ RealDomain(lower = 0.0001, init = 0.2)
    end
    @random begin
        η ~ MvNormal(Ω)
    end
    @covariates begin
        "0  PO, 1 IV"
        formulation
        "Body Weight (kg)"
        wt
        "Age (years)"
        age
        "Race"
        racen
        "Gender"
        gender
    end
    @pre begin
        CL = tvcl * exp(η[1])
        Vc = tvv * exp(η[2])
        Ka = tvka * exp(η[3])
    end
    @dosecontrol begin
        bioav = (Depot = tvbio * exp(η[4]),)
    end
    @dynamics Depots1Central1
    @derived begin
        cp := @. Central/Vc
        "CTMx Concentrations (ng/mL)"
        dv ~ @. Normal(cp, cp*σ_p)
    end
end

fitted_model = fit(model, pop, init_params(model), Pumas.FOCE())
fitted_model_inspection = inspect(fitted_model)

continous_vpc = vpc(fitted_model)

pkpain_df = DataFrame(CSV.File("pk_painscore.csv", missingstrings=["", "NA", "."]))
pkpain_noplb_df = filter(x -> !(occursin.("Placebo", x.ARM)), pkpain_df)
pkpain_noplb_df[!,:route] .= "ev"
pkpain_noplb_df[!,:amt] .= ifelse.(pkpain_noplb_df.TIME .== 0, pkpain_noplb_df.DOSE, missing)
pkpain_noplb_plot_df = filter(x -> !(x.TIME .== 0), pkpain_noplb_df)
pkpain_noplb_df[!, :evid] .= ifelse.(pkpain_noplb_df.TIME .== 0, 1, 0)
pkpain_noplb_df[!, :cmt] .= ifelse.(pkpain_noplb_df.TIME .== 0, 1, 2)
pkpain_noplb_df[!, :cmt2] .= 1 # for zero order absorption
pkpain_noplb_df[!, :CONC] .= ifelse.(pkpain_noplb_df.evid .== 1, missing, pkpain_noplb_df.CONC)

pkpain_noplb = read_pumas(pkpain_noplb_df,
                          id           = :ID,
                          time         = :TIME,
                          amt          = :amt,
                          observations = [:CONC],
                          covariates   = [:DOSE],
                          evid         = :evid,
                          cmt          = :cmt)


pk_model = @model begin
    @metadata begin
        timeu = u"hr"
    end
    @param begin
        "Clearance (L/hr)"
        tvcl ∈ RealDomain(lower = 0, init = 3.2)
        "Volume (L)"
        tvv  ∈ RealDomain(lower = 0, init = 16.4)
        "Absorption rate constant (h-1)"
        tvka ∈ RealDomain(lower = 0, init = 3.8)
        """
        - IIV CL [1,1] ...
        - IIV V [2,2] ...
        - IIV Ka [3,3] ...
        - IIV Ka [4,4] ... (does not exist)
        """
        Ω    ∈ PDiagDomain(init = [0.04,0.04,0.04])
        "Proportional RUV"
        σ_p  ∈ RealDomain(lower = 0.0001, init = 0.2)
    end
    @random begin
        η ~ MvNormal(Ω)
    end
    @covariates DOSE
    @pre begin
        CL = tvcl * exp(η[1])
        Vc = tvv * exp(η[2])
        Ka = tvka * exp(η[3])
    end
    @dynamics Depots1Central1
    @derived begin
        cp := @. Central/Vc
        CONC ~ @. Normal(cp, cp*σ_p)
    end
end

pk_sim = simobs(pk_model, pkpain_noplb, init_params(pk_model))

convergence_trace

PumasPlots.convergence_traceFunction
convergence_trace!(axis, fit | inspect)
convergence_trace(figpos, fit | inspect)
convergence_trace(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: :ll (Log-Likelihood) and :gn (Gradient Norm).
    • @emmodel-based: , , or their fullnames (:mu, :omega, and :sigma).
  • 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 the limit keyword which can be used to set the limit of figures per page.

  • limit: Sets the maximum number of axes that can be plotted per page when pagination is active.

  • rows: Sets the maximum number of rows of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • columns: Sets the maximum number of columns of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • 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.

Supported Style Keywords

  • color
  • linewidth
  • linestyle

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

convergence_trace(fitted_model_inspection)

convergence_trace

covariates_check

PumasPlots.covariates_checkFunction
covariates_check!(axis, [model,] subject | population | fit | inspect)
covariates_check(figpos, [model,] subject | population | fit | inspect)
covariates_check([model,] subject | population | fit | inspect)

Plot a data checkout by ID of the given population. Optionally the associated model may also be passed in as the first argument which can provide more detailed y-axis labels based on the descriptions provided in the model definition. Passing a fit or inspect do not require the model argument as well.

Keywords

  • covariates: The covariates to be plotted. When not specified then all covariates for the given model will be shown unless plotting into a Makie.Axis or Makie.GridPosition in which case the specific covariate must be given as a Symbol. A subset of covariates can be plotted by providing a Vector{Symbol} of covariate names.

  • 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 the limit keyword which can be used to set the limit of figures per page.

  • limit: Sets the maximum number of axes that can be plotted per page when pagination is active.

  • rows: Sets the maximum number of rows of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • columns: Sets the maximum number of columns of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • 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.

Supported Stype Keywords

  • color
  • markersize

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

covariates_check(model, pop)

covariates_check

covariates_dist

PumasPlots.covariates_distFunction
covariates_dist!(axis, [model,], subject | population | fit | inspect)
covariates_dist(figpos, [model,], subject | population | fit | inspect)
covariates_dist([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.

Keywords

  • covariates: The covariates to be plotted. When not specified then all covariates for the given model will be shown unless plotting into a Makie.Axis or Makie.GridPosition in which case the specific covariate must be given as a Symbol. A subset of covariates can be plotted by providing a 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{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 the limit keyword which can be used to set the limit of figures per page.

  • limit: Sets the maximum number of axes that can be plotted per page when pagination is active.

  • rows: Sets the maximum number of rows of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • columns: Sets the maximum number of columns of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • 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.

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 = [:formulation, :racen, :gender])

covariates_dist

empirical_bayes_dist

PumasPlots.empirical_bayes_distFunction
empirical_bayes_dist!(axis, inspect)
empirical_bayes_dist(figpos, inspect)
empirical_bayes_dist(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. When plotting into a Makie.Axis or Makie.GridPosition only one is plotted, and defaults to the first available, otherwise plots all available. Provide a Vector{Symbol} to plot a subset of all available variables.

  • zeroline: Include a zeroline in the plot. Default is true.

  • 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 the limit keyword which can be used to set the limit of figures per page.

  • limit: Sets the maximum number of axes that can be plotted per page when pagination is active.

  • rows: Sets the maximum number of rows of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • columns: Sets the maximum number of columns of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • 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.

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_dist

empirical_bayes_vs_covariates

PumasPlots.empirical_bayes_vs_covariatesFunction
empirical_bayes_vs_covariates!(axis, inspect)
empirical_bayes_vs_covariates(figpos, inspect)
empirical_bayes_vs_covariates(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.

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 unless plotting into a Makie.Axis or Makie.GridPosition in which case the specific covariate must be given as a Symbol. A subset of covariates can be plotted by providing a Vector{Symbol} of covariate names.

  • ebes: Select which variable, as a Symbol, to plot. When plotting into a Makie.Axis or Makie.GridPosition only one is plotted, and defaults to the first available, otherwise plots all available. Provide a Vector{Symbol} to plot a subset of all available variables.

  • zeroline: Include a zeroline in the plot. Default is true.

  • 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 the limit keyword which can be used to set the limit of figures per page.

  • limit: Sets the maximum number of axes that can be plotted per page when pagination is active.

  • rows: Sets the maximum number of rows of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • columns: Sets the maximum number of columns of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • 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.

Supported Style Keywords

  • color
  • 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 = [:formulation, :racen, :gender],
)

empirical_bayes_vs_covariates

goodness_of_fit

PumasPlots.goodness_of_fitFunction
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)
  • iwresiduals_vs_ipredictions (or npde_vs_predictions)

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

Note

No figpos or axis variant of this plot type is available since it requires 4 figure positions rather than just a single axis as is the case with most plotting functions.

Keywords

  • loess: Add a loess fit line to the plot. Default is true.

  • ols: Add an OLS 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 unless plotting into a Makie.Axis or Makie.GridPosition in which case the specific observation that should be plotted must be given as a Symbol. If a subset of observations are to be show then provide a Vector{Symbol}.

  • 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 the limit keyword which can be used to set the limit of figures per page.

  • limit: Sets the maximum number of axes that can be plotted per page when pagination is active.

  • rows: Sets the maximum number of rows of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • columns: Sets the maximum number of columns of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • 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.

Supported Style Keywords

  • loess_color
  • loess_linestyle
  • loess_linewidth
  • ols_color
  • ols_linestyle
  • ols_linewidth
  • 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)

goodness_of_fit

iwresiduals_vs_ipredictions

PumasPlots.iwresiduals_vs_ipredictionsFunction
iwresiduals_vs_ipredictions!(axis, inspect | [model], wresiduals, predict)
iwresiduals_vs_ipredictions(figpos, inspect | [model], wresiduals, predict)
iwresiduals_vs_ipredictions(inspect | [model], wresiduals, predict)

Plot the individual weighted 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 true.

  • observations: The observations to be plotted. When not specified then all observations for the given model will be shown unless plotting into a Makie.Axis or Makie.GridPosition in which case the specific observation that should be plotted must be given as a Symbol. If a subset of observations are to be show then provide a Vector{Symbol}.

  • zeroline: Include a zeroline in the plot. Default is true.

  • 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{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 the limit keyword which can be used to set the limit of figures per page.

  • limit: Sets the maximum number of axes that can be plotted per page when pagination is active.

  • rows: Sets the maximum number of rows of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • columns: Sets the maximum number of columns of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • 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.

Supported Style Keywords

  • loess_color
  • loess_linestyle
  • loess_linewidth
  • ols_color
  • ols_linestyle
  • ols_linewidth
  • zeroline_color
  • zeroline_linestyle
  • zeroline_linewidth
  • 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_ipredictions

iwresiduals_vs_time

PumasPlots.iwresiduals_vs_timeFunction
iwresiduals_vs_time!(axis, inspect | [model], wresiduals)
iwresiduals_vs_time(figpos, inspect | [model], wresiduals)
iwresiduals_vs_time(inspect | [model], wresiduals)

Plot the individual weighted 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 true.

  • observations: The observations to be plotted. When not specified then all observations for the given model will be shown unless plotting into a Makie.Axis or Makie.GridPosition in which case the specific observation that should be plotted must be given as a Symbol. If a subset of observations are to be show then provide a Vector{Symbol}.

  • zeroline: Include a zeroline in the plot. Default is true.

  • 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{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 the limit keyword which can be used to set the limit of figures per page.

  • limit: Sets the maximum number of axes that can be plotted per page when pagination is active.

  • rows: Sets the maximum number of rows of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • columns: Sets the maximum number of columns of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • 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.

Supported Style Keywords

  • loess_color
  • loess_linestyle
  • loess_linewidth
  • ols_color
  • ols_linestyle
  • ols_linewidth
  • zeroline_color
  • zeroline_linestyle
  • zeroline_linewidth
  • 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)

iwresiduals_vs_time

npde_dist

For all the npde_* plotting functions we have used the following example:

df = CSV.read("THEOPP.csv"), DataFrame, missingstring=".")
df.dv = max.(1.0, df.dv)
param = (
    θ₁ = 2.77,   #Ka MEAN ABSORPTION RATE CONSTANT for SEX = 1(1/HR)
    θ₂ = 0.0781, #K MEAN ELIMINATION RATE CONSTANT (1/HR)
    θ₃ = 0.0363, #SLP  SLOPE OF CLEARANCE VS WEIGHT RELATIONSHIP (LITERS/HR/KG)
    θ₄ = 1.5,    #Ka MEAN ABSORPTION RATE CONSTANT for SEX=0 (1/HR)
    Ω  = Diagonal(fill(0.05, 2)),
    σ²_add = 0.388
)
theopp = read_pumas(df, covariates=[:WT, :SEX])
mdl_censored = @model begin
    @param begin
        θ₁ ∈ RealDomain(lower=0.1,   upper=5.0, init=2.77)
        θ₂ ∈ RealDomain(lower=0.008, upper=0.5, init=0.0781)
        θ₃ ∈ RealDomain(lower=0.004, upper=0.9, init=0.0363)
        θ₄ ∈ RealDomain(lower=0.1,   upper=5.0, init=1.5)
        Ω ∈ PDiagDomain(2)
        σ²_add ∈ RealDomain(lower=0.001, init=0.388)
    end
    @random begin
        η ~ MvNormal(Ω)
    end
    @pre begin
        Ka = (SEX == 0 ? θ₁ : θ₄)*exp(η[1])
        K  = θ₂
        CL = θ₃*WT*exp(η[2])
        Vc = CL/K
        SC = CL/K/WT
    end
    @covariates SEX WT
    @dynamics Depots1Central1
    @derived begin
        conc := Central / SC
        dv ~ @. Censored(Normal(conc, sqrt(σ²_add)), 1.0, Inf)
    end
end
ft_censored = fit(
    mdl_censored, theopp, param, Pumas.LaplaceI(),
    optimize_fn=Pumas.DefaultOptimizeFN(show_trace=false),
)
inspect_censored = inspect(ft_censored, nsim=1000, rng=StableRNG(123))
vpc_censored = vpc(ft_censored, rng=StableRNG(123), ensemblealg=EnsembleSerial())
PumasPlots.npde_distFunction
npde_dist!(axis, inspect)
npde_dist(figpos, inspect)
npde_dist(inspect)

Keywords

  • observations: The observations to be plotted. When not specified then all observations for the given model will be shown unless plotting into a Makie.Axis or Makie.GridPosition in which case the specific observation that should be plotted must be given as a Symbol. If a subset of observations are to be show then provide a Vector{Symbol}.

  • zeroline: Include a zeroline in the plot. Default is true.

  • 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 the limit keyword which can be used to set the limit of figures per page.

  • limit: Sets the maximum number of axes that can be plotted per page when pagination is active.

  • rows: Sets the maximum number of rows of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • columns: Sets the maximum number of columns of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • 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.

Supported Style Keywords

  • color
  • strokecolor
  • strokewidth
  • zeroline_color
  • zeroline_linestyle
  • zeroline_linewidth

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

npde_dist(inspect_censored)

npde_dist

npde_vs_covariates

PumasPlots.npde_vs_covariatesFunction
npde_vs_covariates!(axis, inspect)
npde_vs_covariates(figpos, inspect)
npde_vs_covariates(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 unless plotting into a Makie.Axis or Makie.GridPosition in which case the specific covariate must be given as a Symbol. A subset of covariates can be plotted by providing a Vector{Symbol} of covariate names.

  • observations: The observations to be plotted. When not specified then all observations for the given model will be shown unless plotting into a Makie.Axis or Makie.GridPosition in which case the specific observation that should be plotted must be given as a Symbol. If a subset of observations are to be show then provide a Vector{Symbol}.

  • zeroline: Include a zeroline in the plot. Default is true.

  • 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 the limit keyword which can be used to set the limit of figures per page.

  • limit: Sets the maximum number of axes that can be plotted per page when pagination is active.

  • rows: Sets the maximum number of rows of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • columns: Sets the maximum number of columns of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • 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.

Supported Style Keywords

  • color
  • markersize
  • zeroline_color
  • zeroline_linestyle
  • zeroline_linewidth

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

npde_vs_covariates(inspect_censored; categorical = [:SEX])

npde_vs_covariates

npde_vs_predictions

PumasPlots.npde_vs_predictionsFunction
npde_vs_predictions!(axis, inspect)
npde_vs_predictions(figpos, inspect)
npde_vs_predictions(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 true.

  • observations: The observations to be plotted. When not specified then all observations for the given model will be shown unless plotting into a Makie.Axis or Makie.GridPosition in which case the specific observation that should be plotted must be given as a Symbol. If a subset of observations are to be show then provide a Vector{Symbol}.

  • zeroline: Include a zeroline in the plot. Default is true.

  • 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{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 the limit keyword which can be used to set the limit of figures per page.

  • limit: Sets the maximum number of axes that can be plotted per page when pagination is active.

  • rows: Sets the maximum number of rows of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • columns: Sets the maximum number of columns of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • 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.

Supported Style Keywords

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

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

npde_vs_predictions(inspect_censored)

npde_vs_predictions

npde_vs_time

PumasPlots.npde_vs_timeFunction
npde_vs_time!(axis, inspect)
npde_vs_time(figpos, inspect)
npde_vs_time(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 true.

  • observations: The observations to be plotted. When not specified then all observations for the given model will be shown unless plotting into a Makie.Axis or Makie.GridPosition in which case the specific observation that should be plotted must be given as a Symbol. If a subset of observations are to be show then provide a Vector{Symbol}.

  • zeroline: Include a zeroline in the plot. Default is true.

  • 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{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 the limit keyword which can be used to set the limit of figures per page.

  • limit: Sets the maximum number of axes that can be plotted per page when pagination is active.

  • rows: Sets the maximum number of rows of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • columns: Sets the maximum number of columns of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • 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.

Supported Style Keywords

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

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

npde_vs_time(inspect_censored)

npde_vs_time

observations_vs_ipredictions

PumasPlots.observations_vs_ipredictionsFunction
observations_vs_ipredictions!(axis, inspect | [model], predict)
observations_vs_ipredictions(figpos, inspect | [model], predict)
observations_vs_ipredictions(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 true.

  • loess: Add a loess fit line to the plot. Default is true.

  • ols: Add an OLS 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 unless plotting into a Makie.Axis or Makie.GridPosition in which case the specific observation that should be plotted must be given as a Symbol. If a subset of observations are to be show then provide a Vector{Symbol}.

  • 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{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 the limit keyword which can be used to set the limit of figures per page.

  • limit: Sets the maximum number of axes that can be plotted per page when pagination is active.

  • rows: Sets the maximum number of rows of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • columns: Sets the maximum number of columns of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • 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.

Supported Style Keywords

  • identity_color
  • identity_linewidth
  • identity_linestyle
  • loess_color
  • loess_linestyle
  • loess_linewidth
  • ols_color
  • ols_linestyle
  • ols_linewidth
  • 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_ipredictions

observations_vs_predictions

PumasPlots.observations_vs_predictionsFunction
observations_vs_predictions!(axis, inspect | [model], predict)
observations_vs_predictions(figpos, inspect | [model], predict)
observations_vs_predictions(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 true.

  • loess: Add a loess fit line to the plot. Default is true.

  • ols: Add an OLS 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 unless plotting into a Makie.Axis or Makie.GridPosition in which case the specific observation that should be plotted must be given as a Symbol. If a subset of observations are to be show then provide a Vector{Symbol}.

  • 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{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 the limit keyword which can be used to set the limit of figures per page.

  • limit: Sets the maximum number of axes that can be plotted per page when pagination is active.

  • rows: Sets the maximum number of rows of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • columns: Sets the maximum number of columns of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • 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.

Supported Style Keywords

  • identity_color
  • identity_linewidth
  • identity_linestyle
  • loess_color
  • loess_linestyle
  • loess_linewidth
  • ols_color
  • ols_linestyle
  • ols_linewidth
  • 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_predictions

observations_vs_time

PlottingUtilities.observations_vs_timeMethod
observations_vs_time!(axis, [model,] subject | population | fit | inspect)
observations_vs_time(figpos, [model,] subject | population | fit | inspect)
observations_vs_time([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 unless plotting into a Makie.Axis or Makie.GridPosition in which case the specific observation that should be plotted must be given as a Symbol. If a subset of observations are to be show then provide a Vector{Symbol}.

  • 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{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 the limit keyword which can be used to set the limit of figures per page.

  • limit: Sets the maximum number of axes that can be plotted per page when pagination is active.

  • rows: Sets the maximum number of rows of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • columns: Sets the maximum number of columns of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • 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.

Supported Style Keywords

  • color
  • linewidth
  • linestyle
  • 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)

observations_vs_time

sim_plot

PumasPlots.sim_plotFunction
sim_plot!(axis, [model,] simobs)
sim_plot(figpos, [model,] simobs)
sim_plot([model,] simobs)

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 unless plotting into a Makie.Axis or Makie.GridPosition in which case the specific observation that should be plotted must be given as a Symbol. If a subset of observations are to be show then provide a Vector{Symbol}.

  • 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{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 the limit keyword which can be used to set the limit of figures per page.

  • limit: Sets the maximum number of axes that can be plotted per page when pagination is active.

  • rows: Sets the maximum number of rows of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • columns: Sets the maximum number of columns of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • 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.

Supported Style Keywords

  • color
  • linestyle
  • linewidth
  • 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 pk_model and pk_sim variables above the following syntax is used to generate the plot below:

sim_plot(pk_model, pk_sim)

sim_plot

subject_fits

PlottingUtilities.subject_fitsMethod
subject_fits!(axis, inspect | [model], predict)
subject_fits(figpos, inspect | [model], predict)
subject_fits(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 unless plotting into a Makie.Axis or Makie.GridPosition in which case the specific observation that should be plotted must be given as a Symbol. If a subset of observations are to be show then provide a Vector{Symbol}.

  • 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{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 the limit keyword which can be used to set the limit of figures per page.

  • limit: Sets the maximum number of axes that can be plotted per page when pagination is active.

  • rows: Sets the maximum number of rows of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • columns: Sets the maximum number of columns of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • 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.

Supported Style Keywords

  • 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,
        facet = (combinelabels = true,),
    )

figures[1]

subject_fits

vpc_plot

PumasPlots.vpc_plotFunction
vpc_plot!(axis, [model,] vpc)
vpc_plot(figpos, [model,] vpc)
vpc_plot([model,] vpc)

Keywords

  • ci_bands::Bool show confidence interval band.

  • group::Tuple select which stratification to display. A tuple of Pair{Symbol,Any} entries.

  • 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 :continuous or :discrete. Used to select which VPC from a censored VPC pair to display.

  • 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 the limit keyword which can be used to set the limit of figures per page.

  • limit: Sets the maximum number of axes that can be plotted per page when pagination is active.

  • rows: Sets the maximum number of rows of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • columns: Sets the maximum number of columns of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • 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
Continuous VPCs

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

vpc_plot(model, continous_vpc)

vpc_plot-continuous

Time-to-Event VPCs

vpc_plot-tte

wresiduals_dist

PumasPlots.wresiduals_distFunction
wresiduals_dist!(axis, inspect | [model], wresiduals)
wresiduals_dist(figpos, inspect | [model], wresiduals)
wresiduals_dist(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 unless plotting into a Makie.Axis or Makie.GridPosition in which case the specific observation that should be plotted must be given as a Symbol. If a subset of observations are to be show then provide a Vector{Symbol}.

  • type: Select which residuals to plot. Options are :wres and :iwres for conditional or individual weighted residuals respectively. Default is to plot both unless plotting directly into a Makie.Axis or Makie.GridPosition in which case only one can be plotted at a time, defaulting to :wres.

  • zeroline: Include a zeroline in the plot. Default is true.

  • 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 the limit keyword which can be used to set the limit of figures per page.

  • limit: Sets the maximum number of axes that can be plotted per page when pagination is active.

  • rows: Sets the maximum number of rows of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • columns: Sets the maximum number of columns of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • 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.

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_dist

wresiduals_vs_covariates

PumasPlots.wresiduals_vs_covariatesFunction
wresiduals_vs_covariates!(axis, inspect | [model], wresiduals)
wresiduals_vs_covariates(figpos, inspect | [model], wresiduals)
wresiduals_vs_covariates(inspect | [model], wresiduals)

Plot the conditional weighted 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 unless plotting into a Makie.Axis or Makie.GridPosition in which case the specific observation that should be plotted must be given as a Symbol. If a subset of observations are to be show then provide a Vector{Symbol}.

  • 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 conditional or individual weighted residuals respectively. Default is to plot both unless plotting directly into a Makie.Axis or Makie.GridPosition in which case only one can be plotted at a time, defaulting to :wres.

  • covariates: The covariates to be plotted. When not specified then all covariates for the given model will be shown unless plotting into a Makie.Axis or Makie.GridPosition in which case the specific covariate must be given as a Symbol. A subset of covariates can be plotted by providing a Vector{Symbol} of covariate names.

  • zeroline: Include a zeroline in the plot. Default is true.

  • 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 the limit keyword which can be used to set the limit of figures per page.

  • limit: Sets the maximum number of axes that can be plotted per page when pagination is active.

  • rows: Sets the maximum number of rows of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • columns: Sets the maximum number of columns of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • 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.

Supported Style Keywords

  • color
  • 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 = [:formulation, :racen, :gender],
    figure = (fontsize = 12,),
)

wresiduals_vs_covariates

wresiduals_vs_predictions

PumasPlots.wresiduals_vs_predictionsFunction
wresiduals_vs_predictions!(axis, inspect | [model], predict)
wresiduals_vs_predictions(figpos, inspect | [model], predict)
wresiduals_vs_predictions(inspect | [model], predict)

Plot the weighted residuals 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

  • loess: Add a loess fit line to the plot. Default is true.

  • ols: Add an OLS 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 unless plotting into a Makie.Axis or Makie.GridPosition in which case the specific observation that should be plotted must be given as a Symbol. If a subset of observations are to be show then provide a Vector{Symbol}.

  • zeroline: Include a zeroline in the plot. Default is true.

  • 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{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 the limit keyword which can be used to set the limit of figures per page.

  • limit: Sets the maximum number of axes that can be plotted per page when pagination is active.

  • rows: Sets the maximum number of rows of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • columns: Sets the maximum number of columns of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • 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.

Supported Style Keywords

  • loess_color
  • loess_linestyle
  • loess_linewidth
  • ols_color
  • ols_linestyle
  • ols_linewidth
  • zeroline_color
  • zeroline_linestyle
  • zeroline_linewidth
  • 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_predictions

wresiduals_vs_time

PumasPlots.wresiduals_vs_timeFunction
wresiduals_vs_time!(axis, inspect | [model], wresiduals)
wresiduals_vs_time(figpos, inspect | [model], wresiduals)
wresiduals_vs_time(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 true.

  • observations: The observations to be plotted. When not specified then all observations for the given model will be shown unless plotting into a Makie.Axis or Makie.GridPosition in which case the specific observation that should be plotted must be given as a Symbol. If a subset of observations are to be show then provide a Vector{Symbol}.

  • zeroline: Include a zeroline in the plot. Default is true.

  • 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{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 the limit keyword which can be used to set the limit of figures per page.

  • limit: Sets the maximum number of axes that can be plotted per page when pagination is active.

  • rows: Sets the maximum number of rows of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • columns: Sets the maximum number of columns of subplots to be displayed on each paginated Makie.Figure when pagination is active.

  • 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.

Supported Style Keywords

  • loess_color
  • loess_linestyle
  • loess_linewidth
  • ols_color
  • ols_linestyle
  • ols_linewidth
  • zeroline_color
  • zeroline_linestyle
  • zeroline_linewidth
  • 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)

wresiduals_vs_time

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 with 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)

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.

custom_layout