ICU discrete-event simulation engine — distribution sampling, patient clustering, and statistical validation.
- Builds patient-level simulation scenarios through
Experiment. - Executes one run with
single_runand many runs withmultiple_replication. - Classifies each patient using nearest-centroid clustering with user-provided centroid CSV data.
- Generates cluster-specific ICU timelines (
pre_vam,vam,post_vam,uci,post_uci). - Validates simulation quality with Wilcoxon, Friedman, coverage, RMSE/MAE/MAPE, KS, and AD tests.
- Validates experiment parameters and simulation run counts before execution.
pip install simuciFor development:
git clone https://github.com/coslatte/simuci.git
cd simuci
pip install -e ".[dev]"fromsimuciimportExperiment, single_run, multiple_replication# Create an experiment with patient parametersexp=Experiment(
age=55,
diagnosis_admission1=11,
diagnosis_admission2=0,
diagnosis_admission3=0,
diagnosis_admission4=0,
apache=20,
respiratory_insufficiency=5,
artificial_ventilation=1,
uti_stay=100,
vam_time=50,
preuti_stay_time=10,
percent=3,
)
# Single replication (requires centroids CSV)result=single_run(exp, centroids_path="path/to/centroids.csv")
print(result)
# {'Tiempo Pre VAM': 5, 'Tiempo VAM': 89, 'Tiempo Post VAM': 168, 'Estadia UCI': 262, 'Estadia Post UCI': 45}# Multiple replications → DataFramedf=multiple_replication(exp, n_reps=200, centroids_path="path/to/centroids.csv")
print(df.describe())You must pass the path to your centroid CSV explicitly:
fromsimuciimportsingle_run, Experimentexp=Experiment(age=55, ..., validate=False)
# Point to your centroids CSVresult=single_run(exp, centroids_path="path/to/real_centroids.csv")The centroids CSV must have:
- An index column (cluster IDs: 0, 1, 2)
- At least 11 numeric columns (features used for nearest-centroid classification)
You can also use the loader directly:
fromsimuci.io.loadersimportCentroidLoaderloader=CentroidLoader()
centroids=loader.load("path/to/centroids.csv") # returns numpy arrayimportnumpyasnpfromsimuciimportSimulationMetrics, Wilcoxon, Friedman# Compare simulation output to real datametrics=SimulationMetrics(
true_data=np.array(...), # (n_patients, n_variables)simulation_data=np.array(...), # (n_patients, n_replicates, n_variables)
)
metrics.evaluate(confidence_level=0.95, result_as_dict=True)
print(metrics.coverage_percentage)
print(metrics.error_margin)
print(metrics.kolmogorov_smirnov_result)
print(metrics.anderson_darling_result)All Experiment inputs are validated on construction by default:
fromsimuciimportExperiment# This raises ValueError: age must be between 14 and 100Experiment(age=200, ...)Skip validation with validate=False if you've already validated externally.
| Symbol | Description |
|---|---|
Experiment | Patient parameters + result container |
single_run(exp) | One simulation replication |
multiple_replication(exp, n_reps) | N replications → DataFrame |
clustering(edad, ...) | Nearest-centroid patient classifier |
Wilcoxon | Paired Wilcoxon signed-rank test |
Friedman | Friedman chi-square test |
SimulationMetrics | Full evaluation suite (coverage, RMSE, KS, AD) |
StatsUtils | Static CI helper |
CentroidLoader | CSV loader with schema validation |
validate_experiment_inputs() | Parameter range checking |
Project map (core vs. validation, I/O, statistics, tooling): docs/architecture.md
Complete function-by-function reference for every source module: docs/function-profile.md
Contributions are welcome through issue proposals, technical feedback, and documentation improvements.
- Public direct commits are closed.
- To appeal or request contribution access, contact:
gabrielpazruiz02@gmail.com. - For implementation work, open an issue with problem statement, expected behavior, and validation plan.
- Keep all new documentation and code comments in English.
MIT