Recurrent Health Events Prediction - Master Thesis & ReadmitAI

This project investigates machine learning approaches for predicting recurrent health events—especially hospital readmissions—using structured clinical data. The repository contains code for two related works:

1. DT-HMM–based transfer learning (Master’s thesis, TU Darmstadt)
2. ReadmitAI: Attention-based deep learning models (Final Graduate Project / "TCC" at Poli-USP Brazil)

Both approaches are evaluated against baseline models using simple historical summary features (Logistic Regression, Random Forests, LightGBM).

Motivation

Hospital readmissions can be defined as unplanned admissions to a hospital within a certain time frame (e.g., 30 days) after discharge from a previous hospitalization. These events are often costly, frequent, and often preventable. Accurately identifying patients at high risk of returning to the hospital shortly after discharge helps clinicians intervene earlier, improve patient outcomes, and reduce pressure on healthcare systems.

While traditional approaches rely on coarse historical features, many relevant temporal patterns in a patient’s clinical trajectory may be lost. This motivates the exploration of sequential modeling methods capable of capturing richer temporal information.

---

Objectives

The DT-HMM–based transfer learning approach, developed in the Master’s thesis at TU Darmstadt, introduced an interpretable representation-learning method for patient trajectories. However, these features did not consistently outperform simple baselines.

Another work (ReadmitAI), performed at Poli-USP Brazil, extends this research by evaluating attention-based deep learning models as an alternative for extracting meaningful temporal patterns from longitudinal health data.

Together, the two main objectives of this project are:

1. Research Goal: Explore and compare sequential modeling techniques—DT-HMM and attention-based deep learning—against baseline models for predicting hospital readmission.
2. Practical Goal: Develop a prototype web application (FastAPI backend + Streamlit frontend) to demonstrate how such predictive models can be integrated into real clinical workflows.

---

ReadmitAI Web Application

The ReadmitAI web application provides an interactive interface for clinicians to input patient data and receive readmission risk predictions. The system architecture consists of a FastAPI backend that serves the predictive models (only one of the attention-based models) and a Streamlit frontend for user interaction.

Architecture Diagram:

Use Cases Diagram:

Sequence Diagram for Prediction Flow:

---

📦 Project Setup

1. Clone the Repository

git clone https://github.com/LucasVon0645/Master-Thesis--Project-ReadmitAI.git
cd master-thesis-recurrent-health-events-prediction

2. Set Up the Virtual Environment with Poetry

Make sure you have Poetry installed.

To create a virtual environment inside the project directory (.venv/):

poetry config virtualenvs.in-project true --local

Then install dependencies:

poetry install

3. Activate the Environment

poetry env activate

📦 Optional Setup: Using a Dev Container (Recommended for Reproducibility)

If you’re using Visual Studio Code and want a fully reproducible, OS-independent development environment, you can use the preconfigured Dev Container.

This ensures that all tools, dependencies, and Python versions are installed identically across machines — ideal for research and collaboration.

⚠️ Note: The first build of the container may take a long time (e.g., ~20–25 minutes).This is normal — the container compiles Python from source and installs scientific libraries with native code. Subsequent launches will be much faster thanks to Docker caching.

🔧 To Use the Dev Container:

1. Install Docker Desktop

2. Install Visual Studio Code

3. Install the Dev Containers extension in VS Code

4. Open the project folder in VS Code

5. Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux)

6. Select: Dev Containers: Reopen in Container

VS Code will build the environment and reopen your project inside a fully configured container.

---

🚀 Running the Project

For running the ReadmitAI web application, use the following commands to start the FastAPI backend and Streamlit frontend:

poetry run api

poetry run app

---

💾 Downloading the MIMIC Dataset

To download the necessary MIMIC files, run the following script:

bash scripts/download_mimic_files.sh

🔐 Note: You must have valid PhysioNet credentials and appropriate permissions to access the MIMIC dataset. Refer to the official MIMIC documentation for instructions on how to gain access.

---

📁 Project Structure

.
├── recurrent_health_events_prediction/   # Core source code for model training and prediction
├── app/                                  # Streamlit Web Application (Frontend)
├── api/                                  # FastAPI Backend serving model predictions
├── scripts/                              # Utility scripts (e.g., data preparation)
├── tests/                                # Automated tests (pytest)
├── docs/                                 # UML diagrams and backend documentation
├── assets/                               # Images, plots, and auxiliary files
│
│   # Local folders not tracked by Git
├── _models/                              # Trained models (deep learning, classical ML, HMMs)
├── _runs/                                # Training/evaluation runs and logs (e.g., TensorBoard)
├── _runs_optuna/                         # Hyperparameter optimization runs (Optuna)
│
├── pyproject.toml                        # Poetry project configuration and dependencies
├── poetry.lock                           # Locked dependency versions for reproducibility
└── README.md                             # Project documentation

---

✅ Requirements

• Python >=3.10 and <3.11
• Poetry
• Access to the MIMIC-III dataset

---

📚 References

• Poetry Documentation
• MIMIC Dataset Info