# Pretrained models & bundles

## Overview

Pretrained MethScope models are distributed from the methscope_data repository as self-contained bundles — a single file that carries both the model and the MRMP feature definition it needs, so a query `.cg` can be run without supplying a separate `.cm` reference.

There are three bundle kinds:

file | task | run with
--- | --- | ---
`.ubjx` | cell-type / trait classifier | `methscope predict`
`.refx` | deconvolution reference | `methscope deconv`
`.updecx` | CpG-level upscaling decoder | `methscope upscale`

## Using a pretrained bundle

Because a bundle carries its own MRMP, pass it directly — no unbundling needed:

    methscope predict query.cg   hg38_celltype.ubjx     > labels.tsv
    methscope deconv  mixture.cg  hg38_65celltypes.refx > props.tsv
    methscope upscale -o out.cg   hg38_10k1.updecx query.cg

Inspect a bundle — its framework mark, on-disk layout, and model summary — without running it:

    methscope inspect hg38_celltype.ubjx

## Bundling and unbundling

Wrap any model together with the MRMP it needs. By convention the bundle gets an `x` suffix (`.ubj` → `.ubjx`, `.ref` → `.refx`, `.updec` → `.updecx`):

    # classifier: booster + MRMP (+ class labels, + framework mark)
    methscope bundle -m ref.mrmp -k xgboost -l labels.tsv -o model.ubjx booster.ubj

    # unwrap a bundle back into its parts (names derived from the bundle path)
    methscope unbundle model.ubjx          #  -> model.ubj + model.mrmp

## Bundle format (technical)

A bundle (magic `MSBNDL1`) uses an MRMP-first layout: the MRMP `.cm` is the file prefix (offset 0), so YAME tools read it directly (`yame summary model.ubjx` works), and any subcommand that expects a `<ref.mrmp>` also accepts a bundle in that slot. After the MRMP come the container sections:

- `mrmp` — the MRMP feature definition (a fmt2 YAME `.cm`).
- `kind` — the framework mark: `xgboost` / `threshold` / `logistic` for a classifier (`predict` requires it), or `refx` for a deconvolution reference. Upscale decoders need no mark.
- `outcpg` (upscale only) — a genome-wide mask of the imputed CpG locations, letting `upscale` emit a whole-genome `.cg`.
- `model` — the raw inner model bytes: an XGBoost UBJ booster, a `methscope-linear` text spec, an `.updec` decoder, or a `.refx` signature TSV.

Because the model and its MRMP travel together, predictions are reproducible and you never have to hand-match a loose `.mrmp` to the right model.

## Models in R

The MethScope R package ships built-in models — e.g. `Zhou2025_HumanAtlas_P1000()` and `Liu2021_MouseBrain_P1000()` — carrying their MRMP metadata, used the same way through `PredictCellType()`. See the Get started tutorial and the methscope-cli command-line guide.