Welcome to `flepimop2`¶

The next generation of the flexible epidemic modeling pipeline.

Quick Start¶

Installation¶

You'll need git and pipx on your system.

git clone git@github.com:ACCIDDA/flepimop2.git
cd flepimop2
pipx install .

This clones the source of the library, then uses it to install the application.

Create a Project¶

Somewhere else on your system, run the command

flepimop2 skeleton quick_start_project -v
cd quick_start_project

This will create a new directory, quick_start_project and populate that directory with some files. The -v flag (for "verbose") will cause skeleton to also display the created directory structure.

The most basic skeleton does not provide a system or engine: you will need to specify those. Here is an example SIR system and an example ODE engine:

Basic SIR Model

"""SIR model plugin for flepimop2 demo."""

import numpy as np

from flepimop2.typing import Float64NDArray


def stepper(
    t: float,  # noqa: ARG001
    y: Float64NDArray,
    beta: float,
    gamma: float,
) -> Float64NDArray:
    """
    Compute dY/dt for the SIR model.

    Args:
        t: The current time (not used in this model, but included for compatibility).
        y: A numpy array containing the current values [S, I, R].
        beta: The infection rate.
        gamma: The recovery rate.

    Returns:
        A numpy array containing the derivatives [dS/dt, dI/dt, dR/dt].

    """
    y_s, y_i, _ = np.asarray(y, dtype=float)
    infection = (beta * y_s * y_i) / np.sum(y)
    recovery = gamma * y_i
    dydt = [-infection, infection - recovery, recovery]
    return np.array(dydt, dtype=float)

Basic scipy ODE Solver Engine

"""ODE solver plugin that wraps `scipy.integrate.solve_ivp` for flepimop2 demo."""

from typing import Any

import numpy as np
from scipy.integrate import solve_ivp

from flepimop2.system.abc import SystemProtocol
from flepimop2.typing import Float64NDArray


def runner(
    fun: SystemProtocol,
    times: Float64NDArray,
    y0: Float64NDArray,
    params: dict[str, Any] | None = None,
    **solver_options: Any,
) -> Float64NDArray:
    """Solve an initial value problem using scipy.solve_ivp.

    Args:
        fun (SystemProtocol): A function that computes derivatives.
        times (Float64NDArray): sequence of time points where we evaluate the
          solution. Must have length >= 1.
        y0 (Float64NDArray): Initial condition.
        params: Optional dict of keyword parameters forwarded to fun.
        **solver_options: Additional keyword options forwarded to
          scipy.integrate.solve_ivp.

    Returns:
        FloatArray: Array with time and state values evaluated at `times`.
        Each row is [t, y...].

    Raises:
        ValueError: If `times` is not a 1D sequence of time points with length >= 1, or
            if the first time point is negative.

    """
    if not (times.ndim == 1 and times.size >= 1):
        msg = "times must be a 1D sequence of time points"
        raise ValueError(msg)

    times.sort()

    t0, tf = 0.0, times[-1]
    if times[0] < t0:
        msg = f"times[0] must be >= 0; got times[0]={times[0]}"
        raise ValueError(msg)

    args = tuple(val for val in params.values()) if params is not None else None
    result = solve_ivp(
        fun,
        (t0, tf),
        y0,
        t_eval=times,
        args=args,  # type: ignore[arg-type]
        **solver_options,
    )
    return np.transpose(np.vstack((result.t, result.y)))

You'll also need to update the skeleton configuration file with these additions and set some parameters:

system:
  - module: wrapper
    script: model_input/plugins/SIR.py

engine:
  - module: wrapper
    script: model_input/plugins/solve_ivp.py

parameter:
  beta:
    module: fixed
    value: 0.3
  gamma:
    module: fixed
    value: 0.1
  s0:
    module: fixed
    value: 999
  i0:
    module: fixed
    value: 1
  r0:
    module: fixed
    value: 0

Simulate an Outbreak¶

Within the quick_start_project folder, you can now use flepimop2 to run your model:

flepimop2 simulate configs/config.yaml

What is `flepimop`?¶

The flepimop python package is a combined command line interface and library. The CLI application works with user commands and configuration files to execute analysis pipelines. Because flepimop is also a library, users can write their own flexible analyses leveraging that library to read and write data (and configuration information) in a way that "just works" with the pipeline. Additionally, advanced users can develop their own shareable modules that work with the pipeline.

illustration of analysis flow illustration of how elements fit together

Work with Us!¶

To contribute to the main flepimop2 pipeline, you can join us on github.

contact info, invitation to collaborate / contribute to repo

Site Development¶

This site uses Material for MkDocs, which is a theme for MkDocs.

To launch the site in developer mode, navigate to the flepimop2 repo and then invoke at the command prompt:

just serve

Welcome to flepimop2¶