gengeneeval 0.2.1__py3-none-any.whl → 0.4.0__py3-none-any.whl

{gengeneeval-0.2.1.dist-info → gengeneeval-0.4.0.dist-info}/METADATA

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: gengeneeval
-Version: 0.2.1
-Summary: Comprehensive evaluation of generated gene expression data. Computes metrics between real and generated datasets with support for condition matching, train/test splits, memory-efficient lazy loading, and publication-quality visualizations.
+Version: 0.4.0
+Summary: Comprehensive evaluation of generated gene expression data. Computes metrics between real and generated datasets with support for condition matching, DEG-focused evaluation, per-context analysis, train/test splits, memory-efficient lazy loading, CPU parallelization, GPU acceleration, and publication-quality visualizations.
 License: MIT
 License-File: LICENSE
-Keywords: gene expression,evaluation,metrics,single-cell,generative models,benchmarking,memory-efficient
+Keywords: gene expression,evaluation,metrics,single-cell,generative models,benchmarking,memory-efficient,DEG,perturbation
 Author: GenEval Team
 Author-email: geneval@example.com
 Requires-Python: >=3.8,<4.0
@@ -24,6 +24,7 @@ Provides-Extra: full
 Provides-Extra: gpu
 Requires-Dist: anndata (>=0.8.0)
 Requires-Dist: geomloss (>=0.2.1) ; extra == "full" or extra == "gpu"
+Requires-Dist: joblib (>=1.0.0)
 Requires-Dist: matplotlib (>=3.5.0)
 Requires-Dist: numpy (>=1.21.0)
 Requires-Dist: pandas (>=1.3.0)
@@ -77,8 +78,12 @@ All metrics are computed **per-gene** (returning a vector) and **aggregated**:
 - ✅ Condition-based matching (perturbation, cell type, etc.)
 - ✅ Train/test split support
 - ✅ Per-gene and aggregate metrics
+- ✅ **DEG-focused evaluation** with per-context (covariate × perturbation) support
+- ✅ **Fast DEG detection** via vectorized Welch's t-test, Student's t-test, Wilcoxon
 - ✅ **Memory-efficient lazy loading** for large datasets
 - ✅ **Batched evaluation** to avoid OOM errors
+- ✅ **CPU parallelization** via joblib (multi-core speedup)
+- ✅ **GPU acceleration** via PyTorch (10-100x speedup)
 - ✅ Modular, extensible architecture
 - ✅ Command-line interface
 - ✅ Publication-quality visualizations
