sampledisco 0.3.0__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sampledisco
-Version: 0.3.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/>
 
 ---
 
@@ -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_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
-└── 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
@@ -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.3.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/>
 
 ---
 
@@ -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_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
-└── 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
@@ -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.3.0 → sampledisco-0.4.0}/pyproject.toml

@@ -9,7 +9,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sampledisco"
-version = "0.3.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.3.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.3.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.3.0 → sampledisco-0.4.0}/src/sampledisco/config/config_demo.yaml

@@ -86,9 +86,10 @@ 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
@@ -207,9 +208,10 @@ 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
@@ -375,9 +377,10 @@ 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

{sampledisco-0.3.0 → sampledisco-0.4.0}/src/sampledisco/parameter_selection/autotune.py

@@ -25,7 +25,6 @@ from typing import Callable, Dict, List, Optional, Tuple, Union
 
 import numpy as np
 import pandas as pd
-import scanpy as sc
 from anndata import AnnData
 from sklearn.cluster import MiniBatchKMeans
 from sklearn.cross_decomposition import CCA
@@ -44,7 +43,10 @@ from sampledisco.sample_embedding.blocks import (
     composition_per_unit,
     derive_weights,
     loo_rmd,
+    resolve_rmd_weight,
+    save_embedding_to_h5ad,
     soft_assign,
+    warn_if_stale_embedding,
 )
 from sampledisco.utils.embedding_keys import resolve_comp_key, resolve_rmd_key
 
