NCA Docstrings

DoseLinearityPowerModel(nca::NCA.NCAReport, variable::Symbol; level = 0.95)

Run a power model to assess dose linearity of variable in NCAReport nca. The power model is of the form log(variable) ~ log(α) + β × log(dose).

The fitted parameters can be assessed by showing the model or running StatsBase.coeftable(model).

The confidence interval level can be set using level.

Example

DoseLinearityPowerModel(ncareport, :cmax; level = 0.9)

DoseLinearityRatioTest(nca::NCA.NCAReport, variable::Symbol; level = 0.95)

Run ratio tests to assess dose linearity for variable in NCAReport nca. The test runs HypothesisTests.EqualVarianceTTests on the log transform of variable. This effectively tests the difference of geometric means between two doses. The groups in each TTest are the low dose and one of each of the remaining dose groups. A confidence interval level for the difference of the means of the log transformed data can be set using level.

The result can be inspected by showing the returned object or using StatsBase.coeftable(model). The real dose ratio can be compared with the estimated ratio and its confidence interval, where these values are re-transformed from the TTest output using exp.

Example

DoseLinearityRatioTest(ncareport, :cmax; level = 0.9)

NCADose(
  time,
  amt,
  duration::D = nothing,
  route = NullRoute,
  ii = zero(time),
  ss = false,
)

NCADose takes the following arguments

• time: time of the dose
• amt: The amount of dosage
• duration: The infusion duration
• route: Type of route, NCA.IVBolus, NCA.IVInfusion or NCA.EV
• ii: interdose interval
• ss: steady-state

NCASubject(
  conc,
  time;
  id = "1",
  group = nothing,
  dose = nothing,
  llq = nothing,
  nominal_time = nothing,
  start_time = nothing,
  end_time = nothing,
  volume = nothing,
  concu = true,
  timeu = true,
  volumeu = true,
  clean = true,
  check = true,
  num_blqs_df = 0,
  concblq = :keep,
  removed_inds = nothing,
  missingconc = nothing,
  missingvolume = nothing,
)

Construct a NCASubject.

Note that llq keyword argument still takes effects with the presence of the blq data column, and llq defaults to 0.

Setting clean=false disables all checks on conc and time to remove the cost of checking and cleaning data. It should only be used when the data is for sure "clean".

Route

Type of routes. There are IVBolus and IVInfusion which are intravenous while EV is used for extravascular. The NullRoute value indicates that no route is specified.

accumulationindex(nca::NCASubject)

Theoretical accumulation ratio. $Accumulation\_index = 1/(1-\exp(-λ_z*τ))$.

auc(nca::NCASubject; auctype::Symbol, method::Symbol, interval=nothing, normalize=false)

Compute area under the curve (AUC) by linear trapezoidal rule (method = :linear) or by log-linear trapezoidal rule (method = :linuplogdown).

auclast(nca::NCASubject; method::Symbol, interval=nothing)

Alias for auc(subj; auctype=:last).

auclinear(C₁, C₂, t₁, t₂)

Compute area under the curve (AUC) in an interval by linear trapezoidal rule.

auclog(C₁, C₂, t₁, t₂)

Compute area under the curve (AUC) in an interval by log-linear trapezoidal rule.

auctau(subj::NCASubject; method::Symbol)

Alias for auctau(subj; auctype=:last, interval=(zero(τ), τ)).

aumc(nca::NCASubject; method::Symbol, interval=(0, Inf))

Compute area under the first moment of the concentration (AUMC) by linear trapezoidal rule (method = :linear) or by log-linear trapezoidal rule (method = :linuplogdown).

aumclast(nca::NCASubject; method::Symbol, interval=nothing)

Alias for aumc(subj; auctype=:last).

aumclinear(C₁, C₂, t₁, t₂)

Compute area under the first moment of the concentration (AUMC) in an interval by linear trapezoidal rule.

aumclog(C₁, C₂, t₁, t₂)

Compute area under the first moment of the concentration (AUMC) in an interval by log-linear trapezoidal rule.

aumctau(subj::NCASubject; method::Symbol)

Alias for aumctau(subj; auctype=:last, interval=(zero(τ), τ)).

bioav(nca::NCASubject; ithdose::Integer)

Compute the bioavailability as the ratio of two AUC values. $Bioavailability (F) = (AUC_{0,po}^\infty/Dose_{po})/(AUC_{0,iv}^\infty/Dose_{iv})$

c0(nca::NCASubject)

Estimate the concentration at dosing time for an IV bolus dose.

cavgss(nca::NCASubject, method = :linear, pred=false)

