Skip to content

Home

Jump to bottom
Christopher Lorton edited this page Feb 27, 2026 · 1 revision

Welcome to the laser-cholera wiki!

Laser Cholera Architecture Diagram

Overview

This document provides a comprehensive architecture diagram for the laser.cholera package, a metapopulation cholera transmission model built on the LASER framework.

High-Level Architecture

graph TB
    CLI[CLI Entry Point<br/>cli_run] --> Model
    Model --> Components[Model Components]
    Components --> People[People Frame<br/>LaserFrame]
    Components --> Patches[Patches Frame<br/>LaserFrame]
    Model --> Parameters[Parameters<br/>PropertySet]
    Model --> Results[RInterface<br/>Results]
Loading

Core Class Diagram

classDiagram
    class Model {
        +str name
        +PropertySet params
        +LaserFrame people
        +LaserFrame patches
        +list components
        +list instances
        +list phases
        +datetime tinit
        +datetime tstart
        +datetime tfinish
        +list metrics
        +RInterface results
        +scenario scenario
        +PRNG prng
        +run() void
        +visualize(pdf: bool) str
        +plot() generator
    }

    class PropertySet {
        +int seed
        +datetime date_start
        +datetime date_stop
        +int nticks
        +list location_name
        +ndarray S_j_initial
        +ndarray E_j_initial
        +ndarray I_j_initial
        +ndarray R_j_initial
        +ndarray V1_j_initial
        +ndarray V2_j_initial
        +ndarray b_jt
        +ndarray d_jt
        +ndarray nu_1_jt
        +ndarray nu_2_jt
        +float phi_1
        +float phi_2
        +float omega_1
        +float omega_2
        +float iota
        +float gamma_1
        +float gamma_2
        +float epsilon
        +float rho
        +float sigma
        +validate() void
    }

    class LaserFrame {
        +int npatches
        +add_vector_property(name, length, dtype, default) void
        +add_matrix_property(name, shape, dtype, default) void
    }

    class RInterface {
        +ndarray S
        +ndarray E
        +ndarray Isym
        +ndarray Iasym
        +ndarray R
        +ndarray V1imm
        +ndarray V1sus
        +ndarray V1inf
        +ndarray V2imm
        +ndarray V2sus
        +ndarray V2inf
        +ndarray births
        +ndarray disease_deaths
        +ndarray incidence
        +ndarray N
        +ndarray W
    }

    Model --> PropertySet
    Model --> LaserFrame : people
    Model --> LaserFrame : patches
    Model --> RInterface : results
Loading

Component Architecture

classDiagram
    class Component {
        <<interface>>
        +Model model
        +check() void
        +__call__(model, tick) void
        +plot() generator
    }

    class Susceptible {
        +Model model
        +check() void
        +__call__(model, tick) void
        +plot() generator
    }

    class Exposed {
        +Model model
        +check() void
        +__call__(model, tick) void
        +plot() generator
    }

    class Infectious {
        +Model model
        +check() void
        +__call__(model, tick) void
        +plot() generator
    }

    class Recovered {
        +Model model
        +check() void
        +__call__(model, tick) void
        +plot() generator
    }

    class Vaccinated {
        +Model model
        +check() void
        +__call__(model, tick) void
        +plot() generator
    }

    class Census {
        +Model model
        +check() void
        +__call__(model, tick) void
        +plot() generator
    }

    class HumanToHuman {
        +Model model
        +check() void
        +__call__(model, tick) void
        +plot() generator
    }

    class HumanToHumanVax {
        +Model model
        +check() void
        +__call__(model, tick) void
        +plot() generator
    }

    class EnvToHuman {
        +Model model
        +check() void
        +__call__(model, tick) void
        +plot() generator
    }

    class EnvToHumanVax {
        +Model model
        +check() void
        +__call__(model, tick) void
        +plot() generator
    }

    class Environmental {
        +Model model
        +check() void
        +__call__(model, tick) void
        +plot() generator
    }

    class DerivedValues {
        +Model model
        +check() void
        +__call__(model, tick) void
        +plot() generator
    }

    class Analyzer {
        +Model model
        +check() void
        +__call__(model, tick) void
        +plot() generator
    }

    class Recorder {
        +Model model
        +check() void
        +__call__(model, tick) void
    }

    class Parameters {
        +Model model
        +check() void
        +__call__(model, tick) void
        +plot() generator
    }

    Component <|.. Susceptible
    Component <|.. Exposed
    Component <|.. Infectious
    Component <|.. Recovered
    Component <|.. Vaccinated
    Component <|.. Census
    Component <|.. HumanToHuman
    Component <|.. HumanToHumanVax
    Component <|.. EnvToHuman
    Component <|.. EnvToHumanVax
    Component <|.. Environmental
    Component <|.. DerivedValues
    Component <|.. Analyzer
    Component <|.. Recorder
    Component <|.. Parameters
Loading

Execution Flow

sequenceDiagram
    participant CLI
    participant Model
    participant Components
    participant People
    participant Patches

    CLI->>Model: initialize(parameters)
    Model->>Components: instantiate components
    Components->>People: add_vector_property()
    Components->>Patches: add_vector_property()
    Components->>Components: check()

    loop For each tick
        Model->>Components: phase[0](model, tick)
        Model->>Components: phase[1](model, tick)
        Model->>Components: phase[n](model, tick)
    end

    Model->>Model: create RInterface
    Model->>Model: visualize()
Loading

Component Execution Order

The model components execute in the following order during each tick:

