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.
Files changed (40) hide show
  1. {bsvae-0.3.0 → bsvae-0.3.1}/PKG-INFO +43 -1
  2. {bsvae-0.3.0 → bsvae-0.3.1}/README.md +42 -0
  3. {bsvae-0.3.0 → bsvae-0.3.1}/pyproject.toml +2 -1
  4. {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/cli/simulate.py +98 -3
  5. bsvae-0.3.1/src/bsvae/cli/sweep_k.py +511 -0
  6. {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/cli/train.py +15 -0
  7. {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/models/gmm_prior.py +12 -4
  8. {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/models/losses.py +56 -36
  9. bsvae-0.3.1/src/bsvae/simulation/__init__.py +24 -0
  10. {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/simulation/generate.py +2 -2
  11. bsvae-0.3.1/src/bsvae/simulation/scenario.py +556 -0
  12. {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/utils/training.py +119 -11
  13. bsvae-0.3.0/src/bsvae/simulation/__init__.py +0 -5
  14. {bsvae-0.3.0 → bsvae-0.3.1}/LICENSE +0 -0
  15. {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/__init__.py +0 -0
  16. {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/cli/__init__.py +0 -0
  17. {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/cli/networks.py +0 -0
  18. {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/hyperparam.ini +0 -0
  19. {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/latent/__init__.py +0 -0
  20. {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/latent/latent_analysis.py +0 -0
  21. {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/latent/latent_export.py +0 -0
  22. {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/main.py +0 -0
  23. {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/models/__init__.py +0 -0
  24. {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/models/decoder.py +0 -0
  25. {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/models/encoder.py +0 -0
  26. {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/models/gmvae.py +0 -0
  27. {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/models/vae.py +0 -0
  28. {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/networks/__init__.py +0 -0
  29. {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/networks/cli.py +0 -0
  30. {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/networks/extract_networks.py +0 -0
  31. {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/networks/module_extraction.py +0 -0
  32. {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/networks/utils.py +0 -0
  33. {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/simulation/metrics.py +0 -0
  34. {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/utils/__init__.py +0 -0
  35. {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/utils/datasets.py +0 -0
  36. {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/utils/evaluate.py +0 -0
  37. {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/utils/helpers.py +0 -0
  38. {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/utils/hierarchy.py +0 -0
  39. {bsvae-0.3.0 → bsvae-0.3.1}/src/bsvae/utils/initialization.py +0 -0
  40. {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.0
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.0" # dynamically resolved by poetry-dynamic-versioning
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 Simulate omics data with known block-diagonal module structure.
7
- benchmark ARI/NMI/enrichment vs WGCNA/GNVAE on simulated data.
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=42)
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