---
title: "fourDNData"
author: "Jacques Serizay"
date: "`r Sys.Date()`"
output: 
    BiocStyle::html_document
vignette: >
    %\VignetteIndexEntry{fourDNData}
    %\VignetteEngine{knitr::rmarkdown}
    %\VignetteEncoding{UTF-8}
---

```{r, eval = TRUE, echo=FALSE, results="hide", message = FALSE, warning = FALSE}
knitr::opts_chunk$set(
    collapse = TRUE,
    comment = "#>"
)
suppressPackageStartupMessages({
    library(fourDNData)
})
```

# Introduction 

The 4D Nucleome Data Coordination and Integration Center 
([DCIC](http://dcic.4dnucleome.org/)) has developed and actively maintains a 
[data portal](https://data.4dnucleome.org/browse) providing public access to 
a wealth of resources to investigate 3D chromatin architecture. Notably, 
3D chromatin conformation libraries relying on different technologies 
("in situ" or "dilution" Hi-C, Capture Hi-C, Micro-C, DNase Hi-C, ...), 
generated by 50+ collaborating labs, were homogenously processed, 
yielding more than 350 sets of processed files. 

`fourDNData` (read *4DN-Data*) is a package giving programmatic access 
to these uniformly processed Hi-C contact files. 

The `fourDNData()` function provides a gateway to 4DN-hosted Hi-C files, 
including contact matrices (in `.hic` or `.mcool`) and other Hi-C derived 
files such as annotated compartments, domains, insulation scores, or 
`.pairs` files.

```{r}
library(fourDNData)
head(fourDNData())
cool_file <- fourDNData('4DNESDP9ECMN')
cool_file
```

# Installation

`fourDNData` package can be installed from Bioconductor using the following
command: 

```{r eval = FALSE}
if (!require("BiocManager", quietly = TRUE))
    install.packages("BiocManager")

BiocManager::install("fourDNData")
```

# HiCExperiment and fourDNData

The `HiCExperiment` package can be used to import `.mcool` files provided by 
`fourDNData`. Refer to `HiCExperiment` package documentation for further 
information. 

```{r}
library(HiCExperiment)
ID <- '4DNESDP9ECMN'
cf <- CoolFile(
    path = fourDNData(ID, type = 'mcool'), 
    metadata = as.list(fourDNData()[fourDNData()$experimentSetAccession == ID,])
)
x <- import(cf, resolution = 250000, focus = 'chr5:10000000-50000000')
x
interactions(x)
as(x, 'ContactMatrix')
```

Rather than importing multiple files corresponding to a single experimentSet 
accession ID one by one, one can import all the available files associated with 
a experimentSet accession ID into a `HiCExperiment` object by using the 
`fourDNHiCExperiment()` function.

```{r}
library(HiCExperiment)
x <- fourDNHiCExperiment('4DNESDP9ECMN')
```

# Session info

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