tSNEplots (v1.3)

Automated generation of coloured tSNE plots



'tSNEplots' is an R script for automatically creating coloured tSNE plots. Follow the instructions within the R script to execute, or follow the instructions here.

There are two versions of this script. In the main script (tSNEplots.R), the colour scale for each sample is handled independently. In the new script (tSNEplots_global_scaling.R) the colour, X, and Y scales are 'global', so for any given marker the maximum and minimum will be the same between samples.

This script accepts .csv files as input. A version to read straight from .fcs files will follow soon.

How to download

Go to our github 'releases' (https://github.com/sydneycytometry/tSNEplots/releases) and download source code for the latest version.


If you use this script in your work, please cite this github using the information below. You can cite the specific version that you used in your work (most recent version = v1.3).


Ashhurst, T. M. (2017). tSNEplots v1.3. GitHub repository. Repository: https://github.com/sydneycytometry/tSNEplots.


Citation in EndNote

In EndNote: citaton can be stored as ‘Computer Program’ or ‘Webpage’.

Author = Ashhurst, Thomas Myles
Year = 2017
Title = tSNEplots v1.3
Journal = GitHub repository
Publisher = Github
Website = https://github.com/sydneycytometry/tSNEplots

R and R studio

To use this script you will need to download R (https://www.r-project.org) and R Studio (https://www.rstudio.com). If you are new to R, a tutorial on running R scripts in RStudio can be found at www.sydneycytometry.org.au/usingr.



The intended input files for tSNE plots are .csv files, where each row represents a cell, and each column represents a measured parameter (CD45, CD4, ClusterNumber, tSNE1, tSNE2, etc). For all .csv files present, you will pick one column as the X parameter, and one column as the Y parameter. The script will then generate a plot of your data (using the chosen X and Y parameters) and colour each cell on the plot by the number in the first column. The script will then repeat this for each column, and will repeat this for each .csv file (maintaining the same X and Y parameters).

The individual .csv files can represent individual samples, a merged group of samples, the merged samples from entire experiment, or all of the above. The fundamental requirements are that all .csv files have the same number of columns, and all columns have the same names in each file.

There is a demo .csv file included when you download the latest release of tSNEplots from github (https://github.com/sydneycytometry/tSNEplots). You can use this to test the script.


Setting up your script

Place the R script (tSNEplots.R) in the same folder as the files you want to analyse. Right click on the script and select open with / RStudio. In R studio you can click on a single line and press CMD + return (on Mac) or CTRL + enter (on Windows) to run the command on that line. Alternatively, you can highlight any section of text over one or more lines and press CMD + return (on Mac) or CTRL + enter (on Windows) to run the contents. This script is designed so 'modules' of code can be run. Text on any line beginning with a '#' denotes a comment. This text will not be read by RStudio as a command, rather it is there to instruct the users.


STEP 1: Loading packages

Step 1 of the tSNE plots script is the installation and loading of packages. Select all of the text shown in the snippet below, and press CMD + return. R studio will then install the packages ggplot2, colorRamps, ggthemes, and scales; if they aren't already installed.

##### STEP 1: Load packages and setup required for script #####

  ## Will install packages (if not already installed)
  if (!require("ggplot2")){install.packages("ggplot2")} # for plotting tSNE graphs
  if (!require("colorRamps")){install.packages("colorRamps")} # for colour scheme management
  if (!require("ggthemes")){install.packages("ggthemes")} # for plot themes
  if (!require("scales")){install.packages("scales")} # for re-scaling if necessary

Select all of the code below and press CMD + return to load the packages, and also to create a colour spectrum that we'll call 'jet.colors'. By default, cells with the lowest expression of a marker will be blue, and the highest will be red.

  ## Load packages
  library(ggplot2) # for plotting tSNE graphs
  library(colorRamps) # for colour scheme management
  library(ggthemes) # for plot themes
  library(scales) # for re-scaling, only if necessary

  ## Create 'jet' colour scheme (not available by default in R)
  jet.colors <- colorRampPalette(c("#00007F", "blue", "#007FFF", "cyan", "#7FFF7F", "yellow", "#FF7F00", "red", "#7F0000"))


Next set your working directory (wherever your .csv files are), and assign this as 'PrimaryDirectory'.

##### STEP 2a: USER INPUT #####
  ## Set your working directory here (e.g. "/Users/Tom/Desktop/")

  ## Check your working directory has changed correctly
  ## Assign the working directory as 'PrimaryDirectory'
  PrimaryDirectory <- getwd()

Next, generate a list of .csv files.

  ## Create a list of file names (names of the samples) and check file names
    FileNames <- list.files(path=PrimaryDirectory, pattern = ".csv")

Next, check the column names of one of your files, and use this to define the X and Y parameters for plotting.

    ## Enter the name of your first sample in between the "", and to check the tSNE parameter names (could be bhSNE, bh.SNE, vSNE, tSNE, etc)

    ## In the output of the previous line, you will see the names for the tSNE parameters -- insert them in between the "" below
    plotXname <- "tSNE1"
    plotYname <- "tSNE2"

All the code after the "END USER INPUT LINE" can be select and run at once.

        ########### END USER INPUT ########### 

Aspects of code below this line can be modified based on user preferences. 

  • The size of the points can be changed on line 104 (size = 0.5)
  • The dimensions of the saved image can be changed on line 133 (width = 4, height = 3)