Metadata-Version: 2.4
Name: metastablex
Version: 0.1.0
Summary: Metastable dynamics detection for complex systems
Author: Lucas Amaral Dourado
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: torch

<h1 align="center">🧠 MetastableX</h1>
<h3 align="center">Structural Dynamics Framework for Complex Systems</h3>

<p align="center">
A computational framework for detecting structural instability, metastable regimes and critical transitions in complex systems using time-series analysis, statistical physics and information theory.
</p>

---

# 🧭 Overview

**MetastableX** is a computational framework designed to analyze the **structural dynamics of complex systems**.  
Rather than focusing only on averages or linear correlations, the framework analyzes **structural properties of temporal dynamics**.

The goal is to identify when a system transitions between regimes such as:

- Stable equilibrium
- Metastable configurations
- Critical transitions
- Chaotic dynamics

The framework integrates concepts from:

- Statistical Physics
- Nonlinear Dynamical Systems
- Information Theory
- Complex Systems Science
- Epidemiological Data Science

---

# ⚙️ Mathematical Framework

Many real-world systems can be modeled as stochastic dynamical systems:

$$
\frac{dx}{dt} = f(x) + \sigma \eta(t)
$$

Where:

- $x(t)$ represents the state of the system  
- $f(x)$ represents deterministic dynamics  
- $\sigma \eta(t)$ represents stochastic fluctuations

Such systems may evolve through **multiple dynamical regimes** depending on external perturbations and internal feedback loops.

---

# 🌄 Potential Landscape

Complex systems can be represented through an **effective potential landscape**.

If the probability density of states is $P(x)$, the effective potential is:

$$
U(x) = -\frac{\sigma^2}{2}\log P(x)
$$

Interpretation:

- Deep wells → stable regimes  
- Shallow wells → metastable regimes  
- Flattening landscape → critical transition  

When the landscape flattens, the system becomes highly sensitive to perturbations.

---

# ⚠️ Early Warning Signals

Before abrupt transitions, complex systems often exhibit **early warning signals**.

Two of the most robust signals are:

## Variance increase

$$
\sigma^2 =
\frac{1}{N}
\sum_{i=1}^{N}
(x_i - \mu)^2
$$

Variance measures the magnitude of fluctuations in the system.

An increase in variance indicates that the system is becoming unstable.

---

## Autocorrelation increase

$$
AC_1 =
\frac{
\sum_{t=2}^{N}(x_t-\mu)(x_{t-1}-\mu)
}{
\sum_{t=1}^{N}(x_t-\mu)^2
}
$$

Autocorrelation measures **temporal memory** in the system.

High values indicate **critical slowing down**, meaning the system takes longer to recover from perturbations.

---

# 🧬 Information-Theoretic Metrics

## Shannon Entropy

Entropy measures the informational complexity of the system.

$$
H =
-\sum_{i} p_i \log(p_i)
$$

Interpretation:

| Entropy | Interpretation |
|-------|---------------|
Low | rigid deterministic system |
Moderate | adaptive system |
High | chaotic regime |

---

# 📈 Long-Range Correlations (DFA)

Detrended Fluctuation Analysis detects **fractal memory** in time series.

First, the integrated signal is constructed:

$$
Y(k) =
\sum_{i=1}^{k}(x_i - \mu)
$$

Then fluctuations across scales are computed:

$$
F(n) =
\sqrt{
\frac{1}{N}
\sum (Y(k)-Y_n(k))^2
}
$$

The scaling exponent is obtained from:

$$
F(n) \sim n^{\alpha}
$$

Interpretation:

| α | Interpretation |
|---|--------------|
0.5 | random noise |
0.6–0.8 | long-range memory |
>0.9 | strong structural correlation |

---

# 📊 Distributional Metrics

## Skewness

$$
Skew =
\frac{1}{N}
\sum
\left(
\frac{x_i - \mu}{\sigma}
\right)^3
$$

Measures asymmetry in the distribution.

---

## Kurtosis

$$
Kurt =
\frac{1}{N}
\sum
\left(
\frac{x_i - \mu}{\sigma}
\right)^4
$$

Measures the presence of extreme events.

---

# 🔄 Dynamical Regime Classification

The framework classifies regimes using structural indicators.

| Regime | Condition |
|------|----------|
Stable | $AC_1 < 0.5$ |
Metastable | $0.5 \le AC_1 < 0.7$ |
Critical | $AC_1 \ge 0.7$ |

This classification is inspired by **phase transitions in statistical physics**.

---

# 🏥 Application: Structural Monitoring of Health Systems

Health systems behave as **large-scale complex adaptive systems** composed of interacting agents:

- hospitals
- patients
- healthcare workers
- policy interventions
- epidemiological dynamics

These interactions generate complex temporal patterns observable in **hospitalization data**.

Hospitalization time series therefore act as a proxy for the **systemic state of healthcare infrastructure**.

---

# 📊 Data Source: SIH/SUS

The application of MetastableX described here uses the **Hospital Information System of the Brazilian Unified Health System (SIH/SUS)**.

SIH is one of the largest health administrative datasets in the world.

Each record corresponds to an **Authorization for Hospital Admission (AIH)**.

Key variables include:

| Variable | Meaning |
|--------|--------|
DT_INTER | admission date |
DIAG_PRINC | primary diagnosis |
MUNIC_RES | municipality of residence |
DIAS_PERM | length of stay |
MORTE | mortality indicator |

These records allow the construction of **municipal hospitalization time series**.

---

# 👥 Population Normalization

Hospitalization counts must be normalized by population.

The hospitalization rate is defined as:

$$
Rate =
\frac{\text{Hospitalizations}}{\text{Population}}
\times 10\,000
$$

This transformation allows meaningful comparison across municipalities.

---

# 📈 Structural Monitoring of Municipal Health Systems

For each municipality the framework computes:

### Epidemiological indicators

- hospitalization counts
- hospitalization rate per 10k inhabitants

### Statistical indicators

- mean
- variance
- coefficient of variation

### Complexity indicators

- entropy
- DFA exponent

### Dynamical indicators

- autocorrelation
- rolling variance
- rolling autocorrelation

---

# ⚠️ Detecting Health System Stress

When a health system approaches overload or crisis, hospitalization dynamics may exhibit:

- increase in variance
- increase in autocorrelation
- entropy changes
- volatility spikes

These signals correspond to **loss of systemic resilience**.

Examples include:

- epidemic waves
- hospital overcrowding
- sudden changes in healthcare demand

---

# 📊 Interactive Dashboard

The MetastableX dashboard allows users to:

- select a municipality
- visualize hospitalization time series
- compute structural metrics
- generate automatic analytical reports

This creates a **structural monitoring interface for public health systems**.

---

# 🔬 Scientific Implications

The framework bridges:

- health data science
- epidemiology
- complex systems theory
- statistical physics

It enables monitoring healthcare systems not only through averages but through **dynamic regime analysis**.

---

# 🚀 Future Directions

Potential extensions include:

- nationwide monitoring of all municipalities
- metastable regime maps
- dynamic clustering of healthcare systems
- digital twin simulations of healthcare infrastructure

Such tools may enable **structural monitoring of national health systems in real time**.

---

# 👨‍🔬 Author

**Lucas Amaral Dourado**

- Medical Student — Federal University of Tocantins  
- Biomedical Engineering Student — UNINTER  

---

# 📜 License

MIT License

---

<p align="center">
MetastableX — Structural monitoring of complex systems applied to public health data.
</p>
