FLOWMAPR

This repository houses the code for the FLOW-MAP algorithm, which was developed in R and originally published in Zunder et al., "A Continuous Molecular Roadmap to iPSC Reprogramming Through Progression Analysis of Single Cell Mass Cytometry." Cell Stem Cell 2015.

This code has been reformatted and compiled into a single R package known as FLOWMAPR, for extensible analysis of single-cell datasets including FCS files generated from mass/flow cytometry or data.frames of other single-cell data processed in R. This README provides full instructions for how to install, set-up, and use FLOWMAPR. Other details, including a comparison with other visualization tools for single-cell data, will be published imminently and linked when available.

Version 2 released June 2020:

1. Better scalability to large cell numbers (when using UMAP layout)
2. Removes bugs specified in issues from v1
3. Removes need for dependencies that were no longer maintained & causing install issues

Navigation

<!-- [Code Status]() -->

Getting Started: Installing FLOWMAPR
Updating FLOWMAPR
Running FLOWMAPR: Starting from FCS Files
Running FLOWMAPR: Starting from a Dataframe in R
Example Code for FLOWMAP()
Example Data
Example Output
Example Code for FLOWMAPfromDF()
Practical Guidelines for Running FLOWMAPR
Practical Guidelines for Post-Processing in Gephi
Using the GUI
Authors and License

Getting Started

FLOWMAPR visualizations can be run on any 32- and 64-bit computer with at least 2.2-GHz processor running Windows or Mac OS X with ≥4 GB of RAM (16 GB preferred). FLOWMAPR was developed and tested on a 64-bit computer with a 2.7-GHz processor running Mac OS X (Version 10.11.6) with 16 GB of RAM.

The instructions below demonstrate how to install this package directly from Github to get the latest release.

Software and Package Prerequisites:

Install version 3.3.0 or later of R. Users can install R by downloading the appropriate R-x.y.z.tar.gz file from http://www.r-project.org and following the system-specific instructions. FLOWMAPR was developed and tested on version 3.3.0 of R. As of this release, we recommend using version 3.3.0.

FLOWMAPR depends on the following R libraries: igraph (version 1.2.1), Rclusterpp (version 0.2.3), SDMTools (version 1.1.221), robustbase (version 0.92.8), shiny (version 1.0.5), tcltk (version 3.4.3), rhandsontable (version 0.3.6), spade (version 1.10.4) and flowCore (version 1.44.2) from Bioconductor, and scaffold (version 0.1) published on the Nolan Lab GitHub. The versions provided are the R package versions for which this FLOWMAPR code has been tested.

In order to install a package from github, you will need the devtools package. You can install this package with the following commands:

install.packages("devtools")
library(devtools)

FLOWMAPR package depends on several packages, which can be installed using the below commands:

install.packages("igraph")
install.packages("robustbase")

install.packages("remotes")
remotes::install_version("SDMTools", "1.1-221")

if (!requireNamespace("BiocManager", quietly = TRUE))
  install.packages("BiocManager")
BiocManager::install("flowCore")

The GUI has package dependencies for multiple Shiny-related packages and Rhandsontable. Install these packages with:

install.packages("shiny")
install.packages("shinythemes")
install.packages("shinyFiles")
install.packages("shinydashboard")
install.packages("shinyalert")

devtools::install_version("rhandsontable", version = "0.3.4", repos = "http://cran.us.r-project.org")

Lastly, FLOWMAPR utilizes the R/C++ implementation of ForceAtlas2 as made available in the 'vite' package:

devtools::install_github("ParkerICI/vite")

<a name="install"></a>

Installing FLOWMAPR:

To currently get the FLOWMAPR R package up and working on your computer, once you have installed all package dependencies (see above):

1. Make a github account if you haven't already.
2. Get access to repo zunderlab/FLOWMAP for your github account.
3. Create a token by going to this site when logged into your github account: https://github.com/settings/tokens/new
4. Check off "repo" in the settings for your token.
5. Click generate token and copy/save the provided code (your PAT) somewhere.
6. Open R studio and load devtools using library(devtools). If you don't have devtools you may have to install it with install.packages("devtools") and then use library(devtools).
7. Type the following into R studio: install_github(repo = "zunderlab/FLOWMAP", auth_token = "PAT") but replace PAT in quotations with your code in quotations. This should start installing all library dependencies so it may take a bit to finish. Check that it finishes without ERROR messages, though it may print WARNINGS.

