API

QSPAtlas — Module
QSPAtlas

Reproduce, score and benchmark published PK/PD and QSP models.

Each model lives in models/<author_year>/ and is reproduced by its reproduce.jl, which compares simulations against points digitised from the paper's figures and grades the result A-D (see grade).

source
QSPAtlas.Axis — Type
Axis(label, unit, scale, lo, hi)

One plot axis of a published figure. scale is :linear or :log; lo and hi are the axis limits as drawn in the figure. They set the scale used for comparison, so an error of 0.01 means one percent of the drawn axis.

source
QSPAtlas.ReferenceCurve — Type
ReferenceCurve

Points digitised from one curve of one published figure panel.

Fields: id (unique within the model, e.g. fig4_left_vehicle_P), figure (human description, e.g. "Figure 4 left, vehicle, tumour volume P"), x, y, xaxis, yaxis (Axis), kind (:curve for a line drawn by the authors' simulation, :points for plotted observations, :bars for bar heights or reported single values at category positions, :band for a shaded interval such as the authors' simulated 5th to 95th percentile band), meta (all other header keys, for example source and method), and ylo, yhi (lower and upper edge at each x; only for :band, empty otherwise). For a band, y is the midpoint (ylo + yhi) / 2, which is only used for plotting and the point count.

The eight-argument constructor (without ylo, yhi) is kept for every other kind.

source
QSPAtlas.load_reference — Function
load_reference(path) -> ReferenceCurve

Read a reference CSV. The file starts with # key: value header lines and then has a two-column x,y table. Required keys: id, figure, x, y. Optional: kind (curve, points, bars or band, default curve) and anything else, kept in meta. A # kind: band file has three columns x,lo,hi instead (a shaded interval, lower and upper edge at each x); the reference's y is then the midpoint of lo and hi. A curve may carry # metric: vertical (default nearest): compared by vertical distance at the reference x, as for bands (see compare_curve); use it for simulated percentile lines.

# id: fig4_left_vehicle_P
# figure: Figure 4 left, vehicle, tumour volume P
# x: time [day] linear 0 60
# y: tumour volume [mm^3] linear 0 2500
# kind: curve
# source: PSP4-4-660-g004.jpg (PMC4716582)
# method: colour mask, see digitise.toml
x,y
0.0,150.2
...
source
QSPAtlas.Tolerance — Type
Tolerance(; rms = 0.015, p95 = 0.03)

Pass rule for one curve. Errors are distances in the figure's own axis box, where both axes are scaled to [0, 1] (log axes in decades). rms bounds the root mean square distance over all reference points and p95 bounds the 95th percentile, so one badly traced point cannot fail a curve on its own. The maximum is still reported.

The defaults rest on a measured digitising error study (tools/digitise/error_study/): twice the worst panel type's 99th percentile of digitising-only error gives RMS 0.015 and P95 0.031 (the atlas keeps 0.03). Panels are 85 to 294 px, so the tolerance is roughly 1.3 to 3.5 px vertically. See docs/src/method.md and the sensitivity tables. Tolerances are frozen in each model's protocol.jl before its simulations are compared.

source
QSPAtlas.CurveComparison — Type
CurveComparison

Result of comparing one simulated curve with one reference curve: per-point distances d (axis-box units), their rms, p95 and max, the tolerance used and whether it passed.

source
QSPAtlas.compare_curve — Function
compare_curve(ref, xs, ys; tolerance = Tolerance()) -> CurveComparison

Compare a simulated curve (xs, ys) against ref.

