Use SDTM as input

[Gero1999]

Issue

Closes #624, Closes #1086

Description

Adds SDTM (PC + EX + DM) as an alternative input format alongside the existing ADNCA path, both as R package functions and in the Shiny app.

Phase 1 — R package functions (R/sdtm_to_pknca.R)

Core conversion pipeline from SDTM domain data to PKNCAdata objects:

• sdtm_to_PKNCAdata(pc, ex, dm, metabolites) — top-level entry point. Accepts PC, EX, and optional DM data.frames, returns a PKNCAdata object ready for NCA computation.
• pc_to_PKNCAconc(pc, ex, dm) — converts PC domain to PKNCAconc. Derives timing variables (AFRLT, ARRLT, NFRLT, NRRLT), dose assignment (DOSNOA, ATPTREF), and merges DM demographics.
• ex_to_PKNCAdose(ex) — converts EX domain to PKNCAdose. Parses ISO 8601 durations, maps CDISC routes to PKNCA route values.
• Helper functions: parse_iso8601_duration(), route_cdisc_to_pknca(), std_dtc_to_rdate(), .check_required_cols(), .prepare_dose_table(), .assign_doses_to_conc().

Phase 2 — Example datasets

• pc_example, ex_example, dm_example — SDTM-format datasets derived from adnca_example via data-raw/sdtm_example.R.
• adnca_example updated to fix time-rounding issues that caused inconsistencies between SDTM and ADNCA paths.
• metadata_nca_variables extended with SDTM, PC, EX, DM domain rows for the mapping UI.

Phase 3 — Shiny app integration

• Upload step (data_upload.R): ADNCA/SDTM radio toggle. SDTM mode shows 3 file inputs (PC required, EX required, subject-level optional multi-file). Default SDTM example data loaded when no files uploaded.
• Mapping step (data_mapping.R): SDTM-specific mapping panel with sections (SDTM General, PC Concentrations, EX Dosing, Supplemental Variables). All SDTM input IDs prefixed with sdtm_ to avoid collisions with ADNCA inputs sharing the same variable names.
• NCA pipeline (tab_data.R): SDTM path calls sdtm_to_PKNCAdata() at the mapping step, then feeds the resulting PKNCAdata object into the existing NCA computation pipeline.
• Export (zip-utils.R): SDTM mode exports PC/EX/DM as separate RDS files and uses a dedicated script template (script_template_sdtm.R) that applies column mapping before calling sdtm_to_PKNCAdata().
• Settings (nca_setup.R): Settings YAML records input_mode and sdtm_metabolites.

Tests

• 60+ unit tests for the R conversion functions (test-sdtm_to_pknca.R).
• SDTM example dataset validation tests (test-sdtm_example_data.R).
• Round-trip NCA equivalence tests comparing SDTM and ADNCA paths produce consistent results.

Review guide

This PR is large. To make review manageable, the changes are split into 3 focused review-view PRs. Use these for code review — they show only the relevant files for each phase:

Phase	Review PR	What to review
1. R functions	#1328	Conversion logic, timing derivations, tests
2. Example data	#1329	Dataset generation, adnca_example fixes, metadata
3. Shiny app	#1330	Upload/mapping UI, export, settings

⚠️ The review-view PRs are not meant to be merged — they exist only to provide focused diffs. This PR (#1318) is the one to merge.

Definition of Done

• SDTM conversion functions work standalone via R script
• Shiny app supports SDTM upload, mapping, NCA computation, and export
• Settings save/restore works for SDTM mode
• SDTM script template applies column mapping
• Example SDTM datasets ship with the package
• NEWS entry added
• Package version incremented

How to test

1. R package path (code: #1328)

library(aNCA)
pknca_obj <- sdtm_to_PKNCAdata(pc_example, ex_example, dm_example)
str(pknca_obj)  # should be a PKNCAdata object
nrow(pknca_obj$conc$data)  # concentration rows
nrow(pknca_obj$dose$data)  # dose rows

2. Shiny app — default data (code: #1330)

1. Launch aNCA::run_app()
2. Select "SDTM" radio button
3. Click Submit without uploading files (uses example data)
4. Verify NCA results appear

3. Shiny app — custom data (code: #1330)

1. Upload PC and EX CSV files in SDTM format
2. Optionally upload a DM file
3. Adjust mapping if column names differ from standard
4. Run NCA

4. Export (code: #1330)

1. After running NCA in SDTM mode, download ZIP
2. Verify it contains input_pc.rds, input_ex.rds, input_dm.rds
3. Verify script_template_sdtm.R has column mapping applied

5. Settings round-trip (code: #1330)

1. Run NCA in SDTM mode
2. Download settings YAML — verify it contains input_mode: sdtm
3. Switch to ADNCA mode, upload the settings YAML
4. Verify it switches back to SDTM mode

Contributor checklist

• Code passes lintr checks
• Code passes all unit tests
• New logic covered by unit tests
• New logic is documented
• App or package changes are reflected in NEWS
• Package version is incremented
• R script works with the new implementation (if applicable)
• Settings upload works with the new implementation (if applicable)
• If any .scss change was done, run data-raw/compile_css.R
• If a package dependency was added/changed, run data-raw/test_suggests_hidden.R

Notes to reviewer

Expected SDTM input data

The app expects standard CDISC SDTM domains. Here are the columns used per domain:

PC — Pharmacokinetic Concentrations (required upload)

Column	Required	Description
STUDYID	✅	Study identifier
USUBJID	✅	Subject identifier
PCTEST	✅	Analyte name (maps to PARAM)
PCSTRESN	✅	Numeric concentration result (maps to AVAL)
PCSTRESU	✅	Concentration unit (maps to AVALU)
PCDTC	✅	Collection datetime (ISO 8601, e.g. 2025-01-15T08:30:00)
PCSPEC		Specimen type (e.g. PLASMA, URINE)
PCRFTDTC		Reference datetime for the most recent dose
PCELTM		Planned elapsed time from most recent dose (ISO 8601 duration, e.g. PT2H)
VOLUME		Urine volume (for urinary PK)
VOLUMEU		Volume unit

EX — Exposure / Dosing (required upload)

Column	Required	Description
STUDYID	✅	Study identifier
USUBJID	✅	Subject identifier
EXTRT	✅	Treatment name (maps to DOSETRT)
EXDOSE	✅	Dose amount (maps to DOSEA)
EXDOSU	✅	Dose unit
EXROUTE	✅	Route of administration (e.g. INTRAVENOUS, ORAL)
EXSTDTC	✅	Dosing start datetime (ISO 8601)
EXENDTC		Dosing end datetime — used to derive dose duration if EXDUR is absent
EXDUR		Dose duration (ISO 8601 duration, e.g. PT1H) — takes priority over EXENDTC
EXELTM		Planned elapsed time from first dose (ISO 8601 duration)

DM — Demographics (optional upload, labeled "Subject-level data" in the app)

Column	Required	Description
USUBJID	✅	Subject identifier (join key)
STUDYID		Study identifier (join key if present)
RFXSTDTC		Date/time of first study treatment — used as reference time if PCRFTDTC is absent
AGE		Subject age
AGEU		Age unit
SEX		Sex
RACE		Race
ARM		Planned treatment arm
ACTARM		Actual treatment arm

The app auto-maps columns by name. If column names differ from the standard, users can remap them in the mapping step. The mapping UI also supports WTBL/WTBLU (baseline weight) and custom grouping variables.

Code review

For manual code review, use the phase-specific PRs linked in the Review guide above — each shows only the relevant subset of files. This PR contains the full integrated diff.