---
title: "Running nlmixr2autoinit"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Running nlmixr2autoinit}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 7,
  fig.height = 4
)
```

## Overview

`nlmixr2autoinit` is a tool for automatically generating initial parameter estimates 
for PopPK models, using adaptive single-point methods, naïve pooled NCA, graphic methods, 
and simulation-based parameter sweeping to initialize both structural and statistical parameters. 
Details of the methods are described in https://doi.org/10.1007/s10928-025-10000-z.

## Getting Started
To get started, you need:

- **A concentration–time dataset** in standard nlmixr2-style format. The key required columns are:

| Column | Description |
|--------|-------------|
| `ID`   | Subject identifier |
| `TIME` | Time after first dose (hours) |
| `AMT`  | Dose amount (for dosing records) |
| `DV`   | Observed concentration (for observation records) |
| `EVID` | Event ID: `0` = observation, `1` = dose |

Additional columns such as `MDV` (missing dependent variable) and `ADDL`/`II` (additional doses/interdose interval) are supported when present.

You can inspect the built-in example datasets to see the expected structure:

```{r data-structure}
library(nlmixr2autoinit)
head(Bolus_1CPT)
```

### Supported data

`nlmixr2autoinit` is compatible with a wide range of PK data types and study designs.

```{r supported-data, echo=FALSE, results='asis'}
htmltools::tags$div(
  style = "display: grid; grid-template-columns: repeat(3, 1fr); gap: 12px; margin: 1rem 0;",
  htmltools::tags$div(
    style = "background: #ffffff; border: 1px solid #e2e8f0; border-radius: 10px; padding: 1rem 1.25rem;",
    htmltools::tags$p(style = "font-size: 13px; font-weight: 600; color: #1e293b; margin: 0 0 10px; text-transform: uppercase; letter-spacing: 0.04em;", "Dose routes"),
    htmltools::tags$div(style = "display: flex; flex-direction: column; gap: 6px; font-size: 15px; color: #1e293b;",
      htmltools::tags$span("✅ IV bolus"),
      htmltools::tags$span("✅ IV infusion"),
      htmltools::tags$span("✅ Extravascular dosing")
    )
  ),
  htmltools::tags$div(
    style = "background: #ffffff; border: 1px solid #e2e8f0; border-radius: 10px; padding: 1rem 1.25rem;",
    htmltools::tags$p(style = "font-size: 13px; font-weight: 600; color: #1e293b; margin: 0 0 10px; text-transform: uppercase; letter-spacing: 0.04em;", "Dosing regimens"),
    htmltools::tags$div(style = "display: flex; flex-direction: column; gap: 6px; font-size: 15px; color: #1e293b;",
      htmltools::tags$span("✅ Single dose"),
      htmltools::tags$span("✅ Multiple dose"),
      htmltools::tags$span("✅ Mixed single & multiple dose")
    )
  ),
  htmltools::tags$div(
    style = "background: #ffffff; border: 1px solid #e2e8f0; border-radius: 10px; padding: 1rem 1.25rem;",
    htmltools::tags$p(style = "font-size: 13px; font-weight: 600; color: #1e293b; margin: 0 0 10px; text-transform: uppercase; letter-spacing: 0.04em;", "Data types"),
    htmltools::tags$div(style = "display: flex; flex-direction: column; gap: 6px; font-size: 15px; color: #1e293b;",
      htmltools::tags$span("✅ Rich data"),
      htmltools::tags$span("✅ Sparse data"),
      htmltools::tags$span("✅ Mixed rich & sparse data")
    )
  )
)
```

> Mixed dose routes and datasets where all subjects share a single identical time point are not supported.

## Run an example

Call `getPPKinits()` with your dataset. The function automatically detects the route of administration and data characteristics.

```{r iv-example, eval = FALSE}
library(nlmixr2autoinit)
outs <- getPPKinits(dat = theo_sd)
```

To review the detected data information:
```{r datainfo, eval = FALSE}
outs$Datainfo
```

```{r datainfo-output, echo = FALSE}
cat('                              Infometrics      Value
1                              Dose Route       oral
2                               Dose Type first_dose
3                      Number of Subjects         12
4                  Number of Observations        123
5  Subjects with First-Dose Interval Data         12
6 Observations in the First-Dose Interval        123
7        Subjects with Multiple-Dose Data          0
8       Observations after Multiple Doses          0
')
```

The recommended initial estimates, automatically selected by the algorithm, can be accessed directly via:

```{r iv-print, eval = FALSE}
outs$Recommended_initial_estimates
#            Parameters               Methods   Values
# 1                  Ka Naive pooled NCA (FD)   1.5800
# 2                  CL Naive pooled NCA (FD)   3.0400
# 3                  Vd Naive pooled NCA (FD)  33.0000
# 4                Vmax    Parameter sweeping 105.3596
# 5                  Km    Parameter sweeping  35.0367
# 6           Vc(2CMPT)    Parameter sweeping  31.9000
# 7           Vp(2CMPT)    Parameter sweeping   3.1900
# 8            Q(2CMPT)    Parameter sweeping   6.0800
# 9           Vc(3CMPT)    Parameter sweeping  31.9000
# 10          Vp(3CMPT)    Parameter sweeping   3.1900
# 11         Vp2(3CMPT)    Parameter sweeping   3.1900
# 12           Q(3CMPT)    Parameter sweeping   6.0800
# 13          Q2(3CMPT)    Parameter sweeping   6.0800
# 14     Sigma additive           Model-based   0.1065
# 15 Sigma proportional           Model-based   0.0262
```

## Inspecting the Run History

`$Run.history` records every method combination attempted and evaluated through the pipeline. To access any component, use `<outname>$Run.history$<component>`.

| Component | Description |
|---|---|
| `$base.out` | Method combinations and performance metrics for base PK parameters ($K_a$, $CL$, $V_d$) |
| `$sim.2cmpt` | Simulated parameters for 2-compartment models |
| `$sim.3cmpt` | Simulated parameters for 3-compartment models |
| `$sim.vmax.km` | Simulated $V_{max}$ and $K_m$ values |
| `$single.point.out` | Results from single-point estimation methods |
| `$nca.out` | Results from NCA-based estimation |
| `$ka.wanger.nelson` | Results from Wagner-Nelson method for $K_a$ estimation |
| `$graph.out` | Results from graphical estimation methods |
| `$sigma.out` | Results from residual variability estimation |

For example, the estimation details for the base PK parameters ($CL$, $V_d$, and $K_a$) can be accessed via:

```{r run-history, eval = FALSE}
outs$Run.history$base.out
```

We can see that each row represents a unique combination of estimation methods for $K_a$, $CL$, and $V_d$, and how each combination performs when the resulting parameters are used to predict the observed concentration–time data allowing the best-performing combination to be selected automatically.

```{r run-history-base, echo = FALSE}
cat('  Ka Method CL Method Vd Method    Ka     CL    Vd     APE    MAE   MAPE   RMSE  rRMSE1  rRMSE2  min_count  metrics.rank
1    simpcal   simpcal   simpcal 0.858   2.04  22.1  244.081  1.984  47.623  2.388  44.851  52.053          0             7
2      graph     graph     graph 1.550   2.97  31.9  136.998  1.114  28.773  1.449  27.227  44.965          0             2
3     nca_fd    nca_fd    nca_fd 1.580   3.04  33.0  137.533  1.118  28.216  1.466  27.533  44.926          1             1
4      graph   simpcal   simpcal 1.550   2.04  22.1  293.129  2.383  60.335  2.836  53.277  56.930          0             9
5    simpcal     graph   simpcal 0.858   2.97  22.1  175.088  1.423  34.700  1.788  33.591  49.650          0             5
6      graph     graph   simpcal 1.550   2.97  22.1  226.693  1.843  48.796  2.321  43.601  56.119          0             8
7    simpcal   simpcal     graph 0.858   2.04  31.9  175.953  1.431  37.066  1.812  34.032  50.086          0             6
8      graph   simpcal     graph 1.550   2.04  31.9  162.314  1.320  40.016  1.558  29.260  48.782          0             4
9    simpcal     graph     graph 0.858   2.97  31.9  150.146  1.221  25.191  1.705  32.033  45.691          0             3
')
```

**Note:** `metrics.rank` ranks all method combinations by predictive performance (rank 1 = best), based on the metric specified in `initsControl()` (default: `rRMSE2`). The combination with rank 1 is used as the recommended initial estimates. `min_count` indicates how many metrics are simultaneously at their minimum for a given method combination when multiple metrics are used as selection criteria.

## Controlling the Pipeline

`getPPKinits()` accepts a `control` argument via `initsControl()` to customise the pipeline behaviour. For example, you can enable a fallback value of $K_a = 1$, `nlmixr2autoinit` will assign $K_a = 1$ if the default algorithm is unable to compute it automatically from the dataset:

```{r control-example, eval = FALSE}
inits.out <- getPPKinits(
  dat = theo_md,
  control = initsControl(
    fallback.control = fallback_control(enable_ka_fallback = TRUE)
  )
)
```

See `?initsControl` for the full list of options.

## What's Next?

- **[Integration with nlmixr2](workflow_nlmixr2.html)** — learn how to pass these initial estimates directly into an `nlmixr2` model definition.
- **[Integration with nlmixr2auto](workflow_nlmixr2auto.html)** — trigger automated model selection with `nlmixr2auto`.
- **[Parameter Sweeping and Visualisation](parameter_sweeping.html)** — explore how parameter sweeping works and how to visualise the sweep results.

