DeepPumas

Appearance

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:

julia
using DeepPumas
using CairoMakie
set_theme!(deep_light())

Plotting individual predictions in a grid using plotgrid ​

The evaluation of an NLME model can benefit from the visual inspection of the model predictions. 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 plots can include information such as the measured data, population predictions (when η is set to the posterior mode and specified covariate values), individual predictions (when η is set to the empirical Bayes estimate and specified covariate values), drug dosing events, etc. Example usage of plotgrid can be found in the Getting Started page and in the plotgrid docstring.

DeepPumas.plotgrid Function
julia
plotgrid(objs; kwargs...)

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

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

See plotgrid! for a mutating version.

Arguments:

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

Keyword arguments for figure contents:

  • data::Union{Bool, NamedTuple}=true toggle whether to plot the data. Named tuples 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 (corresponding to Makie.lines) and :scatterlines (corresponding to Makie.scatterlines). See Makie's 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").

  • dose::Union{Bool, NamedTuple}=true toggle whether to plot vertical lines for doses. Named tuples 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).

  • pred::Union{Bool, NamedTuple}=true (only for plotting results of predict) toggle whether to plot the population predictions (preds). Named tuples will be passed as attributes to the selected plotting function, which is set via the plot_type argument and is :lines (corresponding Makie.lines) by default. Other possible values for plot_type are :scatter (corresponding to Makie.scatter) and :scatterlines (corresponding to Makie.scatterlines). See Makie's 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").

  • ipred::Union{Bool, NamedTuple}=true (only for plotting results of predict) toggle whether to plot the individual predictions (ipreds). Named tuples 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 (corresponding to Makie.scatter) and :scatterlines (corresponding to Makie.scatterlines). See Makie's 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 ipred").

  • sim::Union{Bool, NamedTuple}=true (only for plotting results of simobs) toggle whether to plot the simobs result. Named tuples 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 (corresponding to Makie.lines) and :scatter (corresponding to Makie.scatter). See Makie's 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").

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

Keyword arguments for figure layout and customization:

  • layout::Tuple specify how many rows and columns to distribute the plots among. The order is layout=(nrows, ncolumns). Be mindful of the difference with Makie's figure size specification, where size=(width, height).

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

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

  • linkx::Bool=true link the x-axes of all the subplots.

  • linky::Bool=true link the y-axes of all the subplots.

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

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

  • 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 subject ID unless the axis already has a title defined.

  • plot_type::Symbol Plot type for the variable of interest. Can be passed individually via the named tuple 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 Makie.scatter, Makie.lines, and Makie.scatterlines functions.

Keyword arguments forwarded to Makie:

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

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

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

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

Example usage:

plotgrid is commonly used together with its mutating counterpart, plotgrid!. Let pop, sim, pred be a Population, a result from predict or from simobs, respectively.

julia
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(
  pred[1:12],
  figure=(; size=(400,1000)),
  layout=(6,2),
)

plotgrid(
  pred[1:12];
  figure=(; size=(400,1000)),
  data=false,
  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])
DeepPumas.plotgrid! Function
julia
plotgrid!(objs; data=false, dose=false, kwargs...)
plotgrid!(plt::Makie.Figure, objs; data=false, dose=false, kwargs...)
plotgrid!(axes::Array{Makie.Axis}, objs; data=false, dose=false, kwargs...)

Plot the objs in a grid of subplots modifying a previous plot.

Along with plotgrid, this is useful for plotting both predict and simobs results in the same plot, or for plotting predictions from different models in the same subplots.

The plot can be customized by keyword arguments (see plotgrid).

Warning

In contrast to plotgrid, the options to toggle data and dose default to false for plotgrid!.

See plotgrid for usage examples.