sampledisco 0.2.0__tar.gz → 0.4.0__tar.gz

{sampledisco-0.2.0/src/sampledisco.egg-info → sampledisco-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sampledisco
-Version: 0.2.0
+Version: 0.4.0
 Summary: Cross-omics, cross-condition sample embedding for single-cell data (RNA + ATAC)
 Author: Hongkai Ji
 Author-email: Harry Jiang <hjiang55@jh.edu>
@@ -28,7 +28,7 @@ Requires-Dist: patsy>=0.5
 Requires-Dist: scanpy>=1.11
 Requires-Dist: anndata>=0.10
 Requires-Dist: muon>=0.1
-Requires-Dist: harmonypy<0.0.10,>=0.0.9
+Requires-Dist: harmonypy==0.2.0
 Requires-Dist: python-igraph>=0.10
 Requires-Dist: leidenalg>=0.9
 Requires-Dist: networkx>=3.0
@@ -51,7 +51,7 @@ A cross-omics, cross-condition **sample embedding** tool for single-cell data.
 
 SampleDisco takes a cell-level embedding (from any standard scRNA / scATAC / multi-omics integration method) and lifts it to a **sample-level embedding** that captures both cell-type composition and the per-cell-type state of each sample. Every downstream analysis — sample-to-sample distance, clustering, trajectory inference, phenotype association — then runs on that single shared sample embedding, regardless of modality.
 
-Paper draft: [`/users/hjiang/GenoDistance/SampleDisco_Draft-11.pdf`](../SampleDisco_Draft-11.pdf)
+Documentation and tutorial: <https://j041120h.github.io/SampleDisco_tutorial/>
 
 ---
 
@@ -61,15 +61,15 @@ For each modality (RNA, ATAC, or integrated multi-omics) the pipeline produces t
 
 | Key | Role | Source |
 |---|---|---|
-| **`Z_clust`** | sample-removed embedding — used for clustering and composition blocks | Harmony (single-omics) / Harmony post-pass on scGLUE (multi-omics) |
-| **`Z_cmd`**  | sample-preserved embedding — used for the counterfactual displacement (CMD) block | second Harmony pass (single-omics) / scGLUE primary output (multi-omics) |
+| **`Z_comp`** | sample-removed embedding — used for cell typing and the composition blocks | Harmony (single-omics) / Harmony post-pass on scGLUE (multi-omics) |
+| **`Z_rmd`**  | sample-preserved embedding — used for the reference-relative mean displacement (RMD) block | second Harmony pass (single-omics) / scGLUE primary output (multi-omics) |
 
 It then assembles **four blocks** per sample (or per sample × modality for multi-omics):
 
 1. **A1** — one-hot cell-type composition
 2. **A2** — soft k-means composition at K_med (≈120)
 3. **A3** — soft k-means composition at K_fine (≈300)
-4. **CMD** — leave-one-out cell-type-resolved displacement on `Z_cmd`
+4. **RMD** — leave-one-out cell-type-resolved displacement on `Z_rmd`
 
 The four blocks are inverse-variance weighted, Frobenius-stacked, PCA-reduced to 10 dimensions, and Harmony-corrected at sample level. The result is stored as `adata.uns['X_DR_sample']` and feeds every downstream module.
 
@@ -79,46 +79,50 @@ The four blocks are inverse-variance weighted, Frobenius-stacked, PCA-reduced to
 
 ```
 code/
-├── SampleDisc.py              # CLI entry point (simple or complex mode)
-├── config/                    # 9 YAML configs covering covid / blood / eye / heart / ENCODE / tabula / long_covid / unpaired / default
-├── wrapper/                   # Orchestration
-│   ├── wrapper.py             # Master wrapper; gates RNA + ATAC + multiomics + shared downstream
-│   ├── rna_wrapper.py
-│   ├── atac_wrapper.py
-│   └── multiomics_wrapper.py
-├── preparation/               # Preprocessing
-│   ├── rna_preprocess_{cpu,gpu}.py   # QC → HVG → PCA → dual Harmony → Z_clust + Z_cmd
-│   ├── atac_preprocess_{cpu,gpu}.py  # QC → TF-IDF → HVF → LSI → dual Harmony → Z_clust + Z_cmd
-│   ├── cell_type_{cpu,gpu}.py        # Leiden clustering on Z_clust (RNA or ATAC)
-│   ├── ATAC_cell_type{,_gpu}.py      # ATAC-specific cell typing variants
-│   ├── multi_omics_glue.py           # scGLUE integration (cross-modality VAE + guidance graph)
-│   ├── multi_omics_batch_correction.py # Harmony post-pass on X_glue → Z_clust
-│   ├── multi_omics_merge.py          # post-GLUE merge + per-modality preprocess/slimming
-│   └── multi_omics_cell_type_{cpu,gpu}.py  # RNA-Leiden + k-NN label transfer to ATAC
-├── sample_embedding/          # Core method
-│   ├── blocks.py              # composition, CMD, weighting, Frobenius stack, final PCA + Harmony
-│   ├── sample_embedding.py    # CPU pipeline
-│   └── sample_embedding_gpu.py # GPU pipeline (cuML + cupy)
-├── parameter_selection/
-│   └── autotune.py            # Bayesian GP sweep over CMD α; adaptive proxy ensemble
-├── sample_distance/           # Pairwise sample distances (DR / EMD / chi-square / JS)
-├── sample_clustering/         # Hierarchical (HRA / HRC / NN / UPGMA / consensus), K-means, proportion test, RAISIN
-├── sample_trajectory/         # CCA (supervised) and TSCAN (unsupervised) + GAM-based trajectory DGE
-├── sample_association/        # Per-PC variance explained vs sample-level covariates (permutation FDR)
-├── visualization/             # Embedding plots, dendrograms, DGE volcanos, modality-aware multi-omics scatters
-├── utils/                     # Shared helpers: seed, safe h5ad I/O, limma, TF-IDF, batch regress, Grouping
-├── gene_activity/             # ATAC peak → gene activity inference + RNA-ATAC validation
-└── claude/                    # Active one-off run scripts (rerun launchers, monitored SE, parameter sweeps)
+├── pyproject.toml                 # package metadata; `pip install -e .` installs the `sampledisco` command
+├── config/                        # 10 YAML configs for the paper's datasets: covid / blood (1M-scBloodNL) / eye / heart / ENCODE / healthy-aging PBMC / long_covid / unpaired (+ RNA-tuned) / default
+├── src/sampledisco/               # the package
+│   ├── cli.py                     # `sampledisco` command: `-m complex --config <yaml>`, `--init-config <path>`
+│   ├── config/config_demo.yaml    # demo config written by `sampledisco --init-config`
+│   ├── wrapper/                   # Orchestration
+│   │   ├── wrapper.py             # Master wrapper; gates RNA + ATAC + multiomics + shared downstream
+│   │   ├── rna_wrapper.py
+│   │   ├── atac_wrapper.py
+│   │   └── multiomics_wrapper.py
+│   ├── preparation/               # Preprocessing
+│   │   ├── rna_preprocess_{cpu,gpu}.py   # QC → HVG → PCA → dual Harmony → Z_comp + Z_rmd
+│   │   ├── atac_preprocess_{cpu,gpu}.py  # QC → TF-IDF → HVF → LSI → dual Harmony → Z_comp + Z_rmd
+│   │   ├── cell_type_{cpu,gpu}.py        # Leiden clustering on Z_comp (RNA or ATAC)
+│   │   ├── ATAC_cell_type{,_gpu}.py      # ATAC-specific cell typing variants
+│   │   ├── multi_omics_glue.py           # scGLUE integration (cross-modality VAE + guidance graph)
+│   │   ├── multi_omics_batch_correction.py # Harmony post-pass on X_glue → Z_comp
+│   │   ├── multi_omics_merge.py          # post-GLUE merge + per-modality preprocess/slimming
+│   │   └── multi_omics_cell_type_{cpu,gpu}.py  # RNA-Leiden + k-NN label transfer to ATAC
+│   ├── sample_embedding/          # Core method
+│   │   ├── blocks.py              # composition, RMD, weighting, Frobenius stack, final PCA + Harmony
+│   │   ├── sample_embedding.py    # CPU pipeline
+│   │   └── sample_embedding_gpu.py # GPU pipeline (cuML + cupy)
+│   ├── parameter_selection/
+│   │   └── autotune.py            # Bayesian GP sweep over RMD α; adaptive proxy ensemble
+│   ├── sample_distance/           # Pairwise sample distances (DR / EMD / chi-square / JS)
+│   ├── sample_clustering/         # Hierarchical (HRA / HRC / NN / UPGMA / consensus), K-means, proportion test, RAISIN
+│   ├── sample_trajectory/         # CCA (supervised) and TSCAN (unsupervised) + GAM-based trajectory DGE
+│   ├── sample_association/        # Per-PC variance explained vs sample-level covariates (permutation FDR)
+│   ├── visualization/             # Embedding plots, dendrograms, DGE volcanos, modality-aware multi-omics scatters
+│   ├── utils/                     # Shared helpers: seed, safe h5ad I/O, limma, TF-IDF, batch regress, Grouping
+│   └── gene_activity/             # ATAC peak → gene activity inference + RNA-ATAC validation
+├── Benchmark_covid/, Benchmark_multiomics/  # benchmark drivers used for the paper
+└── claude/                        # one-off run scripts (rerun launchers, monitored runs, parameter sweeps)
 ```
 
 ---
 
 ## Usage
 
-### Complex mode (recommended) — YAML-driven
+### Run — YAML-driven
 
 ```bash
-python SampleDisc.py -m complex --config config/config.yaml
+sampledisco -m complex --config config/config.yaml     # same as: python -m sampledisco.cli -m complex --config ...
 ```
 
 The YAML drives every flag and parameter for all three pipelines:
@@ -128,14 +132,16 @@ The YAML drives every flag and parameter for all three pipelines:
 - **Per-modality downstream gates** (Phase 2): `*_sample_distance_calculation`, `*_trajectory_analysis`, `*_trajectory_dge`, `*_sample_cluster`, `*_proportion_test`, `*_cluster_dge`, `*_visualize_data`, `*_dimension_association_analysis`
 - **Multi-omics-specific**: `multiomics_run_glue_*`, `multiomics_treat_sample_as_batch`, `multiomics_run_glue_twice_for_sample_removal`
 
-The 9 ready-to-use configs in `config/` are point-in-time snapshots for the datasets used in the paper; copy one and adjust paths / column names for your own data.
+The 10 ready-to-use configs in `config/` are point-in-time snapshots for the datasets used in the paper; copy one and adjust paths / column names for your own data.
 
-### Simple mode — one positional file, defaults everywhere
+### Starter config
 
 ```bash
-python SampleDisc.py -m simple -c <count_data.h5ad> -o <output_dir>
+sampledisco --init-config my_config.yaml
 ```
 
+writes the demo config (tuned for the Zenodo demo dataset) to `my_config.yaml`. The YAML is validated against every `wrapper()` parameter, so edit values rather than deleting keys.
+
 ---
 
 ## Inputs
@@ -165,7 +171,7 @@ For multi-omics, the pipeline takes two separate h5ads (RNA + ATAC) and integrat
 ├── atac/   (parallel structure)
 ├── multiomics/
 │   ├── integration/glue/{rna-pp,atac-pp,guidance.graphml.gz}
-│   ├── preprocess/adata_sample.h5ad           # post-GLUE merged adata with Z_clust + Z_cmd
+│   ├── preprocess/adata_sample.h5ad           # post-GLUE merged adata with Z_comp + Z_rmd
 │   ├── sample_embedding/sample_embedding.csv
 │   └── (same downstream subdirs as single-omics)
 └── sys_log/main_process_status.json           # which stages completed
@@ -182,7 +188,7 @@ detects and uses them at runtime. There is no separate "GPU build" of SampleDisc
 ### 1. Core install (CPU)
 
 ```bash
-pip install sampledisco          # once published — or `pip install -e .` from a clone
+pip install sampledisco          # or `pip install -e .` from a clone
 ```
 
 ### 2. System prerequisite — bedtools

{sampledisco-0.2.0 → sampledisco-0.4.0}/README.md

@@ -4,7 +4,7 @@ A cross-omics, cross-condition **sample embedding** tool for single-cell data.
 
 SampleDisco takes a cell-level embedding (from any standard scRNA / scATAC / multi-omics integration method) and lifts it to a **sample-level embedding** that captures both cell-type composition and the per-cell-type state of each sample. Every downstream analysis — sample-to-sample distance, clustering, trajectory inference, phenotype association — then runs on that single shared sample embedding, regardless of modality.
 
-Paper draft: [`/users/hjiang/GenoDistance/SampleDisco_Draft-11.pdf`](../SampleDisco_Draft-11.pdf)
+Documentation and tutorial: <https://j041120h.github.io/SampleDisco_tutorial/>
 
 ---
 
@@ -14,15 +14,15 @@ For each modality (RNA, ATAC, or integrated multi-omics) the pipeline produces t
 
 | Key | Role | Source |
 |---|---|---|
-| **`Z_clust`** | sample-removed embedding — used for clustering and composition blocks | Harmony (single-omics) / Harmony post-pass on scGLUE (multi-omics) |
-| **`Z_cmd`**  | sample-preserved embedding — used for the counterfactual displacement (CMD) block | second Harmony pass (single-omics) / scGLUE primary output (multi-omics) |
+| **`Z_comp`** | sample-removed embedding — used for cell typing and the composition blocks | Harmony (single-omics) / Harmony post-pass on scGLUE (multi-omics) |
+| **`Z_rmd`**  | sample-preserved embedding — used for the reference-relative mean displacement (RMD) block | second Harmony pass (single-omics) / scGLUE primary output (multi-omics) |
 
 It then assembles **four blocks** per sample (or per sample × modality for multi-omics):
 
 1. **A1** — one-hot cell-type composition
 2. **A2** — soft k-means composition at K_med (≈120)
 3. **A3** — soft k-means composition at K_fine (≈300)
-4. **CMD** — leave-one-out cell-type-resolved displacement on `Z_cmd`
+4. **RMD** — leave-one-out cell-type-resolved displacement on `Z_rmd`
 
 The four blocks are inverse-variance weighted, Frobenius-stacked, PCA-reduced to 10 dimensions, and Harmony-corrected at sample level. The result is stored as `adata.uns['X_DR_sample']` and feeds every downstream module.
 
@@ -32,46 +32,50 @@ The four blocks are inverse-variance weighted, Frobenius-stacked, PCA-reduced to
 
 ```
 code/
-├── SampleDisc.py              # CLI entry point (simple or complex mode)
-├── config/                    # 9 YAML configs covering covid / blood / eye / heart / ENCODE / tabula / long_covid / unpaired / default
-├── wrapper/                   # Orchestration
-│   ├── wrapper.py             # Master wrapper; gates RNA + ATAC + multiomics + shared downstream
-│   ├── rna_wrapper.py
-│   ├── atac_wrapper.py
-│   └── multiomics_wrapper.py
-├── preparation/               # Preprocessing
-│   ├── rna_preprocess_{cpu,gpu}.py   # QC → HVG → PCA → dual Harmony → Z_clust + Z_cmd
-│   ├── atac_preprocess_{cpu,gpu}.py  # QC → TF-IDF → HVF → LSI → dual Harmony → Z_clust + Z_cmd
-│   ├── cell_type_{cpu,gpu}.py        # Leiden clustering on Z_clust (RNA or ATAC)
-│   ├── ATAC_cell_type{,_gpu}.py      # ATAC-specific cell typing variants
-│   ├── multi_omics_glue.py           # scGLUE integration (cross-modality VAE + guidance graph)
-│   ├── multi_omics_batch_correction.py # Harmony post-pass on X_glue → Z_clust
-│   ├── multi_omics_merge.py          # post-GLUE merge + per-modality preprocess/slimming
-│   └── multi_omics_cell_type_{cpu,gpu}.py  # RNA-Leiden + k-NN label transfer to ATAC
-├── sample_embedding/          # Core method
-│   ├── blocks.py              # composition, CMD, weighting, Frobenius stack, final PCA + Harmony
-│   ├── sample_embedding.py    # CPU pipeline
-│   └── sample_embedding_gpu.py # GPU pipeline (cuML + cupy)
-├── parameter_selection/
-│   └── autotune.py            # Bayesian GP sweep over CMD α; adaptive proxy ensemble
-├── sample_distance/           # Pairwise sample distances (DR / EMD / chi-square / JS)
-├── sample_clustering/         # Hierarchical (HRA / HRC / NN / UPGMA / consensus), K-means, proportion test, RAISIN
-├── sample_trajectory/         # CCA (supervised) and TSCAN (unsupervised) + GAM-based trajectory DGE
-├── sample_association/        # Per-PC variance explained vs sample-level covariates (permutation FDR)
-├── visualization/             # Embedding plots, dendrograms, DGE volcanos, modality-aware multi-omics scatters
-├── utils/                     # Shared helpers: seed, safe h5ad I/O, limma, TF-IDF, batch regress, Grouping
-├── gene_activity/             # ATAC peak → gene activity inference + RNA-ATAC validation
-└── claude/                    # Active one-off run scripts (rerun launchers, monitored SE, parameter sweeps)
+├── pyproject.toml                 # package metadata; `pip install -e .` installs the `sampledisco` command
+├── config/                        # 10 YAML configs for the paper's datasets: covid / blood (1M-scBloodNL) / eye / heart / ENCODE / healthy-aging PBMC / long_covid / unpaired (+ RNA-tuned) / default
+├── src/sampledisco/               # the package
+│   ├── cli.py                     # `sampledisco` command: `-m complex --config <yaml>`, `--init-config <path>`
+│   ├── config/config_demo.yaml    # demo config written by `sampledisco --init-config`
+│   ├── wrapper/                   # Orchestration
+│   │   ├── wrapper.py             # Master wrapper; gates RNA + ATAC + multiomics + shared downstream
+│   │   ├── rna_wrapper.py
+│   │   ├── atac_wrapper.py
+│   │   └── multiomics_wrapper.py
+│   ├── preparation/               # Preprocessing
+│   │   ├── rna_preprocess_{cpu,gpu}.py   # QC → HVG → PCA → dual Harmony → Z_comp + Z_rmd
+│   │   ├── atac_preprocess_{cpu,gpu}.py  # QC → TF-IDF → HVF → LSI → dual Harmony → Z_comp + Z_rmd
+│   │   ├── cell_type_{cpu,gpu}.py        # Leiden clustering on Z_comp (RNA or ATAC)
+│   │   ├── ATAC_cell_type{,_gpu}.py      # ATAC-specific cell typing variants
+│   │   ├── multi_omics_glue.py           # scGLUE integration (cross-modality VAE + guidance graph)
+│   │   ├── multi_omics_batch_correction.py # Harmony post-pass on X_glue → Z_comp
+│   │   ├── multi_omics_merge.py          # post-GLUE merge + per-modality preprocess/slimming
+│   │   └── multi_omics_cell_type_{cpu,gpu}.py  # RNA-Leiden + k-NN label transfer to ATAC
+│   ├── sample_embedding/          # Core method
+│   │   ├── blocks.py              # composition, RMD, weighting, Frobenius stack, final PCA + Harmony
+│   │   ├── sample_embedding.py    # CPU pipeline
+│   │   └── sample_embedding_gpu.py # GPU pipeline (cuML + cupy)
+│   ├── parameter_selection/
+│   │   └── autotune.py            # Bayesian GP sweep over RMD α; adaptive proxy ensemble
+│   ├── sample_distance/           # Pairwise sample distances (DR / EMD / chi-square / JS)
+│   ├── sample_clustering/         # Hierarchical (HRA / HRC / NN / UPGMA / consensus), K-means, proportion test, RAISIN
+│   ├── sample_trajectory/         # CCA (supervised) and TSCAN (unsupervised) + GAM-based trajectory DGE
+│   ├── sample_association/        # Per-PC variance explained vs sample-level covariates (permutation FDR)
+│   ├── visualization/             # Embedding plots, dendrograms, DGE volcanos, modality-aware multi-omics scatters
+│   ├── utils/                     # Shared helpers: seed, safe h5ad I/O, limma, TF-IDF, batch regress, Grouping
+│   └── gene_activity/             # ATAC peak → gene activity inference + RNA-ATAC validation
+├── Benchmark_covid/, Benchmark_multiomics/  # benchmark drivers used for the paper
+└── claude/                        # one-off run scripts (rerun launchers, monitored runs, parameter sweeps)
 ```
 
 ---
 
 ## Usage
 
-### Complex mode (recommended) — YAML-driven
+### Run — YAML-driven
 
 ```bash
-python SampleDisc.py -m complex --config config/config.yaml
+sampledisco -m complex --config config/config.yaml     # same as: python -m sampledisco.cli -m complex --config ...
 ```
 
 The YAML drives every flag and parameter for all three pipelines:
@@ -81,14 +85,16 @@ The YAML drives every flag and parameter for all three pipelines:
 - **Per-modality downstream gates** (Phase 2): `*_sample_distance_calculation`, `*_trajectory_analysis`, `*_trajectory_dge`, `*_sample_cluster`, `*_proportion_test`, `*_cluster_dge`, `*_visualize_data`, `*_dimension_association_analysis`
 - **Multi-omics-specific**: `multiomics_run_glue_*`, `multiomics_treat_sample_as_batch`, `multiomics_run_glue_twice_for_sample_removal`
 
-The 9 ready-to-use configs in `config/` are point-in-time snapshots for the datasets used in the paper; copy one and adjust paths / column names for your own data.
+The 10 ready-to-use configs in `config/` are point-in-time snapshots for the datasets used in the paper; copy one and adjust paths / column names for your own data.
 
-### Simple mode — one positional file, defaults everywhere
+### Starter config
 
 ```bash
-python SampleDisc.py -m simple -c <count_data.h5ad> -o <output_dir>
+sampledisco --init-config my_config.yaml
 ```
 
+writes the demo config (tuned for the Zenodo demo dataset) to `my_config.yaml`. The YAML is validated against every `wrapper()` parameter, so edit values rather than deleting keys.
+
 ---
 
 ## Inputs
@@ -118,7 +124,7 @@ For multi-omics, the pipeline takes two separate h5ads (RNA + ATAC) and integrat
 ├── atac/   (parallel structure)
 ├── multiomics/
 │   ├── integration/glue/{rna-pp,atac-pp,guidance.graphml.gz}
-│   ├── preprocess/adata_sample.h5ad           # post-GLUE merged adata with Z_clust + Z_cmd
+│   ├── preprocess/adata_sample.h5ad           # post-GLUE merged adata with Z_comp + Z_rmd
 │   ├── sample_embedding/sample_embedding.csv
 │   └── (same downstream subdirs as single-omics)
 └── sys_log/main_process_status.json           # which stages completed
@@ -135,7 +141,7 @@ detects and uses them at runtime. There is no separate "GPU build" of SampleDisc
 ### 1. Core install (CPU)
 
 ```bash
-pip install sampledisco          # once published — or `pip install -e .` from a clone
+pip install sampledisco          # or `pip install -e .` from a clone
 ```
 
 ### 2. System prerequisite — bedtools

{sampledisco-0.2.0 → sampledisco-0.4.0}/pyproject.toml

@@ -9,7 +9,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sampledisco"
-version = "0.2.0"
+version = "0.4.0"
 description = "Cross-omics, cross-condition sample embedding for single-cell data (RNA + ATAC)"
 readme = "README.md"
 requires-python = ">=3.10"

{sampledisco-0.2.0 → sampledisco-0.4.0}/requirements.txt

@@ -1,5 +1,5 @@
-# SampleDisco core (CPU) dependencies — no PyTorch.
-# The deep-learning stack (torch, scglue, harmony-pytorch) and RAPIDS GPU
+# SampleDisco core (CPU) dependencies. PyTorch is installed as a dependency of harmonypy 0.2.0.
+# The deep-learning stack (scglue, harmony-pytorch, a CUDA build of torch) and RAPIDS GPU
 # acceleration are NOT installed here — they're OS/driver-specific and you
 # install them yourself (see the Installation page). SampleDisco falls back to
 # the CPU path when they are absent.
@@ -14,7 +14,7 @@ patsy>=0.5
 scanpy>=1.11
 anndata>=0.10
 muon>=0.1
-harmonypy>=0.0.9,<0.0.10   # pin to the pure-NumPy release; harmonypy 0.0.10+ imports torch
+harmonypy==0.2.0   # the version used for the published results; it requires torch
 python-igraph>=0.10
 leidenalg>=0.9
 networkx>=3.0

{sampledisco-0.2.0 → sampledisco-0.4.0}/src/sampledisco/cli.py

@@ -35,14 +35,27 @@ def load_config(config_path):
         return yaml.safe_load(f)
 
 
+# Keys added after 0.2.0. Configs written before them may omit these keys, which
+# then take their wrapper() default; every other key stays required.
+OPTIONAL_KEYS = frozenset(f"{m}_save_cell_adata_after_embedding"
+                          for m in ("rna", "atac", "multiomics"))
+
+
 def validate_config(config, func):
     valid_params = inspect.signature(func).parameters
     for key in config:
         if key not in valid_params:
             raise ValueError(f"Unexpected parameter in config: '{key}'")
     for key in valid_params:
-        if key not in config:
+        if key not in config and key not in OPTIONAL_KEYS:
             raise ValueError(f"Missing required parameter in config: '{key}'")
+    from sampledisco.sample_embedding.blocks import check_rmd_weight
+    for key in config:
+        if key.endswith("_sample_embedding_rmd_weight"):
+            try:
+                check_rmd_weight(config[key])
+            except ValueError as e:
+                raise ValueError(f"Invalid value for '{key}': {e}") from None
 
 
 def write_template(dest):

{sampledisco-0.2.0 → sampledisco-0.4.0}/src/sampledisco/config/config_demo.yaml

@@ -86,16 +86,17 @@ rna_sample_embedding_rmd_dim: 8
 rna_sample_embedding_use_clr: false
 rna_sample_embedding_use_rmd: true
 rna_sample_embedding_block_weights:
-rna_sample_embedding_rmd_weight: 0.60
+rna_sample_embedding_rmd_weight: "equal"   # RMD block weight α: "equal" = same energy as the three composition blocks together (α² = w_A1² + w_A2² + w_A3²); a number fixes α (0.60 = previous default)
 rna_sample_embedding_pca_components: 10
 rna_sample_embedding_batch_method: "harmony"
+rna_save_cell_adata_after_embedding: true   # store .uns['X_DR_sample'] in the cell-level h5ad (updated in place; false = keep only the CSV)
 
 # --- Autotune Parameters ---
 rna_autotune_enable: false
 rna_autotune_search: "bayesian"
 rna_autotune_scoring: "auto"
 rna_autotune_scope: "alpha_only"
-rna_autotune_alpha_bounds: [0.1, 10.0]
+rna_autotune_alpha_bounds: [0.1, 100.0]
 rna_autotune_grouping_col:
 
 # --- Trajectory Analysis Parameters ---
@@ -207,16 +208,17 @@ atac_sample_embedding_rmd_dim: 8
 atac_sample_embedding_use_clr: false
 atac_sample_embedding_use_rmd: true
 atac_sample_embedding_block_weights:
-atac_sample_embedding_rmd_weight: 0.60
+atac_sample_embedding_rmd_weight: "equal"   # RMD block weight α: "equal" = same energy as the three composition blocks together (α² = w_A1² + w_A2² + w_A3²); a number fixes α (0.60 = previous default)
 atac_sample_embedding_pca_components: 10
 atac_sample_embedding_batch_method: "harmony"
+atac_save_cell_adata_after_embedding: true   # store .uns['X_DR_sample'] in the cell-level h5ad (updated in place; false = keep only the CSV)
 
 # --- Autotune Parameters ---
 atac_autotune_enable: false
 atac_autotune_search: "bayesian"
 atac_autotune_scoring: "auto"
 atac_autotune_scope: "alpha_only"
-atac_autotune_alpha_bounds: [0.1, 10.0]
+atac_autotune_alpha_bounds: [0.1, 100.0]
 atac_autotune_grouping_col:
 
 # --- Trajectory Analysis Parameters ---
@@ -332,9 +334,9 @@ multiomics_treat_sample_as_batch: false  # GLUE preserves per-sample variance (V
 
 # --- Sample-removed cluster embedding (X_glue from scGLUE is the RMD/sample-preserved emb) ---
 # By default, one Harmony pass on X_glue removes per-sample variance to
-# produce X_glue_harmony (used by cell typing + A1/A2/A3). Alternative:
+# produce Z_comp (used by cell typing + A1/A2/A3). Alternative:
 # train scGLUE a second time with treat_sample_as_batch=True; that run's
-# embedding is merged in as X_glue_harmony and the Harmony pass auto-skips.
+# embedding is merged in as Z_comp and the Harmony pass auto-skips.
 multiomics_harmonize_xglue_max_iter: 30
 multiomics_run_glue_twice_for_sample_removal: false
 multiomics_save_prefix: "glue"
@@ -355,7 +357,7 @@ multiomics_metric: "cosine"
 multiomics_existing_cell_types: false
 multiomics_n_target_clusters: 8
 multiomics_cluster_resolution: 0.8
-# null → auto-resolve to X_glue_harmony (sample-removed) if present, else X_glue
+# null → auto-resolve to Z_comp (sample-removed); legacy key names accepted
 multiomics_use_rep_celltype:
 multiomics_markers:
 multiomics_generate_umap_celltype: true
@@ -375,16 +377,17 @@ multiomics_sample_embedding_rmd_dim: 8
 multiomics_sample_embedding_use_clr: false
 multiomics_sample_embedding_use_rmd: true
 multiomics_sample_embedding_block_weights:
-multiomics_sample_embedding_rmd_weight: 0.60
+multiomics_sample_embedding_rmd_weight: "equal"   # RMD block weight α: "equal" = same energy as the three composition blocks together (α² = w_A1² + w_A2² + w_A3²); a number fixes α (0.60 = previous default)
 multiomics_sample_embedding_pca_components: 10
 multiomics_sample_embedding_batch_method: "harmony"
+multiomics_save_cell_adata_after_embedding: true   # store .uns['X_DR_sample'] in the cell-level h5ad (updated in place; false = keep only the CSV)
 
 # --- Autotune Parameters ---
 multiomics_autotune_enable: false
 multiomics_autotune_search: "bayesian"
 multiomics_autotune_scoring: "auto"
 multiomics_autotune_scope: "alpha_only"
-multiomics_autotune_alpha_bounds: [0.1, 10.0]
+multiomics_autotune_alpha_bounds: [0.1, 100.0]
 multiomics_autotune_grouping_col:
 
 # --- Trajectory Analysis Parameters ---