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

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

# Overview 

The `r self` package implements methods to save genomic ranges (i.e., `GRanges` and `GRangesList` objects) to file artifacts and load them back into R.
It also supports various `CompressedList` subclasses, including the somewhat useful `CompressedSplitDataFrameList`.
Check out the `r Githubpkg("ArtifactDB/alabaster.base")` for more details on the motivation and concepts of the **alabaster** framework.

# Quick start

Given some genomic ranges, we can use `stageObject()` to save it inside a staging directory:

```{r}
library(GenomicRanges)
gr <- GRanges("chrA", IRanges(sample(100), width=sample(100)))
mcols(gr)$score <- runif(length(gr))
metadata(gr)$genome <- "Aaron"
seqlengths(gr) <- c(chrA=1000)

library(alabaster.ranges)
tmp <- tempfile()
dir.create(tmp)
meta <- stageObject(gr, tmp, "gr")
.writeMetadata(meta, tmp)

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

We can then easily load it back in with `loadObject()`.

```{r}
meta <- acquireMetadata(tmp, "gr/ranges.csv.gz")
roundtrip <- loadObject(meta, tmp)
class(roundtrip)
```

The same can be done for `GRangesList` and `CompressedList` subclasses.

## Further comments 

Metadata is preserved during this round-trip:

```{r}
metadata(roundtrip)
mcols(roundtrip)
seqinfo(roundtrip)
```

# Session information {-}

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