flowchart LR
    subgraph I
        direction TB
        A[Susceptible] --> B[Exposed]
        B --> C[Recovered]
        C --> D[Infectious]
        D --> E[Vaccinated]
    end

    subgraph II
        direction TB
        F[Census] --> G[HumanToHuman]
        G --> H[HumanToHumanVax]
        H --> In[EnvToHuman]
        In --> J[EnvToHumanVax]
    end

    subgraph III
        direction TB
        K[Environmental] --> L[DerivedValues]
        L --> M[Analyzer]
        M --> N[Recorder]
        N --> O[Parameters]
    end

    %% Connect columns
    I --> II
    II --> III
Loading

Parameter Management

classDiagram
    class ParameterLoader {
        +get_parameters(source) PropertySetEx
        +load_json_parameters(filename) PropertySetEx
        +load_compressed_json_parameters(filename) PropertySetEx
        +load_hdf5_parameters(filename) PropertySetEx
        +load_compressed_hdf5_parameters(filename) PropertySetEx
        +validate_parameters(params) void
    }

    class PropertySetEx {
        +dict to_dict()
        +str __str__()
    }

    class PseEncoder {
        <<JSONEncoder>>
        +default(o) object
    }

    ParameterLoader --> PropertySetEx
    PropertySetEx --> PseEncoder
Loading

Data Storage

graph LR
    subgraph People["LaserFrame: People"]
        S[S: Susceptible]
        E[E: Exposed]
        Isym[Isym: Symptomatic Infectious]
        Iasym[Iasym: Asymptomatic Infectious]
        R[R: Recovered]
        V1[V1: Vaccinated Dose 1]
        V2[V2: Vaccinated Dose 2]
    end

    subgraph Patches["LaserFrame: Patches"]
        N[N: Total Population]
        births[births: Birth Events]
        deaths[disease_deaths: Disease Deaths]
        incidence[incidence: New Cases]
        W[W: Environmental Reservoir]
        Lambda[Lambda: Force of Infection]
        Psi[Psi: Environmental Suitability]
    end

    Model --> People
    Model --> Patches
Loading

Likelihood Calculation

classDiagram
    class LikelihoodModule {
        +get_model_likelihood(obs_cases, sim_cases, obs_deaths, sim_deaths) float
    }

    class LikelihoodCalculators {
        +calc_log_likelihood(observed, simulated, family) float
        +calc_log_likelihood_beta(observed, simulated) float
        +calc_log_likelihood_binomial(observed, simulated, trials) float
        +calc_log_likelihood_gamma(observed, simulated) float
        +calc_log_likelihood_negbin(observed, simulated) float
        +calc_log_likelihood_normal(observed, simulated) float
        +calc_log_likelihood_poisson(observed, simulated) float
        +calc_log_likelihood_validation(observed, simulated) tuple
    }

    LikelihoodModule --> LikelihoodCalculators
Loading

State Transitions (SEIRV Model)

stateDiagram-v2
    [*] --> S: Birth
    S --> E: Infection (π›Œ)
    E --> Isym: Progression (π›Š Γ— 𝛔)
    E --> Iasym: Progression (π›Š Γ— (1-𝛔))
    Isym --> R: Recovery (𝛄<sub>1</sub>)
    Iasym --> R: Recovery (𝛄<sub>2</sub>)
    Isym --> [*]: Disease Death (𝛍)
    S --> [*]: Natural Death (𝛅)
    E --> [*]: Natural Death (𝛅)
    Isym --> [*]: Natural Death (𝛅)
    Iasym --> [*]: Natural Death (𝛅)
    R --> [*]: Natural Death (𝛅) 
    S --> V1imm: Vaccination (π›Ž<sub>1</sub>)
    S --> V1sus: Vaccination (π›Ž<sub>1</sub>)
    V1imm --> V2imm: Second Dose (π›Ž<sub>2</sub>)
    V1sus --> V2sus: Second Dose (π›Ž<sub>2</sub>)
    V1sus --> V1inf: Infection
    V2sus --> V2inf: Infection
    V1imm --> [*]: Natural Death (𝛅)
    V1sus --> [*]: Natural Death (𝛅)
    V2imm --> [*]: Natural Death (𝛅)
    V2sus --> [*]: Natural Death (𝛅)
Loading

Key Relationships

  • Model orchestrates the entire simulation
  • LaserFrame stores spatiotemporal data (nticks x npatches)
  • Components implement specific epidemiological processes
  • PropertySet manages all model parameters
  • RInterface provides transposed results for R compatibility
  • Analyzer calculates likelihood against observed data
  • Recorder saves results to HDF5 format

External Dependencies

graph TB
    LC[laser_cholera] --> LF[laser_core.laserframe]
    LC --> PS[laser_core.propertyset]
    LC --> RD[laser_core.random]
    LC --> NP[numpy]
    LC --> SP[scipy]
    LC --> PD[pandas]
    LC --> MPL[matplotlib]
    LC --> H5[h5py]
    LC --> CL[click]
Loading

Notes

  1. The model uses a daily time step (tick) simulation
  2. Spatial structure is represented by patches (locations)
  3. Stochastic processes use binomial and Poisson distributions
  4. Vaccination supports 2-dose regimen with partial efficacy
  5. Force of infection includes both human-to-human and environment-to-human transmission
  6. Seasonality is modeled through time-varying transmission rates
  7. Reporting delays are incorporated for cases and deaths
  8. Output can be saved in compressed HDF5 format

Clone this wiki locally