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.

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

Keyword arguments

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, cpred, ctau, cmaxss and cminss

• 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.