@@ -606,6 +608,7 @@ def run_autotune(
     verbose: bool = True,
     tune_on_modality: Optional[str] = None,
     cluster_emb_key: Optional[str] = None,
+    save_cell_adata: bool = True,
 ) -> Dict:
     """Run autotune and return the best params + final sample-AnnData.
 
@@ -660,11 +663,12 @@ def run_autotune(
                   f"scoring on {int(score_mask.sum())}/{blocks['n_units']} units")
 
     if not score_meta["has_batch"] and not score_meta["has_grouping"]:
+        alpha = resolve_rmd_weight("equal", blocks["K_c"], blocks["K_med"], blocks["K_fine"])
         if verbose:
-            print("[autotune] no batch and no grouping column → using fixed defaults; "
-                  "no search performed.")
+            print(f"[autotune] no batch and no grouping column → using the default "
+                  f"rmd_weight='equal' (α={alpha}); no search performed.")
         weights = derive_weights(blocks["K_c"], blocks["K_med"], blocks["K_fine"],
-                                   rmd_weight=0.60, n_blocks=4)
+                                   rmd_weight=alpha, n_blocks=4)
         final_emb = build_emb_from_blocks(
             [blocks["A1"], blocks["A2"], blocks["A3"], blocks["RMD"]],
             weights,
@@ -675,13 +679,13 @@ def run_autotune(
             seed=seed, verbose=verbose,
         )
         return _finalize(adata, blocks, final_emb, weights,
-                         best_params={"rmd_weight": 0.60},
+                         best_params={"rmd_weight": alpha},
                          best_score=float("nan"),
                          trace=[], search=search, scoring=scoring,
                          scope=scope, alpha_bounds=alpha_bounds,
                          pca_components=pca_components,
                          batch_method=batch_method,
-                         output_dir=output_dir, save=save,
+                         output_dir=output_dir, save=save, save_cell_adata=save_cell_adata,
                          t_start=t0, verbose=verbose,
                          tune_on_modality=tune_on_modality,
                          score_n_units=int(score_mask.sum()))
@@ -737,7 +741,7 @@ def run_autotune(
                      scope=scope, alpha_bounds=alpha_bounds,
                      pca_components=pca_components,
                      batch_method=batch_method,
-                     output_dir=output_dir, save=save,
+                     output_dir=output_dir, save=save, save_cell_adata=save_cell_adata,
                      t_start=t0, verbose=verbose,
                      tune_on_modality=tune_on_modality,
                      score_n_units=int(score_mask.sum()))
@@ -869,7 +873,7 @@ def _finalize(adata, blocks, final_emb, weights, *,
                search, scoring, scope, alpha_bounds,
                pca_components, batch_method,
                output_dir, save, t_start, verbose,
-               tune_on_modality=None, score_n_units=None):
+               tune_on_modality=None, score_n_units=None, save_cell_adata=True):
     """Write the autotuned embedding into the cell-level adata and persist artifacts."""
     elapsed = time.time() - t_start
     adata.uns["X_DR_sample"] = final_emb.copy()
@@ -905,9 +909,11 @@ def _finalize(adata, blocks, final_emb, weights, *,
         final_emb.to_csv(emb_csv)
 
         preprocessed_h5 = os.path.join(output_dir, "preprocess", "adata_preprocessed.h5ad")
-        if os.path.exists(preprocessed_h5):
+        if not save_cell_adata:
+            warn_if_stale_embedding(preprocessed_h5, emb_csv)
+        if save_cell_adata and os.path.exists(preprocessed_h5):
             try:
-                sc.write(preprocessed_h5, adata)
+                save_embedding_to_h5ad(preprocessed_h5, adata)
             except Exception as exc:
                 if verbose:
                     print(f"[autotune] WARNING: could not re-save "

{sampledisco-0.3.0 → sampledisco-0.4.0}/src/sampledisco/preparation/cell_type_cpu.py

@@ -94,20 +94,21 @@ def cell_types(
             if verbose:
                 print(f"{indent}[cell_types] Found {num_clusters_found} clusters")
 
+            # Recursive results fall through (no early return) so the depth-0
+            # call still runs its UMAP / CSV / save block below.
+            new_resolution = leiden_cluster_resolution + RESOLUTION_STEP
             if num_clusters_found >= n_target_clusters:
                 if num_clusters_found > n_target_clusters and verbose:
                     print(f"{indent}[cell_types] Over-shot target; recursing with dendrogram aggregation")
 
-                return cell_types(
+                adata = cell_types(
                     anndata_cell=adata, cell_type_column="cell_type",
                     existing_cell_types=True, n_target_clusters=n_target_clusters, umap=False, save=False,
                     cell_embedding_column=cell_embedding_column, cell_embedding_num_PCs=cell_embedding_num_PCs,
                     verbose=verbose, umap_plots=False, _recursion_depth=_recursion_depth + 1,
                 )
-
-            new_resolution = leiden_cluster_resolution + RESOLUTION_STEP
-            if new_resolution <= MAX_RESOLUTION:
-                return cell_types(
+            elif new_resolution <= MAX_RESOLUTION:
+                adata = cell_types(
                     anndata_cell=adata, cell_type_column=cell_type_column,
                     existing_cell_types=False, n_target_clusters=n_target_clusters, umap=False, save=False,
                     leiden_cluster_resolution=new_resolution, cell_embedding_column=cell_embedding_column,

{sampledisco-0.3.0 → sampledisco-0.4.0}/src/sampledisco/preparation/cell_type_gpu.py

@@ -98,20 +98,21 @@ def cell_types_gpu(
                 if verbose:
                     print(f"{indent}[cell_types] Found {num_clusters_found} clusters")
 
+                # Recursive results fall through (no early return) so the
+                # depth-0 call still runs its UMAP / CSV / save block below.
+                new_resolution = leiden_cluster_resolution + RESOLUTION_STEP
                 if num_clusters_found >= n_target_clusters:
                     if num_clusters_found > n_target_clusters and verbose:
                         print(f"{indent}[cell_types] Over-shot target; recursing with dendrogram aggregation")
 
-                    return cell_types_gpu(
+                    adata = cell_types_gpu(
                         anndata_cell=adata, cell_type_column="cell_type",
                         existing_cell_types=True, n_target_clusters=n_target_clusters, umap=False, save=False,
                         cell_embedding_column=cell_embedding_column, cell_embedding_num_PCs=cell_embedding_num_PCs,
                         verbose=verbose, umap_plots=False, _recursion_depth=_recursion_depth + 1,
                     )
-
-                new_resolution = leiden_cluster_resolution + RESOLUTION_STEP
-                if new_resolution <= MAX_RESOLUTION:
-                    return cell_types_gpu(
+                elif new_resolution <= MAX_RESOLUTION:
+                    adata = cell_types_gpu(
                         anndata_cell=adata, cell_type_column=cell_type_column,
                         existing_cell_types=False, n_target_clusters=n_target_clusters, umap=False, save=False,
                         leiden_cluster_resolution=new_resolution, cell_embedding_column=cell_embedding_column,

{sampledisco-0.3.0 → sampledisco-0.4.0}/src/sampledisco/sample_embedding/__init__.py

@@ -37,13 +37,14 @@ def compute_sample_embedding(
     use_clr: bool = False,
     use_rmd: bool = True,
     block_weights: Optional[List[float]] = None,
-    rmd_weight: float = 0.60,
+    rmd_weight: Union[float, str] = "equal",
     pca_components: int = 10,
     batch_method: str = "harmony",
     save: bool = True,
     verbose: bool = True,
     seed: int = 42,
     cluster_emb_key: Optional[str] = None,
+    save_cell_adata: bool = True,
 ) -> AnnData:
     """Dispatch to the CPU or GPU implementation.
 
@@ -53,6 +54,8 @@ def compute_sample_embedding(
     around the module import is not enough (the import succeeds and the crash
     lands mid-run). We probe for the stack up front and also guard the call.
     """
+    from sampledisco.sample_embedding.blocks import check_rmd_weight
+    check_rmd_weight(rmd_weight)  # before the GPU attempt, so a bad value is not reported as "GPU unavailable"
     kwargs = dict(
         sample_col=sample_col,
         celltype_col=celltype_col,
@@ -73,6 +76,7 @@ def compute_sample_embedding(
         save=save,
         verbose=verbose,
         seed=seed,
+        save_cell_adata=save_cell_adata,
     )
 
     if use_gpu and not _gpu_stack_available():