Plotting Functions

Most plotting functionality that has been designed to work with Pumas.jl and DeepPumas.jl is based on Makie.jl or AlgebraOfGraphics.jl (an introductory tutorial can be found here) with the specific functions implemented in PumasPlots.jl. Here we document a few useful extra pieces of plotting functionality that are currently a part of DeepPumas.jl.

Custom plotting themes

Different plotting themes can be useful when working in different color environments, preparing presentations or reports that use specific color schemes. Therefore, DeepPumas currently contains two functions which return Makie.Theme objects: deep_light() and deep_dark(). These themes may come in handy in producing more legible and better looking plots. Since both themes are implemented as Makie.Theme objects, they are composable and modifiable with other settings described in the Makie documentation. To activate the scheme one would simply write:

using DeepPumas
using CairoMakie
set_theme!(deep_light())

Plotting individual predictions in a grid using plotgrid

NLME modelling may require looking both at individual and population predictions for multiple individuals at once. Therefore, the plotgrid function, which is based on Makie.jl, implements functionality that conveniently plots various different features of a population of patients in a customizable grid. The plotting can include information such as the measured data, population predictions (when $\eta$ is set to the posterior mode and specified covariate values), individual predictions (when $\eta$ is set to the empirical Bayes estimate and specified covariate values), drug delivery, etc. Some example usage of plotgrid is given in the Getting Started page.

DeepPumas.plotgrid Function

plotgrid(objs)
plotgrid!(objs)
plotgrid!(plt::Makie.Figure, objs)
plotgrid!(axes::Array{Makie.Axis}, objs)

Plot the objs (Population, results of simobs or predict) in a grid of subplots.

The plot can be customized by keyword arguments. Several of these keyword arguments can take NamedTuples that are passed on as attributes to the Makie.jl functions that do the plotting.

When used with a bang (!), plotgrid! will modify a previous plot. This is useful for plotting both predict and simobs results in the same plot, or plotting predictions from different models in the same subplots.

Arguments:

• obsj::Vector A vector of the objects to plot.

Keyword arguments:

• add_legend::Bool = true toggle whether to add the plotted objects to the legend.

• axis::NamedTuple = (;) (plotgrid only) arguments to be passed to Makies Axis constructor. For full details, see Makie's documentation, but a common example might be axis = (; ylabel = "My Biomarker", xlims=(0., 1.))

• data::Union{Bool, NamedTuple} = true toggle whether to plot the data. NamedTuples will be passed as attributes to the selected plotting function, which is set via the plot_type argument and is :scatter (corresponding to Makie.scatter!) by default. Other possible values for plot_type are :lines (Makie.lines!) and :scatterlines (Makie.scatterlines!), see Makie documentation for full options for each of the plotting functions. Assuming plot_type=:scatter, some common options are (; markersize=10, color=(:blue, 0.5), label="Trial Name"). Defaults to false for plotgrid!.

• dose::Union{Bool, NamedTuple} = true toggle whether to plot vertical lines for doses. NamedTuples will be passed as attributes to Makie.vlines! - see that documentation for full options. Common options are (; linewidth=2, color=(:red, 0.2), linestyle=:dash) Defaults to false for plotgrid!.

• figure::NamedTuple = (;) (plotgrid only) arguments to be passed to Makies Figure constructor. For full details, see Makie's documentation, but the most common example might be figure = (; size = (1000,800))

• ipred::Union{Bool, NamedTuple} = true (only for plotting results of predict) toggle whether to plot the ipreds. NamedTuples will be passed as attributes to the selected plotting function, which is set via the plot_type argument and is :lines (corresponding to Makie.lines!) by default. Other possible values for plot_type are :scatter (Makie.scatter!) and :scatterlines (Makie.scatterlines!), see Makie documentation for full options for each of the plotting functions. Assumimng plot_type=:lines, some common options are (; linewidth=4, linestyle=:dash, color=(:blue, 0.8), label="My ipred").

