MPAC / README.md

Update README.md

e6e6cd9 verified about 1 month ago

3.97 kB

---
license: cc-by-4.0
library_name: mpac
tags:
  - biology
  - genomics
  - dna
  - mpra
  - cis-regulatory
  - variant-effect-prediction
pipeline_tag: other
---
# MPAC

MPAC (Malinois with Parallel Aggregated Cross-validation) predicts cis-regulatory
activity of 200 bp human sequences in K562, HepG2 and SK-N-SH, and the allelic skew
caused by non-coding variants.

[Identifying non-coding variant effects at scale via machine learning models of
cis-regulatory reporter assays](https://doi.org/10.1101/2025.04.16.648420).

This repository holds the 110 published checkpoints, converted to safetensors from
the [Zenodo deposit](https://doi.org/10.5281/zenodo.15178434) with no retraining or
modification.

## Usage

```python
from modeling_mpac import MPACEnsemble
# Loads the ten models that held chr7 out of training
ensemble = MPACEnsemble.from_pretrained("saarantras1/MPAC", chromosome=7, device="cuda")
preds = ensemble.predict(["ACGT" * 50], device="cuda")   # (n, 3): K562, HepG2, SKNSH
```

Use `from_pretrained` and `predict` rather than loading a checkpoint or calling the
model directly: they select the ensemble that did not train on your query's
chromosome, and they add the MPRA vector context and average over both strands.
Skipping either step returns plausible-looking but wrong numbers instead of an error.

`predict` follows `vcf_predict.py` from the upstream code base, which generated the
published predictions: the reverse strand is the reverse complement of the 200 bp
insert placed back in the forward-orientation vector, matching the assay, rather
than a reverse complement of the whole 600 bp construct.

MPAC covers autosomes only; `from_pretrained` raises on chrX, chrY and anything else
with no held-out fold.

For allelic skew, pass matched reference and alternate contexts. Each variant is tiled into eighteen
200 bp windows at stride 10 and averaged, reproducing the scheme behind the
published predictions.

```python
out = ensemble.predict_skew(ref_contexts, alt_contexts, device="cuda")
out["skew"]   # (n, 3), alt minus ref
```

Command-line tools for MPAC can be found at:
[Reilly-Lab-Yale/coda_mpac](https://github.com/Reilly-Lab-Yale/coda_mpac).

Which provide greater control of prediction parameters including (but not limited to):
  window number
  step size
  strand reduction
  insert/full plasmid reverse complement
  window aggregation (average, max, min, etc.)
  
An example prediction for SNVs from a VCF can be found in the methods of the publication and below:

python vcf_predict.py --artifact_path {10X $MODEL} \ CHROMOSOME HOLDOUT MODELS TO ENSEMBLE
--vcf_file ${VCF} \ VARIANTS OF INTEREST
--fasta_file ${FASTA} \ REFERENCE GENOME
--output ${OUTPUT} \ OUTPUT PATH
--relative_start 9 \ START WINDOW
--relative_end 180 \ END WINDOW
--step_size 10 \ N WINDOWS
--strand_reduction mean \ REDUCTION METHOD OF FWD/REV STRAND PREDICTIONS
--window_reduction mean \ REDUCTION METHOD OF PREDICTION WINDOWS
And include specialized prediction methods for:
  small indels (<= 10bp recommended) (vcf_predict_indel.py)
  haplotypes (vcf_predict_haplotype.py)
Which can be run in the same way as vcf_predict.py but with modifications to handle sequence padding (vcf_predict_indel.py) or windowing (vcf_predict_haplotype.py)
## 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}
}
```

## License

CC-BY-4.0, matching the Zenodo deposit. `modeling_mpac.py` derives from the MIT
licensed model code in [sjgosai/boda2](https://github.com/sjgosai/boda2) and retains
that notice.

	---
	license: cc-by-4.0
	library_name: mpac
	tags:
	- biology
	- genomics
	- dna
	- mpra
	- cis-regulatory
	- variant-effect-prediction
	pipeline_tag: other
	---

	# MPAC

	MPAC (Malinois with Parallel Aggregated Cross-validation) predicts cis-regulatory
	activity of 200 bp human sequences in K562, HepG2 and SK-N-SH, and the allelic skew
	caused by non-coding variants.

	[Identifying non-coding variant effects at scale via machine learning models of
	cis-regulatory reporter assays](https://doi.org/10.1101/2025.04.16.648420).

	This repository holds the 110 published checkpoints, converted to safetensors from
	the [Zenodo deposit](https://doi.org/10.5281/zenodo.15178434) with no retraining or
	modification.

	## Usage

	```python
	from modeling_mpac import MPACEnsemble

	# Loads the ten models that held chr7 out of training
	ensemble = MPACEnsemble.from_pretrained("saarantras1/MPAC", chromosome=7, device="cuda")

	preds = ensemble.predict(["ACGT" * 50], device="cuda") # (n, 3): K562, HepG2, SKNSH
	```

	Use `from_pretrained` and `predict` rather than loading a checkpoint or calling the
	model directly: they select the ensemble that did not train on your query's
	chromosome, and they add the MPRA vector context and average over both strands.
	Skipping either step returns plausible-looking but wrong numbers instead of an error.

	`predict` follows `vcf_predict.py` from the upstream code base, which generated the
	published predictions: the reverse strand is the reverse complement of the 200 bp
	insert placed back in the forward-orientation vector, matching the assay, rather
	than a reverse complement of the whole 600 bp construct.

	MPAC covers autosomes only; `from_pretrained` raises on chrX, chrY and anything else
	with no held-out fold.

	For allelic skew, pass matched reference and alternate contexts. Each variant is tiled into eighteen
	200 bp windows at stride 10 and averaged, reproducing the scheme behind the
	published predictions.

	```python
	out = ensemble.predict_skew(ref_contexts, alt_contexts, device="cuda")
	out["skew"] # (n, 3), alt minus ref
	```

	Command-line tools for MPAC can be found at:
	[Reilly-Lab-Yale/coda_mpac](https://github.com/Reilly-Lab-Yale/coda_mpac).

	Which provide greater control of prediction parameters including (but not limited to):
	window number
	step size
	strand reduction
	insert/full plasmid reverse complement
	window aggregation (average, max, min, etc.)

	An example prediction for SNVs from a VCF can be found in the methods of the publication and below:

	python vcf_predict.py --artifact_path {10X $MODEL} \ CHROMOSOME HOLDOUT MODELS TO ENSEMBLE
	--vcf_file ${VCF} \ VARIANTS OF INTEREST
	--fasta_file ${FASTA} \ REFERENCE GENOME
	--output ${OUTPUT} \ OUTPUT PATH
	--relative_start 9 \ START WINDOW
	--relative_end 180 \ END WINDOW
	--step_size 10 \ N WINDOWS
	--strand_reduction mean \ REDUCTION METHOD OF FWD/REV STRAND PREDICTIONS
	--window_reduction mean \ REDUCTION METHOD OF PREDICTION WINDOWS

	And include specialized prediction methods for:
	small indels (<= 10bp recommended) (vcf_predict_indel.py)
	haplotypes (vcf_predict_haplotype.py)

	Which can be run in the same way as vcf_predict.py but with modifications to handle sequence padding (vcf_predict_indel.py) or windowing (vcf_predict_haplotype.py)
	## 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}
	}
	```

	## License

	CC-BY-4.0, matching the Zenodo deposit. `modeling_mpac.py` derives from the MIT
	licensed model code in [sjgosai/boda2](https://github.com/sjgosai/boda2) and retains
	that notice.