synomicsbench 1.0.0__tar.gz

synomicsbench-1.0.0/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(ssh *)"
+    ]
+  }
+}

synomicsbench-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: Python CI
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+permissions:
+  contents: write
+
+env:
+  RPY2_CFFI_MODE: ABI
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          uv sync --all-extras --dev
+
+      - name: Lint with ruff
+        run: |
+          uvx ruff check src/synomicsbench
+
+
+
+      - name: Run tests
+        run: |
+          # Chạy các test sanity trước cho nhanh, sau đó là integration tests
+          uv run pytest test/ -v

synomicsbench-1.0.0/.github/workflows/deploy-docs.yml

@@ -0,0 +1,39 @@
+name: Deploy MkDocs
+
+on:
+  push:
+    branches:
+      - main
+      - master
+
+permissions:
+  contents: write
+
+env:
+  RPY2_CFFI_MODE: ABI
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install documentation dependencies
+        run: |
+          uv pip install --system mkdocs-material mkdocstrings[python] pandas numpy scikit-learn
+          uv pip install --system -e . --no-deps
+
+      - name: Deploy to GitHub Pages
+        run: |
+          python -m mkdocs gh-deploy --force

synomicsbench-1.0.0/.gitignore

@@ -0,0 +1,47 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+
+# Virtual environments
+venv/
+.venv/
+env/
+
+# IDE / editor
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Environment variables
+.env
+.env.*
+
+# Pytest / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Mypy
+.mypy_cache/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# OS files
+.DS_Store
+Thumbs.db
+synthetic_datasets.zip
+CLAUDE.md

synomicsbench-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The-Chuong TRINH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

