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

geneval/__init__.py

@@ -7,8 +7,10 @@ and generated gene expression datasets stored in AnnData (h5ad) format.
 Features:
 - Multiple distance and correlation metrics (per-gene and aggregate)
 - Condition-based matching (perturbation, cell type, etc.)
+- DEG-focused evaluation with per-context (covariate × perturbation) support
 - Train/test split support
 - Memory-efficient lazy loading for large datasets
+- CPU parallelization and GPU acceleration
 - Publication-quality visualizations
 - Command-line interface
 
@@ -21,6 +23,17 @@ Quick Start:
     ...     output_dir="output/"
     ... )
 
+DEG-Focused Evaluation:
+    >>> from geneval import evaluate_degs
+    >>> results = evaluate_degs(
+    ...     real_data, generated_data,
+    ...     real_obs, generated_obs,
+    ...     condition_columns=["cell_type", "perturbation"],
+    ...     control_key="control",
+    ...     deg_method="welch",
+    ...     device="cuda",  # GPU acceleration
+    ... )
+
 Memory-Efficient Mode (for large datasets):
     >>> from geneval import evaluate_lazy
     >>> results = evaluate_lazy(
@@ -36,7 +49,7 @@ CLI Usage:
               --conditions perturbation cell_type --output results/
 """
 
-__version__ = "0.3.0"
+__version__ = "0.4.1"
 __author__ = "GenEval Team"
 
 # Main evaluation interface
@@ -109,6 +122,22 @@ from .metrics.accelerated import (
     compute_metrics_accelerated,
 )
 
+# DEG-focused evaluation
+from .deg import (
+    DEGEvaluator,
+    DEGResult,
+    DEGEvaluationResult,
+    ContextEvaluator,
+    ContextResult,
+    compute_degs_fast,
+    compute_degs_gpu,
+    get_contexts,
+    plot_deg_distributions,
+    plot_context_heatmap,
+    create_deg_report,
+)
+from .deg.evaluator import evaluate_degs
+
 # Visualization
 from .visualization.visualizer import (
     EvaluationVisualizer,
@@ -174,6 +203,19 @@ __all__ = [
     "ParallelMetricComputer",
     "get_available_backends",
     "compute_metrics_accelerated",
+    # DEG evaluation
+    "DEGEvaluator",
+    "DEGResult",
+    "DEGEvaluationResult",
+    "ContextEvaluator",
+    "ContextResult",
+    "compute_degs_fast",
+    "compute_degs_gpu",
+    "evaluate_degs",
+    "get_contexts",
+    "plot_deg_distributions",
+    "plot_context_heatmap",
+    "create_deg_report",
     # Visualization
     "EvaluationVisualizer",
     "visualize",

geneval/deg/__init__.py

@@ -0,0 +1,69 @@
+"""
+Differentially Expressed Genes (DEG) module for GenGeneEval.
+
+This module provides:
+- Fast DEG detection using vectorized statistical tests
+- Per-context evaluation (covariates × perturbations)
+- DEG-focused metrics computation
+- Integration with GPU acceleration
+
+Example usage:
+    >>> from geneval.deg import DEGEvaluator, compute_degs_fast
+    >>> degs = compute_degs_fast(control_data, perturbed_data, method="welch")
+    >>> evaluator = DEGEvaluator(loader, deg_method="welch", pval_threshold=0.05)
+    >>> results = evaluator.evaluate()
+"""
+
+from .detection import (
+    compute_degs_fast,
+    compute_degs_gpu,
+    compute_degs_auto,
+    DEGResult,
+    DEGMethod,
+)
+from .context import (
+    ContextEvaluator,
+    ContextResult,
+    get_contexts,
+    get_context_id,
+    filter_by_context,
+)
+from .evaluator import (
+    DEGEvaluator,
+    DEGEvaluationResult,
+    DEGSettings,
+    ContextMetrics,
+    evaluate_degs,
+)
+from .visualization import (
+    plot_deg_distributions,
+    plot_context_heatmap,
+    plot_deg_counts,
+    create_deg_report,
+)
+
+__all__ = [
+    # Detection
+    "compute_degs_fast",
+    "compute_degs_gpu",
+    "compute_degs_auto",
+    "DEGResult",
+    "DEGMethod",
+    # Context
+    "ContextEvaluator",
+    "ContextResult",
+    "get_contexts",
+    "get_context_id",
+    "filter_by_context",
+    # Evaluator
+    "DEGEvaluator",
+    "DEGEvaluationResult",
+    "DEGSettings",
+    "ContextMetrics",
+    "evaluate_degs",
+    # Visualization
+    "plot_deg_distributions",
+    "plot_context_heatmap",
+    "plot_deg_counts",
+    "create_deg_report",
+]

geneval/deg/context.py

@@ -0,0 +1,271 @@
+"""
+Context-aware evaluation for gene expression data.
+
+Supports per-context evaluation where context = covariates × perturbation.
+If only perturbation column is given, evaluates per-perturbation.
+If multiple condition columns are given, evaluates every combination.
+"""
+from __future__ import annotations
+
+from typing import Optional, List, Dict, Tuple, Union, Iterator
+from dataclasses import dataclass, field
+import numpy as np
+import pandas as pd
+from itertools import product
+
+
+@dataclass
+class ContextResult:
+    """Results for a single context (covariate × perturbation combination).
+    
+    Attributes
+    ----------
+    context_id : str
+        Unique identifier for this context
+    context_values : Dict[str, str]
+        Values for each condition column
+    n_samples_real : int
+        Number of real samples in this context
+    n_samples_gen : int
+        Number of generated samples in this context
+    deg_result : Any, optional
+        DEG detection result for this context
+    metrics : Dict[str, float]
+        Computed metrics for this context
+    """
+    context_id: str
+    context_values: Dict[str, str]
+    n_samples_real: int
+    n_samples_gen: int
+    deg_result: Optional["DEGResult"] = None  # Forward reference
+    metrics: Dict[str, float] = field(default_factory=dict)
+    per_gene_metrics: Dict[str, np.ndarray] = field(default_factory=dict)
+    
+    def __repr__(self) -> str:
+        return (
+            f"ContextResult(id='{self.context_id}', "
+            f"n_real={self.n_samples_real}, n_gen={self.n_samples_gen}, "
+            f"n_degs={self.deg_result.n_degs if self.deg_result else 'N/A'})"
+        )
+
+
+def get_contexts(
+    obs: pd.DataFrame,
+    condition_columns: List[str],
+    min_samples: int = 2,
+) -> List[Dict[str, str]]:
+    """
+    Get all unique contexts (combinations of condition values).
+    
+    Parameters
+    ----------
+    obs : pd.DataFrame
+        Observation metadata (adata.obs)
+    condition_columns : List[str]
+        Columns to use for context definition
+    min_samples : int
+        Minimum samples required per context
+        
+    Returns
+    -------
+    List[Dict[str, str]]
+        List of context dictionaries
+    """
+    if len(condition_columns) == 0:
+        return [{}]
+    
+    # Get unique values for each column
+    unique_values = []
+    for col in condition_columns:
+        if col in obs.columns:
+            unique_values.append(obs[col].unique().tolist())
+        else:
+            raise ValueError(f"Column '{col}' not found in obs")
+    
+    # Generate all combinations
+    contexts = []
+    for combo in product(*unique_values):
+        context = dict(zip(condition_columns, combo))
+        
+        # Check if context has enough samples
+        mask = np.ones(len(obs), dtype=bool)
+        for col, val in context.items():
+            mask &= (obs[col] == val).values
+        
+        if mask.sum() >= min_samples:
+            contexts.append(context)
+    
+    return contexts
+
+
+def get_context_id(context: Dict[str, str]) -> str:
+    """Generate unique ID for a context."""
+    if not context:
+        return "all"
+    return "_".join(f"{k}={v}" for k, v in sorted(context.items()))
+
+
+def filter_by_context(
+    data: np.ndarray,
+    obs: pd.DataFrame,
+    context: Dict[str, str],
+) -> Tuple[np.ndarray, np.ndarray]:
+    """
+    Filter data by context.
+    
+    Parameters
+    ----------
+    data : np.ndarray
+        Expression matrix (n_samples, n_genes)
+    obs : pd.DataFrame
+        Observation metadata
+    context : Dict[str, str]
+        Context to filter by
+        
+    Returns
+    -------
+    Tuple[np.ndarray, np.ndarray]
+        Filtered data and mask
+    """
+    if not context:
+        return data, np.ones(len(obs), dtype=bool)
+    
+    mask = np.ones(len(obs), dtype=bool)
+    for col, val in context.items():
+        mask &= (obs[col] == val).values
+    
+    return data[mask], mask
+
+
+class ContextEvaluator:
+    """
+    Evaluator that computes metrics per context.
+    
+    A context is defined by the combination of all condition column values.
+    For example, if condition_columns = ["cell_type", "perturbation"],
+    each unique (cell_type, perturbation) pair is a context.
+    
+    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
+    generated_obs : pd.DataFrame
+        Generated data metadata
+    condition_columns : List[str]
+        Columns defining contexts
+    gene_names : np.ndarray, optional
+        Gene names
+    control_key : str, optional
+        Value in perturbation column indicating control (for DEG computation)
+    perturbation_column : str, optional
+        Name of perturbation column (for DEG computation)
+    """
+    
+    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,
+    ):
+        self.real_data = real_data
+        self.generated_data = generated_data
+        self.real_obs = real_obs
+        self.generated_obs = generated_obs
+        self.condition_columns = condition_columns
+        self.gene_names = gene_names
+        self.control_key = control_key
+        
+        # Determine perturbation column
+        if perturbation_column is not None:
+            self.perturbation_column = perturbation_column
+        elif len(condition_columns) > 0:
+            self.perturbation_column = condition_columns[0]
+        else:
+            self.perturbation_column = None
+        
+        # Get contexts
+        self._real_contexts = get_contexts(real_obs, condition_columns)
+        self._gen_contexts = get_contexts(generated_obs, condition_columns)
+        
+        # Find common contexts
+        real_ids = {get_context_id(c) for c in self._real_contexts}
+        gen_ids = {get_context_id(c) for c in self._gen_contexts}
+        common_ids = real_ids & gen_ids
+        
+        self.contexts = [c for c in self._real_contexts if get_context_id(c) in common_ids]
+        
+        # Cache control data for DEG computation
+        self._control_cache: Dict[str, Tuple[np.ndarray, np.ndarray]] = {}
+    
+    def get_context_data(
+        self,
+        context: Dict[str, str],
+    ) -> Tuple[np.ndarray, np.ndarray]:
+        """Get real and generated data for a context."""
+        real_filtered, _ = filter_by_context(self.real_data, self.real_obs, context)
+        gen_filtered, _ = filter_by_context(self.generated_data, self.generated_obs, context)
+        return real_filtered, gen_filtered
+    
+    def get_control_data(
+        self,
+        context: Dict[str, str],
+    ) -> Tuple[np.ndarray, np.ndarray]:
+        """
+        Get control data for DEG computation.
+        
+        For a given context, finds the corresponding control by replacing
+        the perturbation value with control_key.
+        """
+        if self.perturbation_column is None:
+            raise ValueError("perturbation_column required for DEG computation")
+        
+        # Create control context
+        control_context = context.copy()
+        control_context[self.perturbation_column] = self.control_key
+        context_id = get_context_id(control_context)
+        
+        # Check cache
+        if context_id in self._control_cache:
+            return self._control_cache[context_id]
+        
+        # Get control data
+        real_control, _ = filter_by_context(self.real_data, self.real_obs, control_context)
+        gen_control, _ = filter_by_context(self.generated_data, self.generated_obs, control_context)
+        
+        self._control_cache[context_id] = (real_control, gen_control)
+        return real_control, gen_control
+    
+    def iter_contexts(self) -> Iterator[Tuple[str, Dict[str, str], np.ndarray, np.ndarray]]:
+        """Iterate over contexts with their data."""
+        for context in self.contexts:
+            context_id = get_context_id(context)
+            real_data, gen_data = self.get_context_data(context)
+            yield context_id, context, real_data, gen_data
+    
+    def is_control_context(self, context: Dict[str, str]) -> bool:
+        """Check if context is a control (not perturbed)."""
+        if self.perturbation_column is None:
+            return False
+        return context.get(self.perturbation_column) == self.control_key
+    
+    def get_perturbation_contexts(self) -> List[Dict[str, str]]:
+        """Get only perturbation contexts (excluding controls)."""
+        return [c for c in self.contexts if not self.is_control_context(c)]
+    
+    def __len__(self) -> int:
+        return len(self.contexts)
+    
+    def __repr__(self) -> str:
+        return (
+            f"ContextEvaluator(n_contexts={len(self.contexts)}, "
+            f"condition_columns={self.condition_columns})"
+        )