Every non-Simulink capability of this toolbox — global sensitivity analysis (Sobol, Jansen,
Saltelli, and the toolbox's own Xiao method), uncertainty analysis and Monte Carlo filtering,
multistart parameter estimation, practical identifiability analysis (including spectral-clustering
detection of multiple global minima), range refinement, the namesake Confidence Sub-contour Box
algorithm, profile likelihood, and composable Matplotlib plotting — has a Python port in
python/, built on NumPy/SciPy/scikit-learn/SymPy. No MATLAB license required.
cd python && pip install -e ".[all]"import gsua_csb as gc
# gc.UserFunctionModel / gc.SymbolicODEModel, gc.design_matrix, gc.sensitivity_analysis,
# gc.parameter_estimation, gc.identifiability_analysis, gc.confidence_subcontour_box, ...python/README.md— what's implemented, install options, design notespython/USERGUIDE.md— worked examples for every capabilitypython/examples/— end-to-end notebooks (pharmacokinetics, SIR epidemic) plussystem_identification_cycle.py, the full semi-automated identification workflow
Simulink-backed models are intentionally not ported (no Python equivalent — call MATLAB directly via its Python Engine API instead); everything else targets full parity with the MATLAB toolbox below, including symbolic-ODE models via SymPy.
GSUA-CSB (Global Sensitivity and Uncertainty Analysis — Confidence Sub-contour Box) is a MATLAB toolbox for validating mathematical models implemented with Symbolic Math Toolbox or Simulink. It works uniformly across three kinds of model definitions:
- Simulink models
- Symbolic Math Toolbox systems of ODEs
- User-defined MATLAB functions (black-box models)
The toolbox supports:
- variance-based global sensitivity analysis
- uncertainty analysis
- parameter estimation
- practical identifiability analysis (including detection of multiple global minima)
- confidence sub-contour box estimation for fitted parameters
- visualization workflows for model-validation studies
GSUA-CSB was developed at Universidad EAFIT and builds on previous work by Carlos Mario Vélez on GSUA for dynamical systems using variance-based methods.
A single "GSUA table" (a MATLAB table carrying custom properties) records parameter ranges, nominal values,
and everything the toolbox needs to evaluate the underlying model, so the same functions
(gsua_sa, gsua_ua, gsua_pe, gsua_ia, ...) work regardless of which kind of model produced the table.
Two complete system-identification workflows — from writing the model down to reporting confidence intervals. Each one is written twice, as a MATLAB Live Script and as a Python notebook computing the same thing, so you can follow whichever you work in.
| Example | Model kind | Read it | Source |
|---|---|---|---|
| Pharmacokinetics — when a perfect fit hides an unidentifiable parameter | user-defined function | MATLAB · Python | Examples/pk_user_defined.m · python/examples/pk_user_defined.ipynb |
| SIR epidemic — identifiability depends on when you stopped looking | symbolic ODEs | MATLAB · Python | Examples/sir_symbolic.m · python/examples/sir_symbolic.ipynb |
Both reach the same conclusion from opposite directions: the dataset that produced the lower cost is the one that produced the less trustworthy parameters. In the pharmacokinetic example every multistart run converges to the same excellent fit while the parameters correlate at −0.9999; fixing the volume of distribution makes the fit worse and the parameters recoverable. In the epidemic example the first 25 days fit about four times better than the full outbreak, yet transmission and recovery rates become perfectly confounded and R₀ is underestimated at 2.78 against a true 3.5.
All four pages are executed output, not illustrative snippets. Browse them from drojasd.github.io/GSUA-CSB.
A step-by-step course for new users lives in course/: five modules that walk the
whole toolbox workflow — models, sampling, uncertainty, sensitivity, and estimation/identifiability
— each written twice, in MATLAB and Python, with commented demos and exercises (in Spanish).
Clone the repo and run any demo (it locates the toolbox automatically), or read every module
executed online at drojasd.github.io/GSUA-CSB.
Mathematical models used in epidemiology, public health, engineering, and biological systems often depend on uncertain parameters. GSUA-CSB helps researchers understand which parameters matter, how uncertainty propagates through the model, and how identifiable fitted parameters are under available data.
- Documentation site: drojasd.github.io/GSUA-CSB — worked examples and user guide
- User guide: GSUA-CSB documentation
- MATLAB File Exchange: View GSUA-CSB on File Exchange
- Latest GitHub release: releases
- DOI: Zenodo DOI
Search for "GSUA-CSB" in MATLAB's Add-On Explorer, or install directly from File Exchange. Every tagged GitHub release automatically syncs to File Exchange, so the Add-On Explorer always tracks the latest release.
Install GSUA-CSB.mltbx by double-clicking it in MATLAB.
- Clone this repository
- Add the source folders to your MATLAB path:
addpath(genpath('Functions')) addpath(genpath('Add Funcs')) addpath('progressbar')
- Or open
GSUA-UCI.prjin MATLAB to load the project with its path already configured
Open the getting-started guide for an interactive introduction:
open doc/GettingStarted.mlxor the full user guide:
open gsua_userguide% 1. Describe the model (Simulink / symbolic ODE / user-defined function)
T = gsua_dataprep(modelName, Ranges, ParNames);
% 2. Sample the parameter space
M = gsua_dmatrix(T, 1000);
% 3. Analyze
[T,Y,J] = gsua_sa(M,T); % global sensitivity analysis
Y = gsua_ua(M,T); % uncertainty analysis
[T,res] = gsua_pe(T,xdata,ydata); % parameter estimation
% 4. Check practical identifiability across repeated estimations,
% including whether the estimations converge to more than one
% distinct global minimum:
[T,clusterInfo] = gsua_ia(T,T.Estlsqc,false,false,true,true);| Function | Description |
|---|---|
gsua_dataprep |
Consolidation of data and environment (dispatches to the right setup routine for Simulink / symbolic / user-defined models) |
gsua_dpmat |
Consolidation of data and symbolic MATLAB environment |
sens_dataprep |
Consolidation of data and Simulink environment |
gsua_userdefined |
Build a GSUA table around a user-defined MATLAB function |
| Function | Description |
|---|---|
gsua_dmatrix |
Design of experiments (factor space sampling: Latin Hypercube, Uniform, Sobol). Also provides 'Method','Joint' — correlation-preserving sampling that draws whole parameter vectors from an accepted-estimate ensemble (Tia.Est from gsua_ia, or an explicit 'Pool') instead of sampling each parameter independently. For a model with parameter confounding, independent draws leave the identified manifold; joint draws also inherit the pool's own spread rather than the CI-of-the-median that gsua_ia leaves in T.Range. 'JointType' selects Bootstrap (default), SmoothBootstrap or Gaussian; a pool below 'MinPoolN' is refused with a warning and falls back to marginal sampling |
| Function | Description |
|---|---|
gsua_sa |
Global sensitivity analysis (Xiao, Sobol, Jansen, Saltelli, brute-force, OAT methods) |
gsua_ua |
Uncertainty analysis via Monte-Carlo simulation, with automatic Monte-Carlo filtering |
gsua_pe |
Parameter estimation (lsqcurvefit, lsqnonlin, ga, particleswarm, patternsearch, surrogateopt, simulannealbnd, fmincon). The correlation-penalized multi-objective cost path ('margin' ≠ 0/1, i.e. gsua_costf) is NaN-tolerant per output row — a signal with its own gaps (NaN in ydata) no longer blinds other, fully-populated rows in the same joint fit. When that path is used, T's Margin/Alpha CustomProperties are recorded automatically for later recovery by gsua_noisefloor |
gsua_likelihood |
Profile-likelihood confidence intervals for each parameter |
| Function | Description |
|---|---|
gsua_ia |
Practical identifiability analysis with diagnostic plots — including optional spectral-clustering detection of multiple global minima among repeated estimation runs and optional fit-quality ('cost') filtering of failed multistart runs before any statistic is computed |
gsua_dia |
Headless (no-plot) counterpart of gsua_ia, same clustering and fit-quality-filtering support |
gsua_costcutoff |
Shared fit-quality filter behind gsua_ia/gsua_dia's 'cost' option (fixed-tolerance or automatic-gap cutoff, with a minimum-runs floor) |
gsua_noisefloor |
Noise-calibrated fit-acceptance threshold via parametric bootstrap — replaces the scale-dependent res < 1.5*res(1) idiom with a cutoff on the gsua_costf cost scale derived from the data's own observation noise (Poisson / quasi-Poisson (default) / global-NB dispersion models, chosen for count-like or cumulative fitted outputs). Recovers 'margin'/'alpha' from gsua_pe's T automatically, or accepts explicit overrides |
gsua_medianCI |
Distribution-free confidence interval for the median |
gsua_oatr / gsua_oatr2 |
Once-at-a-time range expansion/reduction |
gsua_csb |
Uncertainty-based confidence sub-contour box estimation |
| Function | Description |
|---|---|
gsua_eval |
Evaluate the model for a handful of parameter sets, with optional plotting |
gsua_deval |
Evaluate the model behind a GSUA table for one parameter set (internal dispatcher) |
gsua_pardeval |
Evaluate the model behind a GSUA table for a batch of parameter sets |
gsua_plot |
Visualization function for sensitivity/uncertainty/identifiability results |
gsua_MCF |
Monte-Carlo filtering plots (behavioral vs. non-behavioral parameter sets) |
gsua_mtest |
Animate model output as one parameter is swept, saved as a GIF |
gsua_covmetric |
Percentile-band (P5/P50/P95) coverage-accuracy and band-tightness metrics for gsua_ua results, on the same margin-normalized gsua_costf scale (below 1 = within tolerance) — the stopping signal for semi-automated identification |
| Function | Description |
|---|---|
gsua_save |
Save a GSUA table to disk in a portable form |
gsua_load |
Rebuild a GSUA table's Solver handle after loading from disk |
gsua_costf, gsua_rcostf, gsua_costfMulti, gsua_likecost (objective/cost functions for optimizers),
gsua_corr2omitnan (NaN-tolerant corr2, used by gsua_costf),
gsua_intrp (ODE solution interpolation), gsua_timer (progress reporting), gsua_depth (band depth ranking),
gsua_odefun (symbolic-to-function-handle ODE conversion), gsua_ref (range-adequacy refinement),
sens_montecarlo (Simulink Monte-Carlo evaluation engine).
See the Examples/ folder:
default_example.m— minimal end-to-end rungsua_main.m— full workflow walkthroughuser_free.m/user_dependent.m— user-defined-function model examples
MATLAB with Statistics and Machine Learning Toolbox, Optimization Toolbox, and Global Optimization Toolbox recommended for full functionality. Symbolic Math Toolbox and/or Simulink are required depending on which kind of model you work with.
Sensitivity index estimators implemented in this toolbox are based on:
- Saltelli, A., Annoni, P., Azzini, I., Campolongo, F., Ratto, M., and Tarantola, S. (2010). Variance based sensitivity analysis of model output: design and estimator for the total sensitivity index. Computer Physics Communications, 181(2), 259-270.
- Xiao, S., Lu, Z., and Wang, P. (2018). Multivariate global sensitivity analysis based on distance components decomposition. Risk Analysis, 38(12), 2703-2721.
If you use this toolbox, cite:
Rojas-Diaz, Daniel and Velez-Sanchez, Carlos Mario (2019). GSUA-CSB (https://www.github.com/drojasd/GSUA-CSB), GitHub. doi:10.5755281/zenodo.3383316.
This project is distributed under the MIT License — see LICENSE. Third-party code bundled under
Add Funcs/ retains its own license (see the LICENSE.md/README.md inside that folder).
Source lives under Functions/ (public API), Add Funcs/ (bundled third-party utilities), Examples/, and
doc/. Static analysis is run with MATLAB's Code Analyzer (checkcode); there is currently no automated test
suite — contributions adding matlab.unittest coverage under a tests/ folder are welcome.
Note on releases: this repository is linked to MATLAB File Exchange — publishing a GitHub Release automatically updates the File Exchange listing. Only tag a release when the toolbox is genuinely ready to publish.