# **DE-VAE: Revealing Uncertainty in Parametric and Inverse Projections with Variational Autoencoders using Differential Entropy**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
[![Uses: venv](https://img.shields.io/badge/Environment-venv-blue)](https://docs.python.org/3/library/venv.html)
[![arXiv](https://img.shields.io/badge/paper-arXiv-red)](https://arxiv.org/abs/2508.12145)
[![OSF Project](https://img.shields.io/badge/OSF-View%20Project-lightgrey)](https://osf.io/zr6xf/)

📄 **Paper:** [Link](https://frederikdennig.com/publications/Dennig2025DE-VAE)

## Key Features

* Learns a parametric projection that maps high-dimensional data to a probabilistic latent space, enabling explicit modeling of uncertainty.
* Represents each data point as a full, diagonal, or isotropic Gaussian distribution.
* Provides an uncertainty-aware visualization of the projection, i.e., latent space, showing confidence around points.
* Includes an inverse model to reconstruct original data from projected points.
* Optimizes multiple losses to ensure accurate reconstruction, projection alignment, and interpretable uncertainty.

![Overview][1]

In this example, the encoder of a DE-VAE learns a parametric projection $P$ of MNIST, mapping each data point $x_i$ to a full Gaussian $\mathcal{N}(\mu, \Sigma)$, modeling the uncertainty of a UMAP projection. The decoder learns an inverse projection $P^{-1}$, taking $y_k$ and reconstructing a plausible sample $x̂_k$. $P$ enables uncertainty-aware visualization of the latent space. DE-VAEs optimize the losses: $L_{\text{recon}}$, ensuring reconstruction; $L_{\text{proj}}$, aligning $\mu$ with points of the projection; and $L_{\text{ent}}$, maximizing the variance of $\Sigma$. To show learned Gaussian distributions, we depict the 1st, 2nd, and 3rd standard deviations as ellipses around medoid points per class.

## Requirements

* **Python** ≥ 3.10 ([Python 3.10.x](https://www.python.org/downloads/release/python-3100/))
* **Virtual environment**: [venv](https://docs.python.org/3/library/venv.html) 

## How to Run

### 1. Setup Environment

```bash
# Create a virtual environment
python3 -m venv .venv

# Activate the environment
source .venv/bin/activate

# Install dependencies
pip3 install -r requirements.txt
```

### 2. Retrieve Trained Models

```bash
# Download pretrained models and datasets
sh ./retrieve_replication.sh
```

**Optional:** If you'd like to train the models yourself instead (this may take some time):

```bash
# Compute projection data
python3 projections.py

# Train VAE/AE models
python3 trainer.py
```

### 3. Visualize Results

Explore model outputs and projections visually, e.g., with:

```bash
# usage: visual.py [-h] --model MODEL
#
# Load a model from a specified path and show the latent space visualization.
#
# options:
#   -h, --help     show this help message and exit
#   --model MODEL  Path to the model file.

# Example:
python3 visual.py --model ./models/vae-full-fmnist-umap-p20.00-e4.00000-s0.pt
```

### 4. Show Quantitative Results
```bash
# usage: create_tables.py [-h] [--model MODEL] [--dataset DATASET] [--projection PROJECTION] [--all-latex] [--summary-latex]
#
# Generate and print evaluation tables.
#
# options:
#  -h, --help            show this help message and exit
#  --model MODEL         model name key (e.g., 'vae-full')
#  --dataset DATASET     dataset name key (e.g., 'mnist')
#  --projection PROJECTION
#                        projection name key (e.g., 'umap')
#  --all-latex           Run full evaluation to generate all LaTeX tables
#  --summary-latex       Generate summary LaTeX table

# Example:
python3 create_tables.py --model vae-full --dataset mnist --projection umap
```

### 5. Experimental: Train DE-VAE Models on Own Dataset 

```bash
# usage: main.py [-h] --model MODEL --data DATA [--label LABEL] --projection PROJECTION [--l-proj L_PROJ] [--l-ent L_ENT] [--seed SEED]
#
# Train DE-VAE models on custom datasets.
#
# options:
#   -h, --help            show this help message and exit
#   --model MODEL         model name key (e.g., 'vae-full')
#   --data DATA           high-dimensional data as CSV file
#   --label LABEL         Column name specifying class labels
#   --projection PROJECTION
#                         projection method key (e.g., 'umap', 'tsne', 'pca')
#   --l-proj L_PROJ       projection loss weight
#   --l-ent L_ENT         entropy loss weight
#   --seed SEED           random seed for reproducibility

# Example:
python3 main.py --model vae-diag --data datasets/blobs.csv --label "labels" --projection umap --l-proj 1.0 --l-ent 0.1 --seed 777

# Show visualization
python3 visual.py --model ./models/vae-diag-blobs_10-umap-p1.00-e0.10000-s777.pt
```

---

## File Overview

| File Name           | Description                                                                              |
| ------------------- | ---------------------------------------------------------------------------------------- |
| `create_tables.py`  | Generates tables summarizing model results for each dataset and projection method.       |
| `data_loader.py`    | Loads and preprocesses datasets: MNIST, FashionMNIST, KMNIST, and HAR.                   |
| `loss_functions.py` | Implements loss functions used during training of VAE/AE models.                         |
| `main.py`           | Enables training of DE-VAE models for user-defined datasets and parameters.              |
| `projections.py`    | Projects high-dimensional data to 2D using UMAP, t-SNE, PCA, MDS, Isomap, and LLE.       |
| `trainer.py`        | Training loop and utilities for training VAE/AE models.                                  |
| `vae_models.py`     | Defines the architectures for various VAE and AE model variants.                         |
| `visual.py`         | Visualizes latent space with uncertainty ellipses showing learned Gaussian distributions.|

## Datasets

The HAR (Human Activity Recognition Using Smartphones) dataset is redistributed here under
CC BY 4.0 from the [UCI Machine Learning Repository](https://archive.ics.uci.edu/dataset/240/human+activity+recognition+using+smartphones).

> Anguita, D., Ghio, A., Oneto, L., Parra, X., & Reyes-Ortiz, J. L. (2013). A Public Domain Dataset for Human Activity Recognition Using
> Smartphones. *ESANN 2013*, 437–442.

## License

This project is licensed under the [MIT License](https://opensource.org/licenses/MIT).

[1]: https://github.com/fredooo/DE-VAE/raw/main/overview.png