plot¶

Plot one timecourse or every timecourse of a batch.

With by the curves are colored by group: every sample carrying the same value of the coordinate gets the same color and the group contributes one legend entry, instead of one color and one entry per sample. With facet the batch is split into one panel per value of a coordinate, the colors staying the same across the panels. A legend of more than max_legend entries is left out, since it would cover the figure rather than explain it.

A single curve whose protocol has more than one dose also gets one thin dotted vertical line per dose time (style.dose_color) and, for an infusion, the window from the dose time to the end of the infusion as a shaded span; a batch draws no dose markers, since its curves may carry different protocols (plot_mean_timecourse draws them for the group).

Parameters:

Other Parameters:

Returns:

Raises:

The mean curve of every group with its spread, on a linear and a semi-log panel.

The concentration-time figure of a study report: the arithmetic mean of the samples at every time point, the band \(\bar c \pm s\) of its spread around it and, faint behind both, the individual curves. With by the batch is split into groups (a dose level, a treatment, an arm) and every group gets its own color; without it the whole batch is one group. The reduction is Timecourses.groupby and Timecourses.mean, so the spread is the scatter of the curves and not an uncertainty carried by them.

Both panels show the same curves, the second one on a logarithmic value axis with plain tick labels, and only the first one carries the legend. The dose markers of the first group are drawn on every panel: a dotted line per dose of a protocol of several doses, an infusion as the shaded window from the dose time to the end of the infusion.

Parameters:

Other Parameters:

Returns:

Raises:

The nominal (scheduled) time of every point of a batch.

The variable nominal_time of the batch when it carries one (Timecourses.from_arrays(nominal_time=...), Timecourses.from_dataframe(nominal_time=...)), else the nearest entry of nominal_times for every actual time, else the actual times themselves, which is the right answer for data recorded on its schedule (a simulation, a mean curve of a publication).

Parameters:

Returns:

A copy of the batch whose samples sit on the shared grid of their nominal times.

Every point moves from the time it was taken at to the time it was scheduled for, and the batch gets the sorted union of those times as its grid: the samples of a study then share their time points and can be averaged, which is what the mean profile of a study report is taken on (ICH M13A 2.2.2.1). Two points of one sample with the same nominal time would land on the same place; the later one wins.

Parameters:

Returns:

The concentration-time figures of a study report, individuals and means.

ICH M13A (2024, 2.2.2.1) asks for the concentration-time profile of every subject on a linear and on a semi-logarithmic scale, and for the mean profile of every treatment on both scales as well, the individual figures drawn against the actual sampling times and the mean figures against the nominal ones: a mean over the subjects only exists on the schedule the study sampled by. This function draws the four panels in one call, the individual curves with plot_timecourse in the first row and the mean curves with plot_mean_timecourse (mean, spread band and the individuals behind it) in the second. A group keeps its color and its name over all four panels: the legend of the individual row is drawn from the same group labels as the one of the mean row (50 mg, which there carries the number of subjects behind the mean as well).

The nominal times come from the variable nominal_time of the batch when it carries one, else from nominal_times by nearest neighbour, else the actual times are taken as nominal, which is the right answer for data recorded on its schedule (nominal_grid, on_nominal_times).

Parameters:

Other Parameters:

Returns:

Raises:

The rows of the parameter table of plot_nca.

Parameters:

Returns:

The interval of a named partial area in the times of an NCA panel.

The intervals of NCAOptions.partial_aucs are relative to the first dose of the protocol, while a panel starts at the dose it analyses (the last one of a multiple dose curve): the interval is shifted by the time between the two doses, so that a named area of a multiple dose curve lands where the analysis computed it.

Parameters:

Returns:

Raises:

Draw the NCA diagnostics of one curve into one axes.

