Implement Hospital Hierarchy for Multi-Level Bed Demand Predictions

[zmek]

Implement Hospital Hierarchy for Multi-Level Bed Demand Predictions

Problem Statement

The current package provides bed demand predictions at the specialty level (e.g., medical, surgical, haem/onc, paediatric), but hospital operations may require predictions at multiple levels. For example, at UCLH the levels are:

• Subspecialty level: Individual clinical units (e.g., General Surgery - Upper GI)
• Reporting unit level: Groups of subspecialties
• Division level: Groups of reporting units
• Board level: Groups of divisions
• Hospital level: Overall hospital

Currently, predictions are computed independently for each specialty without considering the hierarchical relationships between organizational units. This limits the ability to:

• Aggregate predictions across organizational levels
• Provide capacity planning at different management levels
• Support flexible organizational structures that vary between hospitals

Proposed Solution

1. Generic Hierarchy Structure

• Create a configurable Hierarchy class that can represent any organisational structure
• Support YAML-based configuration for defining hierarchy levels and relationships
• Enable dynamic entity types (not hard-coded to specific hospital structures)
• Provide utilities to populate hierarchy from DataFrames with organisational mappings

2. Flow-Based Prediction Architecture

• Refactor prediction inputs to use a flow-based model with separate inflows and outflows
• Create SubspecialtyPredictionInputs dataclass that encapsulates:
  • Inflows: ED admissions, yet-to-arrive patients, internal transfers
  • Outflows: Departures (elective and emergency), transfers out
• Use probability distributions (PMFs and Poisson) to represent patient flows
• Enable flexible flow selection (which flows to include in predictions)

3. Hierarchical Aggregation Engine

• Implement DemandPredictor that uses discrete convolution to aggregate predictions bottom-up
• Support statistical capping to bound distribution sizes while maintaining accuracy
• Compute separate predictions for arrivals, departures, and net flow at each level

4. High-Level Prediction Interface

• Create HierarchicalPredictor class that orchestrates predictions across all levels
• Support caching of prediction bundles for efficient retrieval
• Enable predictions for specific organizational entities or entire hierarchy
• Provide DemandPrediction dataclass with probabilities, expected values, and percentiles

5. Distribution Utilities

• Implement Distribution class for working with probability mass functions
• Support operations: convolution, thinning, truncation, statistical capping
• Enable efficient computation of aggregated distributions

Expected Behavior

After implementation:

• Users can define custom hospital hierarchies via YAML configuration
• Predictions are computed at the bottom level (subspecialty) using flow-based inputs
• Predictions automatically aggregate up the hierarchy using convolution
• Each level provides probability distributions, expected values, and percentiles
• The system supports flexible flow selection (e.g., elective-only, emergency-only, all flows)
• Predictions can be queried at any organizational level

Key Components

• Hierarchy: Generic hierarchical structure with configurable levels
• SubspecialtyPredictionInputs: Flow-based input structure for bottom-level predictions
• FlowInputs: Individual flow representation (PMF or Poisson)
• DemandPredictor: Core aggregation engine using convolution
• HierarchicalPredictor: High-level interface for multi-level predictions
• Distribution: Probability distribution utilities
• DemandPrediction: Result structure with probabilities and statistics

Acceptance Criteria

• Hierarchy can be created from YAML configuration file
• Hierarchy can be populated from DataFrame with organisational relationships
• Bottom-level predictions use flow-based architecture (inflows/outflows)
• Predictions aggregate correctly from subspecialty to hospital level
• Statistical capping prevents unbounded distribution sizes
• Percentiles are computed correctly at all levels
• Flow selection allows filtering by flow type and cohort
• All existing single-level prediction functionality remains intact

[zmek]

Related Work

This issue establishes the foundational flow-based architecture and hierarchical prediction system. The cohort-aware patient prediction enhancements in #106 build on top of this work by:

• Extending the flow-based architecture to support cohort-specific predictions (elective vs emergency)
• Adding cohort awareness to transfer predictions within the hierarchical system
• Enabling cohort-based flow selection at all hierarchical levels

The hierarchy structure and flow-based inputs defined here provide the necessary foundation for the cohort-aware features implemented in #106.

[zmek]

Closing. Implemented in #131