# HTML reports for a set of regions

If you wish, you can view this vignette online here.

`regionReport` `(Collado-Torres, Jaffe, and Leek, 2015)` creates HTML reports styled with `knitrBootstrap` `(Hester, 2013)` for a set of regions such as `derfinder` `(Collado-Torres, Frazee, Jaffe, and Leek, 2014)` results.

Currently, this package includes a basic exploration analysis of `derfinder` results which we expect users to be interested in reproducing with their own data. The analysis is written in R Markdown format and `derfinderReport()` takes the results from `derfinder`, performs a couple of setup operations, and then relies on `knitr` `(Xie, 2014)`, `rmarkdown` `(Allaire, Cheng, Xie, McPherson, et al., 2015)`, and `knitrBootstrap` `(Hester, 2013)` for generating the report.

# Using `regionReport`

## General case

This is currently under construction.

## `derfinder` case

Goodies in this report are powered by `ggbio` `(Yin, Cook, and Lawrence, 2012)` and `ggplot2` `(Wickham, 2009)`.

### Run `derfinder`

Prior to using `regionReport::derfinderReport()` you must use `derfinder` to analyze a specific data set. While there are many ways to do so, we recommend using analyzeChr() with the same prefix argument. Then merging the results with mergeResults().

Below, we run `derfinder` for the example data included in the package. The steps are:

