Metadata-Version: 2.4
Name: mmaing_aesop
Version: 0.2.1
Summary: Mixed Model of Artificial Intelligence and Next-Generation for outbreak detection.
Author-email: Dérick Borges <derick.gabriel@ufba.br>
License: Apache-2.0
Project-URL: Homepage, https://pypi.org/project/mmaing_aesop/
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: pandas
Requires-Dist: numpy
Requires-Dist: scikit-learn
Requires-Dist: pyod
Requires-Dist: matplotlib
Requires-Dist: scipy

# 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:

```bash
pip install mmaing_aesop
```

Then import the package in Python:

```python
from mmaing_aesop import MMAING
```

---

## Example

```python
from mmaing_aesop import MMAING

model = MMAING(
    # Ensemble
    vote_threshold=3,

    # Outlier detection
    contamination=0.4,

    # Rt
    limiar_rt=1.25,
    window_rt=5,
    gamma=0.2,

    # Machine learning
    isf_n_estimators=500,
    lof_n_neighbors=200,
    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_real[df_real["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:

```text
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:

```python
model.fit(df)
```

Retrieve all results:

```python
results = model.get_results()
```

Retrieve only detected alerts:

```python
alerts = model.get_alerts()
```

Plot the time series and MMAING alerts:

```python
model.plot(co_ibge=355030)
```

Export the results to CSV:

```python
model.to_csv("mmaing_results.csv")
```

---

## Main parameters

| Parameter | Default | Description |
|---|---:|---|
| `vote_threshold` | `3` | Minimum number of votes required to generate an MMAING alert |
| `contamination` | `0.4` | Expected proportion of anomalies used by the outlier detection models |
| `limiar_rt` | `1.25` | Threshold used for the $R_t$ component |
| `window_rt` | `5` | Window used in the $R_t$ calculation |
| `gamma` | `0.2` | Recovery-rate parameter used in the dynamic model |
| `isf_n_estimators` | `500` | Number of trees in the Isolation Forest |
| `lof_n_neighbors` | `500` | Number of neighbors used by LOF |
| `ocsvm_nu` | `0.8` | `nu` parameter of the One-Class SVM |
| `ocsvm_kernel` | `"rbf"` | Kernel used by the One-Class SVM |
| `ocsvm_gamma` | `0.001` | Kernel coefficient used by the One-Class SVM |
| `alpha` | `0.05` | Significance level used to calculate statistical limits |
| `window_limit` | `5` | Window used for the recent statistical limit |
| `baseline_years` | `[2017, 2018, 2019]` | Years used as the historical baseline |
| `start_year_detection` | `2020` | First year included in the detection period |

---

## Citation

```text
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.
