Analysis and Reporting

A brief overview of the NCA analysis steps was provided in the Run Analysis section of the introduction. In this section, we will dive into the specific functions that facilitate efficient analytics and reporting. After generating a NCAPopulation using read_nca, users have the flexibility to do the following:

1. Compute specific NCA parameters. This is mostly for interactive use and understanding the results of a few parameters. Users are referred to the functions in the NCA Function List to do this.
2. Run an end-to-end analysis using run_nca
3. summarize results of the run_nca
4. Generate automated report of all the results for a NCA analysis.

run_nca function

run_nca is the powerhouse function that:

• executes all valid NCA functions at their default options

• generates a DataFrame of results that can be used for efficient post-processing

• save metadata information passed that are used for:

  • automatic report generation
  • interactive plots

  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 only required argument to run_nca is the first positional argument, the name of the NCAPopulation that was created using read_nca.

result = run_nca(df_r1)

The result object is of type NCAReport that has many fields, the most important one being reportdf that can be accessed via result.reportdf.

Of the other arguments that can be passed to run_nca, they can be grouped into output modifying and metadata storing kinds.

Output Modifying

• parameters: An array of strings from NCA Function List. When the parameters are not specified, run_nca provides an output of all relevant parameters. By setting to only some values such as parameters = ["cmax", "half-life"], users can output a pre-specified set of parameters.

[
    "dose",
    "tlag",
    "tmax",
    "cmax",
    "cmaxss",
    "c0",
    "tlast",
    "clast",
    "clast_pred",
    "auclast",
    "kel",
    "half_life",
    "aucinf_obs",
    "aucinf_pred",
    "auc_tau_obs",
    "auc_tau_pred",
    "tau",
    "tmin",
    "cmin",
    "cminss",
    "ctau",
    "cavgss",
    "vz_obs",
    "cl_obs",
    "vz_f_obs",
    "cl_f_obs",
    "vz_f_pred",
    "cl_f_pred",
    "vz_pred",
    "cl_pred",
    "vss_obs",
    "vss_pred",
    "fluctuation",
    "fluctuation_tau",
    "accumulation_index",
    "n_samples",
    "cmax_dn",
    "auclast_dn",
    "aucinf_dn_obs",
    "auc_extrap_obs",
    "auc_back_extrap_obs",
    "aucinf_dn_pred",
    "auc_extrap_pred",
    "auc_back_extrap_pred",
    "aumclast",
    "aumcinf_obs",
    "aumc_extrap_obs",
    "aumcinf_pred",
    "aumc_extrap_pred",
    "mrtlast",
    "mrtinf_obs",
    "mrtinf_pred",
    "swing",
    "swing_tau",
    "n_samples_kel",
    "rsq_kel",
    "rsq_adj_kel",
    "corr_kel",
    "intercept_kel",
    "kel_t_low",
    "kel_t_high",
    "span",
    "route",
    "run_status",
]

• sigdigits: defaults to nothing, so all reporting quantities are in full Float64 precision. To truncate extraneous digits, one can do e.g., sigdigits=4.

• Additional arguments: NCA Related Keyword Arguments related to the individual NCA functions can be specified in run_nca.

  • A few of the keyword arguments are applied by default, and the results are included in the output of run_nca. These include, normalize (which provides the dose normalized parameters provided valid dose information), pred (provides predicted value of parameters in addition to observed, e.g. aucinf_obs vs aucinf_pred), auctype (that by default provides both :last and :inf results for both observed and predicted).

Other, function specific, arguments can be found at the NCA Functions section.

Metadata storing

As detailed in the function signature, there are many additional arguments that can be passed into run_nca that capture metadata information. This information is used by the report function, in addition to providing a convenient method to store extra information associate with a specific analysis.

• studyid::String="": A study ID that is included in the title page of the report. Provide a string, e.g. "STUDY -001"
• studytitle::String="": A study title that is included in the title page of the report. Provide a string, e.g. "Single ascending dose study of Drug X"
• author=[]: A list of authors and affiliation. Each author and affiliation has to be a tuple. When multiple authors are included, provide them as an array of tuples. e.g. author = [("Vijay", "Pumas-AI"),("Vaibhav", "Julia Computing") ].
• sponsor::String = "": Name of a sponsor to be included in report title. Provide as a string, e.g. "Pumas-AI"
• date::DateTime=Dates.now(): Default date is picked up from the system date and time.
• conclabel::String="": Concentration labels to be used for interactive plotting and plots in reports.
• timelabel::String="": Time labels to be used for interactive plotting and plots in reports.
• grouplabels::Array=String[]: If stratifying the analysis by a group or a list of groups, provide an array of strings that can be used for interactive plotting and plots in reports.
• groupsizes::NamedTuple=NamedTuple(): If stratifying the analysis by groups, provide the number of subjects in each group that can be used in certain aspects of the report. Note that this argument will be handled internally in the next release.
• versionnumber::Union{String, VersionNumber}=v"0.1": A version number that can be specified for the report.
• investigational_product::String="" and protocol_number::String="": Study specific information.

