matlab-fit-simbiology-model

Name: matlab-fit-simbiology-model
Author: matlab

815stars105forks

How to install matlab-fit-simbiology-model?

matlab/matlab-agentic-toolkit/matlab-fit-simbiology-model

$npx -y skills add matlab/matlab-agentic-toolkit --skill matlab-fit-simbiology-model

Installs into the current project.

Summary

Fit SimBiology model parameters to data — fitproblem, population NLME, virtual patients, and NCA. Use when asked to fit, estimate, calibrate, or compute PK metrics.

Files · 1

View on GitHub

SKILL.md

1	# Fit SimBiology Models
2
3	Estimate parameters from data using `fitproblem`, fit population models
4	with NLME, generate virtual patients, and compute NCA metrics.
5
6	## When to Use
7
8	- "fit", "estimate", "calibrate" model parameters
9	- Parameter estimation from experimental/observed data
10	- Population PK/PD, NLME, mixed effects, inter-individual variability
11	- Virtual patients, virtual cohorts
12	- NCA, AUC, Cmax, Tmax, half-life, clearance
13	- Keywords: "fit", "estimate", "calibrate", "population", "NCA", "AUC"
14
15	## When NOT to Use
16
17	- Model construction or diagram (use `matlab-build-simbiology-model`)
18	- Simulation without fitting (use `matlab-simulate-simbiology-model`)
19	- Sensitivity analysis (use `matlab-simulate-simbiology-model`)
20
21	## Must-Follow Rules
22
23	### 1. Use `fitproblem` for parameter estimation
24
25	Always use `fitproblem` instead of calling `sbiofit` or `sbiofitmixed`
26	directly. `fitproblem` provides a unified, declarative interface:
27	```matlab
28	prob = fitproblem;
29	prob.Model = model;
30	prob.Data = data;
31	prob.ResponseMap = "Species = DataColumn";
32	prob.Estimated = estimatedInfo({'param'}, 'Bounds', [lo hi]);
33	results = fit(prob);
34	```
35	Do NOT call `sbiofit(model, data, ...)` or `sbiofitmixed(model, data, ...)`
36	directly — their positional argument signatures are error-prone.
37
38	### 2. Fitting requires `groupedData`, NOT a plain table
39
40	Always wrap data:
41	```matlab
42	data = groupedData(table(...));
43	data.Properties.IndependentVariableName = 'Time';
44	```
45
46	### 3. `ResponseMap` maps model outputs to data columns
47
48	Format is always `"ModelOutput = DataColumnName"`:
49
50	```matlab
51	% Single compartment — use species name on the left
52	prob.ResponseMap = "Drug = DrugConc";
53
54	% Multi-compartment — use qualified name to disambiguate
55	prob.ResponseMap = "Central.Drug = DrugConc";
56
57	% When species name matches data column name, still use the = format
58	prob.ResponseMap = "Drug = Drug";
59	```
60
61	Use the unqualified species name unless the same species name exists
62	in multiple compartments (then qualify with `Compartment.Species`).
63
64	### 4. Always set bounds
65
66	Prevent non-physical values (negative rates, etc.):
67	```matlab
68	estimParams = estimatedInfo({'ke','ka'}, ...
69	'InitialValue', [0.2, 1.0], ...
70	'Bounds', [0.01 1; 0.1 5]);
71	```
72
73	### 5. Use log transform for rate constants
74
75	Parameters spanning orders of magnitude (clearances, rate constants)
76	benefit from log-transform estimation. Set `.Transform` after creation:
77	```matlab
78	ei = estimatedInfo({'ke','ka'}, 'InitialValue', [0.1, 0.5], 'Bounds', [0.01 1; 0.1 5]);
79	ei(1).Transform = 'log';
80	ei(2).Transform = 'log';
81	```
82
83	Alternative: use `'log(param)'` name syntax (equivalent result):
84	```matlab
85	ei = estimatedInfo({'log(ke)','log(ka)'}, 'InitialValue', [0.1, 0.5], 'Bounds', [0.01 1; 0.1 5]);
86	```
87
88	Important: `InitialValue` and `Bounds` are always in the
89	untransformed (natural) domain. Do NOT pass `log(value)`.
90
91	Available transforms: `'log'`, `'logit'`, `'probit'`
92
93	Do NOT pass `'Transform'` as a name-value pair to the `estimatedInfo`
94	constructor — it errors. Always set the `.Transform` property after.
95
96	### 6. Error models for population fitting
97
98	Choose the error model that matches the noise structure:
99	- `'constant'` — absolute noise uniform
100	- `'proportional'` — noise scales with magnitude (most PK data)
101	- `'combined'` — both constant and proportional
102	- `'exponential'` — log-normal residual
103
104	### 7. NCA requires `sbioncaoptions` object
105
106	Do not use name-value pairs. Column names are camelCase.
107	EVDose column uses `NaN` for non-dose rows.
108
109	## Decision Table
110
111	\| Scenario \| Approach \|
112	\|----------\|----------\|
113	\| Single subject or pooled fit \| `fitproblem` with `FitFunction="sbiofit"` \|
114	\| Individual fits per subject \| `fitproblem` with `Pooled=false` \|
115	\| Population NLME (IIV, random effects) \| `fitproblem` with `FitFunction="sbiofitmixed"` \|
116	\| Model-independent PK metrics \| `sbionca` \|
117
118	## `fitproblem` Workflow (Preferred)
119
120	Use `fitproblem` for all parameter estimation. It provides a unified,
121	declarative interface that replaces direct calls to `sbiofit`/`sbiofitmixed`:
122
123	```matlab
124	% 1. Prepare data
125	data = groupedData(table(tSample, yData, 'VariableNames', {'Time','Drug'}));
126	data.Properties.IndependentVariableName = 'Time';
127
128	% 2. Define parameters with bounds
129	estimParams = estimatedInfo({'ke','ka'}, ...
130	'InitialValue', [0.2, 1.0], ...
131	'Bounds', [0.01 1; 0.1 5]);
132
133	% 3. Build the fit problem
134	prob = fitproblem;
135	prob.Model = model;
136	prob.Data = data;
137	prob.ResponseMap = "Drug = Drug";
138	prob.Estimated = estimParams;
139	prob.Doses = dose; % optional
140	prob.FunctionName = 'scattersearch';
141	prob.ProgressPlot = true; % show live progress
142
143	% 4. Fit
144	results = fit(prob);
145
146	% 5. Inspect
147	disp(results.ParameterEstimates

People who liked this also viewed

6 picks

Type

matlab-fit-simbiology-model

815stars105forks

View on GitHub

How to install matlab-fit-simbiology-model?

matlab/matlab-agentic-toolkit/matlab-fit-simbiology-model

$npx -y skills add matlab/matlab-agentic-toolkit --skill matlab-fit-simbiology-model

Installs into the current project.

Summary

Fit SimBiology model parameters to data — fitproblem, population NLME, virtual patients, and NCA. Use when asked to fit, estimate, calibrate, or compute PK metrics.

Files · 1

View on GitHub

SKILL.md

1	# Fit SimBiology Models
2
3	Estimate parameters from data using `fitproblem`, fit population models
4	with NLME, generate virtual patients, and compute NCA metrics.
5
6	## When to Use
7
8	- "fit", "estimate", "calibrate" model parameters
9	- Parameter estimation from experimental/observed data
10	- Population PK/PD, NLME, mixed effects, inter-individual variability
11	- Virtual patients, virtual cohorts
12	- NCA, AUC, Cmax, Tmax, half-life, clearance
13	- Keywords: "fit", "estimate", "calibrate", "population", "NCA", "AUC"
14
15	## When NOT to Use
16
17	- Model construction or diagram (use `matlab-build-simbiology-model`)
18	- Simulation without fitting (use `matlab-simulate-simbiology-model`)
19	- Sensitivity analysis (use `matlab-simulate-simbiology-model`)
20
21	## Must-Follow Rules
22
23	### 1. Use `fitproblem` for parameter estimation
24
25	Always use `fitproblem` instead of calling `sbiofit` or `sbiofitmixed`
26	directly. `fitproblem` provides a unified, declarative interface:
27	```matlab
28	prob = fitproblem;
29	prob.Model = model;
30	prob.Data = data;
31	prob.ResponseMap = "Species = DataColumn";
32	prob.Estimated = estimatedInfo({'param'}, 'Bounds', [lo hi]);
33	results = fit(prob);
34	```
35	Do NOT call `sbiofit(model, data, ...)` or `sbiofitmixed(model, data, ...)`
36	directly — their positional argument signatures are error-prone.
37
38	### 2. Fitting requires `groupedData`, NOT a plain table
39
40	Always wrap data:
41	```matlab
42	data = groupedData(table(...));
43	data.Properties.IndependentVariableName = 'Time';
44	```
45
46	### 3. `ResponseMap` maps model outputs to data columns
47
48	Format is always `"ModelOutput = DataColumnName"`:
49
50	```matlab
51	% Single compartment — use species name on the left
52	prob.ResponseMap = "Drug = DrugConc";
53
54	% Multi-compartment — use qualified name to disambiguate
55	prob.ResponseMap = "Central.Drug = DrugConc";
56
57	% When species name matches data column name, still use the = format
58	prob.ResponseMap = "Drug = Drug";
59	```
60
61	Use the unqualified species name unless the same species name exists
62	in multiple compartments (then qualify with `Compartment.Species`).
63
64	### 4. Always set bounds
65
66	Prevent non-physical values (negative rates, etc.):
67	```matlab
68	estimParams = estimatedInfo({'ke','ka'}, ...
69	'InitialValue', [0.2, 1.0], ...
70	'Bounds', [0.01 1; 0.1 5]);
71	```
72
73	### 5. Use log transform for rate constants
74
75	Parameters spanning orders of magnitude (clearances, rate constants)
76	benefit from log-transform estimation. Set `.Transform` after creation:
77	```matlab
78	ei = estimatedInfo({'ke','ka'}, 'InitialValue', [0.1, 0.5], 'Bounds', [0.01 1; 0.1 5]);
79	ei(1).Transform = 'log';
80	ei(2).Transform = 'log';
81	```
82
83	Alternative: use `'log(param)'` name syntax (equivalent result):
84	```matlab
85	ei = estimatedInfo({'log(ke)','log(ka)'}, 'InitialValue', [0.1, 0.5], 'Bounds', [0.01 1; 0.1 5]);
86	```
87
88	Important: `InitialValue` and `Bounds` are always in the
89	untransformed (natural) domain. Do NOT pass `log(value)`.
90
91	Available transforms: `'log'`, `'logit'`, `'probit'`
92
93	Do NOT pass `'Transform'` as a name-value pair to the `estimatedInfo`
94	constructor — it errors. Always set the `.Transform` property after.
95
96	### 6. Error models for population fitting
97
98	Choose the error model that matches the noise structure:
99	- `'constant'` — absolute noise uniform
100	- `'proportional'` — noise scales with magnitude (most PK data)
101	- `'combined'` — both constant and proportional
102	- `'exponential'` — log-normal residual
103
104	### 7. NCA requires `sbioncaoptions` object
105
106	Do not use name-value pairs. Column names are camelCase.
107	EVDose column uses `NaN` for non-dose rows.
108
109	## Decision Table
110
111	\| Scenario \| Approach \|
112	\|----------\|----------\|
113	\| Single subject or pooled fit \| `fitproblem` with `FitFunction="sbiofit"` \|
114	\| Individual fits per subject \| `fitproblem` with `Pooled=false` \|
115	\| Population NLME (IIV, random effects) \| `fitproblem` with `FitFunction="sbiofitmixed"` \|
116	\| Model-independent PK metrics \| `sbionca` \|
117
118	## `fitproblem` Workflow (Preferred)
119
120	Use `fitproblem` for all parameter estimation. It provides a unified,
121	declarative interface that replaces direct calls to `sbiofit`/`sbiofitmixed`:
122
123	```matlab
124	% 1. Prepare data
125	data = groupedData(table(tSample, yData, 'VariableNames', {'Time','Drug'}));
126	data.Properties.IndependentVariableName = 'Time';
127
128	% 2. Define parameters with bounds
129	estimParams = estimatedInfo({'ke','ka'}, ...
130	'InitialValue', [0.2, 1.0], ...
131	'Bounds', [0.01 1; 0.1 5]);
132
133	% 3. Build the fit problem
134	prob = fitproblem;
135	prob.Model = model;
136	prob.Data = data;
137	prob.ResponseMap = "Drug = Drug";
138	prob.Estimated = estimParams;
139	prob.Doses = dose; % optional
140	prob.FunctionName = 'scattersearch';
141	prob.ProgressPlot = true; % show live progress
142
143	% 4. Fit
144	results = fit(prob);
145
146	% 5. Inspect
147	disp(results.ParameterEstimates

People who liked this also viewed

6 picks

Type