1 Introduction

This program is developed based on the Shiny framework, a set of R packages and a collection of scripts written by members of Junhyong Kim Lab at University of Pennsylvania. Its goal is to facilitate fast and interactive RNA-Seq data analysis and visualization. Current version of PIVOT supports routine RNA-Seq data analysis including normalization, differential expression analysis, dimension reduction, correlation analysis, clustering and classification. Users can complete workflows of DESeq2, monocle and scde package with just a few button clicks. All analysis reports can be exported, and the program state can be saved, loaded and shared.

See http://kim.bio.upenn.edu/software/pivot.shtml for more details.

2 Installation

  • Main Program: Please copy and paste the following command to R console.
  • Upgrading R and Rstudio to the latest version (R >= 3.4, Rstudio > 1.0.0) is strongly recommended.
# dependecies that needs to be manually installed 
install.packages("devtools") # First run this line alone then paste rest.
library("devtools")
source("http://bioconductor.org/biocLite.R")  
biocLite("GO.db")
biocLite("HSMMSingleCell")
biocLite("org.Mm.eg.db")
biocLite("org.Hs.eg.db")
biocLite("DESeq2")
biocLite("SingleCellExperiment")
biocLite("scater")

# Install PIVOT
install_github("qinzhu/PIVOT")
biocLite("BiocGenerics") # You need the latest BiocGenerics >=0.23.3

3 Launch PIVOT

  • To run PIVOT, in Rstudio console, use command

    library(PIVOT)
pivot()

  • For advanced users, if you want to only load needed modules,

Then you can either use

pivot_module()

which shows the available modules in PIVOT:

ID Module
1 PIVOT.base
2 DESeq2
3 edgeR
4 scde
5 monocle
6 PIVOT.network
7 caret
8 PIVOT.toolkit

Then use pivot(#ID_vector) to launch selected modules, e.g., pivot(c(1,2,3)) to launch PIVOT with the base PIVOT module, DESeq2 and edgeR.

Alternatively, use

pivot_launcher()

to launch a window to directly pick modules or install required components.

4 Data Input

4.1 Input expression matrix

  • To input expression matrix, select “Counts Table” as input file type. PIVOT expects the count matrix to have rows as genes and samples as columns. Gene names and sample names should be the first column and the first row, respectively.

  • PIVOT support expression matrix in csv, txt, xls or xlsx formats. Choose proper settings on the left file input panel until the right “Loaded File Preview” correctly shows the data frame.

  • you need to make sure that the data matrix:

    • Contains no NA or non-numeric values.

    • Does not have duplicated feature or sample names (PIVOT will alert the user if it detects any).

4.2 Input counts directory

  • If you have counts files with genes in the first column and gene counts in the second column. You can input the entire data folder. PIVOT will automatically combine the counts files into an expression matrix. Note you need to make sure that the files are all quantified using the same pipeline with the same annotation file.

  • PIVOT also allows you to select subset of files in the folder. E.g., type ‘exon’ in the filter textbox to only select files with “exon” in the file name.

4.3 Input 10x Cell Ranger output

  • You need to install Cell Ranger R Kit from 10x Genomics to allow PIVOT to directly read in 10x data: https://support.10xgenomics.com/single-cell-gene-expression/software/pipelines/latest/rkit

  • Then choose “10x Directoy” for input file type, and use the “Select 10x Folder” button to point PIVOT to the Cell Ranger output directory (the folder containing the “outs” folder).

  • By default, PIVOT will use gene symbol as row names for the expression matrix, the other option is the gene id, which is the default setting of Cell Ranger output.

4.4 Data Normalization

We have included a multitude of normalization methods in PIVOT. Some normalization methods are mostly used for bulk RNA-Seq data, while others may only be applicable to single-cell data. Users should be aware of which method best suits their data.

  • If your data has already been processed by DESeq or other methods, please specify “none” in the normalization method.

  • If DESeq failed on your data, one possibility is that you have low counts samples, which leads to all the genes contain at least one 0 in the counts matrix. You can either find out and remove these samples, or choose the “modified DESeq” normalization method. Setting sample inclusion 100% is equivalent to the original DESeq.

  • Some normalization method require additional information from the user. For example, if you choose ERCC normalization then you must provide experimental parameters. Please also make sure the ERCC feature names matches those in the standard table: (https://tools.thermofisher.com/content/sfs/manuals/cms_095046.txt).

  • PIVOT applies a pre-filtering step before doing normalization. By default, PIVOT will filter out genes with all 0 expressions. Users can also specify a different row mean or row sum threshold to remove those low confidence features.

  • Once data have been normalized, you can check the normlization details which contain information such as the estimated size factors.

4.5 Input Design Information

  • The design infomation are used for sample point coloring and differential expression analysis. Users can input the entire sample meta sheet as design information, or manually specify groups or batches for each sample.

  • The first column of the design table should always be the sample name list, which must include all samples that’s in the expression matrix. The rest columns will be treated as “categories” or “design variables”, which can be “condition”, “batch”, “operator”, “experiment date”, etc. You will be able to choose which category to be used for analysis such as DE, as well as if the category should be treated as categorical or numerical.

  • You can also manually make a design-info file by specifying the sample grouping in PIVOT, and download it for later upload.

  • Empty or NA entries are allowed in design table. But You need to make sure the categories used for DE testing (conditions/time points/batches) do not contain NAs.

  • The design categories will be used as “meta” info for sample coloring in many modules, such as PCA or heatmap.

4.6 Load Example Dataset

  • We have included in PIVOT an example dataset from Dueck, Hannah, et al., 2015. This data consists of a subset of cells from 5 different cell types (brown adipocytes (BA), cardiomyocytes (CM), cortical pyramidal neurons (CPN) and hippocampal pyramidal neuron (HPN)). User can press the question mark button on the top right corner of PIVOT and the “Load Example” button to load this example dataset. Results of many modules have already been pre-computed for users to explore all features of PIVOT.

5 Data Manipulation

5.1 Feature ID/Name Conversion

PIVOT supports automatic ID/Name conversion and supports most of the ID/Names listed in the BioMart database. Despite this powerful feature, we still recommend users to get the feature name right in the first place (i.e., use proper gene id/name output when doing the count quantification), as id/name conversion could inevitably lead to id or name duplicates, and unmapped features.

  • For features that has no match in the database, PIVOT will keep its original ID.
  • For features that map to multiple entries in the database, PIVOT will use the first matched entry.
  • For multiple features that map to one entry in the database, PIVOT will name the duplicates as ‘name.1’, ‘name.2’,etc.
  • Note that feature name conversion will be performed globally. To keep the consistency of downstream subsetting, filtering and analysis, all previous data subsets will be deleted from the current session. Thus, we recommend users convert feature IDs first before generating any data subsets, if necessary.

5.2 Feature Filtering

  • There are currently 3 types of feature filter in PIVOT: the expression filter, which filters based on various expression statistics; the feature list filter, which filters based on user input gene list; and the P-value filter, which filters data with differentially expressed genes.

Expression Filter: PIVOT incorperates the scater package to provide users various QC plots for feature filtering. You can choose any of the stats and select range to only keep those features within the specified range.

  • Filter can be either positive (selecting the genes that satisfy the condition) or negative (delete the genes).

Feature List Filter: You can provide a marker feature list to get a marker feature expression subset.

  • The marker features should appear as the first column in your file.

  • Some of the features in your marker list may not be found in the dataset, because they may have already been removed due to 0 expression in all your samples.

P-Value Filter: