The PKNCA Mental Model: Objects, Intervals, and Results

Understand how PKNCA structures NCA workflows using concentration objects, dose objects, intervals, and results containers.
Tip

Big idea: PKNCA is not just a function — it is a structured pipeline of objects that make NCA reproducible and auditable.

Learning Objectives

By the end of this lesson, you will be able to:

  • Describe the core object pipeline in PKNCA.
  • Explain the roles of PKNCAconc, PKNCAdose, and PKNCAdata.
  • Understand what a PKNCAresults object contains.
  • Conceptually map raw data → structured objects → NCA results.

Key Ideas

  • PKNCA separates data definition from calculation.
  • Concentration data and dose data are stored in structured objects.
  • Intervals define what exposure window is being calculated.
  • Results are stored in a formal container (PKNCAresults) before summarization.
  • This structure supports transparency and reproducibility.

The Core Pipeline

At a high level, the PKNCA workflow follows this sequence:

  1. Define concentration data → PKNCAconc()
  2. Define dosing data → PKNCAdose()
  3. Combine them with interval rules → PKNCAdata()
  4. Run calculations → pk.nca()
  5. Inspect outputs → PKNCAresults

Conceptually:

\[ \text{Raw Data} \rightarrow \text{Structured Objects} \rightarrow \text{NCA Calculations} \rightarrow \text{Results Container} \]

Each step makes assumptions explicit.

Step 1: Concentration Object

PKNCAconc() stores:

  • Subject identifiers
  • Time variable
  • Concentration variable
  • Grouping variables (e.g., treatment, visit)

This object does not perform calculations.

It defines:

“These rows represent concentration–time observations belonging together.”

That grouping logic is critical for correct exposure estimation.

Step 2: Dose Object

PKNCAdose() stores:

  • Subject identifiers
  • Dose amount
  • Dose timing
  • Optional metadata (route, infusion duration)

NCA requires knowledge of dosing history to calculate metrics like:

  • \(CL/F = \frac{Dose}{AUC}\)
  • \(AUC_{\tau}\)
  • Accumulation metrics

Without explicit dose structure, those quantities cannot be computed reliably.

Step 3: Interval Definition

Intervals define:

  • Start time
  • End time
  • Whether to calculate half-life
  • Whether to extrapolate to infinity

Examples:

  • \(AUC_{0-t}\)
  • \(AUC_{0-\infty}\)
  • \(AUC_{0-\tau}\)

Intervals are where you encode study design decisions.

Step 4: Running the Calculation

pk.nca() takes a PKNCAdata object and performs:

  • Trapezoidal AUC calculation
  • Terminal slope estimation
  • Half-life calculation
  • Derived parameter calculation

The result is stored as a PKNCAresults object.

Step 5: Understanding PKNCAresults

A PKNCAresults object:

  • Contains calculated parameters
  • Retains grouping structure
  • Keeps interval definitions
  • Preserves metadata for reproducibility

It is not yet a polished summary table.

To create report-ready summaries, you use:

  • summary()
  • Post-processing functions

This separation between calculation and summary is deliberate and powerful.

Strategies

  • Think in objects, not just functions.
  • Explicitly define intervals instead of relying on implicit behavior.
  • Inspect objects before running pk.nca().
  • Separate calculation from reporting in your workflow.

Worked Example (Conceptual Flow)

Imagine a single-dose study:

  1. Build PKNCAconc from observed concentration data.
  2. Build PKNCAdose from dosing records.
  3. Define interval 0–Inf with half-life estimation enabled.
  4. Combine via PKNCAdata.
  5. Run pk.nca().
  6. Inspect the PKNCAresults structure.
  7. Summarize for reporting.

Each stage is inspectable and scriptable.

Common Mistakes

Warning
  • Treating PKNCA as a single black-box function.
  • Ignoring how grouping variables define analysis units.
  • Confusing raw results with summarized outputs.
  • Failing to document interval rules.

Practice Problems

  1. Why does PKNCA separate concentration and dose objects?
  2. What role do intervals play in reproducibility?
  3. Why might directly exporting raw PKNCAresults be risky for reporting?

1. Separation purpose:
It enforces clarity between observed data and dosing design, reducing ambiguity.

2. Interval role:
Intervals encode design assumptions explicitly, ensuring consistent exposure calculations.

3. Reporting risk:
Raw results may not reflect required summaries (e.g., geometric means, CV%) and may include parameters not appropriate for final tables.

Summary

PKNCA’s strength lies in its structured object pipeline:

  • Define data clearly.
  • Encode study design via intervals.
  • Run calculations reproducibly.
  • Separate results from reporting.

Understanding this mental model prevents misuse and prepares you for deeper control over NCA options.

  • Inspect each object before moving to the next stage.
  • Keep grouping variables explicit.
  • Treat intervals as part of study design, not defaults.
  • Separate computation scripts from reporting scripts.