---
title: "Getting started with vmxr"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting started with vmxr}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE, purl = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", eval = FALSE, purl = FALSE)
```

`vmxr` is a native R client for the VeloMetrix API. It collapses the
upload → prep → data-version → NCA / modeling / simulation
workflow into a few pipe-friendly verbs that block-and-poll for you and return
tibbles and typed S3 objects.

> The examples below are not evaluated (they need a live API + token). Set
> `VMX_API_BASE_URL` / `VMX_API_TOKEN` and run them in your session.

## Authentication

`vmxr` uses the same mental model as the CLI: a base URL and an Authentik PAT,
read from the environment (or `~/.Renviron`).

```{r, purl = FALSE}
# ~/.Renviron
# VMX_API_BASE_URL=https://vmx-api.staging.gnrbl.co
# VMX_API_TOKEN=pat_...

library(vmxr)
vmx_whoami()   # confirms the PAT works
```

## The whole workflow, in-session

```{r, purl = FALSE}
tmt   <- vmx_treatment_create("Compound XYZ", indication = "atrial fibrillation")
study <- vmx_study_create(tmt, "Phase 1 SAD", phase = "1")

ds <- vmx_upload(study, files = c("conc.csv", "dosing.csv"),
                 mode = "initial", wait = TRUE)

dv  <- vmx_data_version(vmx_prep_status(ds)$data_version_id)
nca <- vmx_nca(dv, time_basis = "observed")   # creates + waits

vmx_nca_result(nca)
```

## Model-ready data into R

```{r, purl = FALSE}
dv <- vmx_data_version("dv_...")

# tidy domain tables
vmx_pk(dv)         # PK observations + events
vmx_subjects(dv)   # one row per subject (covariates)

# or the whole bundle at once
md <- vmx_model_data(dv)
md$pk; md$subjects; md$meta
```

## Fit a model and pull diagnostics

```{r, purl = FALSE}
run <- vmx_model_build(dv, time_basis = "observed", wait = TRUE)
fit <- vmx_model_fits(run = run) |> dplyr::slice(1) |> dplyr::pull(model_fit_id) |> vmx_model_fit()

vmx_fit_global_estimates(fit)   # population parameters + credible intervals
vmx_fit_obs_vs_pred(fit)        # tidy observed-vs-predicted
```

See the design proposal in `docs/r-client-design.md` for the full intended API,
including the planned nlmixr2 / Stan·Torsten adapters.