Average concentration over one period. $Cavgss = AUC_{\tau}/\tau$. The keyword arguments are passed to the auc function and more information about them can be found in the auc documentation.

checkconctime(conc, time=nothing; monotonictime=true, dose=nothing)

Verify that the concentration and time are valid

If the concentrations or times are invalid, will provide an error. Reasons for being invalid are:

1. conc is not a Number
2. time is not a Number
3. time value is missing
4. time is not monotonically increasing
5. conc and time are not of same length
6. conc is empty.
7. time is empty.

Some cases may generate warnings

1. A negative concentration is often but not always an error; it will generate a warning.

cl(nca::NCASubject, auctype=:inf, method = :linear, pred=false)

Calculate total drug clearance. The keyword arguments are passed to the auc function and more information about them can be found in the auc documentation.

clast(nca::NCASubject)

Calculate clast

cleanblq(conc′, time′; llq=nothing, concblq=nothing)

Handle BLQ values in the concentration measurements as requested by the user.

missing concentrations (and their associated times) will be handled as described in cleanmissingconc before working with the BLQ values. The method for handling missing concentrations can affect the output of which points are considered BLQ and which are considered "middle". Values are considered BLQ if they are 0.

Arguments

• conc: Measured concentrations

• time: Time of the concentration measurement

• concblq: How to handle a BLQ value that is between above LOQ values? See details for description.

• cleanmissingconc: How to handle NA concentrations.

concblq can be set either a scalar indicating what should be done for all BLQ values or a list with elements named "first", "middle", and "last" each set to a scalar. If nothing, BLQ values will be dropped (:drop)

The meaning of each of the list elements is:

1. first: Values up to the first non-BLQ value. Note that if all values are BLQ, this includes all values.
2. middle: Values that are BLQ between the first and last non-BLQ values.
3. last: Values that are BLQ after the last non-BLQ value

The valid settings for each are:

1. "drop" Drop the BLQ values
2. "keep" Keep the BLQ values
3. a number Set the BLQ values to that number

cleanmissingconc(conc, time; missingconc=nothing)

Handle missing values in the concentration measurements as requested by the user.

missing concentrations (and their associated times) will be removed

Arguments

• missingconc: How to handle missing concentrations? Either :drop or a number to impute.

cmax(nca::NCASubject; normalize=false, interval=nothing)

Calculate $Cmax_{t_0}^{t_1}$

cmaxss(nca::NCASubject; normalize=false)

Calculate $Cmaxss$

cmin(nca::NCASubject; normalize=false, interval=nothing)

Calculate $Cmin_{t_0}^{t_1}$

cminss(nca::NCASubject; normalize=false)

Calculate $Cminss$

cpred(nca::NCASubject, t)

Predicted concentrations at any time t

ctau(nca::NCASubject; method=:linear)

Calculate concentration at τ

extrapaucinf(clast, tlast, lambdaz)

Extrapolate AUC to the infinite.

extrapaumcinf(clast, tlast, lambdaz)

Extrapolate the first moment to the infinite.

fluctuation(nca::NCASubject; usetau=false)

Peak trough fluctuation over one dosing interval at steady state. $Fluctuation = 100*(Cmaxss - Cminss)/Cavgss$ (usetau=false) or $Fluctuation = 100*(Cmaxss - C_{tau})/Cavgss$ (usetau=true)

lambdaz(nca::NCASubject; concthreshold=1e-10, threshold=10, idxs=nothing) -> lambdaz

Calculate terminal elimination rate constant $λ_z$ with the end point greater than concthreshold.

lambdazadjr2(nca::NCASubject)

Give the adjusted coefficient of determination ($adjr²$) when calculating $λ_z$.

See also lambdaz.

lambdazintercept(nca::NCASubject)

Give the y-intercept in the log-linear scale when calculating $λ_z$.

See also lambdaz.

lambdaznpoints(nca::NCASubject)

Give the number of points that is used in the $λ_z$ calculation.

See also lambdaz.

lambdazr(nca::NCASubject)

Give the correlation coefficient ($r$) when calculating $λ_z$.

See also lambdaz.

lambdazr2(nca::NCASubject)

Give the coefficient of determination ($r²$) when calculating $λ_z$.

See also lambdaz.

lambdaztimefirst(nca::NCASubject)

Give the first time point that is used in the $λ_z$ calculation.

See also lambdaz.

lambdaztimelast(nca::NCASubject)

Give the last time point that is used in the $λ_z$ calculation.

See also lambdaz.

liftunits2header(df::AbstractDataFrame)

Lift units to the header row.

