Plots

NCA.jl ships Makie recipes for the input data, the analysis results and the dose linearity models. Each one returns a Makie.Figure and takes either the parsed input data frame or the run_nca result, depending on what it plots. CairoMakie comes with NCA.jl, so there is no separate backend to load.

Every recipe also has an interactive Plotly counterpart, obtained by passing the figure specification through interactive.

using NCA, PharmaDatasets, DataFrames, Unitful

df = dataset("nca/dapa_IV_ORAL")
df[!, :route] .= map(f -> f == "ORAL" ? "ev" : "ivbolus", df.FORMULATION)

nca_data = read_nca_pumas(
    df;
    id = :ID,
    time = :TIME,
    concentration = :COBS,
    dose = :AMT,
    route = :route,
    time_unit = u"hr",
    concentration_unit = u"mg/L",
    dose_unit = u"mg",
    group = [:OCC],
)
results = run_nca(nca_data)

Checking groups

groups_check(nca_data)

NCA.groups_check — Function

groups_check(input_df | report_df)
groups_check(figpos, input_df | report_df)

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{AlgebraOfGraphics.FigureGrid} rather than a single AlgebraOfGraphics.FigureGrid, splitting the returned plot over several "pages" if there are too many to fit on a single figure comfortably. See also limit, rows, and columns for controlling page size and grid shape.
limit: Sets the maximum number of axes that can be plotted per page when pagination is active. Cannot be combined with rows and columns.
rows: Sets the number of rows per page when pagination is active. For plots with a layout scale, must be specified together with columns. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
columns: Sets the number of columns per page when pagination is active. For plots with a layout scale, must be specified together with rows. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
axis: A key-value object with axis options that gets passed to the underlying AlgebraOfGraphics.draw call.
figure: A key-value object with figure options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)
legend: A key-value object with legend options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.) A legend will be drawn automatically unless legend = (; show = false) is set.
facet: A key-value object with facet options that gets passed to the underlying AlgebraOfGraphics.draw call.
colorbar: A key-value object with colorbar options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)

Supported Style Keywords

color
markersize

Observations over time

observations_vs_time(nca_data; ids = [1, 2])

PlottingUtilities.observations_vs_time — Function

observations_vs_time(input_df | report_df)
observations_vs_time(figpos, input_df | report_df)

Keywords

llq: Set to a numeric value to display a horizontal line indicating the Lower Limit of Quantification (LLQ). Defaults to nothing (no line).
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{AlgebraOfGraphics.FigureGrid} rather than a single AlgebraOfGraphics.FigureGrid, splitting the returned plot over several "pages" if there are too many to fit on a single figure comfortably. See also limit, rows, and columns for controlling page size and grid shape.
limit: Sets the maximum number of axes that can be plotted per page when pagination is active. Cannot be combined with rows and columns.
rows: Sets the number of rows per page when pagination is active. For plots with a layout scale, must be specified together with columns. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
columns: Sets the number of columns per page when pagination is active. For plots with a layout scale, must be specified together with rows. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
axis: A key-value object with axis options that gets passed to the underlying AlgebraOfGraphics.draw call.
figure: A key-value object with figure options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)
legend: A key-value object with legend options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.) A legend will be drawn automatically unless legend = (; show = false) is set.
facet: A key-value object with facet options that gets passed to the underlying AlgebraOfGraphics.draw call.
colorbar: A key-value object with colorbar options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)

Supported Style Keywords

- `color`
- `linestyle`
- `linewidth`
- `markercolor`
- `markersize`
- `group_fontsize`
- `llq_color`: Color of the LLQ line (default: `Makie.automatic`).
- `llq_linestyle`: Linestyle of the LLQ line (default: `Makie.automatic`).
- `llq_label`: Label for the LLQ line in the legend (default: "LLQ").
- `llq_linewidth`: Linewidth of the LLQ line (default: `Makie.automatic`).

Summarized observations over time

summary_observations_vs_time(nca_data)

NCA.summary_observations_vs_time — Function

summary_observations_vs_time(input_df)
summary_observations_vs_time(figpos, input_df)

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.
show_subjects: Set to true to overlay individual traces ("spaghetti plots")
llq: Set to a numeric value to display a horizontal line indicating the Lower Limit of Quantification (LLQ). Defaults to nothing (no line).
paginate: (default false) When true sets the return type of a plot to a Vector{AlgebraOfGraphics.FigureGrid} rather than a single AlgebraOfGraphics.FigureGrid, splitting the returned plot over several "pages" if there are too many to fit on a single figure comfortably. See also limit, rows, and columns for controlling page size and grid shape.
limit: Sets the maximum number of axes that can be plotted per page when pagination is active. Cannot be combined with rows and columns.
rows: Sets the number of rows per page when pagination is active. For plots with a layout scale, must be specified together with columns. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
columns: Sets the number of columns per page when pagination is active. For plots with a layout scale, must be specified together with rows. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
axis: A key-value object with axis options that gets passed to the underlying AlgebraOfGraphics.draw call.
figure: A key-value object with figure options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)
legend: A key-value object with legend options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.) A legend will be drawn automatically unless legend = (; show = false) is set.
facet: A key-value object with facet options that gets passed to the underlying AlgebraOfGraphics.draw call.
colorbar: A key-value object with colorbar options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)

Supported Style Keywords

