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

geneval/__init__.py

@@ -49,7 +49,7 @@ CLI Usage:
               --conditions perturbation cell_type --output results/
 """
 
-__version__ = "0.4.0"
+__version__ = "0.4.1"
 __author__ = "GenEval Team"
 
 # Main evaluation interface

geneval/deg/__init__.py

@@ -31,6 +31,8 @@ from .context import (
 from .evaluator import (
     DEGEvaluator,
     DEGEvaluationResult,
+    DEGSettings,
+    ContextMetrics,
     evaluate_degs,
 )
 from .visualization import (
@@ -56,6 +58,8 @@ __all__ = [
     # Evaluator
     "DEGEvaluator",
     "DEGEvaluationResult",
+    "DEGSettings",
+    "ContextMetrics",
     "evaluate_degs",
     # Visualization
     "plot_deg_distributions",

geneval/deg/evaluator.py

@@ -1,7 +1,9 @@
 """
 DEG-focused evaluator for GenGeneEval.
 
-Computes metrics only on differentially expressed genes, with support for:
+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
@@ -45,29 +47,109 @@ from ..metrics.accelerated import (
 )
 
 
+@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.
+    """Complete DEG evaluation results with comparison to all-genes metrics.
     
     Attributes
     ----------
-    context_results : List[ContextResult]
-        Results for each context
+    context_results : List[ContextMetrics]
+        Results for each context with both DEG and all-gene metrics
     aggregated_metrics : pd.DataFrame
-        Aggregated metrics across contexts
+        Aggregated metrics across contexts (both DEG and all-genes)
     expanded_metrics : pd.DataFrame
-        Per-context expanded metrics
+        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
+        Evaluation settings including DEG parameters
     """
-    context_results: List[ContextResult]
+    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]
     
@@ -76,9 +158,15 @@ class DEGEvaluationResult:
         output_dir = Path(output_dir)
         output_dir.mkdir(parents=True, exist_ok=True)
         
-        self.aggregated_metrics.to_csv(output_dir / "deg_aggregated_metrics.csv")
-        self.expanded_metrics.to_csv(output_dir / "deg_expanded_metrics.csv")
-        self.deg_summary.to_csv(output_dir / "deg_summary.csv")
+        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"
@@ -86,24 +174,41 @@ class DEGEvaluationResult:
         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"
+                    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"metrics={list(self.aggregated_metrics.columns)})"
+            f"avg_degs={n_degs_avg:.1f}, "
+            f"settings={self.settings.get('deg_method', 'unknown')})"
         )
 
 
 class DEGEvaluator:
     """
-    Evaluator that computes metrics on DEGs only.
+    Evaluator that computes metrics on DEGs with comparison to all genes.
     
     This evaluator:
     1. Detects DEGs for each perturbation context
-    2. Computes distributional metrics only on DEG genes
-    3. Reports per-context and aggregated results
+    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
     ----------
@@ -126,11 +231,15 @@ class DEGEvaluator:
     deg_method : str
         DEG detection method: "welch", "student", "wilcoxon", "logfc"
     pval_threshold : float
-        P-value threshold for DEG significance
+        P-value threshold for DEG significance (default: 0.05)
     lfc_threshold : float
-        Log2 fold change threshold
+        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 metrics
+        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
@@ -142,15 +251,39 @@ class DEGEvaluator:
         
     Examples
     --------
+    >>> # Basic usage - computes both DEG and all-genes metrics
     >>> evaluator = DEGEvaluator(
     ...     real_data, generated_data,
     ...     real_obs, generated_obs,
     ...     condition_columns=["perturbation"],
-    ...     deg_method="welch",
-    ...     device="cuda",
     ... )
     >>> results = evaluator.evaluate()
-    >>> results.save("output/")
+    >>> 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
@@ -176,7 +309,9 @@ class DEGEvaluator:
         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",
@@ -187,15 +322,23 @@ class DEGEvaluator:
         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(real_data.shape[1])]
+            [f"Gene_{i}" for i in range(self.n_genes)]
         )
         self.control_key = control_key
         self.perturbation_column = perturbation_column or condition_columns[0]
-        self.deg_method = deg_method
-        self.pval_threshold = pval_threshold
-        self.lfc_threshold = lfc_threshold
-        self.min_degs = min_degs
+        
+        # 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
@@ -224,7 +367,11 @@ class DEGEvaluator:
         }
         
         self._log(f"DEGEvaluator initialized with {len(self.context_evaluator)} contexts")
-        self._log(f"Perturbation contexts: {len(self.context_evaluator.get_perturbation_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."""
@@ -237,78 +384,87 @@ class DEGEvaluator:
         perturbed: np.ndarray,
     ) -> DEGResult:
         """Compute DEGs using configured method and device."""