Example:

julia> first(df, 3)
3×8 DataFrame
│ Row │ id    │ conc            │ time     │ ii       │ addl  │ occasion │ route  │ amt       │
│     │ Int64 │ Quantity…       │ Quantit… │ Quantit… │ Int64 │ Int64    │ String │ Quantity… │
├─────┼───────┼─────────────────┼──────────┼──────────┼───────┼──────────┼────────┼───────────┤
│ 1   │ 1     │ 157.021 mg L^-1 │ 0.0 hr   │ 10 hr    │ 4     │ 1        │ iv     │ 5000.0 mg │
│ 2   │ 1     │ 141.892 mg L^-1 │ 0.05 hr  │ 10 hr    │ 4     │ 1        │ iv     │ 0.0 mg    │
│ 3   │ 1     │ 116.228 mg L^-1 │ 0.35 hr  │ 10 hr    │ 4     │ 1        │ iv     │ 0.0 mg    │

julia> first(NCA.liftunits2header(df), 3)
3×8 DataFrame
│ Row │ id    │ conc (mg L^-1) │ time (hr) │ ii (hr) │ addl  │ occasion │ route  │ amt (mg) │
│     │ Int64 │ Float64        │ Float64   │ Int64   │ Int64 │ Int64    │ String │ Float64  │
├─────┼───────┼────────────────┼───────────┼─────────┼───────┼──────────┼────────┼──────────┤
│ 1   │ 1     │ 157.021        │ 0.0       │ 10      │ 4     │ 1        │ iv     │ 5000.0   │
│ 2   │ 1     │ 141.892        │ 0.05      │ 10      │ 4     │ 1        │ iv     │ 0.0      │
│ 3   │ 1     │ 116.228        │ 0.35      │ 10      │ 4     │ 1        │ iv     │ 0.0      │

mrt(nca::NCASubject)

Mean residence time from the time of dosing to the time of the last measurable concentration.

IV infusion: $AUMC/AUC - TI/2$ where $TI$ is the length of infusion. non-infusion: $AUMC/AUC$

normalizedose(x::Number, d::NCADose)

Normalize x, a parameter of NCA, e.g., AUC, by dosing amount.

read_nca(file::AbstractString; kwargs...)
read_nca(df_obs::AbstractDataFrame, df_dose::AbstractDataFrame; id = :id, time = :time, kwargs...)
read_nca(df::DataFrame; id=:id, time=:time, observations=:conc, nominal_time = :nominal_time,
                        start_time=:start_time, end_time=:end_time, volume=:volume,
                        amt=:amt, route=:route, duration=:duration, blq=:blq,
                        ii=:ii, ss=:ss, group=nothing, concu=true, timeu=true, amtu=true, volumeu=true,
                        verbose=true, sparse = false, kwargs...)

Parse a DataFrame object or a CSV file to NCAPopulation. NCAPopulation holds an array of NCASubjects which contain relevant data for the individual subjects.

• df : DataFrame containing the data for the analysis.

2 dataframes, in order, observations dataframe and dosing dataframe, can be passed to read_nca as well, rest of the arguments stay consistent in this case.

The following keyword arguments are used to specify column names in the df:

• id : The numeric or string id of the subject. Defaults to :id.
• time : The actual time at which the observations were measured. Defaults to :time.
• observations: The observation (e.g. concentration) time series measurements. Values must be numbers or missing. Defaults to :conc.
• amt: The amount of a dose. Can either be the dosing amount at each dosing time and otherwise missing or the dosing amount is present at each time, in this case the first time (for a subject in a subgroup) is considered as the dosing time. Defaults to :amt.
• route: The route of administration. Possible choices are iv for intravenous, ev for extravascular, and inf for infusion. These can be specified as lower, upper or mixed case. E.g. iv, IV or Ev are accepted. Defaults to :route.
• duration: The infusion duration. Should be the duration value or missing. Defaults to :duration.
• blq: Below the lower Limit of Quantification (BLQ). Used to specify the observation is BLQ. The BLQ column can take a value of 1 for BLQ observation and 0 otherwise. Defaults to :blq.
• ii: The interdose interval, equivalent to tau. Used to specify the interval length for steady-state dosing. Defaults to the :ii column. If specified, and ss is true, then analysis returns steady-state parameters e.g., cminss, cavgss, cmaxss by computing the accumulationindex.
• ss: The steady-state. Used to specify whether a dose is steady-state, a steady-state dose takes the value 1 and 0 otherwise. It defaults to the :ss column. If ss is set to 1 for a subject, ii should be greater than 0.
• group: The columns to group the data by, splits the subjects based on the group information associated with them. Defaults to no grouping.
• llq: The Lower Limit of Quantification (LLQ). Defaults to nothing.
• concblq: The scheme for handling of BLQ values. Defaults to the dictionary Dict(:first=>:keep, :middle=>:drop, :last=>:keep), further explanation is available in the Handling BLQ Data section.
• concu: The units for observations (e.g. concentration). Defaults to no units.
• amtu: The units for dosing amount. Defaults to no units.
• timeu: The units for time. Defaults to no units.
• volumeu: The units for volume. Defaults to no units.
• verbose: When true, warnings will be thrown when the output does not match PumasNCADF. Defaults to true.
• nominal_time: The nominal time corresponding to the observations. Defaults to :nominal_time.
• sparse: Boolean flag to indicate if the dataset should be treated as a case of sparse sampling. Defaults to false.

