Understanding Results#

This guide explains how to interpret PatchSim simulation outputs.

Output Directory Structure#

After running patchsim run -c config.yaml, your OutputDir contains:

output/
├── runs/
│   └── all_patches_MODEL_ode.csv       # Time series data (main output)
├── plots/
│   └── patch_timeseries_MODEL_ode.png  # Visualization
└── logs/
    └── MODEL_run_YYYYMMDD_HHMMSS.log   # Detailed simulation log

CSV Output (runs/)#

File Format#

The CSV file contains time series for all compartments across all patches.

Columns:

  • time – Time step (0, 1, 2, …, TMax-1)

  • COMPARTMENT_PATCH – Values for each compartment-patch combination

Example: SIR with 2 patches

time,S_0,I_0,R_0,S_1,I_1,R_1
0.0,950,50,0,475,25,0
1.0,937.2,59.1,3.7,463.8,32.8,3.4
2.0,923.1,67.2,9.7,451.2,39.4,9.4
...
99.0,2.1,0.3,997.6,1.2,0.1,498.7

Interpreting Values#

  • Early (t ~ 0–20): Growth phase. Infectious cases rising, susceptible declining.

  • Mid (t ~ 20–50): Peak phase. Cases plateau or decline. Recovery accelerates.

  • Late (t ~ 50+): Endemic equilibrium. Susceptible, infectious, recovered settle.

Key metrics from CSV:

Metric

Calculation

Meaning

Final S

Last value in S column

How many never got infected

Max I

Maximum across all I columns

Peak infections (key for healthcare burden)

Time of max I

Timestamp of peak

When to expect peak demand

Final R

Last value in R column

Total infected (across outbreak)

Attack rate

Final R / initial N

Proportion of population infected

Multi-Patch Analysis#

For network models, compare patches to identify:

  • Leading patches: Higher I earlier (index cases / hubs)

  • Trailing patches: Delayed peaks (transmission lag)

  • Heterogeneous outcomes: Some patches have more infections due to network structure

PNG Plots (plots/)#

What’s Shown#

Line plot with:

  • X-axis: Time

  • Y-axis: Population count

  • One subplot per patch

  • One line per compartment (color-coded)

Interpreting Plots#

  • S line (usually blue) → Decreases as people become infected

  • I line (usually red) → Shows epidemic curve (peaks then declines)

  • R line (usually green) → Increases over time (cumulative recovered)

Example scenarios:

Pattern

Meaning

Sharp I peak early

Rapid spread (high β, dense network)

Flat I peak

Slow spread (low β, isolated patches)

Long tail in I

Chronic endemicity (SIRS-like behavior)

S → 0

Epidemic exhausted susceptible pool

Multi-Patch Plots#

For network models, subplots show:

  • Urban patch: Usually steeper I peak (more contacts)

  • Rural patch: Usually delayed, flatter peak (fewer contacts)

  • Synchrony: Patches with high network weight peak closer in time

Logs (logs/)#

What’s Recorded#

Each simulation generates a detailed log including:

  • Configuration summary – Model name, parameters, compartments, transitions

  • Data validation – Patches loaded, seed values confirmed

  • Solver progress – Time steps completed, solver diagnostics

  • Output paths – Where CSV/plots were saved

  • Warnings/errors – Any issues encountered (but simulation completed)

When to Check Logs#

  • Simulation failed – Log explains what went wrong

  • Results seem wrong – Log shows if data was loaded correctly

  • Slow simulation – Log shows solver iteration counts

  • Production runs – Archive logs for reproducibility

Example Log Snippet#

2026-04-14 10:30:45 INFO Starting PatchSim simulation...
2026-04-14 10:30:45 INFO Model: sample-sir-ode
2026-04-14 10:30:45 INFO Compartments: S, I, R
2026-04-14 10:30:45 INFO Parameters: beta=0.5, gamma=0.1
2026-04-14 10:30:45 INFO Transitions: S->I: beta*I, I->R: gamma
2026-04-14 10:30:45 INFO Loading patches from data/patch/sample.csv
2026-04-14 10:30:45 INFO Loaded patches: PatchA (1000 individuals)
2026-04-14 10:30:45 INFO Loading seeds from data/seeds/initial.csv
2026-04-14 10:30:45 INFO Seed validation: OK
2026-04-14 10:30:45 INFO Running ODE solver for 100 time steps...
2026-04-14 10:30:46 INFO Simulation completed successfully
2026-04-14 10:30:46 INFO Saved to: output/runs/all_patches_sample-sir-ode_ode.csv

Analysis Workflow#

1. Quick Sanity Check#

  • Open CSV and spot-check first/last rows

    • S values should decrease over time

    • R values should increase over time (or stay flat for SIS)

    • Sum S + I + R should equal population (within rounding)

  • View PNG plot

    • Does epidemic curve look reasonable for your parameters?

    • Are compartment trajectories monotonic as expected?

2. Extract Key Metrics#

import pandas as pd

df = pd.read_csv('output/runs/all_patches_sample-sir-ode_ode.csv')

# Attack rate (% infected)
attack_rate = df['R_0'].iloc[-1] / 1000

# Peak infections
peak_I = df['I_0'].max()
peak_time = df.loc[df['I_0'].idxmax(), 'time']

# Final state
final_S = df['S_0'].iloc[-1]
final_I = df['I_0'].iloc[-1]
final_R = df['R_0'].iloc[-1]

print(f"Attack rate: {attack_rate:.1%}")
print(f"Peak infections: {peak_I:.0f} at time {peak_time:.0f}")
print(f"Final state: S={final_S:.0f}, I={final_I:.0f}, R={final_R:.0f}")

3. Compare Scenarios#

Run multiple simulations (e.g., different β values) and compare:

import matplotlib.pyplot as plt

scenarios = [
  ('low_transmission.csv', 'β=0.3'),
  ('baseline.csv', 'β=0.5'),
  ('high_transmission.csv', 'β=0.7'),
]

fig, ax = plt.subplots()
for fname, label in scenarios:
    df = pd.read_csv(f'output/runs/{fname}')
    ax.plot(df['time'], df['I_0'], label=label)

ax.set_xlabel('Time')
ax.set_ylabel('Infectious count')
ax.legend()
plt.show()

Common Questions#

Q: Why do my compartments have fractional values?
A: Compartments are continuous (not individual counts). This is standard in ODE models. Round to integers if needed for reporting.

Q: Sum of S+I+R doesn’t equal population exactly.
A: Rounding error from ODE solver. Typically <0.01% relative error. If larger, check your seed file.

Q: I see negative values in the CSV.
A: Solver numerical issue (very rare). Check your rates and initial conditions; they should all be positive.

Q: Compartment values don’t match my expected model.
A: Check that your transition expressions are correct. See Configuration for syntax.

Q: How do I export results to another format (Excel, JSON, etc.)?
A: CSV can be imported into any tool. Use patchsim run --json for machine-readable summary.

Next Steps#