generateCGNM_script: generateCGNM_script

In CGNM: Cluster Gauss-Newton Method

generateCGNM_script

Description

Programmatic (non-GUI) equivalent of the shinyCGNM app's "make CGNM script" workflow. Takes the ODE model text and the same three tables the shinyCGNM app uses (parameter info, observed data, and dose data), runs the same validation checks the app performs on those tables (ODE compiles, dosing targets a real compartment, every referenced parameter has a range, observed values are numeric, residual error model is 0/1, ...), and returns the generated R script (an rxode2-based model function plus a Cluster_Gauss_Newton_method/Cluster_Gauss_Newton_Bootstrap_method call) as a character string, ready to be written to a file, cat()'d, or eval(parse(text = .))'d directly.

Usage

generateCGNM_script(
  ODE_text,
  parameterInfo_table,
  observedData_table,
  doseData_table = NA,
  initialConditionData_table = NA,
  runName = "",
  num_minimizersToFind = 250,
  num_iteration = 25,
  bootstrap = TRUE,
  parallel = "none",
  includeMiddleOutCode = FALSE,
  includeSimulationCode = FALSE,
  simulationDoseData_table = NA,
  simulationTimepoints_table = NA,
  scriptFileName = NA
)

Arguments

ODE_text	(required input) string the ODE model, written in rxode2 syntax (see rxode2::RxODE()). Its state variables become the compartments doseData_table$dosing.to and initialConditionData_table$state can target, and its parameters (together with any free symbols used in doseData_table's dose/start.time/rate columns and initialConditionData_table's value column) are the parameters parameterInfo_table must provide ranges for.
parameterInfo_table	(required input) data.frame one row per parameter. Required columns: ParameterName, Initial_lower_range, Initial_upper_range. Optional columns (defaulted if absent): Lower_bound (default 0), Upper_bound (default NA), VaryByID (default 0; 0=shared across IDs, 3=vary by the first 3 characters of ID, any other nonzero value=vary by the full ID), MO_weight (default 0), MO_value (default NA), Unit (default NA). See make_ShinyCGNM_parameterInfo.
observedData_table	(required input) data.frame one row per observation. Required columns: ID, time, Observation_expression, Observed_value. Optional columns (defaulted if absent): ResidualError_model (default 0; 0=additive, 1=relative), Memo (default NA). See make_ShinyCGNM_observationData.
doseData_table	(default: NA) data.frame or NA one row per dosing event. Required columns if supplied: ID, dose, dosing.to, start.time. Optional columns (defaulted if absent): rate (default NA, i.e. bolus dose), nbr.doses (default 1), dosing.interval (default NA). Set to NA (the default) if the model has no dosing events. See make_ShinyCGNM_doseData.
initialConditionData_table	(default: NA) data.frame or NA one row per (ID, compartment) whose initial condition (the value of that ODE state variable at time 0) should be set explicitly, instead of implicitly deriving it purely from dosing. Required columns: ID, state (a compartment name defined by ODE_text), value (a number, or an expression that may reference a parameter name, mirroring doseData_table's dose column). Set to NA (the default) if every compartment should simply start at 0. doseData_table and initialConditionData_table are independent and may be used together, separately, or not at all for a given ID: any dosing events are simulated on top of whatever initial condition is set (or 0, if none is set) for that compartment, exactly as rxode2's own inits argument to solve() composes with an eventTable. See make_ShinyCGNM_initialCondition.
runName	(default: "") string passed through to Cluster_Gauss_Newton_method's runName; also used to name the generated model function. Punctuation is stripped and spaces are replaced with underscores, matching shinyCGNM's behavior.
num_minimizersToFind	(default: 250) positive integer passed through as Cluster_Gauss_Newton_method's num_minimizersToFind.
num_iteration	(default: 25) positive integer passed through as Cluster_Gauss_Newton_method's num_iteration.
bootstrap	(default: TRUE) logical if TRUE the generated script also calls Cluster_Gauss_Newton_Bootstrap_method on the fit.
parallel	(default: "none") "none", "win", or "mac" if not "none", the generated model function is wrapped for parallel evaluation using doParallel ("win") or parallel::mclapply ("mac"), matching the parallel computation options offered in shinyCGNM.
includeMiddleOutCode	(default: FALSE) logical if TRUE, appends a post-hoc middle-out code template (postHoc_likelihood() plus a plot_profileLikelihood() call using it) after the main script, matching shinyCGNM's "download post-hoc middle-out code" button. This is a separate mechanism from the built-in MO_weight/MO_value columns in parameterInfo_table (which bake the middle-out constraint into the CGNM search itself): this one applies a user-adjustable constraint to an *already-fit* CGNM_result instead, only once you edit the generated weight_<ParameterName> values from their default of 0.
includeSimulationCode	(default: FALSE) logical if TRUE, appends a second, simulation-only model function (built the same way as the main one, but skipping Observed_value) plus a plot_simulationWithCI() call, matching shinyCGNM's simulation tab. Requires bootstrap = TRUE (the simulation code needs CGNM_result$bootstrapParameterCombinations for the confidence band) and simulationTimepoints_table. Any rows of initialConditionData_table whose ID matches an ID used in the simulation still apply to it; there is no separate simulation-only initial condition table.
simulationDoseData_table	(default: NA) data.frame or NA the dosing regimen to simulate, in the same shape as doseData_table (and independently validated the same way) &mdash; only used when includeSimulationCode = TRUE. This can differ from doseData_table (e.g. a new hypothetical regimen); set to NA if the simulation has no dosing.
simulationTimepoints_table	(default: NA) data.frame, required when includeSimulationCode = TRUE the time points/variables to simulate. Required columns: ID, time, Observation_expression (no Observed_value or ResidualError_model, since nothing is being fit here). Unlike observedData_table$Observation_expression, this one is not evaluated as an R expression: the simulation code dumps every compartment/derived (LHS) variable from the ODE and merges by exact name, so each entry here must exactly match one of ODE_text's state or LHS variable names (e.g. "C_central", not "log10(C_central)"). If parameterInfo_table has any individually-varying parameter (VaryByID != 0), every ID referenced here (and in simulationDoseData_table) must already be one of the IDs in doseData_table/observedData_table, since the bootstrap result only has fitted values for those IDs.
scriptFileName	(default: NA) NA or string if not NA, the generated script is additionally written to this file path with writeLines().

Value

string the generated R script.

Examples

## Not run: 
ODE_text="
d/dt(depot) = -ka*depot
d/dt(central) = ka*depot - (CL/V1)*central
C_central = central/V1
"

parameterInfo_table=make_ShinyCGNM_parameterInfo(
  ParameterName=c("ka","CL","V1"),
  Initial_lower_range=c(0.01,0.01,0.01),
  Initial_upper_range=c(100,100,100)
)

doseData_table=make_ShinyCGNM_doseData(
  ID="1", dose=1000, dosing.to="depot", start.time=0, rate=NA,
  nbr.doses=1, dosing.interval=NA
)

observedData_table=make_ShinyCGNM_observationData(
  ID="1",
  time=c(0.1, 0.2, 0.4, 0.6, 1, 2, 3, 6, 12),
  Observation_expression="log10(C_central)",
  Observed_value=log10(c(4.91, 8.65, 12.4, 18.7, 24.3, 24.5, 18.4, 4.66, 0.238)),
  ResidualError_model=0
)

script_text=generateCGNM_script(
  ODE_text=ODE_text,
  parameterInfo_table=parameterInfo_table,
  observedData_table=observedData_table,
  doseData_table=doseData_table,
  runName="oral1cpt"
)

cat(script_text)
eval(parse(text=script_text))

## Same model, but with an explicit initial condition instead of (or in addition
## to) a dose: e.g. central starts at 5 instead of implicitly at 0.
initialConditionData_table=make_ShinyCGNM_initialCondition(
  ID="1", state="central", value=5
)
script_text_withInit=generateCGNM_script(
  ODE_text=ODE_text,
  parameterInfo_table=parameterInfo_table,
  observedData_table=observedData_table,
  doseData_table=doseData_table,
  initialConditionData_table=initialConditionData_table,
  runName="oral1cpt_withInit"
)

## Same fit, plus a post-hoc middle-out template and a simulation of a denser time
## grid at a higher dose (bootstrap = TRUE is required for the simulation part).
## note: unlike observedData_table, Observation_expression here must be an exact
## compartment/derived-variable name from ODE_text (e.g. "C_central"), not an
## expression like "log10(C_central)" - it is not evaluated, only matched by name.
simulationTimepoints_table=make_ShinyCGNM_simulationTimepoints(
  ID="1", time=seq(0.1,12,by=0.1), Observation_expression="C_central"
)
simulationDoseData_table=make_ShinyCGNM_doseData(
  ID="1", dose=2000, dosing.to="depot", start.time=0, rate=NA,
  nbr.doses=1, dosing.interval=NA
)
script_text_full=generateCGNM_script(
  ODE_text=ODE_text,
  parameterInfo_table=parameterInfo_table,
  observedData_table=observedData_table,
  doseData_table=doseData_table,
  runName="oral1cpt_full",
  bootstrap=TRUE,
  includeMiddleOutCode=TRUE,
  includeSimulationCode=TRUE,
  simulationDoseData_table=simulationDoseData_table,
  simulationTimepoints_table=simulationTimepoints_table
)

## End(Not run)

CGNM documentation built on Sept. 13, 2026, 9:06 a.m.