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

geneval/metrics/reconstruction.py

@@ -0,0 +1,243 @@
+"""
+Reconstruction metrics for gene expression evaluation.
+
+Provides MSE (Mean Squared Error) and related reconstruction quality metrics.
+"""
+from __future__ import annotations
+
+import numpy as np
+from typing import Optional
+
+from .base_metric import BaseMetric
+
+
+def _ensure_2d(arr: np.ndarray) -> np.ndarray:
+    """Ensure array is 2D (samples x genes)."""
+    arr = np.asarray(arr, dtype=np.float64)
+    if arr.ndim == 1:
+        arr = arr.reshape(-1, 1)
+    return arr
+
+
+class MSEDistance(BaseMetric):
+    """
+    Mean Squared Error (MSE) between real and generated distributions.
+    
+    Computes the average squared difference between samples. When sample
+    sizes differ, compares mean expression profiles.
+    
+    Lower values indicate better reconstruction.
+    
+    Parameters
+    ----------
+    compare_means : bool
+        If True, always compare mean profiles regardless of sample sizes.
+        If False, compute sample-wise MSE when sizes match.
+        
+    Examples
+    --------
+    >>> mse = MSEDistance()
+    >>> result = mse.compute(real_data, generated_data, gene_names)
+    >>> print(f"MSE: {result.aggregate_value:.4f}")
+    """
+    
+    def __init__(self, compare_means: bool = False):
+        super().__init__(
+            name="mse",
+            description="Mean Squared Error per gene",
+            higher_is_better=False,
+            requires_distribution=True,
+        )
+        self.compare_means = compare_means
+    
+    def compute_per_gene(
+        self,
+        real: np.ndarray,
+        generated: np.ndarray,
+    ) -> np.ndarray:
+        """
+        Compute MSE for each gene.
+        
+        Parameters
+        ----------
+        real : np.ndarray
+            Real data, shape (n_samples_real, n_genes)
+        generated : np.ndarray
+            Generated data, shape (n_samples_gen, n_genes)
+            
+        Returns
+        -------
+        np.ndarray
+            MSE per gene, shape (n_genes,)
+        """
+        real = _ensure_2d(real)
+        generated = _ensure_2d(generated)
+        n_genes = real.shape[1]
+        
+        mse = np.zeros(n_genes)
+        
+        # Compare mean profiles when sample sizes differ or compare_means is True
+        if self.compare_means or real.shape[0] != generated.shape[0]:
+            real_mean = np.mean(real, axis=0)
+            gen_mean = np.mean(generated, axis=0)
+            mse = (real_mean - gen_mean) ** 2
+        else:
+            # Sample-wise MSE when sizes match
+            for i in range(n_genes):
+                r_vals = real[:, i]
+                g_vals = generated[:, i]
+                
+                # Filter NaN values
+                valid = ~(np.isnan(r_vals) | np.isnan(g_vals))
+                if not valid.any():
+                    mse[i] = np.nan
+                    continue
+                
+                mse[i] = np.mean((r_vals[valid] - g_vals[valid]) ** 2)
+        
+        return mse
+
+
+class RMSEDistance(BaseMetric):
+    """
+    Root Mean Squared Error (RMSE) between real and generated distributions.
+    
+    Square root of MSE, in the same units as the original data.
+    Lower values indicate better reconstruction.
+    """
+    
+    def __init__(self, compare_means: bool = False):
+        super().__init__(
+            name="rmse",
+            description="Root Mean Squared Error per gene",
+            higher_is_better=False,
+            requires_distribution=True,
+        )
+        self.compare_means = compare_means
+        self._mse = MSEDistance(compare_means=compare_means)
+    
+    def compute_per_gene(
+        self,
+        real: np.ndarray,
+        generated: np.ndarray,
+    ) -> np.ndarray:
+        """
+        Compute RMSE for each gene.
+        """
+        mse = self._mse.compute_per_gene(real, generated)
+        return np.sqrt(mse)
+
+
+class MAEDistance(BaseMetric):
+    """
+    Mean Absolute Error (MAE) between real and generated distributions.
+    
+    More robust to outliers than MSE.
+    Lower values indicate better reconstruction.
+    """
+    
+    def __init__(self, compare_means: bool = False):
+        super().__init__(
+            name="mae",
+            description="Mean Absolute Error per gene",
+            higher_is_better=False,
+            requires_distribution=True,
+        )
+        self.compare_means = compare_means
+    
+    def compute_per_gene(
+        self,
+        real: np.ndarray,
+        generated: np.ndarray,
+    ) -> np.ndarray:
+        """
+        Compute MAE for each gene.
+        """
+        real = _ensure_2d(real)
+        generated = _ensure_2d(generated)
+        n_genes = real.shape[1]
+        
+        mae = np.zeros(n_genes)
+        
+        if self.compare_means or real.shape[0] != generated.shape[0]:
+            real_mean = np.mean(real, axis=0)
+            gen_mean = np.mean(generated, axis=0)
+            mae = np.abs(real_mean - gen_mean)
+        else:
+            for i in range(n_genes):
+                r_vals = real[:, i]
+                g_vals = generated[:, i]
+                
+                valid = ~(np.isnan(r_vals) | np.isnan(g_vals))
+                if not valid.any():
+                    mae[i] = np.nan
+                    continue
+                
+                mae[i] = np.mean(np.abs(r_vals[valid] - g_vals[valid]))
+        
+        return mae
+
+
+class R2Score(BaseMetric):
+    """
+    Coefficient of Determination (R²) between real and generated data.
+    
+    Measures the proportion of variance explained. Values close to 1
+    indicate good fit, 0 means no better than mean prediction.
+    
+    Higher values indicate better reconstruction.
+    """
+    
+    def __init__(self):
+        super().__init__(
+            name="r2",
+            description="R² (coefficient of determination) per gene",
+            higher_is_better=True,
+            requires_distribution=True,
+        )
+    
+    def compute_per_gene(
+        self,
+        real: np.ndarray,
+        generated: np.ndarray,
+    ) -> np.ndarray:
+        """
+        Compute R² for each gene.
+        """
+        real = _ensure_2d(real)
+        generated = _ensure_2d(generated)
+        n_genes = real.shape[1]
+        
+        r2 = np.zeros(n_genes)
+        
+        # R² only makes sense when sample sizes match
+        if real.shape[0] != generated.shape[0]:
+            # Fall back to using mean comparison
+            real_mean = np.mean(real, axis=0)
+            gen_mean = np.mean(generated, axis=0)
+            
+            ss_tot = np.var(real, axis=0) * real.shape[0]
+            ss_res = (real_mean - gen_mean) ** 2
+            
+            with np.errstate(invalid='ignore', divide='ignore'):
+                r2 = 1 - ss_res / (ss_tot / real.shape[0] + 1e-10)
+            r2 = np.nan_to_num(r2, nan=0.0)
+        else:
+            for i in range(n_genes):
+                r_vals = real[:, i]
+                g_vals = generated[:, i]
+                
+                valid = ~(np.isnan(r_vals) | np.isnan(g_vals))
+                if not valid.any():
+                    r2[i] = np.nan
+                    continue
+                
+                ss_tot = np.sum((r_vals[valid] - np.mean(r_vals[valid])) ** 2)
+                ss_res = np.sum((r_vals[valid] - g_vals[valid]) ** 2)
+                
+                if ss_tot < 1e-10:
+                    r2[i] = 1.0 if ss_res < 1e-10 else 0.0
+                else:
+                    r2[i] = 1 - ss_res / ss_tot
+        
+        return r2

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

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: gengeneeval
-Version: 0.1.1
-Summary: Comprehensive evaluation of generated gene expression data. Computes metrics between real and generated datasets with support for condition matching, train/test splits, and publication-quality visualizations.
+Version: 0.2.1
+Summary: Comprehensive evaluation of generated gene expression data. Computes metrics between real and generated datasets with support for condition matching, train/test splits, memory-efficient lazy loading, and publication-quality visualizations.
 License: MIT
 License-File: LICENSE