• layout::Tuple specify how many columns and rows to distribute the plots among. (nrows, ncolumns).

• legend::NamedTuple = (;) arguments to be passed to Makies Legend constructor. For full details, see Makie's documentation, but a common example might be legend = (; orientation=:horizontal, framevisible=false)

• linkx::Bool = true - link the x-axes of all the subplots. Not applicable with plotgrid!.

• linky::Bool = true - link the y-axes of all the subplots. Not applicable with plotgrid!.

• observation::Union{Int, Symbol} = 1 specify the variable to use for plotting. You can specify by number or symbol.

• pred::Union{Bool, NamedTuple} = true (only for plotting results of predict) toggle whether to plot the preds. NamedTuples will be passed as attributes to the selected plotting function, which is set via the plot_type argument and is :lines (corresponding to Makie.lines!) by default. Other possible values for plot_type are :scatter (Makie.scatter!) and :scatterlines (Makie.scatterlines!), see Makie documentation for full options for each of the plotting functions. Assuming plot_type=:lines, some common options are (; linewidth=4, linestyle=:dash, color=(:blue, 0.8), label="My pred").

• sim::Union{Bool, NamedTuple} = true (only for plotting results of simobs) toggle whether to plot the simobs result. NamedTuples will be passed as attributes to the selected plotting function, which is set via the plot_type argument and is :scatterlines (corresponding to Makie.scatterlines!) by default. Other possible values for plot_type are :lines (Makie.lines!) and :scatterlines (Makie.scatterlines!), see Makie documentation for full options for each of the plotting functions. Assuming plot_type=:scatterlines, some common options are (; linewidth=4, markersize=3, linestyle=:dash, color=(:blue, 0.8), label="Simulated", ).

• title::Union{Function, String, Nothing} = nothing specify how to generate subplot titles. If you pass a function then it will be called like title(subject, i) whereupon it must return a string. Example title = (subject, i) -> "#$i, ID: $(subject.id)". If you pass a string then that string will be applied to all subplots. nothing sets a default behaviour which plots the first 10 characters of the patient ID unless the axis already has a title defined.

• xlabel::String = "Time" specify the x-label.

• xtransform::Function = identity a single-argument function to transform the x-data (typically time).

• ylabel::String specify the single y-label that's placed to the left of the grid of subplots. Defaults to your output name. If you want a ylabel for each of the subplots then pass axis=(; ylabel="My Label") instead.

• ytransform::Function = identity a single-argument transform function to apply to the output before plotting. ytransform = x -> 2*exp(x)

• plot_type::Symbol Plot type for the variable of interest. Can be passed individually via the NamedTuple for data, sim, ipred or pred or as a general keyword argument. The individually passed values will override the general keyword argument. The possible plot types are :scatter, :lines, :scatterlines corresponding to the Makie.scatter!, Makie.lines! and Makie.scatterlines! functions.

• kwargs... Any keyword argument in excess of the above list is passed unmodified to Makies scatter or lines commands (depending on what's being plotted.).

Example usage

Let pop, sim, pred be a Population, a result from simobs or from predict, respectively.

using CairoMakie

plt = plotgrid(pop)
plotgrid!(pred)
plotgrid!(simobs)
save("my_file_name.png", plt)

plotgrid(
  pred; 
  pred=(; label = "MyPredLabel", color=:blue, linewidth = 10),
  ipred=false,
  data=(; markersize=10, color=:red),
)
plotgrid!(sim, color=(:green, 0.3)) 
plotgrid!(sim, color=(:green, 0.3), add_legend=false) 

plotgrid(
  pred[1:12], 
  figure=(; size=(1000,400)),
  linewidth = 10, # applies to both `pred` and `ipred`
  layout=(6,2),
)

fig = Figure()
ax1 = Axis(fig[1,1])
scatter!(ax1, rand(10), rand(10))
ax_group = GridLayout(fig[1,2])
axes = [Axis(ax_group[i,j]) for i in 1:2, j in 1:2]
plotgrid!(axes, pred[1:4])