Summarize

The summarize function computes the summary statistics of key parameters obtained as a result of run_nca:

summarize(
    data;
    stratify_by = Symbol[],
    parameters = Symbol[],
    stats = [numsamples, extrema, mean, std, geomean, geostd, geomeanCV],
)

• data - this should be a DataFrame that comes from the reportdf field of run_nca.
• stratify_by - A single group or a list of groups passed in as Symbols.
• parameters - The parameters to be summarized. The parameter names have to come from the alias list provided above.
• stats - The statistics to report for the summarization. The default statistics are those included in the signature above. Users can pass in any arbitrary function defined in Julia that provides a statistic.

For example:

result = run_nca(df_r1)
strata = [:DOSE]
parms = [:cmax, :aucinf_obs]
stats = [minimum, maximum, mean, std]
output = summarize(result.reportdf; stratify_by = strata, parameters = parms, stats = stats)

Report

The report feature allows users to generate a comprehensive report of an analysis. A report can be generated either directly from a NCAPopulation or from a NCAReport.

Generate report from a NCAPopulation

report(NCAPopulation)

This creates a PDF report based on the given NCAPopulation. This method performs run_nca and summarize automatically on the NCAPopulation and so keywords that can be supplied to those functions can be passed directly to report in order to control the behavior of run_nca and summarize. For a description of the other available keywords that directly control the generated report refer to the details below.

Generate report from a NCAReport

report(NCAReport, DataFrame)

Create a PDF report in output folder based on the given NCAReport and optional summarize DataFrame output. clean=false will leave all intermediate files in output for inspection by the user. header and footer allow the user to provide custom headers and footers for every page of the generated report. Report metadata that should appear in the final report should be passed to the run_nca function as discussed in Metadata storing. Please refer to its documentation for available fields. In the reportsignature, the following arguments are used:

• header: a custom string to print in the header of each page of the report.
• footer: a custom string to print in the footer of each page of the report.
• plot_fontsize: size of font to be used for all plots. Defaults to 16.
• plot_resolution: resolution as a 2-tuple (width and height) of all plots. Defaults to (960, 540).

An example workflow is provided below in 4 steps:

1. Read data and generate a NCAPopulation.

df = CSV.read("pkdf.csv"; missingstrings = ["", "."])
pop = read_nca(df_r1; observations = :conc)

1. Perform NCA analysis using run_nca while passing all metadata

pk_nca = run_nca(
    pop,
    sigdig = 3,
    studyid = "STUDY-001",
    studytitle = "Phase 1 SAD of CTM Analgesic",
    author = [("Vijay", "Pumas-AI"), ("Vaibhav", "Julia Computing")],
    sponsor = "Pumas-AI",
    date = Dates.now(),
    conclabel = "CTMX (ng/mL)",
    grouplabel = "Dose (mg)",
    timelabel = "Time (Hr)",
    versionnumber = v"0.1",
)

1. (Optional) - Summarize the NCA results using summarize

strata = [:DOSE]
parms = [:cmax, :aucinf_obs]
stats = [minimum, maximum, mean, std]
pksummary = summarize(
    pk_nca_report.reportdf;
    stratify_by = strata,
    parameters = parms,
    stats = stats,
)

1. Generate a PDF report of the results using report.

pkreport = report(
    pk_nca,
    pksummary,
    output = "CTM Angalgesic",
    header = "Pumas-AI",
    footer = "Confidential",
    plot_fontsize = 12,
    plot_resolution = (800, 400),
)

A generated PDF report contains the following information in the order below:

1. Title page
2. Table of contents
3. List of tables
4. List of figures
5. Summary of observation vs time plot
6. Summarized NCA parameters
7. List of all NCA parameters across individuals and grouping variables
8. Parameter distribution plots of selected parameters
9. Parameter vs group plots of selected parameters Appendix A: Individual Subject Fits Appendix B: System Information