For kind = :curve references (lines drawn by the authors' own simulation), each reference point's error is its shortest distance to the simulated polyline in the normalised axis box. Using distance-to-curve instead of vertical error keeps steep sections (dose spikes, rapid expansion) from being punished for tiny horizontal digitising error.

For kind = :points references (observed data), the same distance is used; the tolerance should then be loosened by the caller, since a typical-value curve is not expected to pass through every observation.

For kind = :bars references (bar charts, tornado plots, single reported values), x is a category position, not a continuous coordinate. The simulation must supply a value at exactly each reference x (matched within 1e-9), and the error is the vertical distance only, so a bar can never be matched by a neighbouring bar. A missing or non-finite simulated bar counts as the maximum error (1.0), never as a pass.

For kind = :band references (a shaded interval, e.g. the authors' simulated percentile band) and for kind = :curve references with the header # metric: vertical (stored as meta["metric"]; percentile lines of a population simulation) the comparison is VERTICAL at the reference x, not by nearest-polyline distance. The simulated curve is evaluated at each reference x: a finite simulated point at exactly that x (within 1e-9 of the normalised axis) is used as it is, otherwise the value is interpolated between the two neighbouring finite points, linearly in the displayed coordinates (decades on a log axis, x and y). Only then is the error taken: for a band 0 inside [ylo, yhi] (edges inside) and else the distance to the nearest edge, for a vertical line the distance to the reference y, in normalised axis units, capped at 1. A reference x outside the simulated range, or in a gap of non-finite simulated points (gaps are never bridged), counts as the maximum error 1.0. Simulated x must be sorted; one finite point is enough when it matches. For a band the default Tolerance is the allowance for digitising its edges.

Each point's error is capped at 1.0 (one full axis box), so a simulation that leaves the figure is scored as far off rather than infinitely off; the cap is applied to the distance, never to the simulated points.

source
QSPAtlas.CurveDiagnostics — Type
CurveDiagnostics

Report-only checks of one scored curve (none of them changes passed or any grade). All distances are in axis-box units, like CurveComparison. NaN (and 0 for the counts) means "does not apply" or "nothing to measure".

  • coverage: span of the digitised reference x values divided by the axis x range (both in the displayed coordinate, so decades on a log axis), clamped to [0, 1]. A reference that covers 40 % of the axis only constrains the simulation there. n_points is the number of reference points.
  • sim_coverage: fraction of the axis x range on which the simulated curve is defined, i.e. the union of the segments between neighbouring simulated points that are both finite and placeable on the axes (a gap of non-finite points is not bridged), clipped to the axis.
  • rev_rms, rev_p95, rev_n (kind = :curve only): the reverse distance. For every simulated point that is placeable and whose x lies inside the reference's x range, the shortest distance to the reference polyline (reference points in file order), capped at 1 like the forward error. This is the other side of the two-sided check: a simulation that wanders away from the reference where the reference has no points shows up here but not in the forward distance. It is measured at simulated points, so a sparse reference polyline can inflate it on strongly curved sections. rev_n is the number of simulated points used.
  • band_centre_dev_rms, band_n (kind = :band only): root mean square over the reference x, where the simulation is defined, of |s - centre| / half_width: how far the simulated value s (interpolated as for the band score) is from the band centre, in units of the band half-width, in the displayed coordinate. 1 is the band edge; the band score is 0 anywhere up to 1, so this separates "inside but off-centre" from "on the centre line". Reference x with a zero half-width are left out. band_n counts the reference x where the simulation is defined.
  • band_edge_rms, band_edge_max (only when the model passed simulated interval edges, see curve_diagnostics): distance of the simulated lower edge to the reference lower edge and of the simulated upper edge to the reference upper edge at every reference x where both are defined, capped at 1; root mean square and maximum over both edges.
source
QSPAtlas.curve_diagnostics — Function
curve_diagnostics(ref, xs, ys; sim_edges = nothing) -> CurveDiagnostics

Report-only checks of a simulated curve (xs, ys) against ref (see CurveDiagnostics): coverage of the reference and of the simulation, the reverse distance for :curve references, and the distance from the band centre for :band references. Nothing here is used for pass/fail.

sim_edges = (lo = ..., hi = ...) is optional and only read for :band references: the model's own simulated interval edges (for example the lo and hi of a VPC) at the simulated xs, vectors of the same length as xs. They are compared with the reference edges at the reference x (same interpolation and gap rules as the band score) and reported as band_edge_rms and band_edge_max. run_curves passes them on when the model's function returns (x, y, (lo = lo, hi = hi)).

source
QSPAtlas.Fix — Type
Fix(id, kind, description; evidence, basis, stage, figures = String[])

A documented choice needed to run or match a model. Fields:

  • kind: :typo (equation or value misprinted), :missing (value or rule not stated), :units (unit inconsistency), :ambiguity (text allows several readings; the one used is stated), :code (taken from supplementary code where the text differs), or :from_target (an unstated input read from, or chosen by matching, the very figure being reproduced).
  • basis: where the value comes from. :paper (another part of the article or its tables), :supplement (the article's supplementary material or code), :reference (a source the article cites), :standard (a standard physical or physiological value, e.g. a molecular weight or a blood volume), :interpretation (a reading of ambiguous text), :assumption (a value chosen where the paper gives none or only a range or bound, e.g. a midpoint), :figure (the figure being reproduced). :unspecified is the default and is treated as outside the paper by the strict rule.
  • stage: :before_comparison or :after_comparison, i.e. whether the choice was made before or after the simulation was first compared with the target. Choices made after comparison are reported as such.
  • evidence: where a reader can check the value. A fix without evidence cannot earn B.
  • figures: the figures the fix applies to (e.g. ["fig6"]); empty means all. It only affects the per-figure grades.

Fixes listed in the published run are gap fills that run needs even before any correction; a published run with fills can never be graded A.

:from_target fixes are circular for the values they set: a grade that depends on one is marked with a dagger (B†). Only use them for protocol inputs (initial conditions, which of several published scenarios a figure shows), never for model parameters; a model whose parameters must be read off its own figure is D.

source
QSPAtlas.CurveResult — Type
CurveResult(ref, x, y, comparison; sim_edges = nothing)

A simulated curve together with its reference, its comparison (which decides pass/fail) and its CurveDiagnostics (report-only: coverage, reverse distance, band centre and edge deviations). sim_edges is the optional (lo = ..., hi = ...) of curve_diagnostics.

source
QSPAtlas.Run — Type
Run

One attempt at reproducing the figures: label ("as published" or "with fixes"), fixes applied, curves, and error (empty if the model ran).

source
QSPAtlas.run_curves — Function
run_curves(f, refs, label; fixes = Fix[], tolerance = Tolerance(), tolerances = Dict())

Build a Run. f(ref) must return simulated (x, y) vectors for reference curve ref; it is called once per reference. tolerances can override the tolerance per curve id. A NotRunnable thrown inside f is recorded as the run error (the published information does not suffice to run the model); any other exception propagates, so a coding error is never mistaken for a gap in the paper.

f(ref) may return a third element (lo = ..., hi = ...), the model's own simulated interval edges at the returned x (for a band reference, e.g. the lo and hi of a vpc). They are compared with the reference edges as a report-only metric (band_edge_rms, band_edge_max in CurveDiagnostics); the band score and the grade do not use them. Every curve's diagnostics (coverage, reverse distance, band centre) are computed here and stored by write_score; none of them changes pass/fail.

source
QSPAtlas.Reproduction — Type
Reproduction

Everything known about one model's reproduction: id, citation, doi, pmcid, the published run (model exactly as printed), an optional fixed run (after documented Fixes), and blocker (why the model cannot run from published information, for grade D; empty otherwise).

source
QSPAtlas.grade — Function
grade(r::Reproduction) -> Char
  • 'A': the model as published runs and matches every reference curve.
  • 'B': it matches only after the documented fixes, each with evidence.
  • 'C': it runs but does not match, with or without fixes.
  • 'D': it cannot be run from published information (blocker set, or no run completed).

Recalibration never changes the grade: grades describe the published model, and refitted results are reported separately.

source
QSPAtlas.write_score — Function
write_score(path, r::Reproduction)

Write score.toml with the grade and per-curve metrics. The docs site and the test suite read this file. Besides rms, p95, max and passed each curve carries the report-only checks of CurveDiagnostics: coverage, sim_coverage, rev_rms, rev_p95, rev_n (:curve references), band_centre_dev_rms, band_n, band_edge_rms, band_edge_max (:band references; the edge fields only when the model passed simulated edges). They do not enter the grade.

source
QSPAtlas.bolus_callback — Function
bolus_callback(sys, state, times, amounts)

Callback that adds amounts[i] (or a scalar amount) to state at each of times. state is a symbolic unknown of the compiled system sys, for example sys.depot. Use it for IV bolus or for oral doses into a depot compartment.

A dose at the initial time is applied by the callback too, so leave the initial condition of state at its pre-dose value. Doses at the same time all apply (they add up).

source
QSPAtlas.repeated_doses — Function
repeated_doses(start, interval, n) -> Vector{Float64}

Dose times start, start + interval, ... (n doses).

source
QSPAtlas.plot_reproduction — Function
plot_reproduction(r::Reproduction, path; run = :best, ncols = 3)

Save a figure with one panel per reference curve: digitised reference points as dots, the simulation as a line, and the pass/fail metrics in the panel title. run picks :published, :fixed, or :best (fixed if present, else published).

source
QSPAtlas.BenchmarkSetup — Type
BenchmarkSetup(prob; name = "", callback = nothing, saveat = nothing)

What a model exposes for solver benchmarking: the ODEProblem used in its reproduction, any dosing callback, and the saveat grid the figures need. Each model's protocol.jl defines benchmark_setups() returning a vector of these.

source
QSPAtlas.benchmark_problem — Function
benchmark_problem(setup, solvers; reference_alg = nothing, reference = nothing, abstols, reltols, numruns = 10, kwargs...)

Work-precision set for one model problem. Solves a reference with reference_alg at abstol = reltol = 1e-12 (or uses reference, a solution computed that way beforehand), then times every solver in solvers (DiffEqDevTools format, e.g. [Dict(:alg => Tsit5())]) across the tolerance grid.

Error is the dense L2 error (error_estimate = :L2, dense_errors = true): both solutions are compared through their interpolants over the whole time span. Sparse errors at saved points are wrong for dosed models, because a dosing callback saves each dose time twice (before and after the jump) and the comparison then measures the dose size instead of the solver error. saveat is therefore not passed to the timed solves; timings include dense output.

source

Population simulation

QSPAtlas.Route — Type
Route(cmt, state; rate = nothing, scale = 1.0)

Map a dose compartment name cmt to the model. state is the unknown of the compiled system that receives bolus amounts (for example sys.A1). rate is the declared parameter that receives infusion rates, used in the model as D(A1) ~ ... + Rin; leave it nothing for bolus-only routes. scale converts dose units to model units: model amount = scale * dose amount.

source
QSPAtlas.Dose — Type
Dose(time, amt; cmt, rate = 0.0, duration = 0.0, ss = false, ii = 0.0)

One dosing event as entered. With rate = duration = 0 it is a bolus. Give rate for a zero-order infusion of fixed rate (duration = amt / rate), or duration for an infusion of fixed duration (rate = amt / duration). If both are given they must agree. amt must be non-negative; a zero amount is kept as a zero bolus (except for a constant infusion, below).

rate = :model (NONMEM RATE=-1) takes the infusion rate from the subject's DoseControl (rate entry of the compartment), duration = :model (RATE=-2) takes the duration from it (duration entry); the dose is then an infusion with that rate or duration. A dose that needs a modelled value its DoseControl does not have is an error when it is resolved.

The field fixed records which of the two was entered (:rate, :duration, :model_rate, :model_duration, or :none for a bolus), because bioavailability acts differently on each (see DoseControl).

ss is the NONMEM SS item: false/0 an ordinary dose, true/1 (SS=1) the subject is at steady state on this dose repeated every ii when it is given (the state is replaced by the steady state), 2 (SS=2) the steady state of this dose alone is added to the current state. A steady-state dose needs ii > 0 and amt > 0, except a constant infusion at steady state (NONMEM AMT=0, RATE>0, SS=1 or 2): amt = 0 with rate > 0 (or rate = :model) and ii = 0, an infusion that has been running since time minus infinity and ENDS at time (NONMEM convention; stored with duration = Inf). For a non-steady-state dose ii is ignored and stored as 0. The field ss holds 0, 1 or 2.

source
QSPAtlas.Regimen — Type
Regimen(amt; time = 0.0, cmt, ii = 0.0, addl = 0, rate = 0.0, duration = 0.0, ss = false, reset = false)
Regimen(r1, r2, ...)       # Regimens and Resets
vcat(r1, r2, ...)

NONMEM-style dose record: amt at time, then addl more doses every ii. rate and duration make it an infusion, see Dose. Several regimens combine into one, sorted by dose time (doses at equal times keep their order). Get the dose list with doses. rate = :model / duration = :model take the rate / duration from the subject's DoseControl (NONMEM RATE=-1 / -2).

  • ss = true or ss = 1 (NONMEM SS=1, needs ii > 0): the FIRST dose of the record is a steady-state dose. The subject is taken to have received this dose every ii for a very long time (the state at time is the periodic state of the cycle simulated from the initial conditions), including lagged doses and infusions that are still running; the addl doses then follow as ordinary doses. A regimen can hold several SS=1 doses only if they share time and ii (they form one periodic cycle). The record resets the state at time (see below); everything the regimen did before time is superseded at time, and the addl doses of earlier records that are still to come are cancelled (NONMEM: an SS=1 dose cancels pending additional doses), even those whose nominal time is after time.
  • ss = 2 (NONMEM SS=2): the steady state of this dose alone is ADDED to the state at time instead of replacing it; nothing given before is cancelled. The added amount is the periodic state of the dose minus the periodic state without it (both from the initial conditions), so a baseline of the model is not counted twice. This is exact for linear models and an approximation otherwise (as in NONMEM, which assumes linear kinetics for SS=2). Each SS=2 record is its own steady state; it may be at any time and have its own ii.
  • Constant infusion at steady state (NONMEM AMT=0, RATE>0, SS=1 or 2): Regimen(0.0; rate = R, ss = true) with ii = 0 and no addl. The state at time is the equilibrium under the infusion, and the infusion ENDS at time, as in NONMEM (the record marks the end of an infusion that started at minus infinity). To keep it running, add an ordinary infusion from time (for example Regimen(R * 100; time, rate = R, cmt) for 100 time units). Bioavailability does not apply to it (NONMEM) and lag has no effect on it.
  • reset = true (EVID=4, reset and dose): a Reset at time, then the doses. Regimen(Reset(t)) is a pure reset (EVID=3), also usable inside Regimen(r1, Reset(t), r2).
  • A reset at the time of a dose applies BEFORE that dose, and the dose (with its lag) is kept. A reset cancels doses given before it that have not entered the model yet (lag lands at or after the reset time) and stops infusions that are running (the rest of their amount is never given). Steady-state doses are not allowed to combine with reset = true.
source
QSPAtlas.DoseControl — Type
DoseControl(; bioav = Dict(), lag = Dict(), rate = Dict(), duration = Dict())

Subject-specific dose control, per compartment name (Dict(:depot => 0.8)). Missing entries mean bioav = 1, lag = 0. Values that depend on random effects, covariates or the occasion come from the model instead (PopulationModel(...; dosecontrol), evaluated per dose).

  • bioav (F): scales bolus amounts. For an infusion entered with a rate, F scales the duration and keeps the rate (NONMEM and Pumas convention). For an infusion entered with a duration, F scales the rate and keeps the duration. Either way the infused amount is F * amt.
  • lag: delays the start of every dose in that compartment (an infusion keeps its length).
  • rate, duration: the modelled infusion rate (NONMEM R1, R2, ...) and duration (D1, ...) used by doses with rate = :model and duration = :model (NONMEM RATE=-1 and -2). A modelled rate acts like an entered rate (F scales the duration), a modelled duration like an entered duration (F scales the rate).
source
QSPAtlas.DoseEvent — Type
DoseEvent(time, kind, cmt, amount, rate)

One resolved solver event: kind is :bolus, :infusion_start or :infusion_stop. Times are after lag; amount (bolus) and rate (infusion) are in model units, after F and the route scale. Infusion events have amount = 0, bolus events rate = 0.

Two more kinds set the whole state (cmt is :all, amount and rate are 0): :reset sets every state back to its value when the solve started (the initial conditions), and :steady_state sets every state to the vector in the sixth field state (the steady state; resolve leaves it nothing and the simulation fills it in per subject). The state is set first, then the other events of the same time apply on top of it. A third kind, :steady_state_add (SS=2), adds the vector in state to the current state, after any set at the same time and before the doses.

source
QSPAtlas.doses — Function
doses(r::Regimen) -> Vector{Dose}

The expanded dose list of a regimen, sorted by time.

source
QSPAtlas.resolve — Function
resolve(regimen, routes, control = DoseControl()) -> Vector{DoseEvent}

Turn a regimen into the events the solver needs, for one subject: lag shifts every start, bioavailability scales amounts (see DoseControl), the route scale converts to model units, and an infusion becomes a start and a stop event. control is a DoseControl for every dose, or a function (dose, record_time) -> DoseControl giving each dose its own, where record_time is the time of the record the dose comes from (for addl doses the time of their record, so they share its values; a steady-state dose's value applies to its whole periodic history). The result is sorted by time. At the same time infusion stops come first, then infusion starts, then boluses; all boluses at one time are kept (they add up). An infusion whose stop time equals its start time in floating point (duration lost next to the dose time) is an error, not silently dropped.

Resets (Reset, reset = true) become :reset events, sorted before all other events of the same time. A dose is cancelled if a reset comes after the time it was GIVEN but not after it ENTERS the model: a bolus (or infusion start) whose lagged time is at or after the first reset later than the dose time is dropped; an infusion that is running at that reset is stopped there. A dose given at the reset time itself is after the reset and kept.

A steady-state dose (ss = true) becomes a :steady_state event at its time (state still nothing: it depends on the model and the subject, see simulate), which acts as a reset at that time for everything given before: doses of earlier records that land at or after it, including the addl doses of an earlier record whose nominal time is at or after it (NONMEM cancels pending additional doses; the time of the record decides, not the time of each addl dose), are dropped, and running infusions are stopped there. For the doses of the periodic history that are still pending at that time it adds the events they cause from there on: boluses whose lagged time is at or after the steady-state time, and infusions that are still running (switched on at the steady-state time, stopped at their original stop time). Those carried events follow the same rules for later resets as ordinary doses. An SS=2 dose becomes a :steady_state_add event (one per SS=2 dose, in time order) plus the pending events of its own periodic history; it cancels nothing. A constant infusion at steady state leaves no event after its time (it ends there, NONMEM convention); its effect is the steady state alone.

source
QSPAtlas.dosing_callback — Function
dosing_callback(sys, events, routes) -> (callback, tstops)

Callback for an ODEProblem built from the compiled system sys, applying the resolved events. A bolus adds its amount to the route's state. For infusions the route's rate parameter is set at every start or stop to baseline + sum of the rates of the infusions running now, recomputed from scratch, where baseline is the parameter value found when the solve started. So overlapping infusions sum, there is no accumulated rounding, and the parameter is restored to the baseline exactly when the solve ends (also mid-infusion), which leaves sol.prob as found. The per-solve baseline is kept per integrator, so one callback object can be used by many solves at once (for example EnsembleThreads) and for different tspans.

:reset and :steady_state events set all states (in the order of unknowns(sys)) before the other events of their time: a reset to the state the solve started with, a steady state to the vector stored in the event. :steady_state_add events (SS=2) then add their vectors. They do nothing about infusions or pending doses: those are cancelled when the events are produced by resolve.

Events are grouped only when their times are exactly equal; times a rounding error apart stay separate events. An infusion is on for start <= t < stop. Events at the initial time are applied before the first step; events before it are ignored, except that an infusion already running at the initial time is on. Events after the end of tspan are never reached; an event exactly at the end fires. Pass callback (and tstops) to ODEProblem or solve. tstops lists the event times; the callback schedules them too.

source
QSPAtlas.Reset — Type
Reset(time)

Reset event (NONMEM EVID=3): at time every state goes back to its initial condition, running infusions are cancelled and doses that are still pending (lagged, not yet in the model) are cancelled. Combine with doses through Regimen.

source
QSPAtlas.steady_state_cycle — Function
steady_state_cycle(regimen, routes, control = DoseControl()) -> nothing or (T, ii, events)

The periodic cycle behind the SS=1 steady-state dose, for the state iteration: T and ii of the steady-state record, and the events (boluses, infusion starts and stops, ordered like resolve) of the cycle [T, T + ii) of the infinitely repeated record: every dose of the periodic history whose lagged time falls in the cycle, plus the infusions of earlier doses that are running at T (switched on at T). So lag larger than ii wraps into the cycle and an infusion longer than ii overlaps itself. For a constant infusion at steady state ii is 0 and the events are the infusion switched on at T. Returns nothing if the regimen has no SS=1 dose (SS=2 doses are not covered here).

source
QSPAtlas.with_steady_state — Function
with_steady_state(events, state) -> Vector{DoseEvent}

The events with state (a vector in the order of the system's unknowns) filled into the :steady_state event.

source
QSPAtlas.SteadyStateOptions — Type
SteadyStateOptions(; rtol = 1e-8, atol = 1e-10, maxcycles = 1000, allow_time_dependent = false)

Convergence control for steady-state doses (ss = true). The state at the start of a dosing interval is found by simulating cycle after cycle (length ii, same model, parameters, F and lag) from the initial conditions. It has converged when, for EVERY state, the change over a cycle is at most atol + rtol * |x| (compared directly, so a state that stays exactly 0 is fine even with atol = 0). After maxcycles cycles without convergence, or if the state becomes non-finite or the solver fails in a cycle, SteadyStateError is thrown; a non-converged state is never used. The change over one cycle underestimates the distance to the steady state by about 1 / (1 - r) where r is the per-cycle contraction factor (a state that decays slowly compared to ii needs a tighter rtol or a higher maxcycles).

The cycle iteration restarts every cycle at the same absolute time T, so it is only valid for AUTONOMOUS dynamics (plus the dosing). If the compiled system depends explicitly on time (an exp(-δ t) or sin(t) in an equation or observed expression), a steady-state dose is refused with an ArgumentError. allow_time_dependent = true overrides that: the user asserts that the forcing is periodic with period ii (or a divisor of it) and phase-aligned with T.

source
QSPAtlas.NMData — Type
NMData

A NONMEM-style dataset read by read_nmdata.

  • subjects: one Subject per individual record, in dataset order, ready for simulate.
  • obs: one row per observation record (EVID 0), in record order: (id, time, endpoint, order, dv, row); endpoint is nothing when the record reports every endpoint, order is :pre or :post, dv is missing for ".", row the record number.
  • columns, values: the dataset as read (values[j][i] is column j of record i, missing for "." or empty), used by write_nmdata.
  • covariates: the covariate columns; covariate_rule: :nocb or :locf.
source
QSPAtlas.read_nmdata — Function
read_nmdata(source; cmt = Dict(), endpoints = nothing, covariates = nothing, drop = Symbol[],
            covariate_rule = :nocb, control = DoseControl(), occasion = nothing) -> NMData

Read a NONMEM-style dataset: a CSV file path (comma- or whitespace-separated, header first, "." or empty for missing), a vector of NamedTuples (one per record) or a NamedTuple of columns. Returns an NMData whose subjects keep the record order of the file.

Data items (upper or lower case): ID, TIME (required), EVID (0 observation, 1 dose, 2 other, 3 reset, 4 reset and dose), AMT, CMT, RATE (0 bolus, > 0 rate, -1 modelled rate, -2 modelled duration), SS (0, 1, 2), II, ADDL, MDV, DV. Without EVID it is derived as the NONMEM help describes: a record with AMT, RATE or SS nonzero is a dose (so is a steady-state infusion, AMT 0, RATE > 0, SS 1); any other record is an other-type record if MDV is 1, else an observation. Every other column is a covariate (numeric, never missing), unless listed in drop; with covariates given, any other column is an error. Unsupported items (PCMT, CALL, CONT, L1, L2, DATE, ...) and values (EVID > 4, SS = 3, a decreasing TIME, an observation with MDV = 1, an ID that reappears after another ID, ...) are errors, never ignored.

  • cmt: dose compartment of each CMT value, Dict(1 => :depot, 2 => :central). A text CMT without an entry is used as the route name itself; a number without one is an error.
  • endpoints: endpoint of each observation CMT value, Dict(2 => :conc), or :all to report every endpoint at every observation. Observations with CMT 0 or missing report every endpoint.
  • covariate_rule: :nocb (default, NONMEM: a record's covariate values apply over the interval ending at that record) or :locf (they apply from the record onward). Records at the same time must agree on every covariate.
  • control: a DoseControl, or a function (id, covariates) -> DoseControl (the baseline covariates), for bioavailability, lag and the modelled rates and durations that RATE = -1 / -2 need. Dose control that depends on random effects, on time-varying covariates or on the occasion belongs in the model (PopulationModel(...; dosecontrol)), which evaluates it on each dose record with that record's covariates.
  • occasion: the name of the occasion column (for example :OCC), for between-occasion variability. Its values are integer occasion labels, never missing; records at one time must agree. The occasion of a record follows covariate_rule like a covariate (under NOCB the occasion on a record applies over the interval ending at it), and a dose uses the occasion on its record. Without occasion an OCC column is an ordinary covariate.

Record order is kept: an observation record placed before a dose, reset or steady-state record at the same time sees the state before it (:pre), one placed after it the state after it. Doses implied by ADDL at the time of an observation record come before it. An observation between two such records at one time, a reset or SS=1 record after a dose record at the same time, and an observation before a dose record at a time where an ADDL dose also falls are errors.

source
QSPAtlas.write_nmdata — Function
write_nmdata(path, data::NMData; result = nothing, replicate = 1, value = :dv, endpoint = nothing)

Write the dataset as a comma-separated file with the original columns, "." for missing values. With a SimResult from simulating data.subjects, the DV column of every observation record is replaced by the simulated value (:dv or :ipred) of replicate replicate: record by record, matching each subject's observation records in order. Observation records that report every endpoint need endpoint to say which one goes into DV.

source
QSPAtlas.ErrorModel — Type
ErrorModel

Residual error model for one observed endpoint. sample_dv(err, ipred, rng) draws one observation given the individual prediction, always consuming exactly one standard normal draw from rng (also when σ = 0, or ipred is NaN), so that the stream stays aligned. sd(err, ipred) is the standard deviation of that observation given ipred.

  • AdditiveError(σ): dv = ipred + σ ε
  • ProportionalError(σ): dv = ipred (1 + σ ε)
  • CombinedError(σadd, σprop): dv = ipred + sqrt(σadd² + (σprop ipred)²) ε
  • ExponentialError(σ): dv = ipred exp(σ ε); median-centred (median dv = ipred, the mean is ipred exp(σ²/2)), always positive for positive ipred.
source
QSPAtlas.AdditiveError — Type
AdditiveError(σ)

Additive residual error: dv = ipred + σ ε, ε ~ N(0, 1). σ is a standard deviation.

source
QSPAtlas.Subject — Type
Subject(id; regimen, covariates = (;), obstimes, control = DoseControl(), timevarying = nothing,
        obsorder = nothing, endpoints = nothing, covariate_rule = :locf, occasions = nothing)

One individual: dosing regimen (with subject-specific control), baseline covariates (a NamedTuple) and observation times. timevarying lists piecewise-constant covariate changes as time => NamedTuple pairs, for example [10.0 => (WT = 90.0,)]; covariates not listed keep their previous value. How a change applies is set by covariate_rule:

  • :locf (last value carried forward, the default): the values hold from that time onward and override the baseline; an observation at that time sees the new values.
  • :nocb (next observation carried backward, the NONMEM convention for data records): the values hold over the interval ENDING at that time, (previous change, time], so an observation at that time still sees them and the next values start just after it. Before the first change the first change's values apply; after the last change its values remain.

occasions defines occasions for between-occasion variability (IOV, see PopulationModel): a vector of occasion start times (labelled 1, 2, ...) or of time => label pairs with integer labels. The times follow covariate_rule like timevarying: under :locf the occasion starts AT its time (an observation or a dose at that time is in the new occasion); under :nocb (datasets) the occasion listed at a time holds over the interval ending at that time. Before the first time the first occasion applies, after the last time the last one. A label that comes back (1, 2, 1) is the same occasion, with the same random effects. Without occasions the whole record is occasion 1.

obsorder tags each observation (same order as obstimes) :pre or :post: a :pre observation sees the state before the dose, reset and steady-state events at its time, a :post observation (the default) the state after them. Covariate values at that time follow covariate_rule either way. endpoints restricts each observation to one endpoint (a Symbol, or nothing for every endpoint, the default). Observations are stored sorted by time, :pre before :post at equal times, otherwise in the order given.

source
QSPAtlas.occasion_at — Function
occasion_at(subject, t) -> Int

Label of the occasion in force at time t, by the subject's covariate_rule (see Subject): under :locf the last occasion starting at or before t, under :nocb the first occasion listed at or after t. Before the first listed time the first occasion, after the last one the last occasion; 1 if the subject has no occasions.

source
QSPAtlas.PopulationModel — Type
PopulationModel(sys; routes, θ, ηnames, Ω, params, init = (θ, η, c) -> Pair[], observed,
                error, tspan, solver, solve_kwargs = (;), dosecontrol = nothing,
                κnames = Symbol[], Ω_IOV = zeros(0, 0))

A structural model sys (compiled MTK system) with typical values θ, between-subject random effects η ~ N(0, Ω) (names ηnames, covariance Ω in that order) and residual error. Individual values come from

  • params(θ, η, covariates) -> Vector{Pair} of MTK parameter values (η and covariates are NamedTuples),
  • init(θ, η, covariates) -> Vector{Pair} of initial conditions.

observed and error are NamedTuples keyed by endpoint name: symbolic observable (state or expression) and its ErrorModel. routes map dose compartments to states (see Route); their rate parameters must not be returned by params. The final field cache holds the lazily built base problem.

Time-varying covariates re-evaluate params at each change time and set the parameters whose value changed. Initial conditions are not re-applied, and only parameters that params returns are updated.

Dose control from the model. dosecontrol(θ, η, covariates) returns the bioavailability (F), lag (ALAG), modelled rate (R) and modelled duration (D) per dose compartment, as a DoseControl or a NamedTuple with any of the fields bioav, lag, rate, duration (each a Dict(compartment => value)), for example (θ, η, c) -> (bioav = Dict(:depot => θ.F * exp(η.F)), lag = Dict(:depot => θ.ALAG * exp(η.ALAG))). It is evaluated once per dose record, at the record's time (before lag): with the covariates in force at that time (for a dataset dose record, the values on that record) and the random effects of the trajectory (and of the record's occasion). The values stay with the dose: the addl doses of a record use the record's values, and a lagged dose or a running infusion keeps them when covariates or the occasion change later (NONMEM: "the value of ALAGn in effect at time T applies to the dose and to all subsequent additional doses"; mrgsolve does the same for F). A steady-state dose uses the values of its own record for its whole periodic history. The subject's own control is combined with it; the same entry (field and compartment) in both is an error.

Between-occasion variability (IOV). κnames and Ω_IOV declare a second random-effect vector κ ~ N(0, Ω_IOV), drawn independently for every occasion of every subject (occasions: see Subject). Then params, init and dosecontrol are called as f(θ, η, covariates, κ) with the κ of the occasion in force (init at the start of the solve, dosecontrol at the time of the dose record); a function with only a three-argument method is called without κ. Parameters are re-evaluated at every occasion change, like a covariate change. Ω_IOV is checked like Ω.

source
QSPAtlas.SimResult — Type
SimResult

Output of simulate, as tidy rows.

  • obs: one row per (replicate, subject, endpoint, observation time): (replicate, id, time, endpoint, ipred, dv, retcode). ipred is the individual prediction, dv the observation with residual error (equal to ipred when residual = false). If the solver stopped early (retcode is not :Success), the observations it never reached have ipred = dv = NaN; failed subjects are never dropped.
  • subjects: one row per (replicate, subject): (replicate, id, η, covariates, retcode). A cohort trajectory without a steady state has retcode = :SteadyStateFailed and an extra field message.
  • settings: seed, solver and tolerances, package versions.

An observation at the time of a dose or covariate change sees the state AFTER that event, unless the subject tags it :pre (see Subject); rows follow the subject's observation order (time, then :pre before :post), endpoint by endpoint, and an observation restricted to one endpoint gives a row for that endpoint only.

source
QSPAtlas.simulate — Function
simulate(model, subject; η = :sample, residual = true, rng = Xoshiro(0), tspan = nothing,
         steady_state = SteadyStateOptions(), κ = nothing) -> SimResult

Simulate one subject. η = :sample draws η ~ N(0, Ω) from rng, :zero uses η = 0 (the zero-random-effect prediction), or pass a NamedTuple / vector of η values. residual = false returns dv = ipred. The residual error uses its own stream, seeded from rng right after the η draw (so η does not depend on residual). tspan defaults to the model's, extended to the last observation time if needed.

Steady-state doses (ss = true or ss = 2, see Regimen) and resets are handled here: for a steady-state dose at time T the state at T is found per subject with that subject's parameters (covariates frozen at their value at T), by cycling from the subject's initial conditions as set by SteadyStateOptions; the solve then continues from that state with the infusions and pending doses of the periodic history switched on. The steady state uses the parameters, F and lag of the occasion in force at T. T must not be before the start of tspan (an error); a steady-state dose after the end is ignored. If there is no steady state, SteadyStateError is thrown by this single-subject method. (In a cohort the same failure is a per-trajectory outcome, see below.) A reset sets every state to the subject's initial condition at the start of the solve.

Between-occasion random effects (a model with κnames): κ = nothing (the default) samples them, or sets them to zero when η = :zero; :sample, :zero, one NamedTuple / vector for every occasion, or a Dict(occasion label => κ) can be given. Sampled κ of occasion j come from their own stream, seeded by one draw from rng taken after the residual seed (only for a model with IOV, so rng is used as before otherwise), and keyed by the occasion label, so they do not depend on the other occasions. The subject row then has a field κ (label => κ).

source
simulate(model, subjects; replicates = 1, seed = 0, η = :sample, residual = true,
         ensemble = EnsembleThreads(), tspan = nothing, steady_state = SteadyStateOptions(),
         κ = nothing) -> SimResult

Simulate a cohort. replicates is the number of times the whole cohort is re-simulated (new η and residual draws each time). Subject ids must be unique.

Reproducibility: every (replicate, subject id) has its own random streams, derived from seed, one for η and a separate one for the residual error. The results therefore do not depend on the number of threads, on ensemble, or on the order of subjects (the order of the output rows follows the cohort order). Between-occasion random effects (κ, as for one subject) are drawn from a third stream per (replicate, subject id, occasion label), so they do not depend on the other occasions either.

A trajectory whose steady-state dose has no steady state (SteadyStateError) does not abort the cohort: it is not solved, its subject row has retcode = :SteadyStateFailed and an extra field message, its observation rows have ipred = dv = NaN and the same retcode, and the usual single warning counts it. A malformed regimen or model (steady-state dose before tspan, explicit time dependence, unknown compartment, ...) still throws for the whole call.

source
QSPAtlas.zero_re_prediction — Function
zero_re_prediction(model, subject) -> SimResult

Prediction with all random effects (η and, with IOV, κ) at zero and no residual error. This is the typical-individual curve for the subject's covariates; it is generally not the population mean.

source
QSPAtlas.virtual_population — Function
virtual_population(n; regimen, obstimes, covariate_sampler = rng -> (;), seed = 0, control = DoseControl(),
                   occasions = nothing)

n subjects with ids "1", "2", ..., the same regimen, observation times and occasions (see Subject), and baseline covariates drawn by covariate_sampler(rng) (a NamedTuple). Subject i uses its own stream derived from seed and i, so adding subjects does not change earlier ones.

source
QSPAtlas.percentiles — Function
percentiles(r::SimResult, endpoint; q = (0.1, 0.5, 0.9), bins = :obstimes, value = :dv,
            by_replicate = false, min_n = 1, blq = nothing, max_failure_rate = 0.0,
            weighting = :observation, subject_value = :mean) -> Vector{NamedTuple}

Quantiles of one endpoint of a simulation, over subjects, per time bin.

Estimand: by default (weighting = :observation) the values of a bin are pooled, so a subject with several observations in a bin counts several times. This is the usual VPC and what the observed-data percentiles of a standard VPC do. With weighting = :subject each subject contributes one value per bin (and replicate), its subject_value = :mean, :first or :last (by time) of its values in the bin; n is then the number of subjects. With bins = :obstimes and a common sampling schedule the two are identical. A subject mean that includes any censored value is itself censored (it is unknown, whatever the placeholder of the censored value): with :censored it is ranked as censored below its own limit (the mean with the censored values at their limits), with :drop the subject is left out of that bin, with :censor_to_lloq and :keep its number is used and it counts in n_blq. With :first or :last the subject value is censored when the picked value is. n_failed and n_finite always count observations.

Rows (one per bin and q, ordered by bin then q; by replicate first when by_replicate): (bin, bin_lo, bin_hi, t_mid, q, value, n, n_failed, n_blq, n_finite, failure_rate, unreliable), plus replicate first when by_replicate = true. By default the replicates are pooled, so n counts subjects times replicates.

  • value: :dv (with residual error) or :ipred.
  • bins = :obstimes: one bin per distinct observation time, matched exactly (bin_lo == bin_hi == t_mid = the time). bins = edges (a strictly increasing vector): bins [e_k, e_{k+1}), half-open, except that the last bin also contains its upper edge; observations outside the edges are ignored; t_mid is the bin centre.
  • Quantile definition: Hyndman-Fan type 7 (Statistics.quantile's default; linear interpolation between order statistics).
  • Values that are not finite (failed solves leave NaN) are excluded and counted in n_failed; one warning reports the total. A bin with fewer than min_n usable values gives value = NaN (its n is still reported). The default min_n = 1 only rejects empty bins; quantile estimates from a handful of values are poor, raise it to be strict.
  • blq = (lloq = x, handling = :censor_to_lloq | :drop | :keep | :censored): values below lloq are set to lloq (default), removed (this biases quantiles upwards), or kept; n_blq counts the values below lloq in every case, n the values that were used. :censored is the censored-VPC convention: the values below lloq are kept as censored, each known only to lie below its limit (lloq, so below every quantified value), and a quantile that depends on a censored order statistic (the lower of the two neighbouring order statistics of the type 7 interpolation is censored) is NaN with below_lloq = true (an extra field of the rows in this mode), not a number. When the limits differ (subject means, or a prediction-corrected VPC) an order statistic is a number only when it is the same wherever the censored values lie below their own limits (QSPAtlas.censored_quantile_limits). The rows then also have limit: for a quantile below the limit, the largest value its lower order statistic can take (lloq with a common limit), NaN otherwise.
  • Failure gate: n_finite is the number of finite values of the bin (before any BLQ handling), failure_rate = n_failed / (n_failed + n_finite) (NaN for a bin without values); failure_rate gives the overall rate. max_failure_rate = 0 (the default) only reports. With max_failure_rate > 0, bins whose rate is above it get unreliable = true (and one warning); their value is not changed or removed, so a model decides what to do.
source
QSPAtlas.vpc — Function
vpc(model, subjects; endpoint, q = (0.1, 0.5, 0.9), bins = :obstimes, replicates = 200,
    pi_level = 0.95, seed = 0, value = :dv, blq = nothing, observed = nothing, min_n = 1,
    max_failure_rate = 0.0, weighting = :observation, subject_value = :mean,
    pc = false, variability_correction = false, strata = nothing,
    simulate_kwargs...) -> VPCResult or StratifiedVPC
vpc(r::SimResult; endpoint, ..., pred = nothing)

Simulation-based visual predictive check. The cohort subjects is simulated replicates times (simulate(model, subjects; replicates, seed, simulate_kwargs...), so it is reproducible from seed and independent of threads). In every replicate the q-quantile of endpoint is taken per bin over the subjects (percentiles with by_replicate: same bins, value, quantile definition, failed value handling, min_n and blq). Per bin and q the rows then give the median of those replicate quantiles, the pi_level interval across replicates (Hyndman-Fan type 7 quantiles of the K replicate values, at (1 - pi_level) / 2 and (1 + pi_level) / 2) and mc_se, the Monte Carlo standard error of that median (QSPAtlas.mc_se_median: bootstrap over the replicates, 500 resamples, generator seeded from seed and the bin, so it is reproducible and handles ties from BLQ censoring). mc_se shrinks like 1 / sqrt(replicates); the interval lo..hi does not shrink, it estimates the spread of the quantile for a cohort of this size. Only replicates with a defined quantile count (n_rep).

value = :dv includes the residual error, :ipred does not. For a population target freeze subjects, bins, value, replicates and seed before comparing with a reference, and keep mc_se small next to the tolerance.

observed is optional observed data, a vector of (id, time, dv) named tuples. It gives the observed quantiles per bin (pooled over subjects, same bins, min_n, blq), stored in VPCResult.observed. This is a diagnostic: nothing in the atlas is graded on it. With bins = :obstimes, observed times must equal simulated times exactly to be binned; the rest is counted in n_unbinned.

Failed or NaN simulated values are excluded and counted (n_failed, one warning). Each row gives the failure_rate of its bin; max_failure_rate > 0 marks bins above it unreliable (values unchanged; the default 0 only reports). mc_se is NaN (with one warning) when the bootstrap cannot estimate it from heavily tied replicate quantiles, see mc_se_median; mc_check tests mc_se against a tolerance.

Estimand: what is pooled

The binned percentiles pool observations. With weighting = :observation (the default) every value in a bin counts once, so a subject with more observations in a bin weighs more. That is the usual VPC (observed and simulated alike) and the right reading when the bins are narrow or the sampling is the same for everyone; with wide bins and unequal sampling (sparse or informative visit schedules) the percentile is of the pooled observations, not of subjects. weighting = :subject collapses each subject to one value per bin and replicate, its subject_value (:mean, :first or :last by time), so every subject weighs once (n counts subjects). Both observed and simulated values are treated the same way, so the comparison is like with like. With one observation per subject and bin the two are identical.

Censored VPC (blq)

Giving blq = (lloq = x, handling = ...) also computes, per bin, the fraction of values below lloq (VPCResult.blq_fraction): observed (pooled over observed values, or one per subject with weighting = :subject) and simulated (the fraction of each replicate, summarised by its median and the pi_level interval across replicates). With handling = :censored the quantiles follow the standard censored VPC: values below lloq are kept as censored, below every quantified value; a quantile whose interpolation touches a censored order statistic is not a number but NaN with below_lloq = true. The replicate quantiles are then summarised the same way (a replicate quantile below lloq is the lowest value): the median, lo or hi over replicates is NaN with its flag (below_lloq, lo_below, hi_below) when its rank falls among the censored replicates, and mc_se is computed with the censored replicate quantiles set to lloq (NaN when the median itself is below lloq). Observed values are censored when dv < lloq, or, if the observed rows have a blq field, when it is true (use it when below-limit records are stored at the limit). Censored values are flagged on the raw scale also in a prediction-corrected VPC; the correction then moves each record's limit with its value, to LLOQ * PRED_bin / PRED_ij (and through the variability correction), and a censored value is ranked only against its own limit, so a quantile is a number only when it does not depend on where any censored value lies below its limit (see percentiles; the same rule applies to subject means with weighting = :subject). The replicate quantiles below the limit are then summarised with their own bounds. M3 is an estimation method, not an option of the simulation, and is not part of this function.

Prediction-corrected VPC (pc = true)

Bergstrand et al. (2011, AAPS J 13:143) remove the part of the variability that comes from different doses, covariates or sampling times. Every observed and simulated value is normalised by the typical population prediction of its record (η and κ zero, no residual error: zero_re_prediction) relative to the median prediction of its bin:

pcY_ij = Y_ij * PRED_bin / PRED_ij

PRED_ij is the typical prediction of record j of subject i, PRED_bin the median of the predictions of the simulated design (each record once) in the bin of the observation; observed and simulated values use the same PRED_bin. Records are matched by (id, time, k), k numbering the records of a subject at one time in their order (:pre before :post), so a pre-dose and a post-dose record at a dose time keep their own predictions; observed rows at one time are numbered the same way, order = :pre rows first when they have an order field (as from read_nmdata), otherwise in the order given. vpc(model, subjects; pc = true) computes the predictions itself with η = 0 and κ = 0 whatever η and κ are passed for the simulation (observed records that are not records of the cohort design are predicted from their subject observed at those records). vpc(r::SimResult; pc = true, pred = ...) needs pred: a SimResult from simulate(model, subjects; η = :zero, κ = :zero, residual = false) (checked: nonzero η or κ, or residual error, is an error), or a dictionary keyed by (id, time, k) or (id, time) (applies to every record of the subject at that time, so it cannot tell a pre-dose from a post-dose record); observed rows may carry their own pred field. The correction is proportional, so it needs positive predictions: values with a prediction that is not positive and finite (a concentration of zero at the first time, say) cannot be corrected, are left out and are counted in n_nopred (one warning). The lower-bound term and the log-scale variant of the paper are not implemented. Under weighting = :subject the pooled PRED_bin is still the median over observations.

variability_correction = true adds the paper's variability correction (pvcVPC): the spread of the corrected values around PRED_bin is equalised across the observations of a bin,

pvcY_ij = PRED_bin + (pcY_ij - PRED_bin) * sd_bin / sd_ij

with sd_ij the standard deviation over the replicates of the simulated pcY_ij of that record and sd_bin the median of the sd_ij of the bin (finite and positive ones). It needs at least 2 replicates, and observed records must be in the simulated design (same id, time and k); an observation with no spread (sd_ij not positive) is left uncorrected. pred_bin in the result holds PRED_bin.

Stratification

strata = subject -> key splits the cohort and the observed data by the key of each subject (the function gets the Subject, or for vpc(r::SimResult) the subject row, both with id and covariates; a dictionary id => key also works) and returns a StratifiedVPC, one independent VPC per stratum (also the PRED_bin of a pcVPC and the bins' n_rep). One simulation serves all strata, so the replicate and seed are the same as without strata. Observed rows must belong to a subject of the cohort (matched by id).

source
QSPAtlas.VPCResult — Type
VPCResult

Result of vpc.

  • rows: one per (bin, q), ordered by bin then q: (bin, bin_lo, bin_hi, t_mid, q, median, lo, hi, mc_se, n, n_rep, n_failed, n_blq, failure_rate, unreliable). median is the median over replicates of the replicate's q-quantile in the bin, lo and hi the pi_level interval of those quantiles across replicates (the prediction interval of the quantile, not a confidence interval of any data), mc_se the Monte Carlo standard error of median. n is the median number of usable values per replicate, n_rep the number of replicates with a defined quantile, n_failed the total number of excluded non-finite values and n_blq the total number of values below lloq over all replicates. failure_rate is the fraction of the simulated values of the bin (over all replicates) that were not finite, and unreliable is true when it is above max_failure_rate (never when that is 0, the report-only default). With blq.handling = :censored four fields are added: below_lloq, lo_below, hi_below (the median, lo or hi is below the limit: its value is NaN) and n_cens (replicates whose quantile was below the limit; they count in n_rep).
  • observed: nothing, or rows (bin, bin_lo, bin_hi, t_mid, q, value, n, n_failed, n_blq) of the observed quantiles (diagnostic only), plus below_lloq and limit with :censored (see percentiles).
  • blq_fraction: nothing unless blq was given, else one row per bin (bin, bin_lo, bin_hi, t_mid, median, lo, hi, mc_se, n, n_rep, observed, n_observed, n_observed_blq): the fraction of values below lloq, simulated (median and pi_level interval across the replicates, mc_se of the median, n the median number of values per replicate) and observed (NaN without observed data).
  • pred_bin: for a prediction-corrected VPC the median typical population prediction of each bin (over the records of the simulated design), else nothing; pc is :none, :pc or :pvc; n_nopred counts values left out because their prediction was not positive and finite.
  • weighting, subject_value (see percentiles), stratum (the key of this result inside a StratifiedVPC, else nothing).
  • endpoint, q, pi_level, replicates, seed, value, blq, n_failed (all excluded simulated values), n_unbinned (observed values in no bin), failure_rate (overall fraction of non-finite simulated values, also failure_rate(v)), max_failure_rate. mc_check tests the Monte Carlo precision per row.

Iterating, length and indexing act on rows.

source
QSPAtlas.StratifiedVPC — Type
StratifiedVPC

Result of vpc with strata: one VPCResult per stratum, in results, with the stratum keys in strata (same order; every result also has its key in stratum). Indexing by a key gives its result, indexing by an integer the i-th; iterating gives key => result pairs; length is the number of strata. plot_vpc draws one panel per stratum. Use mc_check and failure_rate on the individual results.

source
QSPAtlas.mc_check — Function
mc_check(v::VPCResult, tolerance; fraction = 0.2) -> Vector{NamedTuple}

Is the Monte Carlo precision of a vpc good enough for a comparison against tolerance? One row per (bin, q) of v: (bin, t_mid, q, mc_se, limit, ok) with limit = fraction * tolerance and ok = mc_se < limit (false when mc_se is NaN, i.e. fewer than 10 replicates or too many ties). tolerance is in the units of the value (for example the allowed deviation of the median in concentration units); pass a function row -> tolerance to give each bin or quantile its own, for instance when the tolerance is a fraction of the value. A model asserts precision with all(c.ok for c in mc_check(v, tol)) and raises replicates if it fails. Nothing in the atlas uses this for grading yet.

source
QSPAtlas.failure_rate — Function
failure_rate(rows) -> Float64
failure_rate(v::VPCResult) -> Float64

Overall fraction of failed (non-finite) values: the sum of n_failed over the bins divided by the sum of n_failed + n_finite, each bin counted once (not once per quantile). For percentiles rows pass the vector it returned; NaN if there are no values at all. The rate per bin is failure_rate in each row. A failed solve leaves NaN for every observation it did not reach, so this is the fraction of failed subject trajectories, weighted by how many observations each one contributes.

source
QSPAtlas.spaghetti — Function
spaghetti(r::SimResult, endpoint; value = :dv, replicate = 1, logy = false, path = nothing) -> Figure

One line per subject: endpoint against time. replicate = 1 shows the first replicate of the cohort; replicate = nothing overlays all of them. Non-finite values (failed solves) leave gaps, they are not joined. path saves the figure (png, pdf, svg by extension).

source
QSPAtlas.bands — Function
bands(r::SimResult, endpoint; q = (0.05, 0.5, 0.95), bins = :obstimes, value = :dv,
      logy = false, path = nothing) -> Figure

Percentile bands of a simulation: percentiles (pooled over replicates, same bins and quantile definition) drawn as nested shaded bands between the lowest and the highest q, the next lowest and next highest, and so on, and a line for an unpaired middle q (the median for the default).

source
QSPAtlas.plot_vpc — Function
plot_vpc(v::VPCResult; observed = nothing, logy = false, blq_fraction = false, path = nothing) -> Figure
plot_vpc(v::StratifiedVPC; logy = false, blq_fraction = false, ncols = 3, path = nothing) -> Figure

Plot a vpc result. For every quantile a shaded band (the pi_level interval of the replicate quantiles, lo..hi) and a line (their median); the median quantile is drawn in orange, the others in blue. If the result has observed quantiles (vpc(...; observed = data)) they are drawn as black lines with points. observed here may also be raw data, a vector of (id, time, dv), drawn as grey dots behind everything. Bins with an undefined quantile (NaN, including quantiles below the limit in a censored VPC) leave gaps; with blq.handling = :censored the limit is drawn as a dotted line, except for a prediction-corrected result: the correction gives every record its own limit (LLOQ * PRED_bin / PRED_ij), so no single line would be correct and none is drawn.

blq_fraction = true adds a panel below with the fraction of values below the limit of quantification per bin (VPCResult.blq_fraction): the simulated median and interval, and the observed fraction when the result has observed data; it needs a result computed with blq. A prediction-corrected result is labelled as such.

For a StratifiedVPC every stratum gets its own panel (ncols per row, the stratum key in the title; the raw observed points are not available there, the observed quantile lines are drawn from the results).

source
QSPAtlas.grade_strict — Function
grade_strict(r) -> Char

The grade under the strict reading of "from published information": only the article and its supplement count. If any run needs a value whose basis is a cited reference, a standard value, the target figure or unspecified, the model cannot be run from the published information alone and is D; otherwise the strict grade equals grade.

source
QSPAtlas.NotRunnable — Type
NotRunnable(msg)

Thrown by a model's simulation when the published information is not enough to run it (an undefined symbol, a missing equation). run_curves records it as "did not run"; any other exception is a bug in the model code and propagates.

source
QSPAtlas.from_target — Function
from_target(r::Reproduction) -> Bool

True when the grade rests on a :from_target fix (B only), i.e. some input was read from the figure being reproduced. Shown as B† on the site.

source
QSPAtlas.post_comparison — Function
post_comparison(r::Reproduction) -> Bool

True when the grade is B and rests on at least one fix made after the first comparison with the target (stage = :after_comparison). Shown as ‡ on the site (B‡, or B†‡ together with from_target).

source
QSPAtlas.figure_grades — Function
figure_grades(r::Reproduction) -> Vector{Pair{String, String}}

Grade per figure, using the same rules as grade on that figure's curves alone. The model grade is set by all frozen targets together, so a model can be C overall while one of its figures reproduces; this breakdown shows that.

source

Internals

Helpers that are not exported but are documented for contributors.

QSPAtlas.covariates_at — Method
covariates_at(subject, t)

Covariates in force at time t. With covariate_rule = :locf the baseline values overridden by every change at or before t, in time order. With :nocb the baseline overridden by every change before t and then by the first change at or after t (the one whose interval contains t).

source
QSPAtlas.eta_factor — Method
eta_factor(Ω) -> Matrix

Matrix L with L L' = Ω, so that η = L z with z ~ N(0, I) has covariance Ω. Zero-variance η get an exactly zero row (their draw is exactly 0). The positive part is factored by Cholesky; if it is only positive semidefinite (singular, for example two perfectly correlated η), an eigen-decomposition is used instead.

source
QSPAtlas.eta_value — Method
eta_value(model, η) -> NamedTuple

Normalise a user-given η (NamedTuple with exactly the ηnames, or a vector in that order).

source
QSPAtlas.explicit_time_dependence — Method
explicit_time_dependence(sys) -> Bool

True if an equation or observed expression of the compiled system sys depends on time explicitly, beyond the states.

source
QSPAtlas.figure_key — Method
figure_key(ref) -> String

Which figure a reference curve belongs to: the group header key if present, otherwise the figure number at the start of the curve id (fig2_a_T -> fig2, fig4b_neut -> fig4), otherwise the id up to its first underscore.

source
QSPAtlas.kappa_value — Method
kappa_value(model, κ) -> NamedTuple

Normalise a user-given κ for one occasion (NamedTuple with exactly the κnames, or a vector in that order).

source
QSPAtlas.mc_se_median — Method
mc_se_median(x, rng; B = 500, warn = true) -> Float64

Monte Carlo standard error of the median of x, the per-replicate quantiles of one bin (treated as independent draws), by the bootstrap over replicates: B resamples of x with replacement, the standard deviation of their medians. It needs no density estimate and, unlike rank-interval formulas, it stays honest for tied or discrete values (BLQ censoring puts many replicate quantiles at exactly lloq; a rank interval then has width zero and says "no error"). rng is a random number generator, seeded by vpc from its seed, so the result is reproducible. NaN for fewer than 10 values. A bootstrap SE of a median is itself noisy (about 10-20 % at K = 100-400) and slightly rough for discrete values; treat it as a noise level, not an exact number. It is exactly 0 only when all values are equal (no spread at all).

Degenerate case: with heavily tied values (say 98 % of the replicate quantiles at lloq) every resample can have the same median although x is not constant, and the standard deviation of the medians would be 0, "no error", which is false. When x is not constant, fewer than 3 distinct resampled medians occur and fewer than 1 % of the resamples (at least one) differ from the commonest median, the result is NaN and, with warn = true, a warning says so. Use more replicates (or fewer ties) to get a number. Two distinct medians that both occur often (a balanced 0/1 sample of odd size) are a usable estimate and are not flagged. vpc calls this with warn = false and reports the number of such cells in one warning.

source
QSPAtlas.merge_control — Method
merge_control(a::DoseControl, b::DoseControl) -> DoseControl

Union of two dose controls (the subject's own and the one computed by the model's dosecontrol). The same entry (field and compartment) in both is an error.

source
QSPAtlas.normalise — Method
normalise(axis, v)

Map a data value to the fraction of the drawn axis (0 at lo, 1 at hi). Log axes are mapped in decades. Values below zero on a log axis map to -Inf clamped at -1, which counts as a large error rather than an exception.

source
QSPAtlas.sample_eta — Method
sample_eta(model, rng) -> NamedTuple

Draw η ~ N(0, Ω) as a NamedTuple keyed by ηnames. Always consumes length(ηnames) standard normal draws, whatever the structure of Ω.

source
QSPAtlas.sample_kappa — Method
sample_kappa(model, rng) -> NamedTuple

Draw one occasion's κ ~ N(0, Ω_IOV) as a NamedTuple keyed by κnames. Always consumes length(κnames) standard normal draws.

source
QSPAtlas.sd — Method
sd(err, ipred)

Standard deviation of the observation dv given ipred under error model err. For ExponentialError this is the sd of dv itself (not of log dv).

source
QSPAtlas.stream_seed — Method
stream_seed(seed, replicate, id, stream) -> UInt64

Seed of the random stream stream (a Symbol such as :eta or :residual) of subject id in replicate replicate. It depends only on those four values, never on the subject's position in the cohort, the thread or the order of execution.

source
QSPAtlas.trajectory_control — Method
trajectory_control(model, subject, η, κs) -> DoseControl or function

The dose control of one trajectory: the subject's control when the model has no dosecontrol, else a function (dose, record_time) -> DoseControl that evaluates the model's dosecontrol with the covariates and the occasion's κ at the time of the dose's record (covariates_at, occasion_at; addl doses use their record's time) and combines it with the subject's control.

source
QSPAtlas.validate_omega — Function
validate_omega(Ω, ηnames, name = "Ω") -> Matrix{Float64}

Check that Ω is square, matches ηnames, is symmetric and positive semidefinite (zero-variance η allowed). Returns the symmetrised matrix. name is used in error messages ("Ω_IOV" for the between-occasion covariance).

source
QSPAtlas.with_obstimes — Method
with_obstimes(subject, obstimes) -> Subject

The same subject (regimen, covariates and covariate rule, control, occasions) observed at obstimes instead, every observation :post and for all endpoints.

source