% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nm_scale.R
\name{nonmem_scaling}
\alias{nonmem_scaling}
\title{Compute S1 scaling expression for NONMEM}
\usage{
nonmem_scaling(
  dv_unit,
  amt_unit,
  v_unit,
  sig_digits = 8L,
  example = FALSE,
  example_amt = 1,
  example_v = 1
)
}
\arguments{
\item{dv_unit}{Character scalar. DV concentration unit, e.g. "ng/mL", "mg/L", "ug per mL".}

\item{amt_unit}{Character scalar. AMT unit (mass), e.g. "mg", "ug", "ng".}

\item{v_unit}{Character scalar. Unit for model volume parameter V, e.g. "L", "mL".}

\item{sig_digits}{Integer scalar. Significant digits for formatted output (default = 8).}

\item{example}{Logical scalar. If TRUE, include a numeric example (default = FALSE).}

\item{example_amt}{Numeric scalar. Example AMT value (default = 1).}

\item{example_v}{Numeric scalar. Example V value (default = 1).}
}
\value{
A list with elements:
\describe{
  \item{factor}{Numeric. The multiplicative factor such that S1 = V * factor.}
  \item{S1_expression}{Character. NONMEM-ready expression (e.g. "S1 = V/1000").}
  \item{explanation}{Character. Human-readable explanation of the derivation.}
  \item{example}{Named list (present only when \code{example = TRUE}) with numeric example.}
}
}
\description{
Given the units used in your dataset/model for the dependent variable (DV,
a concentration like "ng/mL"), the dosing amount (AMT, e.g. "mg") and the
model volume parameter V (e.g. "L" or "mL"), this function returns a robust
NONMEM-ready S1 expression so that \code{A(n)/S1} has the same units as DV.

The function:
\itemize{
  \item parses common unit notations and synonyms (e.g. "ug", "mcg"),
  \item validates input and provides informative errors,
  \item computes the numeric factor such that \code{S1 = V * factor},
  \item returns a human-readable explanation and an optional numeric example.
}
}
\details{
Compute NONMEM S1 scaling from concentration, amount, and volume units
}
\examples{
# Typical PK: DV in ng/mL, AMT in mg, V in L -> S1 = V * 1e+06 / 1000 = V * 1000
nonmem_scaling("ng/mL", "mg", "L")

# If V is stored in mL:
nonmem_scaling("ng/mL", "mg", "mL")

# With numeric example
nonmem_scaling("ng/mL", "mg", "L", example = TRUE, example_amt = 100, example_v = 40)

# Microgram dosing
nonmem_scaling("pg/mL", "ug", "L")

}