synomicsbench-1.0.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: synomicsbench
+Version: 1.0.0
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: anonymeter>=1.0.0
+Requires-Dist: baycomp>=1.0.3
+Requires-Dist: codecarbon>=3.2.5
+Requires-Dist: copulas>=0.12.0
+Requires-Dist: ctgan>=0.10.2
+Requires-Dist: deptry>=0.25.1
+Requires-Dist: gseapy>=1.1.12
+Requires-Dist: ipykernel>=7.2.0
+Requires-Dist: joblib>=1.5.3
+Requires-Dist: jupyter>=1.1.1
+Requires-Dist: lab>=8.9
+Requires-Dist: lifelines>=0.30.3
+Requires-Dist: lightgbm>=4.6.0
+Requires-Dist: matplotlib>=3.10.8
+Requires-Dist: memory-profiler>=0.61.0
+Requires-Dist: miceforest>=6.0.5
+Requires-Dist: missingno>=0.5.2
+Requires-Dist: mpl-tools>=0.4.1
+Requires-Dist: mygene>=3.2.2
+Requires-Dist: numba>=0.64.0
+Requires-Dist: numpy>=1.26.4
+Requires-Dist: pandas>=2.3.3
+Requires-Dist: polar>=0.0.127
+Requires-Dist: polars>=1.39.2
+Requires-Dist: pytest>=9.0.3
+Requires-Dist: rpy2==3.6.5
+Requires-Dist: scienceplots>=2.2.1
+Requires-Dist: scikit-bio>=0.7.0
+Requires-Dist: scikit-learn>=1.8.0
+Requires-Dist: scipy>=1.17.1
+Requires-Dist: sdmetrics>=0.18.0
+Requires-Dist: sdv>=1.18.0
+Requires-Dist: seaborn>=0.13.2
+Requires-Dist: statsmodels>=0.14.6
+Requires-Dist: torch>=2.10.0
+Requires-Dist: tqdm>=4.67.3
+Description-Content-Type: text/markdown
+
+# SynOmicsBench
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19660703.svg)](https://zenodo.org/records/19660703)
+[![CI](https://github.com/trinhthechuong/SynOmicsBench/actions/workflows/ci.yml/badge.svg)](https://github.com/trinhthechuong/SynOmicsBench/actions/workflows/ci.yml)
+[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue.svg)](https://trinhthechuong.github.io/SynOmicsBench/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-red.svg)](https://www.python.org/downloads/release/python-3120/)
+
+
+**SynOmicsBench** is a unified benchmarking framework for synthetic data generation (SDG) for clinical transcriptomic cancer cohorts.
+
+Achieving a trade-off between **biological utility** and **patient privacy** is critical for secure data sharing when applying transcriptomic clinical datasets to artificial intelligence in precision oncology. Here, we present the **SynOmicsBench** framework. SynOmicsBench combines standardized preprocessing with multidimensional evaluation, prioritizing downstream biological validation alongside statistical fidelity and attack-based privacy assessment. This work provides a reproducible decision-support tool for method selection and promotes biologically informed, privacy-aware adoption of synthetic data in precision oncology.
+
+---
+
+## 🔬 Framework Overview
+
+![Framework Overview](docs/assets/figures/Figure_1_Graphical_abstract.png)
+
+SynOmicsBench compares synthetic data generation methods using a standardized pipeline that combines:
+
+- **Standardized Preprocessing**: Automated data filtering, harmonization, and integration.
+- **Multidimensional Evaluation**: Assessing Statistical Fidelity, Downstream Biological Utility, and Privacy Risk.
+- **State-of-the-Art SDG Methods**: Native support for **CTGAN, TVAE, Gaussian Copula, Synthpop, and Avatars (K5/K10)**. 
+
+---
+
+## 🛠 Installation
+
+SynOmicsBench can be installed in three different ways depending on your environment. **Python 3.12+** is required.
+
+### Option 1: From PyPI (Recommended)
+
+```bash
+pip install synomicsbench
+```
+
+### Option 2: From Source (GitHub)
+We recommend using [`uv`](https://docs.astral.sh/uv/) for fast, reliable dependency management. This method uses the provided uv.lock file to ensure reproducible installations.
+```bash
+git clone https://github.com/trinhthechuong/SynOmicsBench.git
+cd SynOmicsBench
+
+# With uv (Fastest)
+uv sync
+source .venv/bin/activate
+
+# Or with traditional pip
+pip install -e .
+```
+
+### Option 3: Pre-built Container (Apptainer/Singularity)
+For HPC environments or reproducible workflows, you can pull our fully prepared Apptainer container which contains all dependencies (including heavy ML frameworks and R):
+
+```bash
+# Pull the latest SynOmicsBench container
+apptainer pull synomicsbench.sif oras://ghcr.io/trinhthechuong/synomicsbench:latest
+
+# Verify the container is working and the package is ready
+apptainer exec synomicsbench.sif python -c "import synomicsbench; print('OK: SynOmicsBench is ready!')"
+```
+*(To use the container for your scripts, simply mount your directories via `--bind` and run your Python scripts using `apptainer exec`)*
+
+---
+
+## 🚀 Quick Start
+
+Here is a brief example of how to generate synthetic data with Gaussian Copula and evaluate its statistical fidelity:
+
+```python
+import pandas as pd
+from synomicsbench.synthesizer.GaussianCopulasynthesizer import GaussianCopulasynthesizer
+from synomicsbench.processing.metadata import MetaData
+from synomicsbench.metrics.fidelity.UnivariateSimilarity import UnivariateSimilarity 
+
+# 1. Load Data & Prepare Metadata
+original_data = pd.read_csv("your_clinical_transcriptomic_data.csv")
+ordinal_features = ["Mstage", "Tx_Start_ECOG", "numPriorTherapies"]
+metadata = MetaData.get_metadata(data=original_data, ordinal_features=ordinal_features)
+
+# 2. Generate Synthetic Data
+synth = GaussianCopulasynthesizer(output_path="./results", metadata=metadata)
+synthetic_data = synth.generate(
+    data=original_data, 
+    n_samples=original_data.shape[0]
+)
+
+# 3. Evaluate Fidelity
+evaluator = UnivariateSimilarity(output_dir="./evaluation_results")
+score = evaluator.get_univariate_score(
+    original_data=original_data, 
+    synthetic_data=synthetic_data, 
+    metadata=metadata, 
+    save=True
+)
+print(f"Overall Fidelity Score: {score:.4f}")
+```
+
+---
+
+## 📚 Documentation
+
+For complete API references, tutorials, and full benchmarking results, check out the **[SynOmicsBench Official Documentation](https://trinhthechuong.github.io/SynOmicsBench/)**:
+
+- [**Getting Started**](https://trinhthechuong.github.io/SynOmicsBench/getting-started/): Step-by-step setup guides.
+- [**Preprocessing Pipeline**](https://trinhthechuong.github.io/SynOmicsBench/preprocessing/): Harmonizing multimodal data.
+- [**SDG Methods**](https://trinhthechuong.github.io/SynOmicsBench/synthetic-data/): Deep dive into generation models.
+- [**Evaluation Framework**](https://trinhthechuong.github.io/SynOmicsBench/evaluation/): Understand our metrics for Privacy and Biological signal preservation.
+
+---
+
+## 📝 Citation
+
+If you use SynOmicsBench in your research, please cite:
+
+> Trinh, T. C., Woillard, J. B., Uguzzoni, G., & Battail, C. (2024). **A unified benchmark of synthetic data generation for clinical and transcriptomic cancer data.** *(Manuscript in preparation)*
+
+## 📄 License
+This project is open-sourced under the MIT License.

synomicsbench-1.0.0/README.md

@@ -0,0 +1,119 @@
+# SynOmicsBench
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19660703.svg)](https://zenodo.org/records/19660703)
+[![CI](https://github.com/trinhthechuong/SynOmicsBench/actions/workflows/ci.yml/badge.svg)](https://github.com/trinhthechuong/SynOmicsBench/actions/workflows/ci.yml)
+[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue.svg)](https://trinhthechuong.github.io/SynOmicsBench/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-red.svg)](https://www.python.org/downloads/release/python-3120/)
+
+
+**SynOmicsBench** is a unified benchmarking framework for synthetic data generation (SDG) for clinical transcriptomic cancer cohorts.
+
+Achieving a trade-off between **biological utility** and **patient privacy** is critical for secure data sharing when applying transcriptomic clinical datasets to artificial intelligence in precision oncology. Here, we present the **SynOmicsBench** framework. SynOmicsBench combines standardized preprocessing with multidimensional evaluation, prioritizing downstream biological validation alongside statistical fidelity and attack-based privacy assessment. This work provides a reproducible decision-support tool for method selection and promotes biologically informed, privacy-aware adoption of synthetic data in precision oncology.
+
+---
+
+## 🔬 Framework Overview
+
+![Framework Overview](docs/assets/figures/Figure_1_Graphical_abstract.png)
+
+SynOmicsBench compares synthetic data generation methods using a standardized pipeline that combines:
+
+- **Standardized Preprocessing**: Automated data filtering, harmonization, and integration.
+- **Multidimensional Evaluation**: Assessing Statistical Fidelity, Downstream Biological Utility, and Privacy Risk.
+- **State-of-the-Art SDG Methods**: Native support for **CTGAN, TVAE, Gaussian Copula, Synthpop, and Avatars (K5/K10)**. 
+
+---
+
+## 🛠 Installation
+
+SynOmicsBench can be installed in three different ways depending on your environment. **Python 3.12+** is required.
+
+### Option 1: From PyPI (Recommended)
+
+```bash
+pip install synomicsbench
+```
+
+### Option 2: From Source (GitHub)
+We recommend using [`uv`](https://docs.astral.sh/uv/) for fast, reliable dependency management. This method uses the provided uv.lock file to ensure reproducible installations.
+```bash
+git clone https://github.com/trinhthechuong/SynOmicsBench.git
+cd SynOmicsBench
+
+# With uv (Fastest)
+uv sync
+source .venv/bin/activate
+
+# Or with traditional pip
+pip install -e .
+```
+
+### Option 3: Pre-built Container (Apptainer/Singularity)
+For HPC environments or reproducible workflows, you can pull our fully prepared Apptainer container which contains all dependencies (including heavy ML frameworks and R):
+
+```bash
+# Pull the latest SynOmicsBench container
+apptainer pull synomicsbench.sif oras://ghcr.io/trinhthechuong/synomicsbench:latest
+
+# Verify the container is working and the package is ready
+apptainer exec synomicsbench.sif python -c "import synomicsbench; print('OK: SynOmicsBench is ready!')"
+```
+*(To use the container for your scripts, simply mount your directories via `--bind` and run your Python scripts using `apptainer exec`)*
+
+---
+
+## 🚀 Quick Start
+
+Here is a brief example of how to generate synthetic data with Gaussian Copula and evaluate its statistical fidelity:
+
+```python
+import pandas as pd
+from synomicsbench.synthesizer.GaussianCopulasynthesizer import GaussianCopulasynthesizer
+from synomicsbench.processing.metadata import MetaData
+from synomicsbench.metrics.fidelity.UnivariateSimilarity import UnivariateSimilarity 
+
+# 1. Load Data & Prepare Metadata
+original_data = pd.read_csv("your_clinical_transcriptomic_data.csv")
+ordinal_features = ["Mstage", "Tx_Start_ECOG", "numPriorTherapies"]
+metadata = MetaData.get_metadata(data=original_data, ordinal_features=ordinal_features)
+
+# 2. Generate Synthetic Data
+synth = GaussianCopulasynthesizer(output_path="./results", metadata=metadata)
+synthetic_data = synth.generate(
+    data=original_data, 
+    n_samples=original_data.shape[0]
+)
+
+# 3. Evaluate Fidelity
+evaluator = UnivariateSimilarity(output_dir="./evaluation_results")
+score = evaluator.get_univariate_score(
+    original_data=original_data, 
+    synthetic_data=synthetic_data, 
+    metadata=metadata, 
+    save=True
+)
+print(f"Overall Fidelity Score: {score:.4f}")
+```
+
+---
+
+## 📚 Documentation
+
+For complete API references, tutorials, and full benchmarking results, check out the **[SynOmicsBench Official Documentation](https://trinhthechuong.github.io/SynOmicsBench/)**:
+
+- [**Getting Started**](https://trinhthechuong.github.io/SynOmicsBench/getting-started/): Step-by-step setup guides.
+- [**Preprocessing Pipeline**](https://trinhthechuong.github.io/SynOmicsBench/preprocessing/): Harmonizing multimodal data.
+- [**SDG Methods**](https://trinhthechuong.github.io/SynOmicsBench/synthetic-data/): Deep dive into generation models.
+- [**Evaluation Framework**](https://trinhthechuong.github.io/SynOmicsBench/evaluation/): Understand our metrics for Privacy and Biological signal preservation.
+
+---
+
+## 📝 Citation
+
+If you use SynOmicsBench in your research, please cite:
+
+> Trinh, T. C., Woillard, J. B., Uguzzoni, G., & Battail, C. (2024). **A unified benchmark of synthetic data generation for clinical and transcriptomic cancer data.** *(Manuscript in preparation)*
+
+## 📄 License
+This project is open-sourced under the MIT License.

synomicsbench-1.0.0/mkdocs.yml

@@ -0,0 +1,84 @@
+site_name: SynOmicsBench Documentation
+site_description: Synthetic data benchmarking for omics data
+site_author: SynOmicsBench Team
+site_url: https://trinhthechuong.github.io/SynOmicsBench/
+repo_url: https://github.com/trinhthechuong/SynOmicsBench
+repo_name: SynOmicsBench
+
+# Theme configuration
+theme:
+  name: material
+  logo: assets/logo.png
+  favicon: assets/logo.png
+  palette:
+    primary: custom
+  features:
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.indexes
+    - navigation.top
+    - search.highlight
+    - search.suggest
+    - content.code.copy
+
+# Markdown extensions
+markdown_extensions:
+  - admonition
+  - attr_list
+  - md_in_html
+  - pymdownx.highlight:
+      use_pygments: true
+      pygments_style: default
+  - pymdownx.inlinehilite
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.details
+  - pymdownx.arithmatex:
+      generic: true
+  - toc:
+      permalink: true
+
+# Navigation Structure (EXACTLY 6 top-level tabs)
+nav:
+  - Home: index.md
+  - Getting Started: getting-started/index.md
+  - Preprocessing Data: preprocessing/index.md
+  - Generate Synthetic Data: synthetic-data/index.md
+  - Evaluation:
+      - evaluation/index.md
+      - Statistical Fidelity: evaluation/statistical-fidelity.md
+      - Biological Utility:
+          - DGE: evaluation/biological-utility/dge.md
+          - GSEA: evaluation/biological-utility/gsea.md
+          - ssGSEA: evaluation/biological-utility/ssgsea.md
+          - Cell Type Deconvolution: evaluation/biological-utility/cell-deconvolution.md
+          - Survival Analysis: evaluation/biological-utility/survival-analysis.md
+      - Biological Results: evaluation/biological-results.md
+      - Privacy: evaluation/privacy.md
+  - API: api/index.md
+
+# Documentation Directory
+docs_dir: docs
+
+# Plugins
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [src]
+          options:
+            docstring_style: google
+            show_source: true
+            show_root_heading: true
+            show_root_full_path: false
+            heading_level: 2
+
+# Custom CSS and JavaScript
+extra_css:
+  - stylesheets/extra.css
+
+extra_javascript:
+  - javascripts/mathjax.js
+  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js

synomicsbench-1.0.0/pyproject.toml

@@ -0,0 +1,66 @@
+[project]
+name = "synomicsbench"
+version = "1.0.0"
+# description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "anonymeter>=1.0.0",
+    "baycomp>=1.0.3",
+    "codecarbon>=3.2.5",
+    "copulas>=0.12.0",
+    "ctgan>=0.10.2",
+    "deptry>=0.25.1",
+    "gseapy>=1.1.12",
+    "ipykernel>=7.2.0",
+    "joblib>=1.5.3",
+    "jupyter>=1.1.1",
+    "lab>=8.9",
+    "lifelines>=0.30.3",
+    "lightgbm>=4.6.0",
+    "matplotlib>=3.10.8",
+    "memory-profiler>=0.61.0",
+    "miceforest>=6.0.5",
+    "missingno>=0.5.2",
+    "mpl-tools>=0.4.1",
+    "mygene>=3.2.2",
+    "numba>=0.64.0",
+    "numpy>=1.26.4",
+    "pandas>=2.3.3",
+    "polar>=0.0.127",
+    "polars>=1.39.2",
+    "pytest>=9.0.3",
+    "rpy2==3.6.5",
+    "scienceplots>=2.2.1",
+    "scikit-bio>=0.7.0",
+    "scikit-learn>=1.8.0",
+    "scipy>=1.17.1",
+    "sdmetrics>=0.18.0",
+    "sdv>=1.18.0",
+    "seaborn>=0.13.2",
+    "statsmodels>=0.14.6",
+    "torch>=2.10.0",
+    "tqdm>=4.67.3",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/synomicsbench"]
+
+[tool.hatch.build]
+exclude = [
+  "test/test_data/*",
+  "Manuscripts/",
+  "docs/",
+  "site/",
+  "*.sif",
+  "*.ipynb",
+  "*.png",
+  "*.pdf",
+  "*.csv"
+]
+
+

synomicsbench-1.0.0/src/synomicsbench/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

synomicsbench-1.0.0/src/synomicsbench/metrics/__init__.py

@@ -0,0 +1,13 @@
+"""
+Metrics module for evaluating synthetic data quality.
+
+This module provides comprehensive evaluation metrics across three dimensions:
+- Statistical Fidelity: Univariate and bivariate similarity measures
+- Biological Utility: Downstream bioinformatics task performance
+- Privacy Risk: Attack-based privacy assessment
+
+Submodules:
+    - fidelity: Statistical similarity metrics
+    - narrow_utility: Biological signal preservation metrics
+    - privacy: Privacy attack risk assessment
+"""