Add the 110 MPAC crossval checkpoints as safetensors

README.md

@@ -0,0 +1,165 @@
+---
+license: cc-by-4.0
+library_name: mpac
+tags:
+  - biology
+  - genomics
+  - dna
+  - mpra
+  - cis-regulatory
+  - variant-effect-prediction
+pipeline_tag: other
+---
+
+# MPAC: Malinois with Parallel Aggregated Cross-validation
+
+MPAC predicts cis-regulatory activity of 200 bp human DNA sequences in three cell
+lines (K562, HepG2, SK-N-SH), and the allelic skew caused by non-coding variants.
+It is a convolutional network trained on massively parallel reporter assay (MPRA)
+measurements from 776,474 sequences.
+
+This repository holds the **110 MPAC checkpoints**. The autosomes are split into 11
+pairs whose chromosome numbers sum to 23 (chr1+chr22, chr2+chr21, ... chr11+chr12).
+Each pair is held out as a test fold for 10 models that differ in which pair was
+used for validation, giving 11 x 10 = 110 models under `crossval/`.
+
+All 110 share one architecture (`BassetBranched`, 4,110,587 parameters) described by
+the single `config.json`.
+
+## Why there is no default model
+
+Every MPAC checkpoint is tied to a chromosome fold, so there is deliberately no
+`model.safetensors` at the repository root. Scoring a sequence with a fold that
+trained on its chromosome leaks training data and inflates accuracy, and it does so
+silently -- nothing errors, the numbers just get better than they should be.
+Nominating one checkpoint as "the" model would make that the default behaviour.
+
+The correct ensemble for a query is the fold whose **test** chromosomes contain the
+query's source chromosome; its 10 replicate predictions are averaged.
+`MPACEnsemble.from_pretrained` picks it for you, and `provenance.json` records the
+test and validation chromosomes for every file.
+
+Only autosomes are covered. Sequences on chrX, chrY, or outside the human genome
+have no held-out fold; `from_pretrained` raises rather than guessing.
+
+## Usage
+
+```python
+from modeling_mpac import MPACEnsemble
+
+# The ten models that never saw chr7 during training
+ensemble = MPACEnsemble.from_pretrained("<repo-id>", chromosome=7, device="cuda")
+
+sequences = ["ACGT" * 50, "TTGC" * 50]   # 200 bp each
+preds = ensemble.predict(sequences, device="cuda")   # (2, 3) tensor
+print(dict(zip(ensemble.output_names, preds[0].tolist())))
+```
+
+`predict` handles the two steps that are easy to get wrong, and that produce
+plausible-looking but incorrect numbers when omitted:
+
+1. **MPRA vector context.** The models were trained on the full 600 bp construct, not
+   a bare 200mer. `predict` pads each sequence with the flanking plasmid sequence
+   (`MPRA_UPSTREAM` / `MPRA_DOWNSTREAM`). If you call the model directly you must
+   supply a `(batch, 4, 600)` tensor yourself, e.g. via `add_flanks(x)`.
+2. **Reverse-complement averaging.** Predictions are averaged over the forward strand
+   and the reverse complement. The flip is applied to the **flanked 600 bp tensor**,
+   not to the bare insert -- flipping the insert and then attaching
+   forward-orientation flanks is not a reverse complement, and costs about 0.05
+   Pearson. Disable with `rc_average=False` only if you know why.
+
+Allelic skew for a variant is the difference in predicted activity between the
+alternate and reference sequence. The preprint averages 18 sliding 200 bp windows
+placed at 10 bp increments around the variant; a single variant-centred window is
+used when reproducing empirical MPRA measurements directly. See
+[john-c-butts/MPAC](https://github.com/john-c-butts/MPAC) for that tooling.
+
+## Outputs
+
+Three values per sequence, in the order `["K562", "HepG2", "SKNSH"]`, on the scale of
+MPRA activity log2 fold-change. They are not probabilities and are not calibrated
+across cell types.
+
+## Verified performance
+
+Predicted vs empirical MPRA activity across all 754,588 length-200 sequences on
+covered chromosomes, each scored by the ensemble that held its chromosome out:
+
+| Cell type | Pearson r | Preprint (Fig. 1B) |
+| --- | --- | --- |
+| K562 | 0.892 | 0.89 |
+| HepG2 | 0.888 | 0.89 |
+| SK-N-SH | 0.879 | 0.88 |
+
+Applying an activity-noise filter raises these (row-wise `lfcSE < 0.5` gives
+0.909 / 0.906 / 0.902 at n = 639,806). Reproduce with `verify.py`.
+
+The inference path (flanking, reverse-complement averaging, one-hot encoding) was
+separately checked against an independent implementation on the chr7+chr13 test set
+and agrees to five decimal places in both Pearson and Spearman correlation.
+
+## Limitations
+
+- Trained on episomal reporter activity in three immortalized cell lines. Predictions
+  are a model of the assay, not of endogenous expression in tissue.
+- The 200 bp variable region is the entire input. Long-range regulatory context,
+  chromatin state, and cell types outside the three assayed lines are out of scope.
+- Accuracy on sequences unlike the training library (non-human, heavily repetitive,
+  extreme GC) is uncharacterized.
+
+## Provenance
+
+The 110 checkpoints were trained by the authors of the preprint below and deposited
+at [Zenodo](https://doi.org/10.5281/zenodo.15178434). This repository is a
+repackaging: weights are converted from the original `torch_checkpoint.pt` pickles to
+safetensors, with no retraining or modification. All 110 files here were confirmed
+byte-identical to the Zenodo deposit before conversion, and every converted
+checkpoint reproduces the original `boda` loader bitwise. `provenance.json` maps each
+file to its original source path, training timestamp, and chromosome split.
+
+The architecture originates with Malinois in
+[sjgosai/boda2](https://github.com/sjgosai/boda2). MPAC variant-effect tooling lives
+at [john-c-butts/MPAC](https://github.com/john-c-butts/MPAC) and
+[Reilly-Lab-Yale/MPAC_gnomAD_and_satmut](https://github.com/Reilly-Lab-Yale/MPAC_gnomAD_and_satmut).
+
+## License
+
+**CC-BY-4.0**, matching the Zenodo deposit these checkpoints are published under.
+Use them for any purpose, including commercially, with attribution to the paper
+below.
+
+`modeling_mpac.py` is derived from the model-definition code in
+[sjgosai/boda2](https://github.com/sjgosai/boda2), which is MIT licensed, and it
+retains that notice. MIT permits redistribution here; the CC-BY-4.0 term above
+governs the weights.
+
+## Citation
+
+```bibtex
+@article{butts2025mpac,
+  title   = {Identifying non-coding variant effects at scale via machine learning
+             models of cis-regulatory reporter assays},
+  author  = {Butts, John C. and Rong, Stephen and Gosai, Sager J. and
+             Castro, Rodrigo I. and Noon, Mackenzie and Adeniran, Kehinde and
+             Ghosh, Rohit and Sabeti, Pardis C. and Tewhey, Ryan and Reilly, Steven K.},
+  journal = {bioRxiv},
+  year    = {2025},
+  doi     = {10.1101/2025.04.16.648420}
+}
+```
+
+Malinois and the CODA framework:
+
+```bibtex
+@article{gosai2024coda,
+  title   = {Machine-guided design of cell-type-targeting cis-regulatory elements},
+  author  = {Gosai, Sager J. and Castro, Rodrigo I. and Fuentes, Natalia and
+             Butts, John C. and Mouri, Kousuke and Alasoadura, Michael and
+             Kales, Susan and Nguyen, Thanh Thanh L. and Noche, Ramil R. and
+             Rao, Arya S. and Joy, Mary T. and Sabeti, Pardis C. and
+             Reilly, Steven K. and Tewhey, Ryan},
+  journal = {Nature},
+  year    = {2024},
+  doi     = {10.1038/s41586-024-08070-z}
+}
+```

config.json

@@ -0,0 +1,26 @@
+{
+  "branched_activation": "ReLU",
+  "branched_channels": 140,
+  "branched_dropout_p": 0.5757068086404574,
+  "conv1_channels": 300,
+  "conv1_kernel_size": 19,
+  "conv2_channels": 200,
+  "conv2_kernel_size": 11,
+  "conv3_channels": 200,
+  "conv3_kernel_size": 7,
+  "input_len": 600,
+  "linear_activation": "ReLU",
+  "linear_channels": 1000,
+  "linear_dropout_p": 0.11625456877954289,
+  "n_branched_layers": 3,
+  "n_linear_layers": 1,
+  "n_outputs": 3,
+  "output_names": [
+    "K562",
+    "HepG2",
+    "SKNSH"
+  ],
+  "use_batch_norm": true,
+  "use_weight_norm": false,
+  "variable_region_len": 200
+}

crossval/test_10_13/val_11_12.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f4edafa0b53b6ca2a12947c2b6521244103e273cd5e836e2bd12bbc8fe064bc3
+size 16445652

crossval/test_10_13/val_1_22.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3ba7e8c743088b9769101fdeb9e00381fa3ce94aa14da28cbdae22de8f1cee15
+size 16445652

crossval/test_10_13/val_2_21.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0264699c0a598bb54f3c972886262fcdea1791742af06ac8b9683705f9ccfc48
+size 16445652

crossval/test_10_13/val_3_20.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:be78b35c3e0b457f747eded7d144052c0dd48f0d1aad9165360bd7aadeedfa6a
+size 16445652

crossval/test_10_13/val_4_19.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ff7cb36fd02f103b196c94ea2bad9a0daaea3115797403a497a998ffc03b076c
+size 16445652

crossval/test_10_13/val_5_18.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b8bd32450188a58640638ed103534cc2af70461f1d152f6b7c5ba02f52ed1eff
+size 16445652

crossval/test_10_13/val_6_17.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d850c7142c017e443b4acdc6eab96ab7a06cd9ff16ff0eed81c13b662c986d5a
+size 16445652

crossval/test_10_13/val_7_16.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1e827aeb905e101e41e5c0c04ae5acd25d6164effaa4110011dc40b0dac8f425
+size 16445652

crossval/test_10_13/val_8_15.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:639d9a83be65c08312fdaa682d361597e975b070ecd2e637232aa067984c4704
+size 16445652

crossval/test_10_13/val_9_14.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5dcdb66222aa6219e3d38d718be45de98836121e13ac072b4771d4f4904cd1dd
+size 16445652

crossval/test_11_12/val_10_13.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f21c981063fb0989036d6cda2890f78bffa821063f3a839c965bde1c33dd5f05
+size 16445652

crossval/test_11_12/val_1_22.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:46889bc9ff68f71cbdce7542a0a35e13da3b8b1b84ec02c91d4e086e64603e3e
+size 16445652

crossval/test_11_12/val_2_21.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:36757d938e610443e898292cdd3861ab30f91f907a2e68daae28e55c3131e202
+size 16445652

crossval/test_11_12/val_3_20.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ce70e5af301aa9d64343e266003c62d13f4a3f63f48ab918475c348d11fcadd7
+size 16445652

crossval/test_11_12/val_4_19.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:971767fe36688e4708b0bc85cf119c0eb9c1787c3b3dfcb583fe72fce2a0b511
+size 16445652

crossval/test_11_12/val_5_18.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:20191dcdc37479cbb94948c617e3fc07edce4680537039e4e1898e76c91d674d
+size 16445652

crossval/test_11_12/val_6_17.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b506ac488d8c9c4c655dd7a82870021ac56eafcc93fa59d8e6e93caacba50409
+size 16445652

crossval/test_11_12/val_7_16.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:bff9e3e1b12666b6c5e4c2fddbfc2082a541f2c3325377ccebbd83298f497419
+size 16445652

crossval/test_11_12/val_8_15.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:554423caab7027a16c6db80ee2081333e8d89292f6dd55ed56ca3033ca1603ea
+size 16445652

crossval/test_11_12/val_9_14.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e46f7d52b63702177a20a95edafaa8e786b44a7905c0073f9fc6ed6e44424db6
+size 16445652

crossval/test_1_22/val_10_13.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5f51aa6c9daad5ebcd57a9a37294a365b02e58609b26b1738a397274aa7dd432
+size 16445652

crossval/test_1_22/val_11_12.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:eb278df1ba736d9ea3b208bd77c27bc2bccd5c9a28188b9627a060eea3873ef4
+size 16445652

crossval/test_1_22/val_2_21.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1e5a94110ab1e9c6bfa89039d74cd689b3158c354653aaee3e540ad09c38651b
+size 16445652

crossval/test_1_22/val_3_20.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b1e52be65ea30acbc21ce9eb134a48e1d4bd9a22d626cc9a58ccc1f2bc3157b2
+size 16445652

crossval/test_1_22/val_4_19.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d2d1b556a765cf6671a820cd93bcf00d56771e1ef8ec1ad44c573868c6949fe5
+size 16445652

crossval/test_1_22/val_5_18.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5a4d2fee3a61e858768e43f7cdcd58c59a78f55afcd0a7972eed11776a19acdb
+size 16445652

crossval/test_1_22/val_6_17.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:afe9b89c183118a1d574be81870eb9cfaa64784d2e142932c52af05ac995b811
+size 16445652

crossval/test_1_22/val_7_16.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c347a5b62e6b29171fdf34747b95c88dd0e016b8a2f4a04147b1e5101f01f4c5
+size 16445652

crossval/test_1_22/val_8_15.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5af860532e6df1804fb875e6f346ab7cc6ffaf18f137d6718b5eca2547476bb0
+size 16445652

crossval/test_1_22/val_9_14.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:43d5ef50852901435ed5f61cfae2690e99d4ea38f3067c3a99d7770f2bce0a44
+size 16445652

crossval/test_2_21/val_10_13.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ff24474f4fc5f7a0e01f9a6d056827ece7a57b8990b0b779d2b711ea94802866
+size 16445652

crossval/test_2_21/val_11_12.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:08dea24dcca3eed96e2c38363de38c8ccffca9aeb205001964ead8459455b39e
+size 16445652

crossval/test_2_21/val_1_22.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d7bb47cd71be84496488e012e5a700c0772a8949423354efa29756cfbf2423b3
+size 16445652

crossval/test_2_21/val_3_20.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a66d45dd0f12117b1386ad70849f6b617222f07cbff2871b8865df39c42b5aba
+size 16445652

crossval/test_2_21/val_4_19.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:babc74a57078874ec4efa999a1e86a36522201c2bb2de08060427e7088632c6a
+size 16445652

crossval/test_2_21/val_5_18.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5def7f2aa52b34db37548e2c9b8dd9c2e1bc4d9cbca825e6d3e3aae9fecd3660
+size 16445652

crossval/test_2_21/val_6_17.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3f9fb591d248e2fb5b3caf30b606feee3056990908b0bdd8378d485d8d2c477a
+size 16445652

crossval/test_2_21/val_7_16.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c15407a665a4ef5819b9e038a3ee374f5d42aaf767bea764dea913db0b611f0b
+size 16445652

crossval/test_2_21/val_8_15.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:89087c9af0956e26664bf1d3bd804216394292e85ae6dff8d12369dafac858eb
+size 16445652

crossval/test_2_21/val_9_14.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:73b76f1a25ab6e8353b8ba60cb8a05417f6604637eb5f75f78853735a86a759e
+size 16445652

crossval/test_3_20/val_10_13.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9a04999edbbd45cfe305368ff814ff0e9c83c154111dd160ea142cd292f3a940
+size 16445652

crossval/test_3_20/val_11_12.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:258fdbcc5c368cda367c82fa73357565276140e3b4f33af614fd25d62253ffb3
+size 16445652

crossval/test_3_20/val_1_22.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f7ca76d95d70b6ae1e5d3bb4a785dfad92285773941baec984f57a22978a4887
+size 16445652

crossval/test_3_20/val_2_21.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:049cb28366427f3323af6b27e5256b772cb5c6b779a05a5b5557aa4d639de27c
+size 16445652

crossval/test_3_20/val_4_19.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f9733c13c420a2a50cba26f9b8aeea516c782854b844f20d8b2d5b3057dc0906
+size 16445652

crossval/test_3_20/val_5_18.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:418d7333c14d70afee24f2ece1aff43cf00497930d89afa413f239557818291f
+size 16445652

crossval/test_3_20/val_6_17.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:67ed2ee69d23350ff6b159272eee3a16d53664bb8d07ec640c530069c993576b
+size 16445652

crossval/test_3_20/val_7_16.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:04f1cefd40405b7b5b318944e3a3c275744e540a0ec8a877587ad1bfea41cb32
+size 16445652