bsvae 0.3.0__tar.gz → 0.3.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {bsvae-0.3.0 → bsvae-0.3.1}/PKG-INFO +43 -1
- {bsvae-0.3.0 → bsvae-0.3.1}/README.md +42 -0
- {bsvae-0.3.0 → bsvae-0.3.1}/pyproject.toml +2 -1
- {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/cli/simulate.py +98 -3
- bsvae-0.3.1/src/bsvae/cli/sweep_k.py +511 -0
- {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/cli/train.py +15 -0
- {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/models/gmm_prior.py +12 -4
- {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/models/losses.py +56 -36
- bsvae-0.3.1/src/bsvae/simulation/__init__.py +24 -0
- {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/simulation/generate.py +2 -2
- bsvae-0.3.1/src/bsvae/simulation/scenario.py +556 -0
- {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/utils/training.py +119 -11
- bsvae-0.3.0/src/bsvae/simulation/__init__.py +0 -5
- {bsvae-0.3.0 → bsvae-0.3.1}/LICENSE +0 -0
- {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/__init__.py +0 -0
- {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/cli/__init__.py +0 -0
- {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/cli/networks.py +0 -0
- {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/hyperparam.ini +0 -0
- {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/latent/__init__.py +0 -0
- {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/latent/latent_analysis.py +0 -0
- {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/latent/latent_export.py +0 -0
- {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/main.py +0 -0
- {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/models/__init__.py +0 -0
- {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/models/decoder.py +0 -0
- {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/models/encoder.py +0 -0
- {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/models/gmvae.py +0 -0
- {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/models/vae.py +0 -0
- {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/networks/__init__.py +0 -0
- {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/networks/cli.py +0 -0
- {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/networks/extract_networks.py +0 -0
- {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/networks/module_extraction.py +0 -0
- {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/networks/utils.py +0 -0
- {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/simulation/metrics.py +0 -0
- {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/utils/__init__.py +0 -0
- {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/utils/datasets.py +0 -0
- {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/utils/evaluate.py +0 -0
- {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/utils/helpers.py +0 -0
- {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/utils/hierarchy.py +0 -0
- {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/utils/initialization.py +0 -0
- {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/utils/modelIO.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: bsvae
|
|
3
|
-
Version: 0.3.
|
|
3
|
+
Version: 0.3.1
|
|
4
4
|
Summary: Gaussian Mixture VAE for multi-modal biological module discovery in omics data.
|
|
5
5
|
License: GPL-3.0-only
|
|
6
6
|
License-File: LICENSE
|
|
@@ -44,6 +44,7 @@ BSVAE is a PyTorch package centered on `GMMModuleVAE`, a Gaussian-mixture variat
|
|
|
44
44
|
- Extracts feature-feature networks from trained models (`bsvae-networks`)
|
|
45
45
|
- Extracts module assignments and optional eigengenes (`bsvae-networks`)
|
|
46
46
|
- Exports latents (`mu`, `logvar`, `gamma`) as `.npz`
|
|
47
|
+
- Runs latent analysis (UMAP/t-SNE, clustering, covariate correlation) (`bsvae-networks latent-analysis`)
|
|
47
48
|
- Simulates synthetic datasets and benchmarks module recovery (`bsvae-simulate`)
|
|
48
49
|
|
|
49
50
|
## Installation
|
|
@@ -72,6 +73,23 @@ pip install -e .
|
|
|
72
73
|
|
|
73
74
|
For a full walkthrough (minimal run, production run, post-training analysis, simulation benchmark, troubleshooting, and migration), see `docs/tutorial.md`.
|
|
74
75
|
|
|
76
|
+
### Tune K (Recommended)
|
|
77
|
+
|
|
78
|
+
`--n-modules` (K) sets the expected number of modules. Recommended approach is
|
|
79
|
+
`bsvae-sweep-k` with stability replicates:
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
bsvae-sweep-k sweep1 \
|
|
83
|
+
--dataset data/expression.csv \
|
|
84
|
+
--k-grid 8,12,16,24,32 \
|
|
85
|
+
--sweep-epochs 60 \
|
|
86
|
+
--stability-reps 5 \
|
|
87
|
+
--val-frac 0.1
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
The selected model is retrained on the full dataset at:
|
|
91
|
+
`results/sweep1/final_k<K>/`.
|
|
92
|
+
|
|
75
93
|
### 1. Train
|
|
76
94
|
|
|
77
95
|
Input matrix must be `features x samples` with feature IDs in row index and sample IDs in columns.
|
|
@@ -114,6 +132,8 @@ bsvae-networks export-latents \
|
|
|
114
132
|
|
|
115
133
|
### 5. Simulate and benchmark
|
|
116
134
|
|
|
135
|
+
Single dataset:
|
|
136
|
+
|
|
117
137
|
```bash
|
|
118
138
|
bsvae-simulate generate \
|
|
119
139
|
--output data/sim_expr.csv \
|
|
@@ -126,6 +146,28 @@ bsvae-simulate benchmark \
|
|
|
126
146
|
--output results/exp1/sim_metrics.json
|
|
127
147
|
```
|
|
128
148
|
|
|
149
|
+
Scenario grid for publication-style benchmarking:
|
|
150
|
+
|
|
151
|
+
```bash
|
|
152
|
+
bsvae-simulate init-config --output sim.yaml
|
|
153
|
+
|
|
154
|
+
bsvae-simulate generate-grid \
|
|
155
|
+
--config sim.yaml \
|
|
156
|
+
--outdir results/sim_pub_v1 \
|
|
157
|
+
--reps 30 \
|
|
158
|
+
--base-seed 13
|
|
159
|
+
|
|
160
|
+
bsvae-simulate validate-grid --grid-dir results/sim_pub_v1
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
Each scenario replicate writes method-ready files under
|
|
164
|
+
`results/sim_pub_v1/scenarios/<scenario_id>/rep_<rep>/`, including:
|
|
165
|
+
|
|
166
|
+
- `expr/features_x_samples.tsv.gz` (BSVAE, GNVAE)
|
|
167
|
+
- `expr/samples_x_features.tsv.gz` (WGCNA)
|
|
168
|
+
- `truth/modules_hard.csv` (hard labels for ARI/NMI)
|
|
169
|
+
- `method_inputs.json` (canonical paths for each method)
|
|
170
|
+
|
|
129
171
|
## Training Outputs
|
|
130
172
|
|
|
131
173
|
`bsvae-train` writes to `results/<experiment>/`:
|
|
@@ -13,6 +13,7 @@ BSVAE is a PyTorch package centered on `GMMModuleVAE`, a Gaussian-mixture variat
|
|
|
13
13
|
- Extracts feature-feature networks from trained models (`bsvae-networks`)
|
|
14
14
|
- Extracts module assignments and optional eigengenes (`bsvae-networks`)
|
|
15
15
|
- Exports latents (`mu`, `logvar`, `gamma`) as `.npz`
|
|
16
|
+
- Runs latent analysis (UMAP/t-SNE, clustering, covariate correlation) (`bsvae-networks latent-analysis`)
|
|
16
17
|
- Simulates synthetic datasets and benchmarks module recovery (`bsvae-simulate`)
|
|
17
18
|
|
|
18
19
|
## Installation
|
|
@@ -41,6 +42,23 @@ pip install -e .
|
|
|
41
42
|
|
|
42
43
|
For a full walkthrough (minimal run, production run, post-training analysis, simulation benchmark, troubleshooting, and migration), see `docs/tutorial.md`.
|
|
43
44
|
|
|
45
|
+
### Tune K (Recommended)
|
|
46
|
+
|
|
47
|
+
`--n-modules` (K) sets the expected number of modules. Recommended approach is
|
|
48
|
+
`bsvae-sweep-k` with stability replicates:
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
bsvae-sweep-k sweep1 \
|
|
52
|
+
--dataset data/expression.csv \
|
|
53
|
+
--k-grid 8,12,16,24,32 \
|
|
54
|
+
--sweep-epochs 60 \
|
|
55
|
+
--stability-reps 5 \
|
|
56
|
+
--val-frac 0.1
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
The selected model is retrained on the full dataset at:
|
|
60
|
+
`results/sweep1/final_k<K>/`.
|
|
61
|
+
|
|
44
62
|
### 1. Train
|
|
45
63
|
|
|
46
64
|
Input matrix must be `features x samples` with feature IDs in row index and sample IDs in columns.
|
|
@@ -83,6 +101,8 @@ bsvae-networks export-latents \
|
|
|
83
101
|
|
|
84
102
|
### 5. Simulate and benchmark
|
|
85
103
|
|
|
104
|
+
Single dataset:
|
|
105
|
+
|
|
86
106
|
```bash
|
|
87
107
|
bsvae-simulate generate \
|
|
88
108
|
--output data/sim_expr.csv \
|
|
@@ -95,6 +115,28 @@ bsvae-simulate benchmark \
|
|
|
95
115
|
--output results/exp1/sim_metrics.json
|
|
96
116
|
```
|
|
97
117
|
|
|
118
|
+
Scenario grid for publication-style benchmarking:
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
bsvae-simulate init-config --output sim.yaml
|
|
122
|
+
|
|
123
|
+
bsvae-simulate generate-grid \
|
|
124
|
+
--config sim.yaml \
|
|
125
|
+
--outdir results/sim_pub_v1 \
|
|
126
|
+
--reps 30 \
|
|
127
|
+
--base-seed 13
|
|
128
|
+
|
|
129
|
+
bsvae-simulate validate-grid --grid-dir results/sim_pub_v1
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Each scenario replicate writes method-ready files under
|
|
133
|
+
`results/sim_pub_v1/scenarios/<scenario_id>/rep_<rep>/`, including:
|
|
134
|
+
|
|
135
|
+
- `expr/features_x_samples.tsv.gz` (BSVAE, GNVAE)
|
|
136
|
+
- `expr/samples_x_features.tsv.gz` (WGCNA)
|
|
137
|
+
- `truth/modules_hard.csv` (hard labels for ARI/NMI)
|
|
138
|
+
- `method_inputs.json` (canonical paths for each method)
|
|
139
|
+
|
|
98
140
|
## Training Outputs
|
|
99
141
|
|
|
100
142
|
`bsvae-train` writes to `results/<experiment>/`:
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[tool.poetry]
|
|
2
2
|
name = "bsvae"
|
|
3
|
-
version = "0.3.
|
|
3
|
+
version = "0.3.1" # dynamically resolved by poetry-dynamic-versioning
|
|
4
4
|
description = "Gaussian Mixture VAE for multi-modal biological module discovery in omics data."
|
|
5
5
|
readme = "README.md"
|
|
6
6
|
authors = ["Kynon J Benjamin <kj.benjamin90@gmail.com>"]
|
|
@@ -50,6 +50,7 @@ repository = "https://github.com/heart-gen/BSVAE"
|
|
|
50
50
|
bsvae-train = "bsvae.cli.train:cli"
|
|
51
51
|
bsvae-networks = "bsvae.cli.networks:cli"
|
|
52
52
|
bsvae-simulate = "bsvae.cli.simulate:cli"
|
|
53
|
+
bsvae-sweep-k = "bsvae.cli.sweep_k:cli"
|
|
53
54
|
|
|
54
55
|
[tool.poetry.group.dev.dependencies]
|
|
55
56
|
pytest = ">=8.4.2,<9.0.0"
|
|
@@ -3,8 +3,12 @@ bsvae-simulate — Generate synthetic omics data and benchmark module methods.
|
|
|
3
3
|
|
|
4
4
|
Subcommands
|
|
5
5
|
-----------
|
|
6
|
-
generate
|
|
7
|
-
benchmark
|
|
6
|
+
generate Simulate omics data with known block-diagonal module structure.
|
|
7
|
+
benchmark ARI/NMI/enrichment vs WGCNA/GNVAE on simulated data.
|
|
8
|
+
init-config Write starter simulation grid config.
|
|
9
|
+
generate-grid Generate all scenarios/replicates defined in config.
|
|
10
|
+
generate-scenario Generate one scenario/replicate.
|
|
11
|
+
validate-grid Validate generated grid output structure.
|
|
8
12
|
"""
|
|
9
13
|
|
|
10
14
|
from __future__ import annotations
|
|
@@ -43,7 +47,7 @@ def build_parser() -> argparse.ArgumentParser:
|
|
|
43
47
|
gp.add_argument("--between-corr", type=float, default=0.0,
|
|
44
48
|
help="Between-module correlation (default: 0.0).")
|
|
45
49
|
gp.add_argument("--noise-std", type=float, default=0.2)
|
|
46
|
-
gp.add_argument("--seed", type=int, default=
|
|
50
|
+
gp.add_argument("--seed", type=int, default=13)
|
|
47
51
|
gp.add_argument("--save-ground-truth", help="Path to save ground-truth module labels CSV.")
|
|
48
52
|
|
|
49
53
|
# ------------------------------------------------------------------
|
|
@@ -57,6 +61,37 @@ def build_parser() -> argparse.ArgumentParser:
|
|
|
57
61
|
bp.add_argument("--batch-size", type=int, default=128)
|
|
58
62
|
bp.add_argument("--no-cuda", action="store_true", default=False)
|
|
59
63
|
|
|
64
|
+
# ------------------------------------------------------------------
|
|
65
|
+
# init-config
|
|
66
|
+
# ------------------------------------------------------------------
|
|
67
|
+
cp = subs.add_parser("init-config", help="Write a starter simulation config file.")
|
|
68
|
+
cp.add_argument("--output", default="sim.yaml", help="Destination config path.")
|
|
69
|
+
|
|
70
|
+
# ------------------------------------------------------------------
|
|
71
|
+
# generate-grid
|
|
72
|
+
# ------------------------------------------------------------------
|
|
73
|
+
gp2 = subs.add_parser("generate-grid", help="Generate a scenario grid from config.")
|
|
74
|
+
gp2.add_argument("--config", required=True, help="Simulation config path.")
|
|
75
|
+
gp2.add_argument("--outdir", required=True, help="Output directory for scenario grid.")
|
|
76
|
+
gp2.add_argument("--reps", type=int, default=None, help="Override replicates per scenario.")
|
|
77
|
+
gp2.add_argument("--base-seed", type=int, default=None, help="Override base seed for all runs.")
|
|
78
|
+
|
|
79
|
+
# ------------------------------------------------------------------
|
|
80
|
+
# generate-scenario
|
|
81
|
+
# ------------------------------------------------------------------
|
|
82
|
+
sp = subs.add_parser("generate-scenario", help="Generate a single scenario/replicate from config.")
|
|
83
|
+
sp.add_argument("--config", required=True, help="Simulation config path.")
|
|
84
|
+
sp.add_argument("--scenario-id", required=True, help="Scenario identifier from config expansion.")
|
|
85
|
+
sp.add_argument("--rep", type=int, default=0, help="Replicate index.")
|
|
86
|
+
sp.add_argument("--outdir", required=True, help="Output directory for scenario grid.")
|
|
87
|
+
sp.add_argument("--base-seed", type=int, default=None, help="Override base seed for this run.")
|
|
88
|
+
|
|
89
|
+
# ------------------------------------------------------------------
|
|
90
|
+
# validate-grid
|
|
91
|
+
# ------------------------------------------------------------------
|
|
92
|
+
vp = subs.add_parser("validate-grid", help="Validate scenario grid output files.")
|
|
93
|
+
vp.add_argument("--grid-dir", required=True, help="Scenario grid output directory.")
|
|
94
|
+
|
|
60
95
|
return parser
|
|
61
96
|
|
|
62
97
|
|
|
@@ -144,6 +179,58 @@ def handle_benchmark(args, logger: logging.Logger) -> None:
|
|
|
144
179
|
logger.info("Benchmark metrics saved to %s", out)
|
|
145
180
|
|
|
146
181
|
|
|
182
|
+
def handle_init_config(args, logger: logging.Logger) -> None:
|
|
183
|
+
from bsvae.simulation.scenario import write_starter_config
|
|
184
|
+
|
|
185
|
+
write_starter_config(args.output)
|
|
186
|
+
logger.info("Starter simulation config written to %s", args.output)
|
|
187
|
+
|
|
188
|
+
|
|
189
|
+
def handle_generate_grid(args, logger: logging.Logger) -> None:
|
|
190
|
+
from bsvae.simulation.scenario import load_config, generate_grid
|
|
191
|
+
|
|
192
|
+
config = load_config(args.config)
|
|
193
|
+
summary = generate_grid(
|
|
194
|
+
config=config,
|
|
195
|
+
outdir=args.outdir,
|
|
196
|
+
reps=args.reps,
|
|
197
|
+
base_seed=args.base_seed,
|
|
198
|
+
)
|
|
199
|
+
logger.info(
|
|
200
|
+
"Grid complete: %d scenarios × %d reps = %d runs",
|
|
201
|
+
summary["n_scenarios"],
|
|
202
|
+
summary["n_reps"],
|
|
203
|
+
summary["n_runs"],
|
|
204
|
+
)
|
|
205
|
+
logger.info("Manifest: %s", summary["manifest"])
|
|
206
|
+
|
|
207
|
+
|
|
208
|
+
def handle_generate_scenario(args, logger: logging.Logger) -> None:
|
|
209
|
+
from bsvae.simulation.scenario import load_config, generate_scenario
|
|
210
|
+
|
|
211
|
+
config = load_config(args.config)
|
|
212
|
+
run_dir = generate_scenario(
|
|
213
|
+
config=config,
|
|
214
|
+
scenario_id=args.scenario_id,
|
|
215
|
+
rep=args.rep,
|
|
216
|
+
outdir=args.outdir,
|
|
217
|
+
base_seed=args.base_seed,
|
|
218
|
+
)
|
|
219
|
+
logger.info("Scenario generated: %s", run_dir)
|
|
220
|
+
|
|
221
|
+
|
|
222
|
+
def handle_validate_grid(args, logger: logging.Logger) -> None:
|
|
223
|
+
from bsvae.simulation.scenario import validate_grid
|
|
224
|
+
|
|
225
|
+
result = validate_grid(args.grid_dir)
|
|
226
|
+
logger.info(
|
|
227
|
+
"Grid validation: checked %d/%d rows, all required files present=%s",
|
|
228
|
+
result["checked_rows"],
|
|
229
|
+
result["manifest_rows"],
|
|
230
|
+
result["all_required_files_present"],
|
|
231
|
+
)
|
|
232
|
+
|
|
233
|
+
|
|
147
234
|
def cli(argv=None):
|
|
148
235
|
parser = build_parser()
|
|
149
236
|
args = parser.parse_args(argv)
|
|
@@ -153,6 +240,14 @@ def cli(argv=None):
|
|
|
153
240
|
handle_generate(args, logger)
|
|
154
241
|
elif args.command == "benchmark":
|
|
155
242
|
handle_benchmark(args, logger)
|
|
243
|
+
elif args.command == "init-config":
|
|
244
|
+
handle_init_config(args, logger)
|
|
245
|
+
elif args.command == "generate-grid":
|
|
246
|
+
handle_generate_grid(args, logger)
|
|
247
|
+
elif args.command == "generate-scenario":
|
|
248
|
+
handle_generate_scenario(args, logger)
|
|
249
|
+
elif args.command == "validate-grid":
|
|
250
|
+
handle_validate_grid(args, logger)
|
|
156
251
|
else:
|
|
157
252
|
parser.error(f"Unknown command: {args.command}")
|
|
158
253
|
|