README.Rmd

---
title: "PCAGO"
output: github_document
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = F)
```

PCAGO is an interactive web service that allows analysis of RNA-Seq read count data with principal component analysis (PCA)
and agglomerative clustering. The tool also includes features like read count normalization, filtering read counts by 
gene annotation and various visualization options.

[PCAGO on GitLab](https://gitlab.com/rumangerst/pcago) | [PCAGO on GitHub](https://github.com/rumangerst/pcago-electron) | [PCAGO-Electron on GitHub](https://github.com/rumangerst/pcago-electron/)

## Running

You have following options to run PCAGO:

* Use our servers ([PCAGO Stable](http://pcago.bioinf.uni-jena.de/) or [PCAGO Development Version](http://pcago.bioinf.uni-jena.de/unstable))
* Use a standalone desktop application
* Run the PCAGO server on one of your servers or your local computer

### Using the standalone application

Download the PCAGO-Electron [here](https://github.com/rumangerst/pcago-electron). This application wraps a
PCAGO-server within an [Electron](https://electronjs.org/) application.

### Running manually

Open a R console in the PCAGO folder and run

```
shiny::runApp()
```

**Note: ** If you use packrat (see below), you have to run

```
source('packrat/init.R')
shiny::runApp()
```

## Requirements

Following packages are required to run PCAGO if the dependencies are already installed:

* `r sessionInfo()$R.version$version.string` or higher
* ffmpeg (Debian/Ubuntu: `ffmpeg`)
* libmariadb (Debian/Ubuntu: `libmariadb2`)

Following packages are required to install PCAGO if the required libraries have to be installed

* libcurl dev package (Debian/Ubuntu: `libcurl4-openssl-dev`)
* xml2-config dev package (Debian/Ubuntu: `libxml2-dev`)
* openssl dev package (Debian/Ubuntu: `libssl-dev`)
* mariadb dev package (Debian/Ubuntu: `libmariadb-client-lgpl-dev`)
* cairo2 dev package (Debian/Ubuntu: `libcairo2-dev`)
* GTK2 dev package (Debian/Ubuntu: `libgtk2.0-dev`)
* XVFB package (Debian/Ubuntu: `xvfb`)
* xAuth package (Debian/Ubuntu: `xauth`)
* xfonts dev package (Debian/Ubuntu: `xfonts-baselibgtk2.0-dev`)
* xfonts base package (Debian/Ubuntu: `xfonts-base`)
* libxt dev package (Debian/Ubuntu: `libxt-dev`)

PCAGO also requires several R packages (see table below). You can either install those packages manually or by using the 
package management system packrat.

### Using packrat

[Packrat](https://rstudio.github.io/packrat/) is a package management system that allows creating snapshots
of the libraries used for development of the application. This prevents breakage introduced by newer library versions.
To use packrat, follow these steps:

1. Download the [package sources](https://github.com/rumangerst/pcago/releases)
2. Unpack them into the `packrat` directory within the PCAGO project folder
3. Start R within the project directory
4. Run `source('packrat/init.R')`

**Important note: ** `source('packrat/init.R')` must be always called before starting PCAGO to enable packrat. If you want to automate this
process or want to deploy a server using [Shiny Server](https://www.rstudio.com/products/shiny/shiny-server/), create a file `.Rprofile` that contains `source('packrat/init.R')` in the PCAGO directory.

**Important note: ** If the installation of the dependencies failed for any reason `source('packrat/init.R')` will **not** continue the installation of the library. Additionally run `packrat::restore()` to continue the dependency installation.

**Tip: ** You can copy the packrat directory to other computers running the same operating system to skip the building times. This will likely not work if you copy data between different distributions or different versions of the same distribution.

### Installing requirements manually

If you do not want to use packrat, you can install the dependencies manually.
Please note that newer library versions might break functionality.
Following command installs all dependencies:

```{r, comment=""}

r.packages.cran <- Filter(function(x) { "Repository" %in% names(x) && x$Repository == "CRAN" }, sessionInfo()$otherPkgs)
r.packages.bioc <- Filter(function(x) { !("Repository" %in% names(x)) }, sessionInfo()$otherPkgs)
r.packages.cran.install <- paste0("install.packages(c(",
                             paste(as.vector(sapply(r.packages.cran, function(x) { paste0("\"", x$Package, "\"") }))
                             ,collapse = ", "), "))")
r.packages.bioc.install <-  paste0("biocLite(c(", paste(as.vector(sapply(r.packages.bioc, function(x) { paste0("\"", x$Package, "\"") })), collapse = ", ") ,
                                   "), type = \"source\")")

cat("# CRAN packages",
  r.packages.cran.install,
  "",
  "# BioConductor packages. Install them from source, so known bugs with newer R versions can be avoided.",
  "source(\"https://bioconductor.org/biocLite.R\")",
  r.packages.bioc.install,
  sep = "\n")

```

## R packages

```{r, results = 'asis'}

library(knitr)
library(rmarkdown)

r.packages <- sessionInfo()$otherPkgs

table <- data.frame(
  Package = sapply(r.packages, function(x) { x$Package }),
  Author = sapply(r.packages, function(x) { if("Author" %in% names(x)) gsub("\n", " ", x$Author) else "" }),
  URL = sapply(r.packages, function(x) { if("URL" %in% names(x)) gsub("\n", " ", x$URL, fixed = T) else "" }),
  "License" = sapply(r.packages, function(x) { gsub("|", ";", x$License, fixed = T) }),
  "Version" = sapply(r.packages, function(x) { x$Version }),
  stringsAsFactors = F,
  check.names = F,
  row.names = NULL
)

kable(table, caption = "Required packages")

```


## Updating this README file

This README file is autogenerated using RMarkdown. Please don't forget to run PCAGO once before
rebuilding this README.

**Note:** You cannot use RStudio as RStudio's RMarkdown builder runs in a separate environment!

```
# Run PCAGO once
shiny::runApp()
# Cancel with Ctrl + C
# Build the README file
rmarkdown::render("README.Rmd")
```

## Credits

Uses code from https://github.com/daattali/advanced-shiny by Dean Attali. Licensed under the MIT license.