Typical installation time should take no more than 5 minutes for the most up-to-date FLOWMAPR package. However, total installation time will vary depending on the installation time of other required packages and the speed of your internet connectoin.

<a name="update"></a>

Updating FLOWMAPR:

To quickly update your FLOWMAPR R package and get the latest version from GitHub:

1. Open R studio and load devtools using library(devtools).
2. Type the following into R studio: install_github(repo = "zunderlab/FLOWMAP", auth_token = "PAT") but replace PAT in quotations with your code in quotations.
3. Load FLOWMAPR using library(FLOWMAPR).

If the above commands run without error, you should have the latest version of FLOWMAPR.

Running FLOWMAPR

<a name="FLOWMAPR-FCS"></a>

Starting from FCS Files:

To run a FLOW-MAP analysis on your data set if you are using FCS files or an example data set:

0. Make your data available and parseable by FLOWMAPR.

• For MultiFLOW-MAP, you must specify the "files" variable as a directory wherein each subfolder represented samples at the same time. If FCS files in the same subdirectory that come from different time points (e.g. "ConditionA-d01.fcs" with "ConditionB-d02.fcs"), FLOWMAPR will pick one time label arbitrarily.
• Please make sure the time labels can be parsed and sorted with proper labels (e.g. "01", "02", "04", "06", "10" vs. "1", "2", "4", "6", "10" where it would sort as "1" and "10" first instead of "10" last).
• To properly label each condition within the timepoint, please put the Condition as the first part of the file name separated by "-" or "." characters (e.g. "ConditionA-d01.fcs" where "ConditionA" will be the condition label).
• Do not use any digits (i.e. 0-9) in the name of the FCS file unless they specify time. Change any labels for the conditions in the FCS file name to be alphabetical characters. Ex: Condition1-t24.fcs should be renamed to ConditionOne-t24.fcs or else the time label will be parsed as "124" instead of "24" for this file.
• Please note that when your FCS files are loaded into FLOWMAPR, any "Time" variables already in the data will be removed and overwritten with the "time" of each FCS file.

1. Once you have successfully installed and loaded FLOWMAPR using library(FLOWMAPR), if you are working in R Studio, you should see FLOWMAPR::FLOWMAP() autocomplete if you type it into the command line.
2. Establish variable names (you can copy the way they are assigned from the FLOWMAP_run.R file to declare each variable). Some variables you have to assign are:

• mode - what type of FLOW-MAP you want to run, this can be "single" - one condition, multiple timepoints, "multi" - multiple conditions, multiple timepoints or "one" - one condition, one timepoint
• files - the directory where you can find the FCS files to be used
• name.sort - sort FCS files according to name in alphabetical/numerical order, default is set to TRUE for sorting
• seed.X - an integer that sets the seed, can be re-used to reproduce results, default is set to 1
• var.remove - any channels you want completely excluded from analysis, you can auto-generate a suggested vector of variables for removal using the FLOWMAPR::SuggestVarRemove() function and supplying var.annotate as well as an optional var.to.remove vector that describes a character string for channels that should be removed (for example, blank channels in FCS files for mass cytometry may retain the "Di" or "Dd" substring in the desc, like in "Ba138Di"), default is to remove these channels with "Di" or "Dd" in the desc
• var.annotate - rename channels as you see fit, the names you provide will the ones used to print out the PDFs, you can auto-generate a suggested var.annotate based on the desc attribute in your FCS files by using the FLOWMAPR::ConstructVarAnnotate() function and supplying a single FCS file name (full path)
• clustering.var - which channels to use to influence the graph shape, you can generate a set of suggested clustering.var using the FLOWMAPR::SuggestClusteringVar() function, supplying the variables fcs.file.names (complete set of FCS files to be used in analysis), mode (as in FLOWMAPR mode), var.annotate, var.remove, top.num (which specifies how many clustering variables you want to use, less than the total number of variables in the dataset)
• cluster.numbers - how many clusters to generate from each subsampled file, recommended ratio 1:2 from subsample (if subsample = 1000, recommended cluster.numbers = 500), default is set to 100
• distance.metric - choose "manhattan" or "euclidean" for most cases, default is set to "manhattan"
• subsamples - how many cells to randomly subsample from each FCS file, default is set to 200
• downsample - use density-dependent downsampling, in which case you may want to specify and pass optional variables exclude.pctile, target.pctile, target.number, target.percent, default is se