color: Either any scalar color that Makie can handle, or if separate = false and the population is grouped, a palette: a vector of colors (for example using Makie.categorical_colors or manually specified), a PlotUtils.CategoricalColorGradient (what Makie.cgrad(colormap, n, categorical = true) returns) or the name of a categorical colormap such as :Set1_5, with at least as many colors as there are groups. In this case, the groups 1 to n will get the colors 1 to n from these objects. Unused colors are ignored.
linewidth
linestyle
marker
markercolor
markersize
errorbar_color
errorbar_linewidth
errorbar_linestyle
whiskerwidth
subjects_color: Either any scalar color that Makie can handle or a number between 0 and 1 which takes the main color and applies the number as an alpha value to it.
subjects_linewidth
subjects_linestyle
llq_color: Color of the LLQ line (default: Makie.automatic).
llq_linestyle: Linestyle of the LLQ line (default: Makie.automatic).
llq_label: Label for the LLQ line in the legend (default: "LLQ").
llq_linewidth: Linewidth of the LLQ line (default: Makie.automatic).

Subject fits

subject_fits(nca_data; ids = [1, 2])

PlottingUtilities.subject_fits — Function

subject_fits(input_df)
subject_fits(figpos, input_df)

Keywords

llq: Set to a numeric value to display a horizontal line indicating the Lower Limit of Quantification (LLQ). Defaults to nothing (no line).
threshold: Passed to NCA.run_nca for lambdaz fitting. Defaults to nothing.
adjr2factor: Passed to NCA.run_nca for lambdaz fitting. Defaults to nothing.
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{AlgebraOfGraphics.FigureGrid} rather than a single AlgebraOfGraphics.FigureGrid, splitting the returned plot over several "pages" if there are too many to fit on a single figure comfortably. See also limit, rows, and columns for controlling page size and grid shape.
limit: Sets the maximum number of axes that can be plotted per page when pagination is active. Cannot be combined with rows and columns.
rows: Sets the number of rows per page when pagination is active. For plots with a layout scale, must be specified together with columns. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
columns: Sets the number of columns per page when pagination is active. For plots with a layout scale, must be specified together with rows. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
axis: A key-value object with axis options that gets passed to the underlying AlgebraOfGraphics.draw call.
figure: A key-value object with figure options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)
legend: A key-value object with legend options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.) A legend will be drawn automatically unless legend = (; show = false) is set.
facet: A key-value object with facet options that gets passed to the underlying AlgebraOfGraphics.draw call.
colorbar: A key-value object with colorbar options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)

Supported Style Keywords

- `cpred_color`
- `cpred_linestyle`
- `cpred_linewidth`
- `removed_color`
- `removed_marker`
- `removed_markersize`
- `markercolor`
- `markerstyle`
- `group_fontsize`
- `llq_color`: Color of the LLQ line (default: `Makie.automatic`).
- `llq_linestyle`: Linestyle of the LLQ line (default: `Makie.automatic`).
- `llq_label`: Label for the LLQ line in the legend (default: "LLQ").
- `llq_linewidth`: Linewidth of the LLQ line (default: `Makie.automatic`).

Parameter distributions

parameters_dist(results; parameter = :auclast)

NCA.parameters_dist — Function

parameters_dist(report_df)
parameters_dist(figpos, report_df)

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{AlgebraOfGraphics.FigureGrid} rather than a single AlgebraOfGraphics.FigureGrid, splitting the returned plot over several "pages" if there are too many to fit on a single figure comfortably. See also limit, rows, and columns for controlling page size and grid shape.
limit: Sets the maximum number of axes that can be plotted per page when pagination is active. Cannot be combined with rows and columns.
rows: Sets the number of rows per page when pagination is active. For plots with a layout scale, must be specified together with columns. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
columns: Sets the number of columns per page when pagination is active. For plots with a layout scale, must be specified together with rows. The grid shape is controlled via AlgebraOfGraphics.wrapped(; cols = columns) and the page limit is computed as rows × columns. For plots with row/col scales, translates directly to the corresponding pagination parameter.
axis: A key-value object with axis options that gets passed to the underlying AlgebraOfGraphics.draw call.
figure: A key-value object with figure options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)
legend: A key-value object with legend options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.) A legend will be drawn automatically unless legend = (; show = false) is set.
facet: A key-value object with facet options that gets passed to the underlying AlgebraOfGraphics.draw call.
colorbar: A key-value object with colorbar options that gets passed to the underlying AlgebraOfGraphics.draw call. (Does not apply when plotting into an existing figure.)

bins = 15: Number of histogram bins.
link_histograms = false: If true, uses the same histogram bins in each facet, with limits encompassing all data.

Supported Style Keywords

color
strokecolor
strokewidth

Parameters by group

parameters_vs_group(results; parameter = :auclast)

NCA.parameters_vs_group — Function

parameters_vs_group(report_df)
parameters_vs_group(figpos, report_df)

Keywords

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

Supported Style Keywords

color
markersize

Dose linearity

sad = dataset("po_sad_1")
sad_results = run_nca(read_nca_pumas(sad; concentration = :dv, dose = :amt))
model = DoseLinearityPowerModel(sad_results, :cmax)

power_model(model)

dose_vs_dose_normalized(sad_results, :cmax)

NCA.power_model — Function

power_model(dose_linearity_powermodel)
power_model(figpos, dose_linearity_powermodel)

Keywords

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

Supported Style Keywords

color
markersize
markercolor
strokewidth
geomean_markersize
geomean_marker
geomean_strokecolor
geomean_strokewidth
geomean_markercolor
geomean_linestyle
geomean_color
band_color

NCA.dose_vs_dose_normalized — Function

dose_vs_dose_normalized(report_df, variable)
dose_vs_dose_normalized(figpos, report_df, variable)

Regress variable, normalized to the highest dose, on the dose column of report_df.

Arguments

report_df: The output of run_nca, with a dose column.
variable: The endpoint column to plot, e.g. :cmax.

Keywords

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

Supported Style Keywords

color
markersize
strokecolor
bandcolor
strokewidth