---
title: Saving `MultiAssayExperiment`s to artifacts and back again
author:
- name: Aaron Lun
  email: infinite.monkeys.with.keyboards@gmail.com
package: alabaster.mae
date: "Revised: September 22, 2022"
output:
  BiocStyle::html_document
vignette: >
  %\VignetteIndexEntry{Saving and loading MultiAssayExperiments}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, echo=FALSE}
library(BiocStyle)
self <- Githubpkg("ArtifactDB/alabaster.mae")
knitr::opts_chunk$set(error=FALSE, warning=FALSE, message=FALSE)
```

# Overview 

The `r self` package implements methods to save `MultiAssayExperiment` objects to file artifacts and load them back into R.
Check out the `r Githubpkg("ArtifactDB/alabaster.base")` for more details on the motivation and concepts of the **alabaster** framework.

# Quick start

Let's create a mildly complicated MAE containing RNA-seq and ChIP-seq data with partial overlaps:

```{r}
library(SummarizedExperiment)
rna.counts <- matrix(rpois(60, 10), ncol=6)
colnames(rna.counts) <- c("disease1", "disease2", "disease3", "control1", "control2", "control3")
rownames(rna.counts) <- c("ENSMUSG00000000001", "ENSMUSG00000000003", "ENSMUSG00000000028", 
    "ENSMUSG00000000031", "ENSMUSG00000000037", "ENSMUSG00000000049",  "ENSMUSG00000000056", 
    "ENSMUSG00000000058", "ENSMUSG00000000078",  "ENSMUSG00000000085")
rna.se <- SummarizedExperiment(list(counts=rna.counts))
colData(rna.se)$disease <- rep(c("disease", "control"), each=3)

chip.counts <- matrix(rpois(100, 10), ncol=4)
colnames(chip.counts) <- c("disease1", "disease2", "control1", "control3")
chip.peaks <- GRanges("chr1", IRanges(1:25*100+1, 1:25*100+100))
chip.se <- SummarizedExperiment(list(counts=chip.counts), rowRanges=chip.peaks)

library(MultiAssayExperiment)
mapping <- DataFrame(
    primary = c(colnames(rna.se), colnames(chip.se)), # sample identifiers
    assay = rep(c("rnaseq", "chipseq"), c(ncol(rna.se), ncol(chip.se))), # experiment name
    colname = c(colnames(rna.se), colnames(chip.se)) # column names inside each experiment
)
mae <- MultiAssayExperiment(list(rnaseq=rna.se, chipseq=chip.se), sampleMap=mapping)
```

We can use `stageObject()` to save it inside a staging directory:

```{r}
library(alabaster.mae)
tmp <- tempfile()
dir.create(tmp)
meta <- stageObject(mae, tmp, "mae")
.writeMetadata(meta, tmp)

list.files(tmp, recursive=TRUE)
```

We can then load it back into the session with `loadObject()`.

```{r}
meta <- acquireMetadata(tmp, "mae/dataset.json")
roundtrip <- loadObject(meta, tmp)
class(roundtrip)
```

More details on the metadata and on-disk layout are provided in the [schema](https://artifactdb.github.io/BiocObjectSchemas/html/dataset/v1.html).

# Session information {-}

```{r}
sessionInfo()
```