@@ -173,6 +178,162 @@ with load_data_lazy("real.h5ad", "gen.h5ad", ["perturbation"]) as loader:
         pass
 ```
 
+### Accelerated Evaluation (CPU Parallelization & GPU)
+
+GenEval supports CPU parallelization and GPU acceleration for significant speedups:
+
+```python
+from geneval import evaluate, get_available_backends
+
+# Check available backends
+print(get_available_backends())
+# {'joblib': True, 'torch': True, 'geomloss': True, 'cuda': True, 'mps': False}
+
+# Parallel CPU evaluation (use all cores)
+results = evaluate(
+    real_path="real.h5ad",
+    generated_path="generated.h5ad",
+    condition_columns=["perturbation"],
+    n_jobs=-1,  # Use all available CPU cores
+)
+
+# GPU-accelerated evaluation
+results = evaluate(
+    real_path="real.h5ad",
+    generated_path="generated.h5ad",
+    condition_columns=["perturbation"],
+    device="cuda",  # Use NVIDIA GPU
+)
+
+# Combined: parallel CPU + auto device selection
+results = evaluate(..., n_jobs=8, device="auto")
+```
+
+#### Low-level Accelerated API
+
+For custom workflows, use the accelerated metrics directly:
+
+```python
+from geneval.metrics.accelerated import (
+    compute_metrics_accelerated,
+    GPUWasserstein1,
+    GPUMMD,
+    vectorized_wasserstein1,
+)
+import numpy as np
+
+# Load your data
+real = np.random.randn(1000, 5000)      # 1000 cells, 5000 genes
+generated = np.random.randn(1000, 5000)
+
+# Compute multiple metrics with acceleration
+results = compute_metrics_accelerated(
+    real, generated,
+    metrics=["wasserstein_1", "wasserstein_2", "mmd", "energy"],
+    n_jobs=8,          # CPU parallelization
+    device="cuda",     # GPU acceleration
+    verbose=True,
+)
+
+# Access results
+print(f"W1: {results['wasserstein_1'].aggregate_value:.4f}")
+print(f"MMD: {results['mmd'].aggregate_value:.4f}")
+```
+
+#### Performance Tips
+
+| Optimization | Speedup | When to Use |
+|--------------|---------|-------------|
+| `n_jobs=-1` (all cores) | 4-16x | Always (if joblib available) |
+| `device="cuda"` | 10-100x | Large datasets, NVIDIA GPU available |
+| `device="mps"` | 5-20x | Apple Silicon Macs |
+| Vectorized NumPy | 2-5x | Automatic fallback |
+
+### DEG-Focused Evaluation
+
+GenEval supports **Differentially Expressed Genes (DEG)-focused evaluation**, computing metrics only on biologically relevant DEGs rather than all genes. This provides more meaningful evaluation for perturbation prediction tasks.
+
+#### Key Features
+
+- **Fast DEG detection**: Vectorized Welch's t-test, Student's t-test, or Wilcoxon rank-sum
+- **Per-context evaluation**: Automatically evaluates each (covariate × perturbation) combination
+- **GPU acceleration**: DEG detection and metrics on GPU for large datasets
+- **Comprehensive reporting**: Aggregated and expanded results with visualizations
+
+#### Quick Start
+
+```python
+from geneval import evaluate_degs
+import pandas as pd
+
+# Evaluate with DEG-focused metrics
+results = evaluate_degs(
+    real_data=real_adata.X,           # (n_samples, n_genes)
+    generated_data=gen_adata.X,
+    real_obs=real_adata.obs,
+    generated_obs=gen_adata.obs,
+    condition_columns=["cell_type", "perturbation"],  # Context columns
+    control_key="control",            # Value indicating control samples
+    perturbation_column="perturbation",
+    deg_method="welch",               # or "student", "wilcoxon", "logfc"
+    pval_threshold=0.05,
+    lfc_threshold=0.5,                # log2 fold change threshold
+    device="cuda",                    # GPU acceleration
+)
+
+# Access results
+print(results.aggregated_metrics)     # Summary across all contexts
+print(results.expanded_metrics)       # Per-context metrics
+print(results.deg_summary)            # DEG counts per context
+
+# Save results with plots
+results.save("deg_evaluation/")
+```
+
+#### Per-Context Evaluation
+
+When multiple condition columns are provided (e.g., `["cell_type", "perturbation"]`), GenEval evaluates **every combination** separately:
+
+| Context | n_DEGs | W1 (DEGs only) | MMD (DEGs only) |
+|---------|--------|----------------|-----------------|
+| TypeA_drug1 | 234 | 0.42 | 0.031 |
+| TypeA_drug2 | 189 | 0.38 | 0.027 |
+| TypeB_drug1 | 312 | 0.51 | 0.045 |
+
+If only `perturbation` column is provided, evaluation is done per-perturbation.
+
+#### Available DEG Methods
+
+| Method | Description | Speed |
+|--------|-------------|-------|
+| `welch` | Welch's t-test (unequal variance) | ⚡ Fast |
+| `student` | Student's t-test (equal variance) | ⚡ Fast |
+| `wilcoxon` | Wilcoxon rank-sum (non-parametric) | 🐢 Slower |
+| `logfc` | Log fold change only (no p-value) | ⚡⚡ Fastest |
+
+#### Visualization
+
+```python
+from geneval.deg import (
+    plot_deg_distributions,
+    plot_context_heatmap,
+    plot_deg_counts,
+    create_deg_report,
+)
+
+# Distribution of metrics across contexts
+plot_deg_distributions(results, save_path="dist.png")
+
+# Heatmap: context × metric
+plot_context_heatmap(results, save_path="heatmap.png")
+
+# DEG counts per context (up/down regulated)
+plot_deg_counts(results, save_path="deg_counts.png")
+
+# Generate comprehensive report
+create_deg_report(results, "report/", include_plots=True)
+```
+
 ## Expected Data Format
 
 GenEval expects AnnData (h5ad) files with:

{gengeneeval-0.2.1.dist-info → gengeneeval-0.4.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-geneval/__init__.py,sha256=_WxX5Kjk7y3u7mBZ5cf6ficy9SIT2FutZNcMe1fr9Ro,3989
+geneval/__init__.py,sha256=1ENlptAErFX1ThLDuO8J5Hs0ko5gIxGGVq7PZUhBUKY,5418
 geneval/cli.py,sha256=0ai0IGyn3SSmEnfLRJhcr0brvUxuNZHE4IXod7jvosU,9977
 geneval/config.py,sha256=gkCjs_gzPWgUZNcmSR3Y70XQCAZ1m9AKLueaM-x8bvw,3729
 geneval/core.py,sha256=No0DP8bNR6LedfCWEedY9C5r_c4M14rvSPaGZqbxc94,1155
@@ -6,12 +6,18 @@ geneval/data/__init__.py,sha256=NQUPVpUnBIabrTH5TuRk0KE9S7sVO5QetZv-MCQmZuw,827
 geneval/data/gene_expression_datamodule.py,sha256=XiBIdf68JZ-3S-FaZsrQlBJA7qL9uUXo2C8y0r4an5M,8009
 geneval/data/lazy_loader.py,sha256=5fTRVjPjcWvYXV-uPWFUF2Nn9rHRdD8lygAUkCW8wOM,20677
 geneval/data/loader.py,sha256=zpRmwGZ4PJkB3rpXXRCMFtvMi4qvUrPkKmvIlGjfRpY,14555
-geneval/evaluator.py,sha256=wZFzLo2PLHanjA-9L6C3xJBjMWXxPM63kU6usU4P7bs,11619
+geneval/deg/__init__.py,sha256=joH816k_UWvu2qVhWb-fTbMQTmAhz4nUvt6yraziRek,1499
+geneval/deg/context.py,sha256=_9gnWnRqqCZUDlegV2sT_rQrw8OeP1TIE9NZjNcI0ig,9069
+geneval/deg/detection.py,sha256=gDdHOyFLOfl_B0xutS3KVFy53sreJ19N33B0RRI01wo,18119
+geneval/deg/evaluator.py,sha256=MiBT2GOXUwq9rxHVAnJOVSbybX0rVgTsSDvOeJtnanE,18570
+geneval/deg/visualization.py,sha256=9lWW9vRH_FbkIjJrf1MPobU1Yu_CAh6aw60S7g2Qe2k,10448
+geneval/evaluator.py,sha256=WgdrgqOcGYT35k1keiFEIIRIj2CQaD2DsmBpq9hcLrI,13440
 geneval/evaluators/__init__.py,sha256=i11sHvhsjEAeI3Aw9zFTPmCYuqkGxzTHggAKehe3HQ0,160
 geneval/evaluators/base_evaluator.py,sha256=yJL568HdNofIcHgNOElSQMVlG9oRPTTDIZ7CmKccRqs,5967
 geneval/evaluators/gene_expression_evaluator.py,sha256=v8QL6tzOQ3QVXdPMM8tFHTTviZC3WsPRX4G0ShgeDUw,8743
 geneval/lazy_evaluator.py,sha256=I_VvDolxPFGiW38eGPrjSoBOKICKyYN3GHbjJBAe5tg,13200
-geneval/metrics/__init__.py,sha256=H5IXTKR-zoP_pGht6ioJfhLU7IHrSDQElMk0Cp4-JTw,1786
+geneval/metrics/__init__.py,sha256=yVlNcFxfudOE4q-Y1VNJIXw1HrM70LkxocJgg3Cp7vo,2359
+geneval/metrics/accelerated.py,sha256=iVxXg1Bf4aAeh-0kz7JRZS1I7xHHy9vNRozGDmCY_QY,27364
 geneval/metrics/base_metric.py,sha256=prbnB-Ap-P64m-2_TUrHxO3NFQaw-obVg1Tw4pjC5EY,6961
 geneval/metrics/correlation.py,sha256=jpYmaihWK89J1E5yQinGUJeB6pTZ21xPNHJi3XYyXJE,6987
 geneval/metrics/distances.py,sha256=9mWzbMbIBY1ckOd2a0l3by3aEFMQZL9bVMSeP44xzUg,16155
@@ -27,8 +33,8 @@ geneval/utils/preprocessing.py,sha256=1Cij1O2dwDR6_zh5IEgLPq3jEmV8VfIRjfQrHiKe3M
 geneval/visualization/__init__.py,sha256=LN19jl5xV4WVJTePaOUHWvKZ_pgDFp1chhcklGkNtm8,792
 geneval/visualization/plots.py,sha256=3K94r3x5NjIUZ-hYVQIivO63VkLOvDWl-BLB_qL2pSY,15008
 geneval/visualization/visualizer.py,sha256=lX7K0j20nAsgdtOOdbxLdLKYAfovEp3hNAnZOjFTCq0,36670
-gengeneeval-0.2.1.dist-info/METADATA,sha256=aRjsh5JUIcH8huIngsCi14eyE3-Vl_AFv9Uo1j5mciw,7497
-gengeneeval-0.2.1.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-gengeneeval-0.2.1.dist-info/entry_points.txt,sha256=xTkwnNa2fP0w1uGVsafzRTaCeuBSWLlNO-1CN8uBSK0,43
-gengeneeval-0.2.1.dist-info/licenses/LICENSE,sha256=RDHgHDI4rSDq35R4CAC3npy86YUnmZ81ecO7aHfmmGA,1073
-gengeneeval-0.2.1.dist-info/RECORD,,
+gengeneeval-0.4.0.dist-info/METADATA,sha256=R3GI2E_z6qC1olM0D3aPKrJ3yjQDf_9-GncDqvNhwMY,12879
+gengeneeval-0.4.0.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+gengeneeval-0.4.0.dist-info/entry_points.txt,sha256=xTkwnNa2fP0w1uGVsafzRTaCeuBSWLlNO-1CN8uBSK0,43
+gengeneeval-0.4.0.dist-info/licenses/LICENSE,sha256=RDHgHDI4rSDq35R4CAC3npy86YUnmZ81ecO7aHfmmGA,1073
+gengeneeval-0.4.0.dist-info/RECORD,,