Running NCA

run_nca(dataframe::DataFrame [, endpoints::Vector]; kwargs...)

Compute all the NCA analyses defined in endpoints using dataframe which should come from read_nca, read_nca_pumas or transform_nca. Observations flagged in the exclusion column (see read_nca) are omitted from the calculations.

The elements of endpoints specify which NCA endpoint functions to compute. Each element requires the name of the endpoint as a Symbol and can optionally be paired with keyword arguments specified as a NamedTuple as well as an output name specified as another Symbol.

endpoints = [
  :tmax, # endpoint only
  :lambdaz => :kel, # rename
  :auclast => (; method = :linuplogdown) => :auclast_log, # keywords and rename
  # multiple versions of the same endpoint are also possible
  :auc_partial => (; interval = (1, 2)) => :auc_1_2,
  :auc_partial => (; interval = (3, 4)) => :auc_3_4,
]

If no endpoints are specified, all endpoints applicable to the current dataframe (considering plasma/urine, steady-state, etc.) are computed.

Keyword arguments

Endpoints that cannot be computed appear as missing in their output column. For any endpoint column with at least one such missing, a companion [endpoint]_err column is added that carries the failure reason as a String in the corresponding rows (and missing in rows that computed normally).

The following keywords are endpoint options that are commonly changed and are therefore made available at the top level.

Forwarded to lambdaz_fit

• adjr2factor
• threshold

Forwarded to all auc endpoints

• method = :linear

Examples

julia> using NCA, PharmaDatasets

julia> df = dataset("nca/ev_sd_example");

julia> df_r = NCA.read_nca(df);

julia> report = run_nca(df_r, [:cmax, :tmax, :auclast, :half_life]); # selected endpoints

julia> names(report)
11-element Vector{String}:
 "id"
 "profile"
 "dose"
 "route"
 "duration"
 "tau"
 "assumed_tau"
 "cmax"
 "tmax"
 "auclast"
 "half_life"

julia> renamed = run_nca(df_r, [:cmax, :auclast => :auc_0_last]); # rename an endpoint

julia> names(renamed)
9-element Vector{String}:
 "id"
 "profile"
 "dose"
 "route"
 "duration"
 "tau"
 "assumed_tau"
 "cmax"
 "auc_0_last"

julia> partial = run_nca(df_r, [
         :auclast,
         :auc_partial => (; interval = (0, 4)) => :auc_0_4,
         :auc_partial => (; interval = (4, 12)) => :auc_4_12,
       ]); # pass keyword arguments to endpoints

julia> names(partial)
10-element Vector{String}:
 "id"
 "profile"
 "dose"
 "route"
 "duration"
 "tau"
 "assumed_tau"
 "auclast"
 "auc_0_4"
 "auc_4_12"

julia> size(run_nca(df_r)) # all default endpoints
(2, 48)

summarize(data::AbstractDataFrame; stratify_by, parameters, stats)

Compute summary statistics across subjects for columns in an NCA result DataFrame returned by run_nca.

Arguments

• data: the DataFrame returned by run_nca.
• stratify_by: columns to group by before computing statistics. Defaults to group_columns(data), i.e. the grouping columns that were present in the input to read_nca.
• parameters: which result columns to summarize. Defaults to all non-grouping, non-reserved, non-error columns.
• stats: a vector of summary functions. Default: [minimum, maximum, mean, std, geomean, geostd, geomeanCV].

The output always includes numsamples (total rows per group) and nonmissing (non-missing values per group) in addition to the requested stats. Each statistic is computed on non-missing values only and returns missing when all values are missing.

Example

using NCA, PharmaDatasets
df = dataset("nca/ev_sd_example")
df_r = NCA.read_nca(df)
results = run_nca(df_r, [:cmax, :auclast, :half_life])
summarize(results)

guess_parameter_columns(report_df::DataFrames.AbstractDataFrame)

Returns all column names of a report dataframe that are not grouping columns, internally reserved column names like dose or tau, or error columns ending with "_err".

The detection is purely structural: every column that is not a grouping column, not a reserved column, and does not end in "_err" is treated as a parameter column. As a consequence, any column you add to the dataframe after run_nca is also picked up, including transformed, derived, or renamed endpoints and non-standard names such as partial AUCs. For example, a column added as report_df.cmax_over_auc = report_df.cmax ./ report_df.auclast is returned as :cmax_over_auc, and is therefore summarized by default by summarize.