Outbreak Detection - Help & Demo Guide

Overview

The Outbreak Detection module identifies clusters of related infections for Infection Prevention investigation. It aggregates cases from multiple data sources (MDRO Surveillance, HAI Detection, CDI) and applies clustering algorithms to detect potential outbreaks.

Key Features

• Multi-Source Integration - Aggregates MDRO, HAI, and CDI cases from separate modules
• Cluster Detection - Groups cases by infection type, unit, and time window
• Severity Classification - Categorizes clusters as low, medium, high, or critical
• IP Alerts - Generates alerts when clusters meet thresholds
• Investigation Workflow - Track cluster status through investigation to resolution

Cluster Detection Algorithm

Clusters are formed when multiple cases of the same infection type occur in the same unit within a defined time window.

Clustering Criteria

Cluster Severity Levels

Data Sources

The Outbreak Detection module pulls case data from multiple surveillance modules using data source adapters:

Quick Start - Generate Demo Data

Create Outbreak Scenarios

Generate demo outbreak scenarios with multiple cases:

# Create a random outbreak scenario
cd /home/david/projects/aegis
python scripts/demo_outbreak.py

# Create a specific scenario
python scripts/demo_outbreak.py --scenario mrsa-icu
python scripts/demo_outbreak.py --scenario vre-medsurg
python scripts/demo_outbreak.py --scenario cre-unit

# Create larger cluster
python scripts/demo_outbreak.py --scenario mrsa-icu --cases 5

# Create all scenario types
python scripts/demo_outbreak.py --all

# Use direct database mode (faster, skips FHIR)
python scripts/demo_outbreak.py --scenario mrsa-icu --direct

Run the Outbreak Detector

After creating demo data, run the detector to identify clusters:

# Run once
cd /home/david/projects/aegis/outbreak-detection
python -m outbreak_src.runner --once

# Run with extended lookback
python -m outbreak_src.runner --once --days 30

# Run continuously
python -m outbreak_src.runner --continuous --interval 60

# Debug mode
python -m outbreak_src.runner --once --debug

Then view results on the Outbreak Dashboard.

Demo Scenarios

Cluster Lifecycle

Cluster Status Definitions

Alert Types

IP Investigation Workflow

1. Acknowledge Alert - Mark alert as received and begin investigation
2. Review Cases - Examine all cases in the cluster for common factors
3. Environmental Assessment - Inspect unit for potential transmission sources
4. Contact Tracing - Identify exposed patients and staff
5. Implement Controls - Enhanced cleaning, cohorting, contact precautions
6. Monitor - Watch for new cases over defined period
7. Resolve - Close cluster when investigation complete and transmission stopped

Investigation Checklist

• Common room or equipment exposure
• Shared healthcare workers
• Temporal relationship between cases
• Prior contact between patients
• Environmental culture results
• Hand hygiene compliance observations

Dashboard Pages

Architecture

+-------------------+     +-------------------+     +-------------------+
|  MDRO Surveillance|     |   HAI Detection   |     |   CDI Module      |
|  (mdro_src)       |     |   (hai_src)       |     |   (cdi_src)       |
+--------+----------+     +---------+---------+     +---------+---------+
         |                          |                         |
         |   MDROSource             |   HAISource             |   CDISource
         v                          v                         v
+-------------------------------------------------------------------------+
|                        Outbreak Detector                                 |
|                    (outbreak_src/detector.py)                           |
|                                                                         |
|  +----------------+    +----------------+    +------------------+       |
|  | Aggregate Cases|-->| Cluster by     |-->| Calculate        |       |
|  | from Sources   |    | Type + Unit    |    | Severity         |       |
|  +----------------+    +----------------+    +------------------+       |
+-------------------------------------------------------------------------+
                                    |
                                    v
                    +-------------------------------+
                    |      Outbreak Database        |
                    |   (outbreak_clusters table)   |
                    |   (outbreak_alerts table)     |
                    +-------------------------------+
                                    |
                    +---------------+---------------+
                    v                               v
         +-------------------+           +-------------------+
         |   IP Alerts       |           |   Dashboard       |
         |  (Notifications)  |           |   (Flask Routes)  |
         +-------------------+           +-------------------+
        

Troubleshooting

No clusters detected

# Check if source data exists
sqlite3 ~/.aegis/mdro.db "SELECT COUNT(*) FROM mdro_cases"
sqlite3 ~/.aegis/nhsn.db "SELECT COUNT(*) FROM hai_events"

# Run detector with debug
cd /home/david/projects/aegis/outbreak-detection
python -m outbreak_src.runner --once --debug

Clear outbreak data and start fresh

# Remove outbreak database
rm -f ~/.aegis/outbreak.db

# Reinitialize
cd /home/david/projects/aegis/outbreak-detection
python -c "from outbreak_src.db import OutbreakDatabase; OutbreakDatabase()"

Check cluster contents

sqlite3 ~/.aegis/outbreak.db "SELECT id, infection_type, unit, case_count, severity, status FROM outbreak_clusters"

Related Modules

• MDRO Surveillance - Source for MDRO case data
• HAI Detection - Source for HAI case data
• NHSN Reporting - Quarterly reporting for confirmed events