# MeRN tutorial

A walkthrough of MeRN on mouse embryogenesis data: loading a pretrained model, extracting the
metabolic and background embeddings, decoding reaction activity, building KEGG pathway scores and
data-driven pathways (DDPs), and comparing metabolic coordination between wild-type and *Folr1*
knockout embryos.

## Running it

The notebook, example data, and pretrained models are included in the GitHub
repository. Installing `mern` with pip installs the library; clone the repository
to get the complete tutorial:

```bash
git clone https://github.com/wagnerlab-berkeley/mern.git
cd mern/docs/source/tutorials
conda env create -f environment.yml
conda activate mern-tutorial
jupyter lab MeRN_tutorial.ipynb
```

If you already have a clone, start from its `docs/source/tutorials` directory
and run the environment and notebook commands above.

Create the environment from this directory: `environment.yml` installs the `mern` package from the
surrounding clone by relative path.

The supplied data are already prepared, and the notebook loads pretrained models
on CPU by default. You can run the analyses without preprocessing data or
training new models. Everything the notebook reads is in this directory.

The first run expands the five model checkpoints to about 524 MB. Kaleido 1.x also requires
Chrome for the notebook's static image exports; if Chrome is not installed, run
`plotly_get_chrome` after creating the environment.

### Installing without conda

```bash
brew install graphviz            # or: apt-get install graphviz graphviz-dev
pip install -e ../../.. kaleido jupyterlab ipywidgets
```

## What this folder contains

| path | contents |
| --- | --- |
| `data/main_wt_anndata_pp_subsample.h5ad.gz` | wild-type cells, model feature space, log1p `X` plus raw `counts_RNA` |
| `data/folr1_anndata_subsample.h5ad.gz` | *Folr1* knockout cells, same feature space |
| `data/folr1_average_enzyme_activity.csv.gz` | knockout reaction activity, its own replicate ensemble |
| `data/wt_ref_color_mapping.csv` | cell-type colors used in the paper's figures |
| `model/mern_rep_0/model.pt.gz` … `mern_rep_4/` | five pretrained replicate checkpoints, gzipped |
| `model/mern_rep_0/metabolic_clustering_0.4.csv` | the paper's metabolic clusters, for comparison with the ones recomputed here |

## About the subsampled data

This is a **cell subsample** of the published dataset. The full study covers
94,204 cells (62,433 wild-type, 31,771 *Folr1*); here is a stratified sample of those,
drawn proportionally across (metabolic state x germ layer).

Only cells were sampled. The gene space, the `highly_variable_metabolic` /
`highly_variable_background` flags, the reaction graph, and the models are exactly those of the
published run, so the pretrained checkpoints load and decode as they do on the full data. The
wild-type reaction activity is decoded in the notebook from the 5 included replicates. The *Folr1*
reaction activity table is the published 8-decode, 10-replicate ensemble, subset to these cells.