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

geneval/deg/evaluator.py

@@ -0,0 +1,821 @@
+"""
+DEG-focused evaluator for GenGeneEval.
+
+Computes metrics on differentially expressed genes with full control:
+- Comparison of DEG-only vs all-genes metrics
+- Configurable DEG selection (top N, p-value, log fold change thresholds)
+- Per-context evaluation (covariates × perturbations)
+- Fast DEG detection with GPU acceleration
+- Aggregated and expanded result reporting
+"""
+from __future__ import annotations
+
+from typing import Optional, List, Dict, Union, Any, Literal
+from dataclasses import dataclass, field
+from pathlib import Path
+import numpy as np
+import pandas as pd
+import warnings
+
+from .detection import (
+    compute_degs_fast,
+    compute_degs_gpu,
+    compute_degs_auto,
+    DEGResult,
+    DEGMethod,
+)
+from .context import (
+    ContextEvaluator,
+    ContextResult,
+    get_context_id,
+    get_contexts,
+)
+
+# Import metrics
+from ..metrics.base_metric import BaseMetric
+from ..metrics.correlation import PearsonCorrelation, SpearmanCorrelation
+from ..metrics.distances import (
+    Wasserstein1Distance,
+    Wasserstein2Distance,
+    MMDDistance,
+    EnergyDistance,
+)
+from ..metrics.accelerated import (
+    get_available_backends,
+    vectorized_wasserstein1,
+    vectorized_mmd,
+)
+
+
+@dataclass
+class DEGSettings:
+    """Settings for DEG detection and filtering.
+    
+    Attributes
+    ----------
+    method : str
+        DEG detection method: "welch", "student", "wilcoxon", "logfc"
+    pval_threshold : float
+        P-value threshold for significance
+    lfc_threshold : float
+        Absolute log2 fold change threshold
+    n_top_degs : int, optional
+        If set, use only top N DEGs by significance (overrides threshold filtering)
+    min_degs : int
+        Minimum number of DEGs required to compute metrics
+    """
+    method: str = "welch"
+    pval_threshold: float = 0.05
+    lfc_threshold: float = 0.5
+    n_top_degs: Optional[int] = None
+    min_degs: int = 5
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "deg_method": self.method,
+            "pval_threshold": self.pval_threshold, 
+            "lfc_threshold": self.lfc_threshold,
+            "n_top_degs": self.n_top_degs,
+            "min_degs": self.min_degs,
+        }
+
+
+@dataclass 
+class ContextMetrics:
+    """Metrics for a single context, comparing DEG-only vs all genes.
+    
+    Attributes
+    ----------
+    context_id : str
+        Context identifier
+    context_values : Dict
+        Context column values
+    n_samples_real : int
+        Number of real samples
+    n_samples_gen : int
+        Number of generated samples
+    n_genes_total : int
+        Total number of genes
+    deg_result : DEGResult
+        DEG detection results
+    deg_metrics : Dict[str, float]
+        Metrics computed on DEGs only
+    all_genes_metrics : Dict[str, float]
+        Metrics computed on all genes
+    """
+    context_id: str
+    context_values: Dict[str, Any]
+    n_samples_real: int
+    n_samples_gen: int
+    n_genes_total: int
+    deg_result: Optional[DEGResult]
+    deg_metrics: Dict[str, float]
+    all_genes_metrics: Dict[str, float]
+    
+    @property
+    def n_degs(self) -> int:
+        """Number of DEGs."""
+        return self.deg_result.n_degs if self.deg_result else 0
+    
+    @property 
+    def deg_indices_used(self) -> np.ndarray:
+        """DEG indices actually used for metrics."""
+        return self.deg_result.deg_indices if self.deg_result else np.array([])
+
+
+@dataclass
+class DEGEvaluationResult:
+    """Complete DEG evaluation results with comparison to all-genes metrics.
+    
+    Attributes
+    ----------
+    context_results : List[ContextMetrics]
+        Results for each context with both DEG and all-gene metrics
+    aggregated_metrics : pd.DataFrame
+        Aggregated metrics across contexts (both DEG and all-genes)
+    expanded_metrics : pd.DataFrame
+        Per-context expanded metrics (both DEG and all-genes)
+    deg_summary : pd.DataFrame
+        Summary of DEG detection per context
+    comparison_summary : pd.DataFrame
+        Comparison between DEG-only and all-genes metrics
+    gene_names : np.ndarray
+        All gene names
+    settings : Dict
+        Evaluation settings including DEG parameters
+    """
+    context_results: List[ContextMetrics]
+    aggregated_metrics: pd.DataFrame
+    expanded_metrics: pd.DataFrame
+    deg_summary: pd.DataFrame
+    comparison_summary: pd.DataFrame
+    gene_names: np.ndarray
+    settings: Dict[str, Any]
+    
+    def save(self, output_dir: Union[str, Path]) -> None:
+        """Save results to directory."""
+        output_dir = Path(output_dir)
+        output_dir.mkdir(parents=True, exist_ok=True)
+        
+        self.aggregated_metrics.to_csv(output_dir / "deg_aggregated_metrics.csv", index=False)
+        self.expanded_metrics.to_csv(output_dir / "deg_expanded_metrics.csv", index=False)
+        self.deg_summary.to_csv(output_dir / "deg_summary.csv", index=False)
+        self.comparison_summary.to_csv(output_dir / "deg_vs_all_comparison.csv", index=False)
+        
+        # Save settings
+        import json
+        with open(output_dir / "settings.json", "w") as f:
+            json.dump(self.settings, f, indent=2, default=str)
+        
+        # Save per-context DEG results
+        deg_dir = output_dir / "deg_per_context"
+        deg_dir.mkdir(exist_ok=True)
+        for ctx_result in self.context_results:
+            if ctx_result.deg_result is not None:
+                ctx_result.deg_result.to_dataframe().to_csv(
+                    deg_dir / f"{ctx_result.context_id}_degs.csv", index=False
+                )
+    
+    def get_deg_only_metrics(self) -> pd.DataFrame:
+        """Get expanded metrics for DEGs only."""
+        base_cols = ["context_id", "n_samples_real", "n_samples_gen", "n_degs", "n_genes_total"]
+        deg_cols = [c for c in self.expanded_metrics.columns if c.startswith("deg_")]
+        cols = [c for c in base_cols if c in self.expanded_metrics.columns] + deg_cols
+        return self.expanded_metrics[cols].copy()
+    
+    def get_all_genes_metrics(self) -> pd.DataFrame:
+        """Get expanded metrics for all genes."""
+        base_cols = ["context_id", "n_samples_real", "n_samples_gen", "n_degs", "n_genes_total"]
+        all_cols = [c for c in self.expanded_metrics.columns if c.startswith("all_")]
+        cols = [c for c in base_cols if c in self.expanded_metrics.columns] + all_cols
+        return self.expanded_metrics[cols].copy()
+    
+    def __repr__(self) -> str:
+        n_degs_avg = self.deg_summary["n_degs"].mean() if len(self.deg_summary) > 0 else 0
+        return (
+            f"DEGEvaluationResult(n_contexts={len(self.context_results)}, "
+            f"avg_degs={n_degs_avg:.1f}, "
+            f"settings={self.settings.get('deg_method', 'unknown')})"
+        )
+
+
+class DEGEvaluator:
+    """
+    Evaluator that computes metrics on DEGs with comparison to all genes.
+    
+    This evaluator:
+    1. Detects DEGs for each perturbation context
+    2. Computes distributional metrics on BOTH DEG genes AND all genes
+    3. Provides comparison between DEG-focused and all-genes evaluation
+    4. Reports per-context and aggregated results
+    
+    Parameters
+    ----------
+    real_data : np.ndarray
+        Real expression matrix (n_samples, n_genes)
+    generated_data : np.ndarray
+        Generated expression matrix (n_samples, n_genes)
+    real_obs : pd.DataFrame
+        Real data observation metadata
+    generated_obs : pd.DataFrame
+        Generated data observation metadata
+    condition_columns : List[str]
+        Columns defining contexts (e.g., ["cell_type", "perturbation"])
+    gene_names : np.ndarray, optional
+        Gene names
+    control_key : str
+        Value indicating control samples (default: "control")
+    perturbation_column : str, optional
+        Column containing perturbation info. If None, uses first condition column.
+    deg_method : str
+        DEG detection method: "welch", "student", "wilcoxon", "logfc"
+    pval_threshold : float
+        P-value threshold for DEG significance (default: 0.05)
+    lfc_threshold : float
+        Log2 fold change threshold (default: 0.5)
+    n_top_degs : int, optional
+        If set, use only top N DEGs by significance instead of thresholds
+    min_degs : int
+        Minimum DEGs required to compute DEG-specific metrics (default: 5)
+    compute_all_genes : bool
+        Whether to also compute metrics on all genes (default: True)
+    metrics : List[str], optional
+        Metrics to compute. Default: all supported metrics.
+    n_jobs : int
+        Number of parallel CPU jobs
+    device : str
+        Compute device: "cpu", "cuda", "mps", "auto"
+    verbose : bool
+        Print progress
+        
+    Examples
+    --------
+    >>> # Basic usage - computes both DEG and all-genes metrics
+    >>> evaluator = DEGEvaluator(
+    ...     real_data, generated_data,
+    ...     real_obs, generated_obs,
+    ...     condition_columns=["perturbation"],
+    ... )
+    >>> results = evaluator.evaluate()
+    >>> print(results.comparison_summary)  # DEG vs all-genes comparison
+    
+    >>> # Use top 100 DEGs only
+    >>> evaluator = DEGEvaluator(
+    ...     real_data, generated_data,
+    ...     real_obs, generated_obs,
+    ...     condition_columns=["perturbation"],
+    ...     n_top_degs=100,  # Use top 100 most significant DEGs
+    ... )
+    
+    >>> # Stricter thresholds
+    >>> evaluator = DEGEvaluator(
+    ...     real_data, generated_data,
+    ...     real_obs, generated_obs,
+    ...     condition_columns=["perturbation"],
+    ...     pval_threshold=0.01,   # More stringent p-value
+    ...     lfc_threshold=1.0,     # log2 FC > 1 (2-fold change)
+    ... )
+    
+    >>> # DEGs only (no all-genes metrics for speed)
+    >>> evaluator = DEGEvaluator(
+    ...     real_data, generated_data,
+    ...     real_obs, generated_obs,
+    ...     condition_columns=["perturbation"],
+    ...     compute_all_genes=False,
+    ... )
+    """
+    
+    # Supported metrics
+    SUPPORTED_METRICS = [
+        "wasserstein_1",
+        "wasserstein_2", 
+        "mmd",
+        "energy",
+        "pearson",
+        "spearman",
+    ]
+    
+    def __init__(
+        self,
+        real_data: np.ndarray,
+        generated_data: np.ndarray,
+        real_obs: pd.DataFrame,
+        generated_obs: pd.DataFrame,
+        condition_columns: List[str],
+        gene_names: Optional[np.ndarray] = None,
+        control_key: str = "control",
+        perturbation_column: Optional[str] = None,
+        deg_method: DEGMethod = "welch",
+        pval_threshold: float = 0.05,
+        lfc_threshold: float = 0.5,
+        n_top_degs: Optional[int] = None,
+        min_degs: int = 5,
+        compute_all_genes: bool = True,
+        metrics: Optional[List[str]] = None,
+        n_jobs: int = 1,
+        device: str = "cpu",
+        verbose: bool = True,
+    ):
+        self.real_data = np.asarray(real_data, dtype=np.float32)
+        self.generated_data = np.asarray(generated_data, dtype=np.float32)
+        self.real_obs = real_obs.reset_index(drop=True)
+        self.generated_obs = generated_obs.reset_index(drop=True)
+        self.condition_columns = condition_columns
+        self.n_genes = real_data.shape[1]
+        self.gene_names = gene_names if gene_names is not None else np.array(
+            [f"Gene_{i}" for i in range(self.n_genes)]
+        )
+        self.control_key = control_key
+        self.perturbation_column = perturbation_column or condition_columns[0]
+        
+        # DEG settings
+        self.deg_settings = DEGSettings(
+            method=deg_method,
+            pval_threshold=pval_threshold,
+            lfc_threshold=lfc_threshold,
+            n_top_degs=n_top_degs,
+            min_degs=min_degs,
+        )
+        
+        self.compute_all_genes = compute_all_genes
+        self.metrics = metrics or self.SUPPORTED_METRICS
+        self.n_jobs = n_jobs
+        self.device = device
+        self.verbose = verbose
+        
+        # Create context evaluator
+        self.context_evaluator = ContextEvaluator(
+            real_data=self.real_data,
+            generated_data=self.generated_data,
+            real_obs=self.real_obs,
+            generated_obs=self.generated_obs,
+            condition_columns=condition_columns,
+            gene_names=self.gene_names,
+            control_key=control_key,
+            perturbation_column=self.perturbation_column,
+        )
+        
+        # Initialize metric objects
+        self._metric_objects = {
+            "wasserstein_1": Wasserstein1Distance(),
+            "wasserstein_2": Wasserstein2Distance(),
+            "mmd": MMDDistance(),
+            "energy": EnergyDistance(),
+            "pearson": PearsonCorrelation(),
+            "spearman": SpearmanCorrelation(),
+        }
+        
+        self._log(f"DEGEvaluator initialized with {len(self.context_evaluator)} contexts")
+        self._log(f"DEG settings: method={deg_method}, pval<{pval_threshold}, |lfc|>{lfc_threshold}")
+        if n_top_degs is not None:
+            self._log(f"  Using top {n_top_degs} DEGs by significance")
+        if compute_all_genes:
+            self._log("Will compute metrics on BOTH DEGs and all genes")
+    
+    def _log(self, msg: str) -> None:
+        """Print if verbose."""
+        if self.verbose:
+            print(msg)
+    
+    def _compute_degs(
+        self,
+        control: np.ndarray,
+        perturbed: np.ndarray,
+    ) -> DEGResult:
+        """Compute DEGs using configured method and device."""
+        deg_result = compute_degs_auto(
+            control=control,
+            perturbed=perturbed,
+            gene_names=self.gene_names,
+            method=self.deg_settings.method,
+            pval_threshold=self.deg_settings.pval_threshold,
+            lfc_threshold=self.deg_settings.lfc_threshold,
+            n_jobs=self.n_jobs,
+            device=self.device,
+        )
+        
+        # If n_top_degs is set, limit to top N by significance
+        if self.deg_settings.n_top_degs is not None:
+            deg_result = self._filter_top_degs(deg_result, self.deg_settings.n_top_degs)
+        
+        return deg_result
+    
+    def _filter_top_degs(self, deg_result: DEGResult, n_top: int) -> DEGResult:
+        """Filter DEG result to keep only top N most significant DEGs."""
+        if deg_result.n_degs <= n_top:
+            return deg_result  # Already fewer than n_top
+        
+        # Sort DEGs by adjusted p-value (lower is more significant)
+        deg_pvals = deg_result.pvalues_adj[deg_result.is_deg]
+        deg_indices = deg_result.deg_indices
+        
+        # Get indices of top N most significant
+        top_n_order = np.argsort(deg_pvals)[:n_top]
+        top_deg_indices = deg_indices[top_n_order]
+        
+        # Create new is_deg mask
+        new_is_deg = np.zeros(len(deg_result.is_deg), dtype=bool)
+        new_is_deg[top_deg_indices] = True
+        
+        # Create modified DEGResult with all required fields
+        return DEGResult(
+            gene_names=deg_result.gene_names,
+            pvalues=deg_result.pvalues,
+            pvalues_adj=deg_result.pvalues_adj,
+            log_fold_changes=deg_result.log_fold_changes,
+            mean_control=deg_result.mean_control,
+            mean_perturbed=deg_result.mean_perturbed,
+            is_deg=new_is_deg,
+            n_degs=n_top,
+            method=deg_result.method,
+            pval_threshold=deg_result.pval_threshold,
+            lfc_threshold=deg_result.lfc_threshold,
+            deg_indices=top_deg_indices,
+        )
+    
+    def _compute_metrics_on_genes(
+        self,
+        real: np.ndarray,
+        generated: np.ndarray,
+        gene_indices: Optional[np.ndarray] = None,
+        min_genes: int = 1,
+    ) -> Dict[str, float]:
+        """Compute metrics on specified genes (or all if indices is None)."""
+        # Slice to selected genes
+        if gene_indices is not None:
+            if len(gene_indices) < min_genes:
+                return {m: np.nan for m in self.metrics}
+            real_subset = real[:, gene_indices]
+            gen_subset = generated[:, gene_indices]
+        else:
+            real_subset = real
+            gen_subset = generated
+        
+        results = {}
+        
+        # Use vectorized implementations where available
+        if "wasserstein_1" in self.metrics:
+            try:
+                w1_per_gene = vectorized_wasserstein1(real_subset, gen_subset)
+                results["wasserstein_1"] = float(np.nanmean(w1_per_gene))
+            except Exception:
+                results["wasserstein_1"] = np.nan
+        
+        if "mmd" in self.metrics:
+            try:
+                mmd_per_gene = vectorized_mmd(real_subset, gen_subset)
+                results["mmd"] = float(np.nanmean(mmd_per_gene))
+            except Exception:
+                results["mmd"] = np.nan
+        
+        # Fall back to standard computation for other metrics
+        for metric_name in self.metrics:
+            if metric_name in results:
+                continue
+            if metric_name not in self._metric_objects:
+                continue
+            
+            metric = self._metric_objects[metric_name]
+            try:
+                per_gene = metric.compute_per_gene(real_subset, gen_subset)
+                results[metric_name] = float(np.nanmean(per_gene))
+            except Exception:
+                results[metric_name] = np.nan
+        
+        return results
+    
+    def evaluate(self) -> DEGEvaluationResult:
+        """
+        Run DEG-focused evaluation on all contexts.
+        
+        Returns both DEG-only and all-genes metrics for comparison.
+        
+        Returns
+        -------
+        DEGEvaluationResult
+            Complete evaluation results with:
+            - Per-context DEG and all-genes metrics
+            - Aggregated metrics
+            - DEG summary
+            - Comparison between DEG and all-genes evaluation
+        """
+        context_results: List[ContextMetrics] = []
+        
+        perturbation_contexts = self.context_evaluator.get_perturbation_contexts()
+        n_contexts = len(perturbation_contexts)
+        
+        self._log(f"\nEvaluating {n_contexts} perturbation contexts...")
+        
+        for i, context in enumerate(perturbation_contexts):
+            context_id = get_context_id(context)
+            
+            if self.verbose:
+                print(f"  [{i+1}/{n_contexts}] {context_id}", end="... ")
+            
+            try:
+                # Get perturbed data
+                real_pert, gen_pert = self.context_evaluator.get_context_data(context)
+                
+                # Get control data
+                real_ctrl, gen_ctrl = self.context_evaluator.get_control_data(context)
+                
+                if len(real_ctrl) < 2 or len(real_pert) < 2:
+                    if self.verbose:
+                        print("skipped (insufficient samples)")
+                    continue
+                
+                # Compute DEGs using real data (control vs perturbed)
+                deg_result = self._compute_degs(real_ctrl, real_pert)
+                
+                if self.verbose:
+                    print(f"{deg_result.n_degs} DEGs", end="... ")
+                
+                # Compute metrics on DEGs
+                deg_metrics = self._compute_metrics_on_genes(
+                    real_pert, gen_pert, 
+                    gene_indices=deg_result.deg_indices,
+                    min_genes=self.deg_settings.min_degs,
+                )
+                
+                # Compute metrics on all genes if requested
+                if self.compute_all_genes:
+                    all_genes_metrics = self._compute_metrics_on_genes(
+                        real_pert, gen_pert, 
+                        gene_indices=None,  # All genes
+                    )
+                else:
+                    all_genes_metrics = {}
+                
+                ctx_result = ContextMetrics(
+                    context_id=context_id,
+                    context_values=context,
+                    n_samples_real=len(real_pert),
+                    n_samples_gen=len(gen_pert),
+                    n_genes_total=self.n_genes,
+                    deg_result=deg_result,
+                    deg_metrics=deg_metrics,
+                    all_genes_metrics=all_genes_metrics,
+                )
+                context_results.append(ctx_result)
+                
+                if self.verbose:
+                    print("done")
+                    
+            except Exception as e:
+                if self.verbose:
+                    print(f"error: {e}")
+                continue
+        
+        # Build result DataFrames
+        expanded_metrics = self._build_expanded_metrics(context_results)
+        aggregated_metrics = self._build_aggregated_metrics(expanded_metrics)
+        deg_summary = self._build_deg_summary(context_results)
+        comparison_summary = self._build_comparison_summary(expanded_metrics)
+        
+        self._log(f"\nEvaluation complete: {len(context_results)} contexts evaluated")
+        
+        return DEGEvaluationResult(
+            context_results=context_results,
+            aggregated_metrics=aggregated_metrics,
+            expanded_metrics=expanded_metrics,
+            deg_summary=deg_summary,
+            comparison_summary=comparison_summary,
+            gene_names=self.gene_names,
+            settings={
+                **self.deg_settings.to_dict(),
+                "compute_all_genes": self.compute_all_genes,
+                "metrics": self.metrics,
+                "device": self.device,
+                "n_jobs": self.n_jobs,
+            },
+        )
+    
+    def _build_expanded_metrics(self, context_results: List[ContextMetrics]) -> pd.DataFrame:
+        """Build expanded metrics DataFrame with both DEG and all-genes columns."""
+        data = []
+        for ctx in context_results:
+            row = {
+                "context_id": ctx.context_id,
+                **ctx.context_values,
+                "n_samples_real": ctx.n_samples_real,
+                "n_samples_gen": ctx.n_samples_gen,
+                "n_genes_total": ctx.n_genes_total,
+                "n_degs": ctx.n_degs,
+            }
+            
+            # DEG metrics with prefix
+            for metric_name, value in ctx.deg_metrics.items():
+                row[f"deg_{metric_name}"] = value
+            
+            # All-genes metrics with prefix
+            for metric_name, value in ctx.all_genes_metrics.items():
+                row[f"all_{metric_name}"] = value
+            
+            data.append(row)
+        
+        return pd.DataFrame(data)
+    
+    def _build_aggregated_metrics(self, expanded_metrics: pd.DataFrame) -> pd.DataFrame:
+        """Build aggregated metrics DataFrame."""
+        if len(expanded_metrics) == 0:
+            return pd.DataFrame()
+        
+        agg_data = {
+            "n_contexts": len(expanded_metrics),
+            "total_samples_real": expanded_metrics["n_samples_real"].sum(),
+            "total_samples_gen": expanded_metrics["n_samples_gen"].sum(),
+            "mean_n_degs": expanded_metrics["n_degs"].mean(),
+            "median_n_degs": expanded_metrics["n_degs"].median(),
+            "min_n_degs": expanded_metrics["n_degs"].min(),
+            "max_n_degs": expanded_metrics["n_degs"].max(),
+        }
+        
+        # Aggregate DEG metrics
+        for metric in self.metrics:
+            col = f"deg_{metric}"
+            if col in expanded_metrics.columns:
+                agg_data[f"deg_{metric}_mean"] = expanded_metrics[col].mean()
+                agg_data[f"deg_{metric}_std"] = expanded_metrics[col].std()
+        
+        # Aggregate all-genes metrics
+        for metric in self.metrics:
+            col = f"all_{metric}"
+            if col in expanded_metrics.columns:
+                agg_data[f"all_{metric}_mean"] = expanded_metrics[col].mean()
+                agg_data[f"all_{metric}_std"] = expanded_metrics[col].std()
+        
+        return pd.DataFrame([agg_data])
+    
+    def _build_deg_summary(self, context_results: List[ContextMetrics]) -> pd.DataFrame:
+        """Build DEG summary DataFrame."""
+        data = []
+        for ctx in context_results:
+            if ctx.deg_result is not None:
+                deg_lfcs = ctx.deg_result.log_fold_changes[ctx.deg_result.is_deg]
+                data.append({
+                    "context_id": ctx.context_id,
+                    **ctx.context_values,
+                    "n_degs": ctx.n_degs,
+                    "n_genes_total": ctx.n_genes_total,
+                    "deg_fraction": ctx.n_degs / ctx.n_genes_total if ctx.n_genes_total > 0 else 0,
+                    "n_upregulated": (deg_lfcs > 0).sum(),
+                    "n_downregulated": (deg_lfcs < 0).sum(),
+                    "mean_abs_lfc": float(np.abs(deg_lfcs).mean()) if len(deg_lfcs) > 0 else np.nan,
+                    "max_abs_lfc": float(np.abs(deg_lfcs).max()) if len(deg_lfcs) > 0 else np.nan,
+                })
+        return pd.DataFrame(data)
+    
+    def _build_comparison_summary(self, expanded_metrics: pd.DataFrame) -> pd.DataFrame:
+        """Build comparison summary between DEG and all-genes metrics."""
+        if len(expanded_metrics) == 0:
+            return pd.DataFrame()
+        
+        comparison_data = []
+        for metric in self.metrics:
+            deg_col = f"deg_{metric}"
+            all_col = f"all_{metric}"
+            
+            if deg_col in expanded_metrics.columns and all_col in expanded_metrics.columns:
+                deg_values = expanded_metrics[deg_col].dropna()
+                all_values = expanded_metrics[all_col].dropna()
+                
+                if len(deg_values) > 0 and len(all_values) > 0:
+                    deg_mean = deg_values.mean()
+                    all_mean = all_values.mean()
+                    
+                    comparison_data.append({
+                        "metric": metric,
+                        "deg_mean": deg_mean,
+                        "deg_std": deg_values.std(),
+                        "all_mean": all_mean,
+                        "all_std": all_values.std(),
+                        "difference": deg_mean - all_mean,
+                        "ratio": deg_mean / all_mean if all_mean != 0 else np.nan,
+                        "n_contexts": len(deg_values),
+                    })
+        
+        return pd.DataFrame(comparison_data)
+
+
+def evaluate_degs(
+    real_data: np.ndarray,
+    generated_data: np.ndarray,
+    real_obs: pd.DataFrame,
+    generated_obs: pd.DataFrame,
+    condition_columns: List[str],
+    gene_names: Optional[np.ndarray] = None,
+    control_key: str = "control",
+    perturbation_column: Optional[str] = None,
+    deg_method: DEGMethod = "welch",
+    pval_threshold: float = 0.05,
+    lfc_threshold: float = 0.5,
+    n_top_degs: Optional[int] = None,
+    min_degs: int = 5,
+    compute_all_genes: bool = True,
+    metrics: Optional[List[str]] = None,
+    n_jobs: int = 1,
+    device: str = "auto",
+    verbose: bool = True,
+) -> DEGEvaluationResult:
+    """
+    Convenience function for DEG-focused evaluation with full control.
+    
+    Computes metrics on both DEGs and all genes for comparison.
+    
+    Parameters
+    ----------
+    real_data : np.ndarray
+        Real expression matrix (n_samples, n_genes)
+    generated_data : np.ndarray
+        Generated expression matrix (n_samples, n_genes)
+    real_obs : pd.DataFrame
+        Real data metadata with condition columns
+    generated_obs : pd.DataFrame
+        Generated data metadata with condition columns
+    condition_columns : List[str]
+        Columns defining contexts (e.g., ["cell_type", "perturbation"])
+    gene_names : np.ndarray, optional
+        Gene names for output
+    control_key : str
+        Control condition identifier (default: "control")
+    perturbation_column : str, optional
+        Column containing perturbation info. If None, uses first condition column.
+    deg_method : str
+        DEG detection method: "welch", "student", "wilcoxon", "logfc"
+    pval_threshold : float
+        Adjusted p-value threshold (default: 0.05)
+    lfc_threshold : float
+        Absolute log2 fold change threshold (default: 0.5)
+    n_top_degs : int, optional
+        If set, use only top N DEGs by significance (overrides thresholds)
+    min_degs : int
+        Minimum DEGs to compute DEG metrics (default: 5)
+    compute_all_genes : bool
+        Also compute metrics on all genes for comparison (default: True)
+    metrics : List[str], optional
+        Metrics to compute. Default: all supported.
+    n_jobs : int
+        Parallel CPU jobs (default: 1)
+    device : str
+        Compute device: "cpu", "cuda", "mps", "auto" (default: "auto")
+    verbose : bool
+        Print progress (default: True)
+        
+    Returns
+    -------
+    DEGEvaluationResult
+        Complete evaluation results including:
+        - expanded_metrics: Per-context metrics for DEGs and all genes
+        - aggregated_metrics: Summary statistics
+        - deg_summary: DEG detection summary
+        - comparison_summary: DEG vs all-genes comparison
+        
+    Examples
+    --------
+    >>> # Basic usage with default thresholds
+    >>> results = evaluate_degs(
+    ...     real_data, generated_data,
+    ...     real_obs, generated_obs,
+    ...     condition_columns=["perturbation"],
+    ... )
+    >>> print(results.comparison_summary)
+    
+    >>> # Top 50 DEGs only
+    >>> results = evaluate_degs(
+    ...     real_data, generated_data,
+    ...     real_obs, generated_obs,
+    ...     condition_columns=["perturbation"],
+    ...     n_top_degs=50,
+    ... )
+    
+    >>> # Strict thresholds
+    >>> results = evaluate_degs(
+    ...     real_data, generated_data,
+    ...     real_obs, generated_obs,
+    ...     condition_columns=["perturbation"],
+    ...     pval_threshold=0.01,
+    ...     lfc_threshold=1.0,  # 2-fold change
+    ... )
+    """
+    evaluator = DEGEvaluator(
+        real_data=real_data,
+        generated_data=generated_data,
+        real_obs=real_obs,
+        generated_obs=generated_obs,
+        condition_columns=condition_columns,
+        gene_names=gene_names,
+        control_key=control_key,
+        perturbation_column=perturbation_column,
+        deg_method=deg_method,
+        pval_threshold=pval_threshold,
+        lfc_threshold=lfc_threshold,
+        n_top_degs=n_top_degs,
+        min_degs=min_degs,
+        compute_all_genes=compute_all_genes,
+        metrics=metrics,
+        n_jobs=n_jobs,
+        device=device,
+        verbose=verbose,
+    )
+    return evaluator.evaluate()