calm-data-generator 2.2.1__tar.gz → 2.3.1__tar.gz

calm_data_generator-2.3.1/AUTHORS

@@ -0,0 +1,32 @@
+CALM-Data-Generator — Authors and Contributors
+==============================================
+
+Project contact: calmdatagenerator@outlook.es
+
+Authorship is documented here and in the project files (pyproject.toml,
+CITATION.cff, README). It is independent of who administers the GitHub
+repository, and the commit history remains the permanent record of
+individual contributions.
+
+
+Original author
+---------------
+Alejandro Belda Fernandez <a.beldafernandez@um.es>
+    Created the library and led its development through version 2.3.0.
+    Universidad de Murcia.
+
+
+Current maintainer
+------------------
+Antonio Guillen Teruel <a.guillenteruel@um.es>
+    Maintains the project from version 2.3.0 onwards.
+    Universidad de Murcia.
+
+
+Contributors
+------------
+Nasim El Arifi Ahmed <nasim.e.a@um.es>
+    Author of scGFT Evaluator (https://github.com/nasim23ea/scgft-evaluator),
+    the Graph Fourier Transform-based single-cell evaluation integrated into
+    QualityReporter via the `use_scgft` option.
+    Universidad de Murcia.

{calm_data_generator-2.2.1/calm_data_generator.egg-info → calm_data_generator-2.3.1}/PKG-INFO

@@ -1,11 +1,12 @@
 Metadata-Version: 2.4
 Name: calm-data-generator
-Version: 2.2.1
+Version: 2.3.1
 Summary: CALM-Data-Generator: A Python library for synthetic data generation with support for drift injection and clinical data.
 Author-email: Alejandro Belda Fernandez <alejandrobeldafernandez@gmail.com>
+Maintainer-email: Antonio Guillen Teruel <a.guillenteruel@um.es>, CALM-Data-Generator project <calmdatagenerator@outlook.es>
 License: MIT
-Project-URL: Homepage, https://github.com/AlejandroBeldaFernandez/Calm-Data_Generator
-Project-URL: Bug Tracker, https://github.com/AlejandroBeldaFernandez/Calm-Data_Generator/issues
+Project-URL: Homepage, https://github.com/AlejandroBeldaFernandez/Calm-Data-Generator
+Project-URL: Bug Tracker, https://github.com/AlejandroBeldaFernandez/Calm-Data-Generator/issues
 Keywords: synthetic-data,machine-learning,generative-ai,data-science,drift-detection,clinical-data,privacy
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
@@ -21,6 +22,7 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
+License-File: AUTHORS
 Requires-Dist: numpy<2.0.0,>=1.26.4
 Requires-Dist: pandas<2.4.0,>=2.3.0
 Requires-Dist: scipy<1.15.0,>=1.14.0
@@ -33,8 +35,8 @@ Requires-Dist: sdmetrics<0.28.0,>=0.27.0
 Requires-Dist: numba<0.63.0,>=0.62.0
 Requires-Dist: llvmlite<0.46.0,>=0.45.0
 Requires-Dist: scikit-learn<1.8.0,>=1.7.0
-Requires-Dist: torch<2.3.0,>=2.2.0
-Requires-Dist: torchvision<0.18.0,>=0.17.0
+Requires-Dist: torch>=2.2.0
+Requires-Dist: torchvision>=0.17.0
 Requires-Dist: lightgbm<4.7.0,>=4.6.0
 Requires-Dist: imbalanced-learn<0.15.0,>=0.14.0
 Requires-Dist: copulae<0.8.0,>=0.7.9
@@ -44,8 +46,6 @@ Requires-Dist: scanpy<1.11.0,>=1.10.0
 Requires-Dist: lightning<2.4.0,>=2.3.0
 Requires-Dist: torchmetrics<1.9.0,>=1.8.0
 Requires-Dist: plotly<6.6.0,>=6.5.0
-Requires-Dist: cell-gears<0.2.0,>=0.1.2
-Requires-Dist: torch-geometric<2.8.0,>=2.7.0
 Requires-Dist: huggingface-hub<1.0.0,>=0.36.0
 Requires-Dist: transformers<5.0.0,>=4.22.1
 Requires-Dist: xgboost<2.2.0,>=2.1.0
@@ -56,8 +56,13 @@ Requires-Dist: fsspec<2026.0.0,>=2025.12.0
 Requires-Dist: scgft-evaluator<0.2.0,>=0.1.0
 Provides-Extra: stream
 Requires-Dist: river>=0.21.0; extra == "stream"
+Provides-Extra: gears
+Requires-Dist: torch-geometric>=2.7.0; extra == "gears"
+Requires-Dist: cell-gears<0.2.0,>=0.1.2; extra == "gears"
+Provides-Extra: privacy
+Requires-Dist: anonymeter<2.0.0,>=1.0.0; extra == "privacy"
 Provides-Extra: full
-Requires-Dist: calm-data-generator[stream]; extra == "full"
+Requires-Dist: calm-data-generator[gears,privacy,stream]; extra == "full"
 Dynamic: license-file
 
 # CALM-Data-Generator
@@ -75,7 +80,7 @@ Dynamic: license-file
 **CALM-Data-Generator** is a comprehensive Python library for synthetic data generation with advanced features for:
 - **Clinical/Medical Data** - Generate realistic patient demographics, genes, proteins
 - **Tabular Data Synthesis** - CTGAN, TVAE, CART, and more
-- **Time Series** - TimeGAN, DGAN
+- **Time Series** - TimeGAN, TimeVAE, FourierFlows
 - **Single-Cell** - scVI, GEARS (Perturbation Prediction)
 - **Latent Differentiation** - Force class separability in TVAE & scVI
 - **Flexible Clipping** - Strict or permissive data range enforcement
@@ -290,7 +295,7 @@ synthetic_df = preset.generate(data=adata_df, n_samples=500)
 ```
 
 ## Key Libraries & Ecosystem
- 
+
  | Library | Role | Usage in Calm-Data-Generator |
  | :--- | :--- | :--- |
  | **Synthcity** | Deep Learning Engine | Powers `CTGAN`, `TVAE`, `DDPM`, `TimeGAN`. Handling privacy & fidelity. |
@@ -334,47 +339,74 @@ Minimalist view of the system's core components and data flow.
 ---
 
 ## Installation
- 
+
  > [!WARNING]
- > The installation might be **heavy (~2-3 GB)** and take a few minutes depending on your internet connection. We strongly recommend using a fresh virtual environment.
- 
+ > The installation is **heavy (~2-3 GB)** and may take several minutes. Use a fresh virtual environment.
+
  ### Versioning Strategy
- 
+
  - **GitHub (Recommended for latest features)**: The `main` branch contains the most up-to-date version with the latest bug fixes and features.
  - **PyPI (Stable)**: Releases on PyPI are stable versions updated less frequently for major changes.
- 
- ### Standard Installation (PyPI - Stable)
- The library is available on PyPI. For the most stable experience, we recommend using a virtual environment:
+
+### Step 1 — Install PyTorch for your hardware
+
+PyTorch must be installed **before** the library so pip resolves the correct wheel (CPU, CUDA, or ROCm).
 
 ```bash
-# 1. Create and activate a virtual environment
-python3 -m venv venv
-source venv/bin/activate
+# CPU — Mac Intel, CI environments, no GPU
+pip install "torch>=2.2.0" "torchvision>=0.17.0"
 
-# 2. Upgrade pip, setuptools and wheel (Crucial for successful installation)
-pip install --upgrade pip setuptools wheel
+# CUDA 12.4 — Linux / Windows with NVIDIA GPU
+pip install "torch>=2.2.0" "torchvision>=0.17.0" --index-url https://download.pytorch.org/whl/cu124
 
-# 3. Install the core library (optimized for speed)
+# ROCm 6.1 — Linux with AMD GPU
+pip install "torch>=2.2.0" "torchvision>=0.17.0" --index-url https://download.pytorch.org/whl/rocm6.1
+
+# Mac Apple Silicon (M1/M2/M3) — MPS is auto-detected, no special wheel needed
+pip install "torch>=2.2.0" "torchvision>=0.17.0"
+```
+
+> Replace `cu124` with your installed CUDA version (e.g. `cu118`, `cu121`). Find yours with `nvidia-smi`.
+
+### Step 2 — Install the library
+
+```bash
+pip install --upgrade pip setuptools wheel
 pip install calm-data-generator
 ```
 
-### Installation Extras
-Depending on your needs, you can install additional capabilities:
+### Optional extras
+
 ```bash
-# For Stream Generator (River)
+# River streaming support
 pip install "calm-data-generator[stream]"
 
+# GEARS perturbation prediction (requires PyG wheels — see below)
+pip install "calm-data-generator[gears]"
 
+# Singling-Out privacy risk metric (anonymeter)
+pip install "calm-data-generator[privacy]"
 
-# Full suite
+# Full suite (stream + gears + privacy)
 pip install "calm-data-generator[full]"
 ```
 
-> [!NOTE]
-> **Performance & Stability Note**: We have optimized the dependency tree since version 1.0.0 by pinning specific versions such as `pydantic`, `xgboost`, and `cloudpickle`. This improves compatibility and reduces installation issues.
+> **GEARS / PyTorch Geometric** requires platform-specific wheels from the PyG index.
+> Install them **before** `calm-data-generator[gears]`:
+> ```bash
+> # Get your torch version first
+> python -c "import torch; print(torch.__version__)"
+>
+> # CPU example (replace torch-2.2.0 and +cpu with your version and platform)
+> pip install torch-geometric --find-links https://data.pyg.org/whl/torch-2.2.0+cpu.html
+>
+> # CUDA 12.4 example
+> pip install torch-geometric --find-links https://data.pyg.org/whl/torch-2.2.0+cu124.html
+>
+> pip install "calm-data-generator[gears]"
+> ```
 
 **From source (GitHub - Latest Updates):**
-Use this method to get the latest bug fixes and features not yet released on PyPI.
 
 ```bash
 # Option A: Install directly from GitHub
@@ -410,11 +442,19 @@ pip install calm-data-generator
 2. Install "Desktop development with C++"
 3. Then retry installation
 
-**PyTorch CPU-only (no GPU):**
-```bash
-pip install torch --index-url https://download.pytorch.org/whl/cpu
-pip install calm-data-generator
+**Windows — Long Path error during installation:**
+
+Some packages (e.g. `orbax-checkpoint`) contain very deep directory structures that exceed the Windows default 260-character path limit. If you see an error like:
 ```
+OSError: [Errno 2] No such file or directory: 'C:\...\very\long\path'
+HINT: This error might have occurred since this system does not have Windows Long Path support enabled.
+```
+Enable long paths via PowerShell (run as Administrator):
+```powershell
+New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
+  -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
+```
+Then restart your machine and retry installation. Alternatively, install your virtual environment in a short root path (e.g. `C:\venv\`) to reduce total path length.
 
 **Dependency conflicts:** Use a clean virtual environment:
 ```bash
@@ -457,36 +497,43 @@ synthetic = gen.generate(
 print(f"Generated {len(synthetic)} samples")
 ```
 
+### Simpler API: `fit()` / `sample()`
+
+For the common case — train once, sample as many times as you want — use the sklearn-style wrapper:
+
+```python
+gen = RealGenerator(auto_report=False).fit(data, method="cart", target_col="label")
+
+small_batch = gen.sample(100)
+large_batch = gen.sample(10_000)   # reuses the fitted model, no retraining
+
+# Chaining works too:
+synthetic = RealGenerator().fit(data, method="ctgan").sample(1000)
+```
+
 ### GPU Acceleration
 
-**Methods with GPU support:**
+GPU is **auto-detected** at runtime in the order CUDA → MPS → CPU. No parameter is needed for most methods.
+
+| Method | Device support | Notes |
+| ------ | -------------- | ----- |
+| `scvi`, `scanvi` | CUDA · MPS · CPU | Auto-detected via Lightning accelerator |
+| `gears` | CUDA · MPS · CPU | Auto-detected via PyTorch device |
+| `ctgan`, `tvae`, `rtvae`, `ddpm`, `timegan`, `timevae`, `fflows`, `dpgan`, `pategan`, `great` | CUDA · CPU | Auto-detected internally by Synthcity |
+| `cart`, `rf`, `lgbm`, `xgboost`, `gmm`, `copula`, `windowed_copula`, `kde`, `smote`, `adasyn`, `hmm`, `bn` | CPU only | Statistical / tree-based, no GPU path |
 
-| Method | GPU Support | Parameter |
-|--------|-------------|-----------|
-| `ctgan`, `tvae` | Yes — CUDA/MPS | `enable_gpu=True` |
-| `diffusion` | Yes — PyTorch | Auto-detected |
-| `ddpm` | Yes — PyTorch + Synthcity | Auto-detected |
-| `timegan` | Yes — PyTorch + Synthcity | Auto-detected |
-| `timevae` | Yes — PyTorch + Synthcity | Auto-detected |
-| `fflows` | Yes — PyTorch + Synthcity | Auto-detected |
+**Mac Apple Silicon (M1/M2/M3):** MPS is used automatically for `scvi`, `scanvi`, and `gears` when `torch.backends.mps.is_available()` returns `True`. Install the standard CPU wheel — no special MPS wheel is required.
 
-| `smote`, `adasyn`, `cart`, `rf`, `lgbm`, `gmm`, `copula` | No — CPU only | - |
+To override the device explicitly:
 
 ```python
-synthetic = gen.generate(
-    data=data,
-    n_samples=1000,
-    method='ctgan',
-    epochs=300, 
-    enable_gpu=True,
-   
-)
-```
+# Force CPU for scVI/scANVI
+gen.generate(data=data, n_samples=1000, method='scvi', accelerator='cpu')
 
-> **Note:** Requires PyTorch with CUDA support:
-> ```bash
-> pip install torch --index-url https://download.pytorch.org/whl/cu118
-> ```
+# Force a specific device for GEARS
+gen.generate(data=data, n_samples=1000, method='gears', device='cuda')
+gen.generate(data=data, n_samples=1000, method='gears', device='mps')
+```
 
 ### Generate Clinical Data
 
@@ -579,7 +626,7 @@ synthetic = gen.generate(
     target_col='cell_type',
     epochs=100,
     n_latent=10,
-    
+
 )
 
 
@@ -646,6 +693,14 @@ reporter.generate_report(
 # Results JSON (including compared_data_files) saved to ./quality_report/report_results.json
 ```
 
+For a fast, in-memory check without writing any file (quality scores, KS/MMD/Wasserstein
+statistical tests, and TSTR if you pass a `target_column`), use `evaluate()` instead:
+
+```python
+result = reporter.evaluate(real_data, synthetic, target_column="target")
+print(result["quality_scores"], result["statistical_metrics"])
+```
+
 For **single-cell data**, enable [scGFT](https://github.com/nasim23ea/scgft-evaluator) evaluation (Graph Fourier Transform-based manifold preservation metrics):
 
 ```python
@@ -682,29 +737,36 @@ reporter.generate_comprehensive_report(
 
 ## Synthesis Methods
 
-| Method | Type | Description | Requirements / Notes |
-|--------|------|-------------|----------------------|
-| `cart` | ML | CART-based iterative synthesis (fast) | Base installation |
-| `rf` | ML | Random Forest synthesis | Base installation |
-| `lgbm` | ML | LightGBM-based synthesis | Base installation (Requires `lightgbm`) |
-| `ctgan` | DL | Conditional GAN for tabular data | Requires `synthcity` |
-| `tvae` | DL | Variational Autoencoder | Requires `synthcity` |
-| `diffusion` | DL | Tabular Diffusion (custom, fast) | Base installation (PyTorch) |
-| `ddpm` | DL | Synthcity TabDDPM (advanced) | Requires `synthcity` |
-| `timegan` | Time Series | TimeGAN for sequential data | Requires `synthcity` |
-| `timevae` | Time Series | TimeVAE for sequential data | Requires `synthcity` |
-| `fflows` | Time Series | FourierFlows — normalizing flows for temporal data, stable for periodic series | Requires `synthcity` |
-| `bn` | DL / Probabilistic | Bayesian Network — models causal dependencies between features | Requires `synthcity` |
-| `smote` | Augmentation | SMOTE oversampling | Base installation |
-| `adasyn` | Augmentation | ADASYN adaptive sampling | Base installation |
-
-
-| `copula` | Copula | Copula-based synthesis | Base installation |
-| `gmm` | Statistical | Gaussian Mixture Models | Base installation |
-| `scvi` | Single-Cell | scVI (Variational Inference) for RNA-seq | Requires `scvi-tools` |
-| `conditional_drift` | Drift-Aware | Temporal conditioning via TVAE/CTGAN | Requires `synthcity` |
-| `windowed_copula` | Drift-Aware | Gaussian Copula interpolated across time windows | Base installation |
-| `hmm` | Drift-Aware | Hidden Markov Model — drift via regime transitions | Requires `hmmlearn` |
+| Method | Type | Description | Requirements |
+| ------ | ---- | ----------- | ------------ |
+| `cart` | ML | CART-based iterative synthesis (fast) | Base |
+| `rf` | ML | Random Forest synthesis | Base |
+| `lgbm` | ML | LightGBM-based synthesis | Base |
+| `xgboost` | ML | XGBoost-based synthesis | Base |
+| `gmm` | Statistical | Gaussian Mixture Models | Base |
+| `kde` | Statistical | Kernel Density Estimation (numeric only) | Base |
+| `copula` | Statistical | Gaussian Copula synthesis | Base |
+| `windowed_copula` | Drift-Aware | Gaussian Copula interpolated across time windows | Base |
+| `hmm` | Drift-Aware | Hidden Markov Model — drift via regime transitions | Base |
+| `smote` | Augmentation | SMOTE oversampling | Base |
+| `adasyn` | Augmentation | ADASYN adaptive sampling | Base |
+| `resample` | Augmentation | Weighted resampling from original data | Base |
+| `ctgan` | DL | Conditional GAN for tabular data | `synthcity` |
+| `tvae` | DL | Variational Autoencoder | `synthcity` |
+| `rtvae` | DL | Robust TVAE | `synthcity` |
+| `great` | DL | GReaT — LLM-based tabular generation | `synthcity` |
+| `bn` | Probabilistic | Bayesian Network — causal dependencies | `synthcity` |
+| `diffusion` | DL | Tabular Diffusion (custom, lightweight) | Base (PyTorch) |
+| `ddpm` | DL | TabDDPM — advanced diffusion | `synthcity` |
+| `dpgan` | DL + Privacy | Differentially private GAN | `synthcity` |
+| `pategan` | DL + Privacy | PATE-GAN — teacher-ensemble privacy | `synthcity` |
+| `timegan` | Time Series | TimeGAN for sequential data | `synthcity` |
+| `timevae` | Time Series | TimeVAE for sequential data | `synthcity` |
+| `fflows` | Time Series | FourierFlows — normalizing flows, stable for periodic series | `synthcity` |
+| `conditional_drift` | Drift-Aware | Temporal stage conditioning via TVAE/CTGAN | `synthcity` |
+| `scvi` | Single-Cell | scVI (VAE) for RNA-seq expression data | `scvi-tools` |
+| `scanvi` | Single-Cell | scANVI — semi-supervised, label-aware scVI | `scvi-tools` |
+| `gears` | Single-Cell | GEARS — perturbation prediction via GNN | `[gears]` extra |
 
 
 ---
@@ -754,6 +816,20 @@ Explore the full documentation in the `calm_data_generator/docs/` directory:
 
 ---
 
+## Authors
+
+**Originally created by** [Alejandro Belda Fernandez](mailto:a.beldafernandez@um.es) (Universidad de Murcia), who led the development of the library through version 2.3.0.
+
+**Currently maintained by** [Antonio Guillen Teruel](mailto:a.guillenteruel@um.es) (Universidad de Murcia), from version 2.3.0 onwards.
+
+The single-cell evaluation integrated via `use_scgft` is powered by [scGFT Evaluator](https://github.com/nasim23ea/scgft-evaluator), authored by [Nasim El Arifi Ahmed](mailto:nasim.e.a@um.es) (Universidad de Murcia).
+
+See [AUTHORS](AUTHORS) for the full attribution and [CITATION.cff](CITATION.cff) if you need to cite this software in academic work.
+
+**Contact:** [calmdatagenerator@outlook.es](mailto:calmdatagenerator@outlook.es) — for questions about the library. For bugs and feature requests, please open an [issue](https://github.com/AlejandroBeldaFernandez/Calm-Data-Generator/issues).
+
+---
+
 ## License
 
 MIT License - see [LICENSE](LICENSE) file