Urine analysis requires the following columns not used in case of plasma.

• start_time : The beginning of the urine collection time. Defaults to :start_time.
• end_time : The end of the urine collection time. Defaults to :end_time.
• volume: Collected urine volume. Defaults to :volume.

For details about the handling of concentration values below the lower limit of quantification, please check out the documentation of NCA.cleanblq. All the keyword arguments of NCA.cleanblq are applicable to read_nca, too.

  run_nca(pop::NCAPopulation;
              parameters = nothing,
              studyid::String="",
              studytitle::String="",
              author=[],
              sponsor::String = "",
              date::DateTime=Dates.now(),
              conclabel::String="",
              timelabel::String="",
              grouplabels::Array=String[],
              groupsizes::NamedTuple=NamedTuple(),
              versionnumber::Union{String, VersionNumber}=v"0.1",
              sigdigits=nothing,
              )

The primary function in NCA.jl, to run NCA analysis on a population. Returns a NCAReport object that has a data frame of parameters computed in the analysis and other metadata information passed when run_nca is called.

span(nca::NCASubject)

Calculate span

  summarize(data::AbstractDataFrame;
              stratify_by::AbstractVector{<:Union{Symbol,Integer,AbstractString}} = Symbol[],
              parameters::AbstractVector{<:Union{Symbol,Integer,AbstractString}} = [:cmax, :tmax, :half_life, :aucinf_obs, :auclast, :cl, :vz],
              stats::AbstractVector{<:Function} = [NCA.numsamples, extrema, Statistics.mean, Statistics.std, StatsBase.geomean, NCA.geostd, NCA.geomeanCV]
              skipmissings = false
            )

Computes summary statistics specified by stats kwarg for parameters obtained from NCA analysis with run_nca. stratify_by allows you to group your computations. The skipmissings argument can be used to obtain summary statistics in presence of missing values.

superposition(data::Union{NCAPopulation,NCASubject}; ii, ndoses=5, amt=nothing, steadystatetol=3e-2, method=:linear)

Superposition calculation.

Arguments:

• ii: interdose interval.
• ndoses: number of doses. It can be a positive integer or Inf.
• amt: dose amount. It defaults to the dose amount of the subject.
• steadystatetol: steady state tolerance. Superposition computation terminates when $abs(1 - c(t-ii) / c(t)) <= steadystatetol$.
• method: the method for interpolation. It defaults to :linear.

swing(nca::NCASubject; usetau=false)

$swing = (Cmaxss - Cminss)/Cminss$ (usetau=false) or $swing = (Cmaxss-C_τ)/C_τ$ (usetau=true)

tau(nca::NCASubject)

Dosing interval. For multiple dosing only.

thalf(nca::NCASubject)

Calculate half life time.

timesfromstart(subj::NCASubject)

get a flat array with all the timepoints.

Ensures consistency between single-dose and multi-dose NCASubjects.

tlag(nca::NCASubject)

The time prior to the first increase in concentration.

tlast(nca::NCASubject)

Calculate tlast

tmax(nca::NCASubject; interval=nothing)

Calculate time of maximum observed concentration

tmin(nca::ncasubject)

Calculate time of minimum observed concentration

vss(nca::NCASubject, method = :linear, pred = false)

Calculate apparent volume of distribution at equilibrium for IV bolus doses. The keyword arguments are passed to the auc function and more information about them can be found in the auc documentation. $V_{ss} = MRT * CL$.

vz(nca::NCASubject, method = :linear, pred=false)

Calculate the volume of distribution during the terminal phase. $V_z = 1/(AUC⋅λ_z)$ for dose normalizedosed AUC. The keyword arguments are passed to the auc function and more information about them can be found in the auc documentation.