| --- |
| library_name: pytorch |
| tags: |
| - bulk-rna-seq |
| - single-cell-rna-seq |
| - cvae |
| - set-transformer |
| - bioinformatics |
| --- |
| |
| # PBISC |
|
|
| Private research snapshot for PBISC bulk RNA-seq to pseudo-single-cell generation. |
|
|
| This repository contains the active training code and the core checkpoint lineage. Raw |
| single-cell source matrices, recipe blocks, patient-level inputs, generated cell matrices, |
| and large analysis outputs are intentionally excluded. |
|
|
| ## Checkpoint lineage |
|
|
| | Folder | Role | State | |
| |---|---|---| |
| | `checkpoints/B048_L1_10x` | Hard-routed expert CVAE baseline and warm-start anchor | Complete | |
| | `checkpoints/Model2_A2_SetLoss` | B048 warm-start with set-level MMD, pseudobulk, and variance losses | Complete | |
| | `checkpoints/M001_R4_ISAB` | B048-based bulk-gated ISAB communication refiner with joint fine-tuning | Complete, 6,144 steps | |
| | `checkpoints/M2A2_R4_Joint` | Model2-A2 base plus the R4 communication refiner | Interrupted at 2,158/3,072 steps | |
|
|
| Use `checkpoint_best.pt` for evaluation or inference. Use |
| `checkpoints/M2A2_R4_Joint/checkpoint_latest.pt` to resume the interrupted M2A2-R4 run. |
| That resume checkpoint includes model, refiner, optimizer, scheduler, and run state. |
|
|
| The exact Model2-A2 initialization expected by M2A2-R4 is |
| `checkpoints/Model2_A2_SetLoss/checkpoint_latest.pt`. |
|
|
| ## Code layout |
|
|
| - `code/model/vae_bulk2sc`: base CVAE, M001 communication architecture, trainers, tests, |
| and reproduction notes. |
| - `code/model_2_setloss_cvae`: set-loss experiments and disease-signal evaluation code. |
| - `code/model_3_set_transformer`: decoder-side set-transformer experiment. This branch was |
| concluded negative and is retained as research evidence. |
| - `code/model_4_population_refiner`: population-refiner planning and implementation records. |
| - `code/inference`: retained PBISC inference utilities. |
| - `code/project_docs`: reassembly, missing-asset, and project manifest documents. |
|
|
| ## Data required for retraining |
|
|
| The upload does not contain the approximately 107 GB training data. Local retraining uses: |
|
|
| - `single-cell-data-block-blood` source block. |
| - `blood-kmatrix-recipes-v1`. |
| - Repaired `blood-kmatrix-recipes-v1-10x` overlay. |
| - The 20,097-gene `metadata/var.parquet` panel. |
|
|
| The original environment used Python 3.12.13 and PyTorch |
| `2.12.0.dev20260306+cu128`. A historical environment freeze is retained under |
| `code/model/vae_bulk2sc/_REPRODUCE/env`. |
|
|
| ## Relocation warning |
|
|
| Historical run metadata contains absolute paths under `/home/sj_server_1/PBISC`. |
| M2A2-R4 resume validation compares `recipe_root`, `source_root`, and `gene_panel_path` |
| against the values embedded in `checkpoint_latest.pt`. Preserve a compatibility symlink |
| for the old project root, or migrate those three saved path values before resuming. |
|
|
| ## Integrity and trust |
|
|
| SHA-256 values are recorded in `manifests/CHECKPOINTS.sha256`. These PyTorch checkpoints |
| come from the private PBISC training environment and may require |
| `torch.load(..., weights_only=False)`. Do not load modified copies from untrusted sources. |
|
|
|
|