1. Load derfinder
2. Create a directory where we'll store the results
3. Generate the pre-requisites for the models to use with the example data
4. Generate the statistical models
5. Analyze the example data for chr21
6. Merge the results (only one chr in this case, but in practice there'll be more)

    ## Load derfinder
    library('derfinder')

    ## The output will be saved in the 'report' directory
    dir.create('report', showWarnings = FALSE, recursive = TRUE)

The following code runs `derfinder`.

    ## Save the current path
    initialPath <- getwd()
    setwd(file.path(initialPath, 'report'))

    ## Generate output from derfinder

    ## Collapse the coverage information
    collapsedFull <- collapseFullCoverage(list(genomeData$coverage),
    verbose=TRUE)

    ## Calculate library size adjustments
    sampleDepths <- sampleDepth(collapsedFull, probs=c(0.5), nonzero=TRUE,
    verbose=TRUE)

    ## Build the models
    group <- genomeInfo$pop
    adjustvars <- data.frame(genomeInfo$gender)
    models <- makeModels(sampleDepths, testvars=group, adjustvars=adjustvars)

    ## Analyze chromosome 21
    analysis <- analyzeChr(chr='21', coverageInfo=genomeData, models=models,
    cutoffFstat=1, cutoffType='manual', seeds=20140330, groupInfo=group,
    mc.cores=1, writeOutput=TRUE, returnOutput=TRUE)

    ## Save the stats options for later
    optionsStats <- analysis$optionsStats

    ## Change the directory back to the original one
    setwd(initialPath)

For convenience, we have included the `derfinder` results as part of `regionReport`. Note that the above functions are routinely checked as part of `derfinder`.

    ## Copy previous results
    file.copy(system.file(file.path('extdata', 'chr21'), package='derfinder',
    mustWork=TRUE), 'report', recursive=TRUE)

    ## [1] TRUE

Next, proceed to merging the results.

    ## Merge the results from the different chromosomes. In this case, there's
    ## only one: chr21
    mergeResults(chrs = 'chr21', prefix = 'report',
        genomicState = genomicState$fullGenome)

    ## 2015-02-27 22:05:08 mergeResults: Saving options used
    ## 2015-02-27 22:05:08 Loading chromosome chr21
    ## Neither 'cutoffFstatUsed' nor 'optionsStats' were supplied, so the FWER calculation step will be skipped.
    ## 2015-02-27 22:05:08 mergeResults: Saving fullNullSummary
    ## 2015-02-27 22:05:08 mergeResults: Re-calculating the p-values
    ## 2015-02-27 22:05:08 mergeResults: Saving fullRegions
    ## 2015-02-27 22:05:08 mergeResults: assigning genomic states
    ## 2015-02-27 22:05:09 annotateRegions: counting
    ## 2015-02-27 22:05:09 annotateRegions: annotating
    ## 2015-02-27 22:05:09 mergeResults: Saving fullAnnotatedRegions
    ## 2015-02-27 22:05:09 mergeResults: Saving fullFstats
    ## 2015-02-27 22:05:09 mergeResults: Saving fullTime

### Create report

Once the `derfinder` output has been generated and merged, use derfinderReport() to create the HTML report.

    ## Load derfindeReport
    library('regionReport')

    ## Generate the HTML report
    report <- derfinderReport(prefix='report', browse=FALSE,
        nBestRegions=15, makeBestClusters=TRUE, outdir='html',
        fullCov=list('21'=genomeDataRaw$coverage), optionsStats=optionsStats)

Once the output is generated, you can browse the report from `R` using browseURL() as shown below.

    ## Browse the report
    browseURL(report)

You can compare the resulting report with the pre-compiled report using the following code.

    browseURL(system.file(file.path('basicExploration', 'basicExploration.html'),
        package = 'regionReport', mustWork = TRUE))

### Notes

Note that the reports require an active Internet connection to render correctly.

The report is self-explanatory and will change some of the text depending on the input options.

If the report is taking too long to compile (say more than 3 hours), you might want to consider setting nBestCluters to a small number or even set makeBestClusters to `FALSE`.

# Advanced arguments

If you are interested in using the advanced arguments, use `derfinder::advancedArg()` as shown below:

    ## URLs to advanced arguemtns
    derfinder::advancedArg('derfinderReport', package = 'regionReport',
        browse = FALSE)
    ## Set browse = TRUE if you want to open them in your browser

# Reproducibility

This package was made possible thanks to:

- R `(R Core Team, 2014)`
- derfinder `(Collado-Torres, Frazee, Jaffe, and Leek, 2014)`
- derfinderPlot `(Collado-Torres, Jaffe, and Leek, 2014)`
- devtools `(Wickham and Chang, 2015)`
- GenomeInfoDb `(Arora, Morgan, Carlson, and Pages, 2015)`
- GenomicRanges `(Lawrence, Huber, Pagès, Aboyoun, et al., 2013)`
- ggbio `(Yin, Cook, and Lawrence, 2012)`
- ggplot2 `(Wickham, 2009)`
- grid `(R Core Team, 2014)`
- gridExtra `(Auguie, 2012)`
- IRanges `(Lawrence, Huber, Pagès, Aboyoun, et al., 2013)`
- knitcitations `(Boettiger, 2014)`
- knitr `(Xie, 2014)`
- knitrBootstrap `(Hester, 2013)`
- mgcv ``
- RColorBrewer `(Neuwirth, 2014)`
- rmarkdown `(Allaire, Cheng, Xie, McPherson, et al., 2015)`
- biovizBase `(Yin, Lawrence, and Cook, 2015)`
- Cairo `(Urbanek and Horner, 2014)`
- TxDb.Hsapiens.UCSC.hg19.knownGene `(Carlson, 2015)`

Code for creating the vignette

    ## Create the vignette
    library('knitrBootstrap')

    knitrBootstrapFlag <- packageVersion('knitrBootstrap') < '1.0.0'
    if(knitrBootstrapFlag) {
        ## CRAN version
        system.time(knit_bootstrap('regionReport.Rmd', chooser=c('boot', 'code'), show_code = TRUE))
        unlink('regionReport.md')
    } else {
        ## GitHub version
        library('rmarkdown')
        system.time(render('regionReport.Rmd',
            'knitrBootstrap::bootstrap_document'))
    }
    ## Note: if you prefer the knitr version use:
    # library('rmarkdown')
    # system.time(render('regionReport.Rmd', 'html_document'))

    ## Extract the R code
    library('knitr')
    knit('regionReport.Rmd', tangle = TRUE)

    ## Copy report output to be distributed with the package for comparison
    ## purposes
    if(gsub('.*/', '', getwd()) == 'realVignettes') {
        file.copy(file.path('report', 'html', 'basicExploration.html'),
            file.path('..', '..', 'inst', 'basicExploration',
                'basicExploration.html'), overwrite=TRUE)
    } else {
        file.copy(file.path('report', 'html', 'basicExploration.html'),
            file.path('..', 'inst', 'basicExploration', 'basicExploration.html'),
                overwrite=TRUE)
    }

    ## Clean up
    file.remove('regionReportRef.bib')
    #unlink('regionReport_files', recursive=TRUE)
    unlink('report', recursive = TRUE)

Date the vignette was generated.

    ## [1] "2015-02-27 22:06:37 PST"

Wallclock time spent generating the vignette.

    ## Time difference of 1.834 mins

`R` session information.

    ## Session info -----------------------------------------------------------------------------------------------------------

    ##  setting  value
    ##  version  R version 3.1.2 (2014-10-31)
    ##  system   i386, mingw32
    ##  ui       RTerm
    ##  language (EN)
    ##  collate  C
    ##  tz       America/Los_Angeles

    ## Packages ---------------------------------------------------------------------------------------------------------------

    ##  package           * version  date       source
    ##  AnnotationDbi     * 1.28.1   2015-02-28 Bioconductor
    ##  BBmisc            * 1.9      2015-02-03 CRAN (R 3.1.2)
    ##  BSgenome          * 1.34.1   2015-02-28 Bioconductor
    ##  BatchJobs         * 1.5      2014-10-30 CRAN (R 3.1.1)
    ##  Biobase           * 2.26.0   2015-02-28 Bioconductor
    ##  BiocGenerics      * 0.12.1   2015-02-28 Bioconductor
    ##  BiocParallel      * 1.0.3    2015-02-28 Bioconductor
    ##  Biostrings        * 2.34.1   2015-02-28 Bioconductor
    ##  DBI               * 0.3.1    2014-09-24 CRAN (R 3.1.1)
    ##  Formula           * 1.2-0    2015-01-20 CRAN (R 3.1.2)
    ##  GGally            * 0.5.0    2014-12-02 CRAN (R 3.1.2)
    ##  GenomeInfoDb      * 1.2.4    2015-02-28 Bioconductor
    ##  GenomicAlignments * 1.2.1    2015-02-28 Bioconductor
    ##  GenomicFeatures   * 1.18.3   2015-02-28 Bioconductor
    ##  GenomicFiles      * 1.2.1    2015-02-28 Bioconductor
    ##  GenomicRanges     * 1.18.4   2015-02-28 Bioconductor
    ##  Hmisc             * 3.15-0   2015-02-16 CRAN (R 3.1.2)
    ##  IRanges           * 2.0.1    2015-02-28 Bioconductor
    ##  MASS              * 7.3-39   2015-02-20 CRAN (R 3.1.2)
    ##  Matrix            * 1.1-5    2015-01-18 CRAN (R 3.1.2)
    ##  OrganismDbi       * 1.8.0    2015-02-28 Bioconductor
    ##  RBGL              * 1.42.0   2015-02-28 Bioconductor
    ##  RColorBrewer      * 1.1-2    2014-12-07 CRAN (R 3.1.2)
    ##  RCurl             * 1.95-4.5 2014-12-06 CRAN (R 3.1.2)
    ##  RJSONIO           * 1.3-0    2014-07-28 CRAN (R 3.1.1)
    ##  RSQLite           * 1.0.0    2014-10-25 CRAN (R 3.1.1)
    ##  Rcpp              * 0.11.4   2015-01-24 CRAN (R 3.1.2)
    ##  RefManageR        * 0.8.45   2015-01-09 CRAN (R 3.1.2)
    ##  Rsamtools         * 1.18.2   2015-02-28 Bioconductor
    ##  S4Vectors         * 0.4.0    2015-02-28 Bioconductor
    ##  VariantAnnotation * 1.12.9   2015-02-28 Bioconductor
    ##  XML               * 3.98-1.1 2013-06-20 CRAN (R 3.1.1)
    ##  XVector           * 0.6.0    2015-02-28 Bioconductor
    ##  acepack           * 1.3-3.3  2013-05-03 CRAN (R 3.1.1)
    ##  base64enc         * 0.1-2    2014-06-26 CRAN (R 3.1.1)
    ##  bibtex            * 0.4.0    2014-12-31 CRAN (R 3.1.2)
    ##  biomaRt           * 2.22.0   2015-02-28 Bioconductor
    ##  biovizBase        * 1.14.1   2015-02-28 Bioconductor
    ##  bitops            * 1.0-6    2013-08-17 CRAN (R 3.1.1)
    ##  brew              * 1.0-6    2011-04-13 CRAN (R 3.1.1)
    ##  bumphunter        * 1.6.0    2015-02-28 Bioconductor
    ##  checkmate         * 1.5.1    2014-12-14 CRAN (R 3.1.2)
    ##  cluster           * 2.0.1    2015-01-31 CRAN (R 3.1.2)
    ##  codetools         * 0.2-10   2015-01-17 CRAN (R 3.1.2)
    ##  colorspace        * 1.2-4    2013-09-30 CRAN (R 3.1.1)
    ##  derfinder           1.0.10   2015-02-28 Bioconductor
    ##  derfinderHelper   * 1.0.4    2015-02-28 Bioconductor
    ##  derfinderPlot     * 1.0.3    2015-02-28 Bioconductor
    ##  devtools            1.7.0    2015-01-17 CRAN (R 3.1.2)
    ##  dichromat         * 2.0-0    2013-01-24 CRAN (R 3.1.1)
    ##  digest            * 0.6.8    2014-12-31 CRAN (R 3.1.2)
    ##  doRNG             * 1.6      2014-03-07 CRAN (R 3.1.1)
    ##  evaluate          * 0.5.5    2014-04-29 CRAN (R 3.1.1)
    ##  fail              * 1.2      2013-09-19 CRAN (R 3.1.1)
    ##  foreach           * 1.4.2    2014-04-11 CRAN (R 3.1.1)
    ##  foreign           * 0.8-63   2015-02-20 CRAN (R 3.1.2)
    ##  formatR           * 1.0      2014-08-25 CRAN (R 3.1.1)
    ##  ggbio             * 1.14.0   2015-02-28 Bioconductor
    ##  ggplot2           * 1.0.0    2014-05-21 CRAN (R 3.1.1)
    ##  graph             * 1.44.1   2015-02-28 Bioconductor
    ##  gridExtra         * 0.9.1    2012-08-09 CRAN (R 3.1.1)
    ##  gtable            * 0.1.2    2012-12-05 CRAN (R 3.1.1)
    ##  highr             * 0.4      2014-10-23 CRAN (R 3.1.1)
    ##  htmltools         * 0.2.6    2014-09-08 CRAN (R 3.1.1)
    ##  httr              * 0.6.1    2015-01-01 CRAN (R 3.1.2)
    ##  iterators         * 1.0.7    2014-04-11 CRAN (R 3.1.1)
    ##  knitcitations       1.0.5    2014-11-26 CRAN (R 3.1.2)
    ##  knitr             * 1.9      2015-01-20 CRAN (R 3.1.2)
    ##  knitrBootstrap      0.9.0    2013-10-17 CRAN (R 3.1.1)
    ##  lattice           * 0.20-30  2015-02-22 CRAN (R 3.1.2)
    ##  latticeExtra      * 0.6-26   2013-08-15 CRAN (R 3.1.1)
    ##  locfit            * 1.5-9.1  2013-04-20 CRAN (R 3.1.1)
    ##  lubridate         * 1.3.3    2013-12-31 CRAN (R 3.1.1)
    ##  markdown          * 0.7.4    2014-08-24 CRAN (R 3.1.1)
    ##  matrixStats       * 0.14.0   2015-02-14 CRAN (R 3.1.2)
    ##  memoise           * 0.2.1    2014-04-22 CRAN (R 3.1.1)
    ##  mgcv              * 1.8-4    2014-11-27 CRAN (R 3.1.2)
    ##  munsell           * 0.4.2    2013-07-11 CRAN (R 3.1.1)
    ##  nlme              * 3.1-120  2015-02-20 CRAN (R 3.1.2)
    ##  nnet              * 7.3-9    2015-02-11 CRAN (R 3.1.2)
    ##  pkgmaker          * 0.22     2014-05-14 CRAN (R 3.1.1)
    ##  plyr              * 1.8.1    2014-02-26 CRAN (R 3.1.1)
    ##  proto             * 0.3-10   2012-12-22 CRAN (R 3.1.1)
    ##  qvalue            * 1.40.0   2015-02-28 Bioconductor
    ##  regionReport        1.0.5    2015-02-28 Bioconductor
    ##  registry          * 0.2      2012-01-24 CRAN (R 3.1.1)
    ##  reshape           * 0.8.5    2014-04-23 CRAN (R 3.1.1)
    ##  reshape2          * 1.4.1    2014-12-06 CRAN (R 3.1.2)
    ##  rmarkdown         * 0.5.1    2015-01-26 CRAN (R 3.1.2)
    ##  rngtools          * 1.2.4    2014-03-06 CRAN (R 3.1.1)
    ##  rpart             * 4.1-9    2015-02-11 CRAN (R 3.1.2)
    ##  rstudioapi        * 0.2      2014-12-31 CRAN (R 3.1.2)
    ##  rtracklayer       * 1.26.2   2015-02-28 Bioconductor
    ##  scales            * 0.2.4    2014-04-22 CRAN (R 3.1.1)
    ##  sendmailR         * 1.2-1    2014-09-21 CRAN (R 3.1.1)
    ##  stringr           * 0.6.2    2012-12-06 CRAN (R 3.1.1)
    ##  survival          * 2.38-1   2015-02-24 CRAN (R 3.1.2)
    ##  xtable            * 1.7-4    2014-09-12 CRAN (R 3.1.1)
    ##  zlibbioc          * 1.12.0   2015-02-28 Bioconductor

# Bibliography

This vignette was generated using `knitrBootstrap` `(Hester, 2013)` with `knitr` `(Xie, 2014)` and `rmarkdown` `(Allaire, Cheng, Xie, McPherson, et al., 2015)` running behind the scenes.

Citations made with `knitcitations` `(Boettiger, 2014)`.

[1] J. Allaire, J. Cheng, Y. Xie, J. McPherson, et al. rmarkdown: Dynamic Documents for R. R package version 0.5.1. 2015. URL: http://CRAN.R-project.org/package=rmarkdown.

[2] S. Arora, M. Morgan, M. Carlson and H. Pages. GenomeInfoDb: Utilities for manipulating chromosome and other 'seqname' identifiers. R package version 1.2.4. 2015.

[3] B. Auguie. gridExtra: functions in Grid graphics. R package version 0.9.1. 2012. URL: http://CRAN.R-project.org/package=gridExtra.

[4] C. Boettiger. knitcitations: Citations for knitr markdown files. R package version 1.0.5. 2014. URL: http://CRAN.R-project.org/package=knitcitations.

[5] M. Carlson. TxDb.Hsapiens.UCSC.hg19.knownGene: Annotation package for TxDb object(s). R package version 3.0.0. 2015.

[6] L. Collado-Torres, A. C. Frazee, A. E. Jaffe and J. T. Leek. derfinder: Annotation-agnostic differential expression analysis of RNA-seq data at base-pair resolution. https://github.com/lcolladotor/derfinder - R package version 1.0.10. 2014. URL: http://www.bioconductor.org/packages/release/bioc/html/derfinder.html.

[7] L. Collado-Torres, A. E. Jaffe and J. T. Leek. derfinderPlot: Plotting functions for derfinder. https://github.com/lcolladotor/derfinderPlot - R package version 1.0.3. 2014. URL: http://www.bioconductor.org/packages/release/bioc/html/derfinderPlot.html.

[8] L. Collado-Torres, A. E. Jaffe and J. T. Leek. regionReport: Generate HTML reports for exploring a set of regions. https://github.com/lcolladotor/regionReport - R package version 1.0.5. 2015. URL: http://www.bioconductor.org/packages/release/bioc/html/regionReport.html.

[9] J. Hester. knitrBootstrap: Knitr Bootstrap framework. R package version 0.9.0. 2013. URL: http://CRAN.R-project.org/package=knitrBootstrap.

[10] M. Lawrence, W. Huber, H. Pagès, P. Aboyoun, et al. “Software for Computing and Annotating Genomic Ranges”. In: PLoS Computational Biology 9 (8 2013). DOI: 10.1371/journal.pcbi.1003118. URL: http://www.ploscompbiol.org/article/info%3Adoi%2F10.1371%2Fjournal.pcbi.1003118}.

[11] E. Neuwirth. RColorBrewer: ColorBrewer Palettes. R package version 1.1-2. 2014. URL: http://CRAN.R-project.org/package=RColorBrewer.

[12] R Core Team. R: A Language and Environment for Statistical Computing. R Foundation for Statistical Computing. Vienna, Austria, 2014. URL: http://www.R-project.org/.

[13] S. Urbanek and J. Horner. Cairo: R graphics device using cairo graphics library for creating high-quality bitmap (PNG, JPEG, TIFF), vector (PDF, SVG, PostScript) and display (X11 and Win32) output. R package version 1.5-6. 2014. URL: http://CRAN.R-project.org/package=Cairo.

[14] H. Wickham. ggplot2: elegant graphics for data analysis. Springer New York, 2009. ISBN: 978-0-387-98140-6. URL: http://had.co.nz/ggplot2/book.

[15] H. Wickham and W. Chang. devtools: Tools to Make Developing R Packages Easier. R package version 1.7.0. 2015. URL: http://CRAN.R-project.org/package=devtools.

[16] Y. Xie. “knitr: A Comprehensive Tool for Reproducible Research in R”. In: Implementing Reproducible Computational Research. Ed. by V. Stodden, F. Leisch and R. D. Peng. ISBN 978-1466561595. Chapman and Hall/CRC, 2014. URL: http://www.crcpress.com/product/isbn/9781466561595.

[17] T. Yin, D. Cook and M. Lawrence. “ggbio: an R package for extending the grammar of graphics for genomic data”. In: Genome Biology 13.8 (2012), p. R77.

[18] T. Yin, M. Lawrence and D. Cook. biovizBase: Basic graphic utilities for visualization of genomic data. R package version 1.14.1. 2015.