The panel shows the data with their spread, the area to \(t_\mathrm{last}\) (AUC(0-tlast)) or over the last dosing interval (AUC(0-tau) of a multiple dose result), the extrapolated tail, the terminal regression line with the points it used and its confidence band (_terminal_band), the peak \(C_\mathrm{max}\)/\(t_\mathrm{max}\) with its guide lines, \(C_0\) of a bolus, the named partial area partial over the area to \(t_\mathrm{last}\), and the dose it analyses (an infusion as its window). With annotate the areas, the peak, the last point, \(C_0\) and the regression carry their values on the plot, the interval of the half-life from the uncertainty analysis (thalf_ci_low/thalf_ci_high) or from the regression (_thalf_interval); the table of every parameter is the third panel of plot_nca.

The panel starts at the dose it analyses (the last one of a multiple dose curve), so only that dose falls inside it and the earlier doses of a protocol are not marked.

Parameters:

Other Parameters:

Returns:

Raises:

Linear and logarithmic panel of one curve with its NCA diagnostics and its parameters.

Both panels show the same curve (draw_nca_panel): the title of the figure names the sample and its flags once, the two panels name the scale they draw it on (linear, semi-logarithmic), and the legend is drawn once, on the linear panel. A third, narrow panel lists the parameters with their values, units and, where the result carries one, the interval of the uncertainty analysis (x_ci_low/x_ci_high; the half-life falls back to the interval of the regression), so that the figure reads as the report of the analysis. axes of the caller take two entries for the two curve panels alone, or three with the table.

Parameters:

Other Parameters:

Returns:

The candidate windows of the terminal regression next to the chosen one.

The selection of the terminal phase is the judgement call a reviewer questions, and every interactive tool shows it (the Slopes Selector of Phoenix WinNonlin, the "Check lambda_z" tab of PKanalix). The figure has two panels: the curve on a logarithmic value axis with the regression line, the points it used and the chosen window between two dashed lines (draw_nca_panel), and the adjusted \(R^2\) of every candidate window against the time its first point was taken at, the chosen window marked and the number of points of every window written above its marker. A window starting later has fewer points, so the second panel reads from left (many points) to right (three): where the curve is flat over several windows the choice hardly matters, where it drops the terminal phase is where the last points sit.

The result must carry the candidate windows, which the analysis keeps only when it is asked for them and only for a single curve:

# not executed
options = NCAOptions(terminal=TerminalPhase(keep_candidates=True))
result = nca_single(tc, options=options)
fig = plot_terminal_windows(tc, result, options=options)

Parameters:

Other Parameters:

Returns:

Raises:

One NCA panel per sample of a batch, with one legend for the figure.

The title of a panel names the sample by its coordinates, dose = 50 mg, individual = s1, with the unit of a coordinate which carries one; the dose coordinate of a batch takes the dose unit of the batch. The panels all draw the same artists, so the legend is drawn once: on the figure when this function creates it, and into the first panel when the caller supplies axes, whose figure keeps its own layout.

Parameters:

Other Parameters:

Returns:

The trough concentration of every dosing interval, the figure of steady state.

The trough of an interval (interval_ctrough, the value at its end) and, when the analysis reports it, its minimum (interval_cmin) against the time the trough was taken (x="time", the end of the interval interval_end, which for a regular regimen is the time of the next dose) or against the interval number (x="interval"). Steady state is where the troughs stop rising.

Over a batch the samples are reduced to the mean of every interval with its spread as error bars, per group when by names a coordinate; a result of a single curve draws that curve's values. The title names the statistic of the markers and the dimension it was taken over (mean ± sd over individual), and stays empty where no reduction is drawn.

Parameters:

Other Parameters:

Returns:

Raises:

Plot a per-interval parameter against the dosing interval.

Without indexers, one line per sample of the result, labelled with the sample's coordinate values; with indexers selecting one sample, a single line. Non-finite values (an incomplete interval) are masked so the line breaks there instead of raising a matplotlib warning. The x axis carries the integer interval numbers only, never a fractional tick.

Parameters:

Other Parameters:

Returns:

Raises:

Plot the excretion rate curve of a urine analysis and the amount recovered.

The figure a mass balance study is read from: the excretion rate \(\dot A_k\) of every collection against the midpoint \(\bar t_k\) of its interval on a logarithmic axis, with the terminal regression \(e^{b - \lambda_z t}\) over its window, and the cumulative amount recovered against the end of every collection on a second axis, which flattens out as the excretion stops.

