API Reference
Complete documentation of all functions, classes, and methods.
Run SIR model simulation.
Parameters:
| Parameter | Type | Description | Default |
|---|---|---|---|
beta |
float | Infection rate (0.0 - 1.0) | Required |
gamma |
float | Recovery rate (0.0 - 1.0) | Required |
S0 |
int | Initial susceptible population | Required |
I0 |
int | Initial infected population | Required |
R0 |
int | Initial recovered population | Required |
t_max |
int | Maximum simulation time (days) | Required |
steps |
int | Number of time steps | 500 |
Returns: pandas DataFrame with columns: time, Susceptible, Infected, Recovered
Example:
from sir_simulator.core_models.sir_model import run_sir_simulation
df = run_sir_simulation(
beta=0.5, gamma=0.2,
S0=990, I0=10, R0=0,
t_max=100, steps=500
)SIR differential equations (for internal use).
Parameters:
-
y: List of [S, I, R] -
t: Time -
beta: Infection rate -
gamma: Recovery rate
Returns: List of [dS/dt, dI/dt, dR/dt]
Run SEIR model simulation.
Parameters:
| Parameter | Type | Description | Default |
|---|---|---|---|
beta |
float | Infection rate (0.0 - 1.0) | Required |
sigma |
float | Incubation rate (1/incubation_days) | Required |
gamma |
float | Recovery rate (0.0 - 1.0) | Required |
S0 |
int | Initial susceptible | Required |
E0 |
int | Initial exposed | Required |
I0 |
int | Initial infected | Required |
R0 |
int | Initial recovered | Required |
t_max |
int | Maximum simulation time (days) | Required |
steps |
int | Number of time steps | 500 |
Returns: pandas DataFrame with columns: time, Susceptible, Exposed, Infected, Recovered
Example:
from sir_simulator.core_models.seir_model import run_seir_simulation
df = run_seir_simulation(
beta=0.5, sigma=0.2, gamma=0.1,
S0=990, E0=5, I0=5, R0=0,
t_max=100, steps=500
)SEIR differential equations (for internal use).
Social network simulator for spread simulation.
Parameters:
-
num_nodes: Number of nodes in network -
network_type:'scale_free','small_world', or'random'
Methods:
Get network statistics.
Returns: Dictionary with:
-
nodes: Number of nodes -
edges: Number of edges -
avg_degree: Average node degree -
density: Network density
Example:
sim = SocialNetworkSimulator(200, 'scale_free')
stats = sim.get_network_stats()
print(stats)Simulate spread on network.
Parameters:
-
transmission_prob: Probability of transmission to neighbor (0.0 - 1.0) -
recovery_prob: Probability of recovery per step (0.0 - 1.0) -
initial_infected: Number of initially infected nodes -
max_steps: Maximum simulation steps
Returns: pandas DataFrame with columns: step, susceptible, infected, recovered
Example:
sim = SocialNetworkSimulator(200, 'scale_free')
df = sim.simulate_spread(transmission_prob=0.3, recovery_prob=0.1)Visualize the network with current spread state.
Parameters:
-
show_labels: Whether to show node labels
Optimizer for fitting model parameters to real data.
Parameters:
-
model_type:'sir'or'seir'
Methods:
Fit model parameters to observed data.
Parameters:
-
real_data: Array of observed infected cases -
t: Array of time points -
initial_conditions: List of initial populations [S0, I0, R0] or [S0, E0, I0, R0] -
method:'differential_evolution'or'L-BFGS-B'
Returns: Dictionary with:
-
beta: Fitted infection rate -
gamma: Fitted recovery rate -
R0: Basic reproduction number (beta/gamma) -
r_squared: Goodness of fit (0-1) -
final_error: Final optimization error -
fitted_curve: Array of fitted values
Example:
from sir_simulator.advanced_features.parameter_optimization import ParameterOptimizer
optimizer = ParameterOptimizer(model_type='sir')
results = optimizer.fit(observed_data, t, [990, 10, 0])
print(f"β={results['beta']:.3f}, γ={results['gamma']:.3f}")generate_synthetic_data(true_beta=0.5, true_gamma=0.2, S0=990, I0=10, R0=0, t_max=100, noise_level=5)
Generate synthetic data for testing.
Returns: Tuple of (t, noisy_data, true_curve)
Machine learning predictor for epidemic forecasting.
Parameters:
-
model_type:'random_forest'or'xgboost'
Methods:
Train the ML model on historical data.
Parameters:
-
data: DataFrame with 'day' and 'cases' columns -
test_size: Proportion for testing (0.0-1.0)
Returns: Tuple of (metrics, predictions, model)
-
metrics: Dictionary with 'r2', 'rmse', 'train_size', 'test_size' -
predictions: Predictions on test set -
model: Trained model
Example:
from sir_simulator.advanced_features.ml_prediction import EpidemicPredictor
predictor = EpidemicPredictor('random_forest')
metrics, predictions, model = predictor.train(historical_data)
print(f"R²: {metrics['r2']:.3f}")Predict future cases.
Parameters:
-
data: Historical data (DataFrame or Series) -
days: Number of days to predict
Returns: pandas Series of future predictions
Example:
future = predictor.predict_future(historical_data, days=30)
print(future.head())Create features for ML model (internal use).
Prepare data for training (internal use).
Compare different intervention scenarios.
Parameters:
-
population: Total population -
initial_infected: Initial infected count -
beta: Infection rate -
gamma: Recovery rate
Methods:
Run baseline scenario (no intervention).
Returns: DataFrame with 'day', 'susceptible', 'infected', 'recovered'
Run quarantine scenario.
Parameters:
-
days: Total simulation days -
start_day: Day quarantine starts -
end_day: Day quarantine ends -
reduction_factor: Transmission reduction (0.1 = 90% reduction)
Returns: DataFrame with 'day', 'susceptible', 'infected', 'recovered'
Run vaccination scenario.
Parameters:
-
days: Total simulation days -
start_day: Day vaccination starts -
daily_vaccinations: People vaccinated per day -
vaccine_efficacy: Vaccine effectiveness (0.7-0.95)
Returns: DataFrame with 'day', 'susceptible', 'infected', 'recovered'
combined_scenario(days=150, quarantine_start=10, quarantine_end=80, quarantine_reduction=0.2, vaccination_start=5, daily_vaccinations=12)
Run combined (quarantine + vaccination) scenario.
Returns: DataFrame with 'day', 'susceptible', 'infected', 'recovered'
Run all scenarios and compare.
Returns: Tuple of (scenarios_dict, metrics_df)
-
scenarios_dict: Dictionary of DataFrames for each scenario -
metrics_df: DataFrame with 'scenario', 'peak_infected', 'peak_day', 'reduction'
Example:
from sir_simulator.advanced_features.scenario_comparison import ScenarioComparator
comp = ScenarioComparator(beta=0.25, gamma=0.1)
scenarios, metrics = comp.compare_all_scenarios(days=120)
print(metrics)| Argument | Type | Default | Description |
|---|---|---|---|
--model |
str | 'sir' | Model type ('sir', 'seir', 'network') |
--beta |
float | 0.5 | Infection rate |
--gamma |
float | 0.2 | Recovery rate |
--sigma |
float | 0.2 | Incubation rate (for SEIR) |
--S0 |
int | 990 | Initial susceptible |
--I0 |
int | 10 | Initial infected |
--E0 |
int | 0 | Initial exposed (for SEIR) |
--R0 |
int | 0 | Initial recovered |
--tmax |
int | 100 | Maximum time (days) |
--steps |
int | 500 | Number of time steps |
--output |
str | 'simulation_output.csv' | Output CSV file |
Example:
sir-simulator --model sir --beta 0.5 --gamma 0.2 --tmax 100
sir-simulator --model seir --beta 0.5 --sigma 0.2 --gamma 0.1
sir-simulator --model network --beta 0.3 --gamma 0.1src/sir_simulator/user_interface/app.py
streamlit run src/sir_simulator/user_interface/app.py- Interactive parameter sliders
- Real-time visualization
- CSV export
- Multiple model support (SIR, SEIR, Network, Optimization, Scenarios)
| Function | Return Type |
|---|---|
run_sir_simulation() |
pd.DataFrame |
run_seir_simulation() |
pd.DataFrame |
SocialNetworkSimulator.simulate_spread() |
pd.DataFrame |
SocialNetworkSimulator.get_network_stats() |
dict |
ParameterOptimizer.fit() |
dict |
EpidemicPredictor.train() |
tuple(dict, array, model) |
EpidemicPredictor.predict_future() |
pd.Series |
ScenarioComparator.baseline_scenario() |
pd.DataFrame |
ScenarioComparator.compare_all_scenarios() |
tuple(dict, pd.DataFrame) |
- Getting Started - Installation and first steps
- SIR Model Tutorial - Detailed SIR guide
- SEIR Model Tutorial - Detailed SEIR guide
- FAQ - Common questions
