Overview

The alabaster.files package implements methods to save common bioinformatics file formats within the alabaster framework. It does not perform any validation or parsing of the files, it just provides very light-weight wrappers for processing via alabaster.base::stageObject(). Check out the alabaster.base package for more details on the motivation and concepts behind alabaster.

Quick start

We’ll start with an indexed BAM file from the Rsamtools package:

bam.file <- system.file("extdata", "ex1.bam", package="Rsamtools", mustWork=TRUE)
bam.index <- paste0(bam.file, ".bai")

We can wrap this inside a BamFileReference class:

library(alabaster.files)
library(S4Vectors)
wrapped.bam <- BamFileReference(bam.file, index=bam.index)

Then we can save it to file:

dir <- tempfile()
saveObject(wrapped.bam, dir)

… and load it back at some later time.

readObject(dir)

## BamFileReference object
## path: /tmp/RtmpBuy6Rx/file1771368e603d/file.bam 
## index: /tmp/RtmpBuy6Rx/file1771368e603d/file.bam.bai

Integration with other objects

The example above isn’t very exciting, but it demonstrates how these files can be easily added to an alabaster project. This allows us to incorporate the Wrapper objects into other Bioconductor data structures, like:

df <- DataFrame(Sample=LETTERS[1:4])

# Adding a column of assorted wrapper files:
df$File <- list(
    wrapped.bam,
    BigWigFileReference(system.file("tests", "test.bw", package = "rtracklayer")),
    BigBedFileReference(system.file("tests", "test.bb", package = "rtracklayer")),
    BcfFileReference(system.file("extdata", "ex1.bcf.gz", package = "Rsamtools"))
)

# Saving it all to the staging directory:
dir <- tempfile()
saveObject(df, dir)

# Now reading it back in:
roundtrip <- readObject(dir)
roundtrip$File

## [[1]]
## BamFileReference object
## path: /tmp/RtmpBuy6Rx/file1771420b5a53/other_columns/1/other_contents/0/file.bam 
## index: /tmp/RtmpBuy6Rx/file1771420b5a53/other_columns/1/other_contents/0/file.bam.bai
## 
## [[2]]
## BigWigFileReference object
## path: /tmp/RtmpBuy6Rx/file1771420b5a53/other_columns/1/other_contents/1/file.bw 
## 
## [[3]]
## BigBedFileReference object
## path: /tmp/RtmpBuy6Rx/file1771420b5a53/other_columns/1/other_contents/2/file.bb 
## 
## [[4]]
## BcfFileReference object
## path: /tmp/RtmpBuy6Rx/file1771420b5a53/other_columns/1/other_contents/3/file.bcf 
## index: NULL

Similarly, if the staging directory is uploaded to a remote store, the wrapped files will automatically be included in the upload. This avoids the need for a separate process to handle these files.

Validation

alabaster.files will try to perform some cursory validation of the wrapped file to catch errors in user inputs. The level of validation is format-dependent but should be fast, e.g., BAM file validation is performed by scanning the header. In all cases, users should not expect an exhaustive check of file validity, as that would take too long and involve more parsing than desired for the scope of alabaster.files. If stricter validation is required, applications calling alabaster.files should override the saveObject() methods for the relevant FileReference classes.