Parameters:

Other Parameters:

Returns:

Raises:

Plot the mean curve of a sparse design with its area and the Bailer error.

The mean of the animals sampled at every nominal time with the standard error \(s_j/\sqrt{n_j}\) of that mean as an error bar, auc_last shaded under the polygon the linear trapezoid rule integrates (from the first nominal time to the last measurable one, which is the window the estimator covers, pkpdutils.nca.sparse.area_window), and the estimate with its standard error and n_animals per time point written into the panel.

Parameters:

Other Parameters:

Returns:

Raises:

Data, fitted curve and weighted residuals of one sample.

The upper panel draws the data points (x_data, y_data, with error bars from sd_data when the fit had sd), the fitted curve on a fine grid between the smallest and the largest finite, plotted x (log-spaced when log_x; the curve is skipped when fewer than two points remain), and a title with the model name, the parameters (name = value +- se) and the flags of the sample. The lower panel draws the weighted residuals against x with a zero line.

The axes are labelled with the names the front end of the fit stored in attrs["x_name"] and attrs["y_name"] (time and the substance for a timecourse, the column names for a table), x and y without them.

Parameters:

Other Parameters:

Returns:

Predicted against observed values of every sample, with the identity line.

Parameters:

Other Parameters:

Returns:

Log-log exposure against dose with the power fit and the acceptance bounds.

The axes are labelled with the names the front end of the fit stored in attrs["x_name"] and attrs["y_name"] (the column names for fit_table), x and y without them.

Parameters:

Other Parameters:

Returns:

Bland-Altman plot of the predictions against the data of every sample.

The difference y_pred - y_data (the log ratio with log_ratio) against the mean of both per point, with the mean difference and the limits of agreement mean +- 1.96 sd as horizontal lines (Bland & Altman 1986).

log_ratio selects the statistic the figure shows and not only the scale of an axis, which is why it is not one of the log_x/log_y keywords of the other figures: it replaces the difference by the log ratio and draws the mean on a logarithmic axis.

Parameters:

Other Parameters:

Returns:

Strip and box plot of a parameter over a sample dimension, with the mean and its interval per group.

Every individual is a jittered point, every group a box plot, and the geometric mean (scale=LOG) or the arithmetic mean with the t interval of summarize at ci_level a marker with an error bar. The statistic is computed from every finite value of the group, whatever the axis: a group with a non-positive value has no geometric mean and gets the arithmetic mean instead, drawn with a marker of its own (logged at debug level).

With log_y=True the non-positive values are left out of both the strip and the box, which are drawn from the same values, since a logarithmic axis cannot show them; a group without a positive value keeps its tick and nothing else, and a marker whose mean is not positive is left out. Without a positive value in any group the axis stays linear and every value is drawn.

The legend names the marker of every statistic once for the figure (geometric mean [95 % CI], mean [...] with scale=Scale.LINEAR or for the groups which fall back to it); the groups themselves are the ticks of the x axis and stay out of it. It sits in the upper right corner in room made above the data (legend_above_data), so it covers no point, box or interval; the room is measured on the figure as laid out when the function returns.

Parameters:

Other Parameters:

Returns:

Raises:

Point estimates and intervals of ratios on a logarithmic axis, with limits and thresholds.

With annotate the rows carry their numbers, gmr [low, high], in a column to the right of the intervals, as the table of a bioequivalence report does; the axis is widened to hold the column.

Parameters:

Other Parameters:

Returns:

Raises:

Forest plot: the effect of every study with its interval, the pooled effects as diamonds.

The marker area of a study is proportional to its random effects weight. A LOG_RATIO analysis is shown as ratios on a logarithmic axis (exp=None or True); the other kinds stay on their scale.

With annotate the rows carry their numbers in a column to the right of the intervals, as a published forest plot does: estimate [low, high] and, for a study, the random effects weight in percent; the axis is widened to hold the column.

Parameters:

Other Parameters:

Returns: