SIB

SIB: [S]tatistical [I]nference in Epidemics via [B]elief Propagation

Message passing algorithm for individual-level inference in epidemics. SIB assumes that the epidemic process is generated by a compartmental model (currently a generalized semi-continuous time SIR model is implemented). Among other things, SIB computes the probability of each individual to be susceptible, infected or recovered at a given time from a list of contacts and partial observations. The method is based on Belief Propagation equations for partial trajectories. See notes and article or go directly to results for more details.

Requirements

• A C++11 compiler
• python3
• pybind11

Install

you can choose one of the following procedures:

• make

  1. Adjust Makefile, if needed.
  2. type: make

• pip install

  1. Adjust the setup.py, if needed.
  2. pip install .

You'll obtain a standalone CLI ./sib, plus a dynamic library containing a python module sib.

When not installing with pip, make sure to include the sib folder into the python path.

note for macosx users

Use OpenMP with Apple Clang and Homebrew libomp:

1. Check requirements.
2. Create a conda env (tested with python=3.8) and activate it
3. conda install openmp
4. open setup.py and uncomment the following line:
   • COMPILE_FLAGS = "-fPIC -std=c++11 -Wall -O3 -g -Xpreprocessor -fopenmp"
   • extra_link_args = ["-lomp", "-lm"]
5. pip install . in the sib folder.

Quick start

Have a look at this notebook.

Results

Have a look at this document for some preliminary results on the containment of the Covid-19 epidemics.

Reference

This code implements and expands the method described in this paper.

Documentation

python module

Classes

sib.Params(
  prob_i = Uniform(1.0), 
  prob_r = Exponential(0.1), 
  pseed = 0.01, 
  psus = 0.5, 
  softconstraint = 0):
    
    Settings the parameters of the model used for inference.

    Parameters
    ----------
    prob_i : Function - optional
        function to compute the probability of infection, 
        depending on the difference (t-ti), ti time of infection.
        [default: Uniform]
    prob_r : Function - optional
        function to compute the probability of recovery, 
        depending on the difference (t-ti), ti time of infection.
        [default: exponential decay with mu = 0.1]
    pseed : Float - optional
        Prior to be source of infections (infected at starting times).
        [default 1e-2]
    psus: Float - optional
        Prior to be susceptible.
        [default: 0.5]        

  
    Returns
    -------
    None

sib.FactorGraph(
  Params,
  contacts = [],
  tests = [],
  individuals = []
)
    Construct the factor graph from the list of contacts,
    the lists of observations, the Parameters of the model.
    Eventually is possible to set infectiousness and 
    recoverability priors on each individual.

    Parameters
    ----------
    Params: Class sib.Params -- optional
        see sib.Params
    contacts: list<tuple(int, int, int, float)>
        list of single direct contacts (for bidirectional contacts add also
        the inverse contact). Order of tuple contact: (node_i, node_j, time, lambda)
        The lambdas are the instantaneous probability of infection.
    tests: list<tuple(int, sib.Test, int)>
        list of single observation on single node a time t. Order of observation tuple: (node_i, sib.Test, time). sib.Test is a class containing the probability to be susceptible, infected, recovery, given by medical tests or symptoms.
    individuals: list(tuple(int, prior_t, prior_r)) [optional]
        List of tuple where each tuple are the prior on the infectiousness and recoverability of node "i".

    return
    ------
      Class FactorGraph

sib.Test(
  ps = 0.0, 
  pi = 0.0, 
  pr = 0.0
)
Evidence given by a test.
    Parameters
    ----------
    ps: probability to be susceptible
    pi: probability to be infected
    pr: probability to be recovery

sib.iterate(
  f,
  maxit=100,
  tol=1e-3, 
  damping=0.0,
  callback=(lambda t, err, f: print(t, err, flush=True))
)
Iterate the BP messages.
    Parameters
    ----------
    f: FactorGraph class
      The factor graph. See sib.FactorGraph
    maxit: int -- optional
      max number of iteration of update of BP equation
    tol: float -- optional
      If the error of the update of BP equation is less than `tol`the iteration stop.
    damping: float -- optional
      Damping parameter to help the convergence of BP equation.
    callback: function(iter_n, err, f) -- optional
      Function callback, called after each iteration. Take as argument the number of current iteration (iter_n), error (err), and the FactorGraph (f). 

Contributions

If you want to participate write us (sibyl-team) or make a pull request.

License

Apache License 2.0

Maintainers

The sibyl-team:

Alfredo Braunstein ([email protected]), Alessandro Ingrosso (@ai_ingrosso), Indaco Biazzo (@ocadni), Luca Dall'Asta, Anna Paola Muntoni, Fabio Mazza, Giovanni Catania

Acknowledgements

This project has been partially funded by Fondazione CRT through call "La Ricerca dei Talenti", project SIBYL and by the SmartData@PoliTO center on Big Data and Data Science.