gengeneeval 0.7.1
Comprehensive evaluation of generated gene expression data. All metrics support raw, PCA, and DEG computation spaces. Features distributional metrics (W1, W2, MMD, Energy), per-context analysis, train/test splits, memory-efficient lazy loading, hardware acceleration (CPU/CUDA/MPS), and publication-quality visualizations.
License: MIT
Requires Python: <4.0,>=3.8
Keywords: gene expression, evaluation, metrics, single-cell, generative models, benchmarking, memory-efficient, DEG, perturbation, pca

# GenGeneEval

[![PyPI version](https://badge.fury.io/py/gengeneeval.svg)](https://badge.fury.io/py/gengeneeval)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://github.com/AndreaRubbi/GenGeneEval/actions/workflows/test.yml/badge.svg)](https://github.com/AndreaRubbi/GenGeneEval/actions)
[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://andrearubbi.github.io/GenGeneEval/)

**Comprehensive evaluation framework for generated gene expression data.**

GenGeneEval provides standardized metrics for comparing real and generated single-cell gene expression datasets. It addresses the critical need for reproducible benchmarking in generative modeling for single-cell biology.

## Features

- **10+ Comprehensive Metrics**: MSE, RMSE, MAE, R², Pearson, Spearman, W₁, W₂, MMD, Energy Distance
- **Multiple Computation Spaces**: All metrics support raw, PCA, and DEG spaces
- **DEG-Focused Evaluation**: Evaluate on differentially expressed genes with configurable thresholds
- **Hardware Acceleration**: Supports CPU, NVIDIA CUDA, and Apple Silicon (MPS) with automatic device selection
- **Memory Efficient**: Lazy loading and batched evaluation for atlas-scale data
- **Explicit Space Selection**: Clear metric naming (e.g., `pearson_pca50`, `mse_deg_welch`)

📚 **[Full Documentation](https://andrearubbi.github.io/GenGeneEval/)**

## Installation

```bash
pip install gengeneeval
```

See [Installation Guide](https://andrearubbi.github.io/GenGeneEval/getting-started/installation/) for details.

## Quick Start

### Python API

```python
import gengeneeval as gge
from gengeneeval.metrics import (
    PearsonCorrelation, SpearmanCorrelation, 
    MSEDistance, W1, W2, MMD, Energy
)

# All metrics now support space selection: "raw", "pca", "deg"
metrics = [
    # Correlation in raw and PCA space
    PearsonCorrelation(),  # raw space (default)
    PearsonCorrelation(space="pca", n_pca_components=50),
    
    # Reconstruction in different spaces
    MSEDistance(),  # raw space
    MSEDistance(space="pca", n_pca_components=50),
    
    # Distributional metrics with automatic device selection
    W2(space="pca", n_components=50, device="auto"),
    W2(space="deg", deg_method="welch", device="auto"),
]

results = gge.evaluate(
    real_path="real_data.h5ad",
    generated_path="generated_data.h5ad",
    condition_columns=["perturbation"],
    metrics=metrics,
    output_dir="results/"
)

print(results.summary())
```

### Command Line

```bash
gengeneeval --real real.h5ad --generated gen.h5ad \
    --conditions perturbation --output results/
```

See [Quick Start Guide](https://andrearubbi.github.io/GenGeneEval/getting-started/quickstart/) for more examples.

## Computation Spaces

All metrics support three computation spaces:

| Space | Description | When to Use |
|-------|-------------|-------------|
| **raw** | Original gene expression space | Baseline, high-dimensional comparison |
| **pca** | PCA-reduced latent space | Recommended for stability, removes noise |
| **deg** | DEG-filtered space | Biologically relevant genes only |

```python
# Example: Same metric in different spaces
import gengeneeval as gge
from gengeneeval.metrics import PearsonCorrelation, W2

# Raw space (default)
pearson_raw = PearsonCorrelation()  # name: "pearson"

# PCA space  
pearson_pca = PearsonCorrelation(space="pca", n_pca_components=50)  # name: "pearson_pca50"

# DEG space
pearson_deg = PearsonCorrelation(space="deg", deg_method="welch")  # name: "pearson_deg_welch"
```

## Documentation

| Section | Description |
|---------|-------------|
| [Installation](https://andrearubbi.github.io/GenGeneEval/getting-started/installation/) | Setup and requirements |
| [Quick Start](https://andrearubbi.github.io/GenGeneEval/getting-started/quickstart/) | Basic usage examples |
| [CLI Usage](https://andrearubbi.github.io/GenGeneEval/getting-started/cli/) | Command-line interface |
| [Metrics Guide](https://andrearubbi.github.io/GenGeneEval/guide/metrics/) | Available metrics |
| [Distributional Metrics](https://andrearubbi.github.io/GenGeneEval/guide/distributional/) | W₁, W₂, MMD, Energy |
| [DEG Evaluation](https://andrearubbi.github.io/GenGeneEval/guide/deg/) | DEG-focused analysis |
| [Scalability](https://andrearubbi.github.io/GenGeneEval/guide/scalability/) | Large dataset handling |
| [API Reference](https://andrearubbi.github.io/GenGeneEval/api/core/) | Full API docs |

## Metrics Overview

| Category | Metrics | Spaces Supported |
|----------|---------|------------------|
| **Reconstruction** | MSE, RMSE, MAE, R² | raw, pca, deg |
| **Correlation** | Pearson, Spearman | raw, pca, deg |
| **Distributional** | W₁, W₂, MMD, Energy | raw, pca, deg |

## Contributing

Contributions welcome! Please open an issue or submit a pull request.

## License

MIT License. See [LICENSE](LICENSE) for details.