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

geneval/deg/visualization.py

@@ -0,0 +1,376 @@
+"""
+Visualization module for DEG evaluation results.
+
+Provides:
+- Distribution plots for metrics across contexts
+- Heatmaps for context × metric results
+- Comprehensive DEG reports
+"""
+from __future__ import annotations
+
+from typing import Optional, List, Dict, Union, Any, TYPE_CHECKING
+from pathlib import Path
+import numpy as np
+
+if TYPE_CHECKING:
+    import matplotlib.pyplot as plt
+    import pandas as pd
+    from .evaluator import DEGEvaluationResult
+
+
+def _check_matplotlib():
+    """Check if matplotlib is available."""
+    try:
+        import matplotlib.pyplot as plt
+        return plt
+    except ImportError:
+        raise ImportError("matplotlib is required for visualization. Install with: pip install matplotlib")
+
+
+def _check_seaborn():
+    """Check if seaborn is available."""
+    try:
+        import seaborn as sns
+        return sns
+    except ImportError:
+        return None  # Seaborn is optional
+
+
+def plot_deg_distributions(
+    results: "DEGEvaluationResult",
+    metrics: Optional[List[str]] = None,
+    figsize: tuple = (12, 4),
+    save_path: Optional[Union[str, Path]] = None,
+    show: bool = True,
+) -> "plt.Figure":
+    """
+    Plot distribution of metrics across contexts.
+    
+    Creates violin/box plots showing metric distributions across all contexts.
+    
+    Parameters
+    ----------
+    results : DEGEvaluationResult
+        DEG evaluation results
+    metrics : List[str], optional
+        Metrics to plot. If None, plots all available.
+    figsize : tuple
+        Figure size per metric
+    save_path : str or Path, optional
+        Path to save figure
+    show : bool
+        Whether to display the figure
+        
+    Returns
+    -------
+    plt.Figure
+        Matplotlib figure
+    """
+    plt = _check_matplotlib()
+    sns = _check_seaborn()
+    
+    df = results.expanded_metrics
+    
+    if metrics is None:
+        # Get all numeric columns that are metrics
+        metrics = [c for c in df.columns if c in results.settings.get("metrics", [])]
+    
+    if len(metrics) == 0:
+        raise ValueError("No metrics to plot")
+    
+    n_metrics = len(metrics)
+    fig, axes = plt.subplots(1, n_metrics, figsize=(figsize[0], figsize[1]))
+    
+    if n_metrics == 1:
+        axes = [axes]
+    
+    for ax, metric in zip(axes, metrics):
+        values = df[metric].dropna()
+        
+        if sns is not None:
+            sns.violinplot(y=values, ax=ax, inner="box")
+        else:
+            ax.boxplot(values, vert=True)
+        
+        ax.set_title(metric)
+        ax.set_ylabel("Value")
+        
+        # Add mean annotation
+        mean_val = values.mean()
+        ax.axhline(mean_val, color='red', linestyle='--', alpha=0.5, label=f'Mean: {mean_val:.3f}')
+        ax.legend(loc='upper right', fontsize=8)
+    
+    plt.suptitle("Metric Distributions Across Contexts (DEGs only)", y=1.02)
+    plt.tight_layout()
+    
+    if save_path:
+        fig.savefig(save_path, dpi=150, bbox_inches='tight')
+    
+    if show:
+        plt.show()
+    
+    return fig
+
+
+def plot_context_heatmap(
+    results: "DEGEvaluationResult",
+    metrics: Optional[List[str]] = None,
+    figsize: tuple = (12, 8),
+    cmap: str = "RdYlBu_r",
+    save_path: Optional[Union[str, Path]] = None,
+    show: bool = True,
+) -> "plt.Figure":
+    """
+    Plot heatmap of metrics across contexts.
+    
+    Parameters
+    ----------
+    results : DEGEvaluationResult
+        DEG evaluation results
+    metrics : List[str], optional
+        Metrics to include
+    figsize : tuple
+        Figure size
+    cmap : str
+        Colormap name
+    save_path : str or Path, optional
+        Path to save figure
+    show : bool
+        Whether to display
+        
+    Returns
+    -------
+    plt.Figure
+        Matplotlib figure
+    """
+    plt = _check_matplotlib()
+    sns = _check_seaborn()
+    
+    df = results.expanded_metrics
+    
+    if metrics is None:
+        metrics = [c for c in df.columns if c in results.settings.get("metrics", [])]
+    
+    # Create matrix for heatmap
+    heatmap_data = df.set_index("context_id")[metrics]
+    
+    fig, ax = plt.subplots(figsize=figsize)
+    
+    if sns is not None:
+        sns.heatmap(
+            heatmap_data,
+            ax=ax,
+            cmap=cmap,
+            annot=True,
+            fmt=".3f",
+            cbar_kws={"label": "Metric Value"},
+        )
+    else:
+        im = ax.imshow(heatmap_data.values, cmap=cmap, aspect='auto')
+        plt.colorbar(im, ax=ax, label="Metric Value")
+        ax.set_xticks(range(len(metrics)))
+        ax.set_xticklabels(metrics, rotation=45, ha='right')
+        ax.set_yticks(range(len(heatmap_data)))
+        ax.set_yticklabels(heatmap_data.index)
+    
+    ax.set_title("Metrics per Context (DEGs only)")
+    ax.set_xlabel("Metric")
+    ax.set_ylabel("Context")
+    
+    plt.tight_layout()
+    
+    if save_path:
+        fig.savefig(save_path, dpi=150, bbox_inches='tight')
+    
+    if show:
+        plt.show()
+    
+    return fig
+
+
+def plot_deg_counts(
+    results: "DEGEvaluationResult",
+    figsize: tuple = (10, 6),
+    save_path: Optional[Union[str, Path]] = None,
+    show: bool = True,
+) -> "plt.Figure":
+    """
+    Plot DEG counts per context.
+    
+    Parameters
+    ----------
+    results : DEGEvaluationResult
+        DEG evaluation results
+    figsize : tuple
+        Figure size
+    save_path : str or Path, optional
+        Path to save figure
+    show : bool
+        Whether to display
+        
+    Returns
+    -------
+    plt.Figure
+        Matplotlib figure
+    """
+    plt = _check_matplotlib()
+    
+    df = results.deg_summary
+    
+    if len(df) == 0:
+        raise ValueError("No DEG data to plot")
+    
+    fig, ax = plt.subplots(figsize=figsize)
+    
+    x = range(len(df))
+    width = 0.35
+    
+    if "n_upregulated" in df.columns and "n_downregulated" in df.columns:
+        ax.bar(x, df["n_upregulated"], width, label='Upregulated', color='red', alpha=0.7)
+        ax.bar(x, -df["n_downregulated"], width, label='Downregulated', color='blue', alpha=0.7)
+        ax.axhline(0, color='black', linewidth=0.5)
+        ax.set_ylabel("Number of DEGs")
+    else:
+        ax.bar(x, df["n_degs"], color='purple', alpha=0.7)
+        ax.set_ylabel("Number of DEGs")
+    
+    ax.set_xlabel("Context")
+    ax.set_xticks(x)
+    ax.set_xticklabels(df["context_id"], rotation=45, ha='right')
+    ax.set_title("DEG Counts per Context")
+    ax.legend()
+    
+    plt.tight_layout()
+    
+    if save_path:
+        fig.savefig(save_path, dpi=150, bbox_inches='tight')
+    
+    if show:
+        plt.show()
+    
+    return fig
+
+
+def create_deg_report(
+    results: "DEGEvaluationResult",
+    output_dir: Union[str, Path],
+    include_plots: bool = True,
+) -> None:
+    """
+    Create a comprehensive DEG evaluation report.
+    
+    Creates:
+    - Summary statistics (CSV)
+    - Aggregated metrics (CSV)
+    - Expanded per-context metrics (CSV)
+    - DEG summary per context (CSV)
+    - Visualization plots (PNG, if include_plots=True)
+    - Markdown report
+    
+    Parameters
+    ----------
+    results : DEGEvaluationResult
+        DEG evaluation results
+    output_dir : str or Path
+        Output directory
+    include_plots : bool
+        Whether to generate plots
+    """
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    
+    # Save CSVs
+    results.save(output_dir)
+    
+    # Generate plots
+    if include_plots:
+        try:
+            plt = _check_matplotlib()
+            
+            # Distribution plot
+            if len(results.expanded_metrics) > 0:
+                plot_deg_distributions(
+                    results,
+                    save_path=output_dir / "deg_metric_distributions.png",
+                    show=False,
+                )
+                plt.close()
+                
+                # Heatmap
+                plot_context_heatmap(
+                    results,
+                    save_path=output_dir / "deg_context_heatmap.png",
+                    show=False,
+                )
+                plt.close()
+            
+            # DEG counts
+            if len(results.deg_summary) > 0:
+                plot_deg_counts(
+                    results,
+                    save_path=output_dir / "deg_counts.png",
+                    show=False,
+                )
+                plt.close()
+                
+        except ImportError:
+            pass  # Skip plots if matplotlib not available
+    
+    # Create markdown report
+    report_lines = [
+        "# DEG Evaluation Report",
+        "",
+        "## Summary",
+        "",
+        f"- **Number of contexts evaluated**: {len(results.context_results)}",
+        f"- **DEG detection method**: {results.settings.get('deg_method', 'N/A')}",
+        f"- **P-value threshold**: {results.settings.get('pval_threshold', 'N/A')}",
+        f"- **Log fold change threshold**: {results.settings.get('lfc_threshold', 'N/A')}",
+        f"- **Compute device**: {results.settings.get('device', 'N/A')}",
+        "",
+        "## Aggregated Metrics",
+        "",
+    ]
+    
+    if len(results.aggregated_metrics) > 0:
+        for col in results.aggregated_metrics.columns:
+            val = results.aggregated_metrics[col].iloc[0]
+            if isinstance(val, float):
+                report_lines.append(f"- **{col}**: {val:.4f}")
+            else:
+                report_lines.append(f"- **{col}**: {val}")
+    else:
+        report_lines.append("No aggregated metrics available.")
+    
+    report_lines.extend([
+        "",
+        "## DEG Summary",
+        "",
+    ])
+    
+    if len(results.deg_summary) > 0:
+        report_lines.append(results.deg_summary.to_markdown(index=False))
+    else:
+        report_lines.append("No DEG data available.")
+    
+    report_lines.extend([
+        "",
+        "## Files Generated",
+        "",
+        "- `deg_aggregated_metrics.csv`: Summary metrics across all contexts",
+        "- `deg_expanded_metrics.csv`: Per-context metrics",
+        "- `deg_summary.csv`: DEG detection summary",
+        "- `deg_per_context/`: Individual DEG results per context",
+    ])
+    
+    if include_plots:
+        report_lines.extend([
+            "- `deg_metric_distributions.png`: Distribution plots",
+            "- `deg_context_heatmap.png`: Context × metric heatmap",
+            "- `deg_counts.png`: DEG counts per context",
+        ])
+    
+    with open(output_dir / "DEG_REPORT.md", "w") as f:
+        f.write("\n".join(report_lines))
+    
+    print(f"DEG report saved to {output_dir}")

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

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: gengeneeval
-Version: 0.3.0
-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, CPU parallelization, GPU acceleration, 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
@@ -78,6 +78,8 @@ 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)
@@ -247,6 +249,91 @@ print(f"MMD: {results['mmd'].aggregate_value:.4f}")
 | `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.3.0.dist-info → gengeneeval-0.4.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-geneval/__init__.py,sha256=K0E3Jyt3l7_KxqIeI3upBBBrjRA4ASdRFugaxMVVGRM,4306
+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,6 +6,11 @@ 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/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
@@ -28,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.3.0.dist-info/METADATA,sha256=5K2bIh59OEM88dNVeUWPOevyyAbnAIyiKaZu6VmJIh0,9680
-gengeneeval-0.3.0.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-gengeneeval-0.3.0.dist-info/entry_points.txt,sha256=xTkwnNa2fP0w1uGVsafzRTaCeuBSWLlNO-1CN8uBSK0,43
-gengeneeval-0.3.0.dist-info/licenses/LICENSE,sha256=RDHgHDI4rSDq35R4CAC3npy86YUnmZ81ecO7aHfmmGA,1073
-gengeneeval-0.3.0.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,,