---
title: "Getting Started"
package: BRGenomics
output:
  BiocStyle::html_document:
    toc: true
    toc_float: true
  BiocStyle::pdf_document:
    toc: true
vignette: |
  %\VignetteIndexEntry{Getting Started}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
---

# Installation

As of Bioconductor 3.11 (release date April 28, 2020), BRGenomics can be 
installed directly from Bioconductor:

```{r, eval = FALSE}
# install.packages("BiocManager")
BiocManager::install("BRGenomics")
```

Alternatively, the latest development version can be installed from  
[GitHub](https://github.com/mdeber/BRGenomics):

```{r, eval = FALSE}
# install.packages("remotes")
remotes::install_github("mdeber/BRGenomics@R3")
```

_BRGenomics (and Bioconductor 3.11) require R version 4.0 (release April 24, 
2020). Installing the `R3` branch, as shown above, is required to install under
R 3.x._

If you install the development version from Github and you're using Windows, 
[Rtools for Windows](https://cran.rstudio.com/bin/windows/Rtools/) is required.

# Parallel Processing

By default, many BRGenomics functions use multicore processing as implemented in 
the `parallel` package. BRGenomics functions that can be parallelized always
contain the argument `ncores`. If not specified, the default is to use the
global option "mc.cores" (the same option used by the `parallel` package), or
2 if that option is not set.

If you wanted to change the global default to 4 cores, for example, you would
run `options(mc.cores = 4)` at the start of your R session. If you're unsure
how many cores your processor has, run `parallel::detectCores()`.

While performance can be memory constrained in some cases (and thus actually 
hampered by excessive parallelization), substantial performance benefits can be
achieved by maximizing parallelization. 

However, parallel processing is not available on Windows. To maintain 
compatibility, all code in this vignette as well as the example code in the 
documentation is to use a single core, i.e. `ncores = 1`.
  
# Included Datasets

BRGenomics ships with an example dataset of PRO-seq data from Drosophila 
melanogaster^[Hojoong Kwak, Nicholas J. Fuda, Leighton J. Core, John T. Lis 
(2013). Precise Maps of RNA Polymerase Reveal How Promoters Direct Initiation 
and Pausing. _Science_  __339__(6122): 950–953. 
https://doi.org/10.1126/science.1229386]. PRO-seq is a basepair-resolution 
method that uses 3'-end sequencing of nascent RNA to map the locations of 
actively engaged RNA polymerases. 

To keep the dataset small, we've only included reads mapping to the fourth 
chromosome^[Chromosome 4 in Drosophila, often referred to as the "dot" 
chromosome, is very small and contains very few genes].

The included datasets can be accessed using the `data()` function:

```{r, message=FALSE}
library(BRGenomics)
```

```{r}
data("PROseq")
PROseq
```

Notice that the data is contained within a `GRanges` object. GRanges objects, 
from the `r Biocpkg("GenomicRanges")` package, are very easy to work with, and 
are supported by a plethora of useful functions and packages.

The structure of the data will be described later on (in section 
_"Basepair-Resolution GRanges Objects"_). For now, we'll just note that both 
annotations (e.g. genelists) and data are contained using the same GRanges 
class.

We've included an example genelist to accompany the PRO-seq data:

```{r}
data("txs_dm6_chr4")
txs_dm6_chr4
```

The GRanges above contains all Flybase annotated transcripts from chromosome 4, 
with no filtering of any kind.

# Basic Operations on GRanges

For users who are unfamiliar with GRanges objects, this section demonstrates a 
number of basic operations. 

A quick summary of the general structure: Each element of a GRanges object is 
called a "range". As you can see above, each range consists of several 
components: `seqnames`, `ranges`, and `strand`. These essential attributes are 
all found to the left of the vertical divider above; everything to the right of 
that divider is an optional, metadata attribute. 

The core attributes can be accessed using the functions `seqnames()`, 
`ranges()`, and `strand()`. All metadata can be accessed using `mcols()`, and 
individual columns are accessible with the `$` operator. The only reserved 
metadata column is the `score` column, which is just like any other metadata 
column, except that users can use the `score()` function to assess it.

All of the above functions are both "getters" and "setters", e.g. `strand(x)` 
returns the strand information, and `strand(x) <- "+"` assigns it.

These and other operations are demonstrated below.

---

_To learn more about GRanges objects, including a general overview of their 
components, see the useful vignette [_An Introduction to the GenomicRanges 
Package_](
https://bioconductor.org/packages/release/bioc/vignettes/GenomicRanges/inst/doc/GenomicRangesIntroduction.html). 
Alternatively, see the archived materials from the 2018 Bioconductor workshop [_Solving Common Bioinformatic Challenges Using GenomicRanges_](
https://bioconductor.github.io/BiocWorkshops/solving-common-bioinformatic-challenges-using-genomicranges.html). 
Note that this package will implement and streamline a number of common 
operations, but users should still have a basic familiarity with GRanges 
objects._

---

\ 

Get the length of the genelist:

```{r}
length(txs_dm6_chr4) 
```

\ 

Select the 2nd transcript:

```{r}
txs_dm6_chr4[2]
```

\ 

Select 4 transcripts:

```{r}
tx4 <- txs_dm6_chr4[c(1, 10, 200, 300)]
tx4
```

\ 

Get the lengths of the first 4 transcripts:

```{r}
width(tx4)
```

\ 

Get a dataframe of the metadata for the first 4 transcripts:

```{r}
mcols(tx4)
```

\ 

Access a single metadata column for the first 4 transcripts:

```{r}
mcols(tx4)[, 2]
mcols(tx4)[, "gene_id"]
tx4$gene_id
tx4_names <- tx4$tx_name
tx4_names
```

\ 

Get the first gene_id (a metadata element):

```{r}
tx4$gene_id[1]
```

\ 

Remove a metadata column:

```{r}
mcols(tx4) <- mcols(tx4)[, -1]
tx4
```

\ 

Rename metadata:

```{r}
names(mcols(tx4)) <- "gene_id"
tx4
```

\ 

Add metadata; same as access methods (`mcols()[]`, `mcols()$`, or simply `$`):

```{r}
tx4$tx_name <- tx4_names
tx4
```

\ 

Modify metadata:

```{r}
tx4$gene_id[1] <- "gene1"
tx4$tx_name <- 1:4
tx4
```

\ 

Get beginning of ranges (not strand specific):

```{r}
start(tx4)
```

\ 

Get beginning of ranges (strand specific):

```{r}
tx4_tss <- resize(tx4, width = 1, fix = "start")
tx4_tss
start(tx4_tss)
```

\ 

Remove all metadata:

```{r}
mcols(tx4) <- NULL
tx4
```
