Enzyme Kinetics — Fit and Inspect

MODEL "Enzyme Kinetics — Fit and Inspect"
DESCRIPTION "Fit synthetic Michaelis–Menten observations, inspect residuals, predict a rate, and deliberately exercise convergence failure."
VERSION "1.0.0"
AUTHOR "Grid Team"
TAGS "biology", "research", "kinetics", "fitting", "charts"

# Five synthetic initial-rate observations; substrate is micromolar.
SubstrateData = {5, 10, 20, 40, 80}
RateData = {20, 33.3333333333333, 50, 66.6666666666667, 80}

input InitialVmax = 80
  VALIDATE BETWEEN 0.001 AND 100000 MESSAGE "The initial Vmax must be positive, in rate units."
input InitialKmMicromolar = 15
  VALIDATE BETWEEN 0.001 AND 100000 MESSAGE "The initial Km must be positive, in micromolar."
input PredictionSubstrateMicromolar = 20
  VALIDATE BETWEEN 0 AND 100000 MESSAGE "Prediction substrate must be nonnegative, in micromolar."
input IterationBudget = 200
  VALIDATE BETWEEN 1 AND 500 MESSAGE "Choose an integer iteration budget from 1 to 500."

# Fit log parameters so all trial Vmax and Km values are positive.
# The underlying operation retains its convergence diagnostics on failure.
output LogParameters = CURVE_FIT(
  (substrate, log_vmax, log_km) => EXP(log_vmax) * substrate / (EXP(log_km) + substrate),
  SubstrateData, RateData, {LN(InitialVmax), LN(InitialKmMicromolar)},
  1e-10, IterationBudget
)
FitSucceeded = NOT ISERROR(LogParameters)
output FittedVmax IS number = FitSucceeded THEN EXP(INDEX(LogParameters, 1, 1)) ELSE #N/A
output FittedKmMicromolar IS number = FitSucceeded THEN EXP(INDEX(LogParameters, 1, 2)) ELSE #N/A
PredictedData = FitSucceeded THEN MAP(SubstrateData, (substrate) => MICHAELIS_MENTEN_RATE(FittedVmax, substrate, FittedKmMicromolar)) ELSE #N/A
output Residuals = FitSucceeded THEN RateData - PredictedData ELSE #N/A
output ResidualSumSquares IS number = FitSucceeded THEN SUMSQ(Residuals) ELSE #N/A
output PredictedRate IS number = FitSucceeded THEN MICHAELIS_MENTEN_RATE(FittedVmax, PredictionSubstrateMicromolar, FittedKmMicromolar) ELSE #N/A
output FitStatus IS string = FitSucceeded THEN "Fit returned coefficients. Inspect residuals and assumptions before interpreting them." ELSE "Fit failed. Inspect LogParameters for the native failure class, context, and recovery advice."
output Assumptions IS string = "Unweighted least squares for initial rates; positive Vmax and Km; micromolar substrate and arbitrary rate units. The synthetic data give Vmax 100 and Km 20. Residuals are measured minus fitted. This example supplies no uncertainty intervals or proof of assay suitability. Predictions outside 5–80 micromolar are extrapolation."
output ScenarioGuide IS string = "Save Baseline. Change prediction substrate from 20 to 40: rate changes from 50 to about 66.6667. Set IterationBudget to 1 to inspect a convergence failure; restore 200 to recover. Reopen the saved archive or reset inputs to restore the baseline."

FitData = FitSucceeded THEN MAP(SEQUENCE(1, 5), (observation) => {
  substrate: INDEX(SubstrateData, 1, observation),
  measured: INDEX(RateData, 1, observation),
  fitted: INDEX(PredictedData, 1, observation)
}) ELSE []

A1 = "Fitted Vmax (rate units)"
B1 = FittedVmax
A2 = "Fitted Km (micromolar)"
B2 = FittedKmMicromolar
A3 = "Sum of squared residuals"
B3 = ResidualSumSquares
A4 = "Predicted rate"
B4 = PredictedRate
A6 = FitStatus
A7 = Assumptions
A8 = ScenarioGuide

Charts_1!type = "charts"
Charts_1!config = <toml>
  version = 1
  kind = "charts"
  title = "Enzyme initial-rate fit"
  [layout]
  title = "Synthetic observations and fitted rates"
  x_axis = "Substrate (micromolar)"
  y_axis = "Initial rate (arbitrary units)"
  [[charts]]
  type = "scatter"
  bind = "FitData"
  x = "substrate"
  y = "measured"
  label = "Synthetic observations"
  [[charts]]
  type = "line"
  bind = "FitData"
  x = "substrate"
  y = "fitted"
  label = "Fitted rate"
</toml>

END MODEL