scenarios Module

Multi-scenario runner for compartmental models.

This module provides tools to run multiple parameter scenarios through a single model class and compare results.

Classes

class episia.models.scenarios.ScenarioRunner(model_class, solver_kwargs=None)

Bases: object

Run multiple parameter scenarios through a single model class.

Example:

from episia.models.parameters import SIRParameters, ScenarioSet
from episia.models.scenarios import ScenarioRunner
from episia.models.sir import SIRModel

scenarios = ScenarioSet([
    ("R0=1.5", SIRParameters(N=1_000_000, I0=10, beta=0.15, gamma=0.1)),
    ("R0=2.5", SIRParameters(N=1_000_000, I0=10, beta=0.25, gamma=0.1)),
    ("R0=3.5", SIRParameters(N=1_000_000, I0=10, beta=0.35, gamma=0.1)),
])

runner = ScenarioRunner(SIRModel)
results = runner.run(scenarios)

results.to_dataframe()
results.plot(compartment="I").show()

Parameters:

• model_class (Type[CompartmentalModel])

• solver_kwargs (Optional[Dict[str, Any]])

__init__(model_class, solver_kwargs=None)

Parameters:

• model_class (Type[CompartmentalModel]) – Model class to instantiate (SIRModel, SEIRModel…).

• solver_kwargs (Dict[str, Any] | None) – Extra kwargs forwarded to model.run().

run(scenarios)

Run all scenarios and return a ScenarioResults container.

Parameters:

scenarios (ScenarioSet) – ScenarioSet of (label, parameters) pairs.

Returns:

ScenarioResults ready for plotting or DataFrame export.

Return type:

ScenarioResults

class episia.models.scenarios.ScenarioResults(labels, results)

Bases: object

Container for results from multiple model scenarios.

Parameters:

• labels (List[str])

• results (List[Any])

labels

Scenario names.

Type:

List[str]

results

Corresponding ModelResult objects.

Type:

List[Any]

metrics_df

pandas DataFrame of key metrics (lazy, call .to_dataframe()).

__iter__()

__len__()

Return type:

int

__repr__()

Return repr(self).

Return type:

str

labels: List[str]

plot(compartment='I', backend='plotly', theme='scientific', title='Scenario Comparison')

Overlay trajectories for all scenarios on a single figure.

Parameters:

• compartment (str) – Compartment to plot (e.g. ‘I’, ‘D’, ‘R’).

• backend (str) – ‘plotly’ or ‘matplotlib’.

• theme (str) – Theme name.

• title (str) – Figure title.

Returns:

Figure object.

Return type:

Any

results: List[Any]

to_dataframe()

Return a pandas DataFrame comparing key metrics across scenarios.

Examples

Comparing intervention strategies:

from episia.models import SIRModel
from episia.models.parameters import SIRParameters, ScenarioSet
from episia.models.scenarios import ScenarioRunner

# Define scenarios
baseline = SIRParameters(N=1e6, I0=10, beta=0.3, gamma=0.1)
lockdown = SIRParameters(N=1e6, I0=10, beta=0.15, gamma=0.1)
masks    = SIRParameters(N=1e6, I0=10, beta=0.2, gamma=0.1)
vaccines = SIRParameters(N=1e6, I0=10, beta=0.25, gamma=0.15)  # Faster recovery

scenarios = ScenarioSet([
    ("Baseline", baseline),
    ("Lockdown", lockdown),
    ("Masks only", masks),
    ("Vaccines", vaccines),
])

# Run all scenarios
runner = ScenarioRunner(SIRModel)
results = runner.run(scenarios)

# Compare metrics
df = results.to_dataframe()
print(df)

# Visualize
results.plot(compartment='I', title="Scenario Comparison: Infectious").show()

Comparing R₀ values:

import numpy as np
from episia.models import SIRModel
from episia.models.parameters import SIRParameters, ScenarioSet
from episia.models.scenarios import ScenarioRunner

scenarios = ScenarioSet()
for r0 in np.linspace(1.5, 4.0, 6):
    gamma = 0.1
    beta = r0 * gamma
    params = SIRParameters(N=1e6, I0=10, beta=beta, gamma=gamma)
    scenarios.add(f"R₀={r0:.1f}", params)

results = ScenarioRunner(SIRModel).run(scenarios)
results.plot(compartment='I').show()

Export results:

# Metrics table
df_metrics = results.to_dataframe()
df_metrics.to_csv("scenario_comparison.csv")

# Extract trajectories for each scenario
for label, result in results:
    df_traj = result.to_dataframe()
    df_traj.to_csv(f"trajectory_{label}.csv")