-Keywords: gene expression,evaluation,metrics,single-cell,generative models,benchmarking
+Keywords: gene expression,evaluation,metrics,single-cell,generative models,benchmarking,memory-efficient
 Author: GenEval Team
 Author-email: geneval@example.com
 Requires-Python: >=3.8,<4.0
@@ -42,11 +42,11 @@ Description-Content-Type: text/markdown
 [![PyPI version](https://badge.fury.io/py/gengeneeval.svg)](https://badge.fury.io/py/gengeneeval)
 [![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Tests](https://github.com/AndreaRubbi/GenGeneEval/actions/workflows/tests.yml/badge.svg)](https://github.com/AndreaRubbi/GenGeneEval/actions)
+[![Tests](https://github.com/AndreaRubbi/GenGeneEval/actions/workflows/test.yml/badge.svg)](https://github.com/AndreaRubbi/GenGeneEval/actions)
 
 **Comprehensive evaluation of generated gene expression data against real datasets.**
 
-GenEval is a modular, object-oriented Python framework for computing metrics between real and generated gene expression datasets stored in AnnData (h5ad) format. It supports condition-based matching, train/test splits, and generates publication-quality visualizations.
+GenEval is a modular, object-oriented Python framework for computing metrics between real and generated gene expression datasets stored in AnnData (h5ad) format. It supports condition-based matching, train/test splits, memory-efficient lazy loading for large datasets, and generates publication-quality visualizations.
 
 ## Features
 
@@ -55,6 +55,10 @@ All metrics are computed **per-gene** (returning a vector) and **aggregated**:
 
 | Metric | Description | Direction |
 |--------|-------------|-----------|
+| **MSE** | Mean Squared Error | Lower is better |
+| **RMSE** | Root Mean Squared Error | Lower is better |
+| **MAE** | Mean Absolute Error | Lower is better |
+| **R²** | Coefficient of Determination | Higher is better |
 | **Pearson Correlation** | Linear correlation between expression profiles | Higher is better |
 | **Spearman Correlation** | Rank correlation (robust to outliers) | Higher is better |
 | **Wasserstein-1** | Earth Mover's Distance (L1) | Lower is better |
@@ -73,6 +77,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
+- ✅ **Memory-efficient lazy loading** for large datasets
+- ✅ **Batched evaluation** to avoid OOM errors
 - ✅ Modular, extensible architecture
 - ✅ Command-line interface
 - ✅ Publication-quality visualizations
@@ -136,6 +142,37 @@ geneval --real real.h5ad --generated generated.h5ad \
         --output results/
 ```
 
+### Memory-Efficient Mode (for Large Datasets)
+
+For datasets too large to fit in memory, use the lazy evaluation API:
+
+```python
+from geneval import evaluate_lazy, load_data_lazy
+
+# Memory-efficient evaluation (streams data one condition at a time)
+results = evaluate_lazy(
+    real_path="large_real.h5ad",
+    generated_path="large_generated.h5ad",
+    condition_columns=["perturbation"],
+    batch_size=256,                    # Process in batches
+    use_backed=True,                   # Memory-mapped file access
+    output_dir="eval_output/",
+    save_per_condition=True,           # Save each condition to disk
+)
+
+# Get summary statistics
+print(results.get_summary())
+
+# Or use the lazy loader directly for custom workflows
+with load_data_lazy("real.h5ad", "gen.h5ad", ["perturbation"]) as loader:
+    print(f"Memory estimate: {loader.estimate_memory_usage()}")
+    
+    # Process one condition at a time
+    for key, real, gen, info in loader.iterate_conditions():
+        # Your custom evaluation logic
+        pass
+```
+
 ## Expected Data Format
 
 GenEval expects AnnData (h5ad) files with:

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

@@ -1,19 +1,22 @@
-geneval/__init__.py,sha256=8D8KN9PSLbux6LMc6Ap1nz_WlQ4Jc6YNylPy_0udJ-Q,2872
+geneval/__init__.py,sha256=_WxX5Kjk7y3u7mBZ5cf6ficy9SIT2FutZNcMe1fr9Ro,3989
 geneval/cli.py,sha256=0ai0IGyn3SSmEnfLRJhcr0brvUxuNZHE4IXod7jvosU,9977
 geneval/config.py,sha256=gkCjs_gzPWgUZNcmSR3Y70XQCAZ1m9AKLueaM-x8bvw,3729
 geneval/core.py,sha256=No0DP8bNR6LedfCWEedY9C5r_c4M14rvSPaGZqbxc94,1155
-geneval/data/__init__.py,sha256=nD3uWostZbYD3Yj_TOE44LvPDen-Vm3gN8ZH0QptPGw,450
+geneval/data/__init__.py,sha256=NQUPVpUnBIabrTH5TuRk0KE9S7sVO5QetZv-MCQmZuw,827
 geneval/data/gene_expression_datamodule.py,sha256=XiBIdf68JZ-3S-FaZsrQlBJA7qL9uUXo2C8y0r4an5M,8009
+geneval/data/lazy_loader.py,sha256=5fTRVjPjcWvYXV-uPWFUF2Nn9rHRdD8lygAUkCW8wOM,20677
 geneval/data/loader.py,sha256=zpRmwGZ4PJkB3rpXXRCMFtvMi4qvUrPkKmvIlGjfRpY,14555
-geneval/evaluator.py,sha256=grPudMng-CcnWwkxQGWM6RZ198Q-1THkR4MCXtadCdU,11545
+geneval/evaluator.py,sha256=wZFzLo2PLHanjA-9L6C3xJBjMWXxPM63kU6usU4P7bs,11619
 geneval/evaluators/__init__.py,sha256=i11sHvhsjEAeI3Aw9zFTPmCYuqkGxzTHggAKehe3HQ0,160
 geneval/evaluators/base_evaluator.py,sha256=yJL568HdNofIcHgNOElSQMVlG9oRPTTDIZ7CmKccRqs,5967
 geneval/evaluators/gene_expression_evaluator.py,sha256=v8QL6tzOQ3QVXdPMM8tFHTTviZC3WsPRX4G0ShgeDUw,8743
-geneval/metrics/__init__.py,sha256=wk0CdFXvipfPqXWUMsRRz9CPiSVPG40Id4lyoSaLIkY,1417
+geneval/lazy_evaluator.py,sha256=I_VvDolxPFGiW38eGPrjSoBOKICKyYN3GHbjJBAe5tg,13200
+geneval/metrics/__init__.py,sha256=H5IXTKR-zoP_pGht6ioJfhLU7IHrSDQElMk0Cp4-JTw,1786
 geneval/metrics/base_metric.py,sha256=prbnB-Ap-P64m-2_TUrHxO3NFQaw-obVg1Tw4pjC5EY,6961
 geneval/metrics/correlation.py,sha256=jpYmaihWK89J1E5yQinGUJeB6pTZ21xPNHJi3XYyXJE,6987
 geneval/metrics/distances.py,sha256=9mWzbMbIBY1ckOd2a0l3by3aEFMQZL9bVMSeP44xzUg,16155
 geneval/metrics/metrics.py,sha256=s3ONmYTOk1ou6DUqCDOREQaqk3ajgpW_lZbZp1WW4aY,4747
+geneval/metrics/reconstruction.py,sha256=phvQtB-CTFyfmkmj0oii4PChMmZtsRdfIRn_ISBq1w0,7387
 geneval/models/__init__.py,sha256=vJHXIhwzykjoqZ-vHQJnPwwjSUu9nnMyo7jGnWlTd94,42
 geneval/models/base_model.py,sha256=2QDtweYTgiovnksaRPBjNbIDu1l9l_WQMMFfeIX3GB8,1345
 geneval/results.py,sha256=iXSB0o0f1jQrCKjc-lbRfwBFGhspTDDJpQ2K2tM-XR4,11362
@@ -24,8 +27,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.1.1.dist-info/METADATA,sha256=4WJtqiCK88ZIKGObjIXQ-Fp0PvmF6D5-YGpm0WciUNc,6041
-gengeneeval-0.1.1.dist-info/WHEEL,sha256=3ny-bZhpXrU6vSQ1UPG34FoxZBp3lVcvK0LkgUz6VLk,88
-gengeneeval-0.1.1.dist-info/entry_points.txt,sha256=xTkwnNa2fP0w1uGVsafzRTaCeuBSWLlNO-1CN8uBSK0,43
-gengeneeval-0.1.1.dist-info/licenses/LICENSE,sha256=RDHgHDI4rSDq35R4CAC3npy86YUnmZ81ecO7aHfmmGA,1073
-gengeneeval-0.1.1.dist-info/RECORD,,
+gengeneeval-0.2.1.dist-info/METADATA,sha256=aRjsh5JUIcH8huIngsCi14eyE3-Vl_AFv9Uo1j5mciw,7497
+gengeneeval-0.2.1.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+gengeneeval-0.2.1.dist-info/entry_points.txt,sha256=xTkwnNa2fP0w1uGVsafzRTaCeuBSWLlNO-1CN8uBSK0,43
+gengeneeval-0.2.1.dist-info/licenses/LICENSE,sha256=RDHgHDI4rSDq35R4CAC3npy86YUnmZ81ecO7aHfmmGA,1073
+gengeneeval-0.2.1.dist-info/RECORD,,

{gengeneeval-0.1.1.dist-info → gengeneeval-0.2.1.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 2.3.0
+Generator: poetry-core 2.2.1
 Root-Is-Purelib: true
 Tag: py3-none-any