-        return compute_degs_auto(
+        deg_result = compute_degs_auto(
             control=control,
             perturbed=perturbed,
             gene_names=self.gene_names,
-            method=self.deg_method,
-            pval_threshold=self.pval_threshold,
-            lfc_threshold=self.lfc_threshold,
+            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 _compute_metrics_on_degs(
-        self,
-        real: np.ndarray,
-        generated: np.ndarray,
-        deg_indices: np.ndarray,
-    ) -> Dict[str, float]:
-        """Compute metrics on DEG genes only."""
-        if len(deg_indices) < self.min_degs:
-            return {m: np.nan for m in self.metrics}
+    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
         
-        # Slice to DEGs only
-        real_degs = real[:, deg_indices]
-        gen_degs = generated[:, deg_indices]
+        # 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
         
-        results = {}
+        # Get indices of top N most significant
+        top_n_order = np.argsort(deg_pvals)[:n_top]
+        top_deg_indices = deg_indices[top_n_order]
         
-        for metric_name in self.metrics:
-            if metric_name not in self._metric_objects:
-                continue
-            
-            metric = self._metric_objects[metric_name]
-            
-            try:
-                # Compute per-gene and aggregate
-                per_gene = metric.compute_per_gene(real_degs, gen_degs)
-                results[metric_name] = float(np.nanmean(per_gene))
-            except Exception as e:
-                if self.verbose:
-                    self._log(f"Warning: {metric_name} failed: {e}")
-                results[metric_name] = np.nan
+        # Create new is_deg mask
+        new_is_deg = np.zeros(len(deg_result.is_deg), dtype=bool)
+        new_is_deg[top_deg_indices] = True
         
-        return results
+        # 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_accelerated(
+    def _compute_metrics_on_genes(
         self,
         real: np.ndarray,
         generated: np.ndarray,
-        deg_indices: np.ndarray,
+        gene_indices: Optional[np.ndarray] = None,
+        min_genes: int = 1,
     ) -> Dict[str, float]:
-        """Compute metrics using accelerated implementations."""
-        if len(deg_indices) < self.min_degs:
-            return {m: np.nan for m in self.metrics}
-        
-        # Slice to DEGs only
-        real_degs = real[:, deg_indices]
-        gen_degs = generated[:, deg_indices]
+        """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 = {}
-        backends = get_available_backends()
         
         # Use vectorized implementations where available
         if "wasserstein_1" in self.metrics:
             try:
-                w1_per_gene = vectorized_wasserstein1(real_degs, gen_degs)
+                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_degs, gen_degs)
+                mmd_per_gene = vectorized_mmd(real_subset, gen_subset)
                 results["mmd"] = float(np.nanmean(mmd_per_gene))
             except Exception:
                 results["mmd"] = np.nan
@@ -322,7 +478,7 @@ class DEGEvaluator:
             
             metric = self._metric_objects[metric_name]
             try:
-                per_gene = metric.compute_per_gene(real_degs, gen_degs)
+                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
@@ -333,17 +489,23 @@ class DEGEvaluator:
         """
         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 and aggregated metrics.
+            Complete evaluation results with:
+            - Per-context DEG and all-genes metrics
+            - Aggregated metrics
+            - DEG summary
+            - Comparison between DEG and all-genes evaluation
         """
-        context_results = []
+        context_results: List[ContextMetrics] = []
         
         perturbation_contexts = self.context_evaluator.get_perturbation_contexts()
         n_contexts = len(perturbation_contexts)
         
-        self._log(f"Evaluating {n_contexts} perturbation contexts...")
+        self._log(f"\nEvaluating {n_contexts} perturbation contexts...")
         
         for i, context in enumerate(perturbation_contexts):
             context_id = get_context_id(context)
@@ -370,17 +532,30 @@ class DEGEvaluator:
                     print(f"{deg_result.n_degs} DEGs", end="... ")
                 
                 # Compute metrics on DEGs
-                metrics = self._compute_metrics_accelerated(
-                    real_pert, gen_pert, deg_result.deg_indices
+                deg_metrics = self._compute_metrics_on_genes(
+                    real_pert, gen_pert, 
+                    gene_indices=deg_result.deg_indices,
+                    min_genes=self.deg_settings.min_degs,
                 )
                 
-                ctx_result = ContextResult(
+                # 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,
-                    metrics=metrics,
+                    deg_metrics=deg_metrics,
+                    all_genes_metrics=all_genes_metrics,
                 )
                 context_results.append(ctx_result)
                 
@@ -393,52 +568,10 @@ class DEGEvaluator:
                 continue
         
         # Build result DataFrames
-        expanded_data = []
-        for ctx_result in context_results:
-            row = {
-                "context_id": ctx_result.context_id,
-                **ctx_result.context_values,
-                "n_samples_real": ctx_result.n_samples_real,
-                "n_samples_gen": ctx_result.n_samples_gen,
-                "n_degs": ctx_result.deg_result.n_degs if ctx_result.deg_result else 0,
-                **ctx_result.metrics,
-            }
-            expanded_data.append(row)
-        
-        expanded_metrics = pd.DataFrame(expanded_data)
-        
-        # Aggregated metrics
-        if len(expanded_metrics) > 0:
-            agg_data = {
-                "n_contexts": len(context_results),
-                "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(),
-            }
-            for metric in self.metrics:
-                if metric in expanded_metrics.columns:
-                    agg_data[f"{metric}_mean"] = expanded_metrics[metric].mean()
-                    agg_data[f"{metric}_std"] = expanded_metrics[metric].std()
-                    agg_data[f"{metric}_median"] = expanded_metrics[metric].median()
-            
-            aggregated_metrics = pd.DataFrame([agg_data])
-        else:
-            aggregated_metrics = pd.DataFrame()
-        
-        # DEG summary
-        deg_summary_data = []
-        for ctx_result in context_results:
-            if ctx_result.deg_result is not None:
-                deg_summary_data.append({
-                    "context_id": ctx_result.context_id,
-                    **ctx_result.context_values,
-                    "n_degs": ctx_result.deg_result.n_degs,
-                    "n_upregulated": (ctx_result.deg_result.log_fold_changes[ctx_result.deg_result.is_deg] > 0).sum(),
-                    "n_downregulated": (ctx_result.deg_result.log_fold_changes[ctx_result.deg_result.is_deg] < 0).sum(),
-                    "mean_abs_lfc": np.abs(ctx_result.deg_result.log_fold_changes[ctx_result.deg_result.is_deg]).mean() if ctx_result.deg_result.n_degs > 0 else np.nan,
-                })
-        deg_summary = pd.DataFrame(deg_summary_data)
+        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")
         
@@ -447,17 +580,122 @@ class DEGEvaluator:
             aggregated_metrics=aggregated_metrics,
             expanded_metrics=expanded_metrics,
             deg_summary=deg_summary,
+            comparison_summary=comparison_summary,
             gene_names=self.gene_names,
             settings={
-                "deg_method": self.deg_method,
-                "pval_threshold": self.pval_threshold,
-                "lfc_threshold": self.lfc_threshold,
-                "min_degs": self.min_degs,
+                **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(
@@ -472,51 +710,93 @@ def evaluate_degs(
     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.
+    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
+        Real expression matrix (n_samples, n_genes)
     generated_data : np.ndarray
-        Generated expression matrix
+        Generated expression matrix (n_samples, n_genes)
     real_obs : pd.DataFrame
-        Real data metadata
+        Real data metadata with condition columns
     generated_obs : pd.DataFrame
-        Generated data metadata
+        Generated data metadata with condition columns
     condition_columns : List[str]
-        Columns defining contexts
+        Columns defining contexts (e.g., ["cell_type", "perturbation"])
     gene_names : np.ndarray, optional
-        Gene names
+        Gene names for output
     control_key : str
-        Control condition identifier
+        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
+        DEG detection method: "welch", "student", "wilcoxon", "logfc"
     pval_threshold : float
-        P-value threshold
+        Adjusted p-value threshold (default: 0.05)
     lfc_threshold : float
-        Log fold change threshold
+        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
+        Metrics to compute. Default: all supported.
     n_jobs : int
-        Parallel CPU jobs
+        Parallel CPU jobs (default: 1)
     device : str
-        Compute device
+        Compute device: "cpu", "cuda", "mps", "auto" (default: "auto")
     verbose : bool
-        Print progress
+        Print progress (default: True)
         
     Returns
     -------
     DEGEvaluationResult
-        Evaluation results
+        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,
@@ -530,6 +810,9 @@ def evaluate_degs(
         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,

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gengeneeval
-Version: 0.4.0
+Version: 0.4.1
 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
@@ -256,6 +256,8 @@ GenEval supports **Differentially Expressed Genes (DEG)-focused evaluation**, co
 #### Key Features
 
 - **Fast DEG detection**: Vectorized Welch's t-test, Student's t-test, or Wilcoxon rank-sum
+- **DEG vs all-genes comparison**: Compute metrics on both and compare
+- **Flexible DEG selection**: Top N by significance, or threshold-based filtering
 - **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
@@ -266,7 +268,7 @@ GenEval supports **Differentially Expressed Genes (DEG)-focused evaluation**, co
 from geneval import evaluate_degs
 import pandas as pd
 
-# Evaluate with DEG-focused metrics
+# Evaluate with DEG-focused metrics (computes both DEG and all-genes by default)
 results = evaluate_degs(
     real_data=real_adata.X,           # (n_samples, n_genes)
     generated_data=gen_adata.X,
@@ -276,29 +278,62 @@ results = evaluate_degs(
     control_key="control",            # Value indicating control samples
     perturbation_column="perturbation",
     deg_method="welch",               # or "student", "wilcoxon", "logfc"
-    pval_threshold=0.05,
+    pval_threshold=0.05,              # Significance threshold
     lfc_threshold=0.5,                # log2 fold change threshold
+    compute_all_genes=True,           # Also compute metrics on all genes
     device="cuda",                    # GPU acceleration
 )
 
-# Access results
-print(results.aggregated_metrics)     # Summary across all contexts
-print(results.expanded_metrics)       # Per-context metrics
+# Compare DEG-only vs all-genes metrics
+print(results.comparison_summary)
+#        metric  deg_mean  all_mean  difference  ratio
+# wasserstein_1     5.34      0.69        4.65   7.74
+#           mmd     1.14      0.13        1.02   9.00
+
+# Access per-context results
+print(results.expanded_metrics)       # Has deg_* and all_* columns
 print(results.deg_summary)            # DEG counts per context
 
 # Save results with plots
 results.save("deg_evaluation/")
 ```
 
+#### DEG Selection Control
+
+```python
+# Option 1: Top N most significant DEGs
+results = evaluate_degs(
+    ...,
+    n_top_degs=50,      # Use only top 50 DEGs by adjusted p-value
+)
+
+# Option 2: Stricter thresholds
+results = evaluate_degs(
+    ...,
+    pval_threshold=0.01,    # More stringent p-value
+    lfc_threshold=1.0,      # 2-fold change minimum
+)
+
+# Option 3: DEGs only (skip all-genes metrics for speed)
+results = evaluate_degs(
+    ...,
+    compute_all_genes=False,
+)
+
+# Get DEG-only or all-genes metrics separately
+deg_only = results.get_deg_only_metrics()
+all_genes = results.get_all_genes_metrics()
+```
+
 #### 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 |
+| Context | n_DEGs | deg_W1 | all_W1 | deg_MMD | all_MMD |
+|---------|--------|--------|--------|---------|---------|
+| TypeA_drug1 | 234 | 5.42 | 0.69 | 1.03 | 0.13 |
+| TypeA_drug2 | 189 | 4.38 | 0.71 | 0.92 | 0.12 |
+| TypeB_drug1 | 312 | 6.51 | 0.68 | 1.21 | 0.14 |
 
 If only `perturbation` column is provided, evaluation is done per-perturbation.
 

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

@@ -1,4 +1,4 @@
-geneval/__init__.py,sha256=1ENlptAErFX1ThLDuO8J5Hs0ko5gIxGGVq7PZUhBUKY,5418
+geneval/__init__.py,sha256=UD-fl1x0J0VUTyktgvUzCqaU1kLaU2vmYALfdzm-TzQ,5418
 geneval/cli.py,sha256=0ai0IGyn3SSmEnfLRJhcr0brvUxuNZHE4IXod7jvosU,9977
 geneval/config.py,sha256=gkCjs_gzPWgUZNcmSR3Y70XQCAZ1m9AKLueaM-x8bvw,3729
 geneval/core.py,sha256=No0DP8bNR6LedfCWEedY9C5r_c4M14rvSPaGZqbxc94,1155
@@ -6,10 +6,10 @@ 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/__init__.py,sha256=iNKvtbumTA-A1usWhHIP1rbRVNkje5tN5x81FzD6CbI,1577
 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/evaluator.py,sha256=uPduuWovUD6B_vie4RomH-F9MgrtaqQbtjmJlvEeDYM,30493
 geneval/deg/visualization.py,sha256=9lWW9vRH_FbkIjJrf1MPobU1Yu_CAh6aw60S7g2Qe2k,10448
 geneval/evaluator.py,sha256=WgdrgqOcGYT35k1keiFEIIRIj2CQaD2DsmBpq9hcLrI,13440
 geneval/evaluators/__init__.py,sha256=i11sHvhsjEAeI3Aw9zFTPmCYuqkGxzTHggAKehe3HQ0,160
@@ -33,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.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,,
+gengeneeval-0.4.1.dist-info/METADATA,sha256=1xoULyzbHjzOKmTEQcx5fRv7DXEMJwe2XqqKxQhCi2Q,14041
+gengeneeval-0.4.1.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+gengeneeval-0.4.1.dist-info/entry_points.txt,sha256=xTkwnNa2fP0w1uGVsafzRTaCeuBSWLlNO-1CN8uBSK0,43
+gengeneeval-0.4.1.dist-info/licenses/LICENSE,sha256=RDHgHDI4rSDq35R4CAC3npy86YUnmZ81ecO7aHfmmGA,1073
+gengeneeval-0.4.1.dist-info/RECORD,,