MMAING-AESOP

MMAING-AESOP is an early outbreak detection model based on the combination of:

• $R_t$ (time-dependent reproduction number estimated using a Next-Generation Matrix approach)
• An ensemble of machine learning models:
  • Isolation Forest
  • Local Outlier Factor (LOF)
  • One-Class Support Vector Machine (OCSVM)
  • COPOD

The model generates Early Warning Signals (EWS) from weekly primary healthcare time series.

If you use MMAING-AESOP in your research, please cite:

Borges, D. G. F., Coutinho, E. R., Cerqueira-Silva, T. et al. Combining machine learning and dynamic system techniques to early detection of respiratory outbreaks in routinely collected primary healthcare records. BMC Medical Research Methodology, 25, 99 (2025). https://doi.org/10.1186/s12874-025-02542-0

Installation

The mmaing_aesop package is available on PyPI.

Install it using:

pip install mmaing_aesop

Then import the package in Python:

from mmaing_aesop import MMAING

Example

from mmaing_aesop import MMAING

model = MMAING(
    # Ensemble
    vote_threshold=3,

    # Outlier detection / Machine learning 
    contamination=0.4,

    # Rt (Reproduction Number)
    limiar_rt=1.25,
    window_rt=5,
    gamma=0.2,

    # Machine learning (Isolation Forest, Local Outiler Factor, One class SVM )
    isf_n_estimators=500,
    lof_n_neighbors=500,
    ocsvm_nu=0.8,
    ocsvm_kernel="rbf",
    ocsvm_gamma=0.001,

    # Statistical limits
    alpha=0.05,
    window_limit=5,

    # Baseline and detection period
    baseline_years=[2017, 2018, 2019],
    start_year_detection=2020
)

model.fit(df[df["co_ibge"] == xxxxxx])

model.plot(co_ibge=xxxxxx)

Required input columns

The input DataFrame must contain the following columns:

• co_ibge: municipality IBGE code (six digits)
• municipio: municipality name
• ano: year
• epiweek: epidemiological week
• atend_ivas: number of primary healthcare encounters for respiratory syndromes

Example:

co_ibge    municipio     ano    epiweek    atend_ivas
355030     São Paulo     2017       1          125
355030     São Paulo     2017       2          138
355030     São Paulo     2017       3          142
...

Basic usage

Fit the model:

model.fit(df)

Retrieve all results:

results = model.get_results()

Retrieve only detected alerts:

alerts = model.get_alerts()

Plot the time series and MMAING alerts:

model.plot(co_ibge=xxxxxx)

Export the results to CSV:

model.to_csv("mmaing_results.csv")

Main parameters

Citation

Borges, D.G.F., Coutinho, E.R., Cerqueira-Silva, T. et al.
Combining machine learning and dynamic system techniques to early detection
of respiratory outbreaks in routinely collected primary healthcare records.
BMC Med Res Methodol 25, 99 (2025).
https://doi.org/10.1186/s12874-025-02542-0

License

MMAING-AESOP is distributed under the Apache License 2.0.