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 data markers. NamedTuples will be passed as attributes to Makie.scatter! - see that documentation for full options. 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 Makie.lines! - see that documentation for full options. 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 ipreds. NamedTuples will be passed as attributes to Makie.lines! - see that documentation for full options. Common options are (; linewidth=4, linestyle=:dash, color=(:blue, 0.8), label="My ipred").

• 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 Makie.lines! and Makie.scatter! - see those documentations for full options. Common options are (; linewidth=4, linestyle=:dash, color=(:blue, 0.8), label="Simulated"). Turn off scatter with markersize=0 and/or turn of the connecting lines with linewidth=0.

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

• 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])

source