boyuegrn

BoYueGRN model checkpoints

Model weights for BoYueGRN, an amortized causal-discovery framework that infers directed gene regulatory networks (GRNs) from single-cell RNA-seq. BoYueGRN is trained exclusively on 10,000 synthetic structural causal models; a single forward pass infers both edge probabilities and regulatory directions for any new dataset, and TF-centric sliding windows with asymmetric fusion extend the fixed-size model to whole-transcriptome coverage.

About the name. "BoYue" (博约, bó yuē) is taken from Su Shi's (苏轼, Song dynasty) "博观而约取，厚积而薄发" — "observe broadly and take precisely, accumulate richly and release sparingly": the model observes a broad ensemble of synthetic SCMs offline, then amortizes that cost into a single forward pass on any new dataset.

Companion code repository (GitHub): https://github.com/holaoctopus/BoYueGRN (pip-installable boyue package + full training / benchmark / case-study pipeline).

---

Contents

checkpoints/
├── main/                          # production models (paper results)
│   ├── edge_v3_seed{0,1,2,3}.pt                    # edge existence, 4-seed ensemble
│   ├── dir_specialist_tf_non_tf_seed{0,1,2,3}.pt   # NT direction specialist (TF→non-TF)
│   └── dir_specialist_tf_tf_seed0.pt               # TT direction specialist (TF→TF)
└── ablation/                      # 7 ablation models (Table 2)
    ├── edge_v3_20k_seed0.pt
    ├── edge_g300_seed0.pt
    ├── edge_rdrop_seed0.pt
    ├── dir_weighted_w3_seed0.pt
    ├── dir_lowrank_r64_seed0.pt
    ├── dir_attn_seed0.pt
    └── joint_lambda03_seed0.pt

• main/ ≈ 896 MB (9 files)
• ablation/ ≈ 699 MB (7 files)
• total ≈ 1.6 GB (16 files)

Each checkpoint is a torch state_dict dict:

• edge models → {'encoder', 'edge_head'}
• direction models → {'encoder', 'dir_head'}
• joint model → {'encoder', 'edge_head', 'dir_head', 'lambda_dir'}

Loading

Install the companion package, then point load_ensemble at these files:

pip install -e /path/to/BoYueGRN   # the GitHub repo (boyue package)

import torch
from boyue import load_ensemble

inf = load_ensemble(
    edge_ckpts=['checkpoints/main/edge_v3_seed0.pt'],
    dir_ckpts=['checkpoints/main/dir_specialist_tf_non_tf_seed0.pt'],
    device=torch.device('cpu'),    # or torch.device('cuda')
)

Quick sanity check on a random 200×200 expression matrix:

import numpy as np
X = np.random.gamma(2.0, 1.0, (200, 200)).astype(np.float32)
out = inf.predict_from_expression(X)
print(out.keys())   # {'edge_p', 'dir_p', ...}

Downloading

from huggingface_hub import snapshot_download
snapshot_download(repo_id="Holaoctopus/boyuegrn", repo_type="model",
                  local_dir="./boyuegrn_ckpt")

License

• Code (boyue/ and pipeline scripts in the GitHub repo): Apache License 2.0.
• Weights in this repository: Apache License 2.0 (see LICENSE).