1. Setup tutorial script and dataset
Load Spectre package
To use Spectre, we first need to load the 'Spectre' package, as well as other relevant packages. To do this, follow the instructions below.
- Copy the code on the right into your R script (MyScript.R). Make sure to SAVE.
- Run each line (one by one) by clicking on the line or highlighting the text, and press CMD + return (Mac) or CTRL + Enter (Windows).
- As above, nothing is returned if they are loaded successfully, or an error message is returned if they are not.
- If you have installed Spectre, but the package won't load, then you can visit our installation troubleshooting page.
|If successful||If unsuccessful|
> Error in library("Spectre") : there is no package called ‘Spectre’
Load other required packages
Rather than having to load each individual package required one-by-one (library('plyr'), library('data.table') etc), we have created two functions to simplify this process:
1. packages.check() will check if all the required packages are installed
2. package.load() will load all the required packages
As each package is loaded, you will see the following:
> Loading required package: PACKAGENAME
So far you should have the following code in your script:
2. Set a working directory and create an output directory
Set a working directory
Normally this would be the location of the files you would like to analyse. For now, you can just this as your desktop or similar. If you aren't sure how to search for directories, please have a look at our basic R tutorial.
Create an output directory
Now we will create a directory where we can save the data and plots we will generate shortly.
3. Load data
Load demo data
Normally, we load some CSV or FCS files from the disk, or a server into R for analysis. In this tutorial, we will skip this step, and use an included demo dataset called 'demo.start'. This is a dataset of 120,000 cells, from 12 bone marrow samples: 6x from mock-infected mice, and 6x West Nile virus (WNV)-infected mice. This amounts to 10,000 cells per sample. The data set is structured as a large data.frame (a table) where each column is a cellular marker (e.g. FITC-CD4, etc), and each row is a cell.
Assign the included demo.start dataset to a new object we will call cell.dat.
You can review the structure of cell.dat by using str(). You can see the cell.dat is both a 'data.table' and a 'data.frame'.
You can review the dimensionality of cell.dat by using dim(). The first entry returned is the number of rows, and the second is the number of columns.
You can review the first 6 rows (out of the 10,000 rows) of cell.dat by using head(). Each column is a marker or cellular feature, and each row is a cell.
Set some preferences
Now we can choose the number of each column that we want to use for clustering, rather than having to write out each column name. To do this, we can put the number of the columns in a vector (i.e. c(5,6,8) for columns 5, 6, and 8) within the function below. You can replace these with the column numbers you would prefer to use (if you leave it as c(5,6,8), then the columns used for clustering will be CD117, CD16/32, and CD115.
We can check to make sure the names have been saved by running 'cluster.cols'.
4. Perform clustering and dimensionality reduction
Now we can perform out clustering and dimensionality reduction. First we are going to cluster the data using FlowSOM.
Run clustering (FlowSOM)
We can use the function 'run.flowsom' to run FlowSOM on our 'cell.dat' dataset. For more information on performing clustering in Spectre, see this page. There are two key arguments we need to provide to the function. The first is 'dat', or the dataset to be used. The second is 'clust.cols', which is the columns to be used for clustering. In this case, we want to set dat to cell.dat, and clust.cols to cluster.cols (which we just created).
As the clustering is running, you will see the following red button show up on your RStudio window. That means that RStudio is in the middle of processing something, and it won't respond to other commands while it is working.
While FlowSOM runs, you will progressively see the three following updates:
Mapping data to SOM
Once FlowSOM has finished (and the red button has gone away) you can check the data to ensure the FlowSOM columns have been added correctly.
At the end of what's returned, your should see the FlowSOM metaclusters and clusters added to the dataset
Now we can perform dimensionality reduction on our data for visualisation. For this we are going to use UMAP. For more information on dimensionality reduction and cytometry data, please see this page. There are two key arguments we need to provide to the function. The first is 'dat', or the dataset to be used. The second is 'use.cols', which is the columns to be used for clustering. In this case, we want to set dat to cell.dat, and use.cols to cluster.cols (which we just created). UMAP by default doesn't provide progress updates.
It might take 1-2 minutes for UMAP to finish running.
Once UMAP has finished (and the red button has gone away) you can check the data to ensure the UMAP columns have been added correctly.
Quick visual check
Now that we have run FlowSOM and UMAP, we want to do a quick visual check to make sure everything looks correct. To do this we are going to create a 'factor' plot – a dot plot with our two UMAP columns as the X and Y axis, and the FlowSOM_metacluster as the colour. We are going to add the labels of each cluster to the plot, and we will tell the function not to save the image to disk. Running this command should generate a plot in the viewer window in RStudio.
5. Save data to disk
Now that we have added the cluster and UMAP information to our data, we should save the files and capture our progress.
First, let's set our working directory to 'OutputDirectory', so the data goes to the right place.
To further explore this data in FlowJo, let's also save some FCS files.
6. Make some plots
Now we should create some informative plots.
First we will make another factor plot of the FlowSOM metaclusters, but this time we will set 'save.to.disk' to TRUE. Once this has been run, check your working directory for the image.
Next we'll make a colour plot showing the expression of a specific marker
7. Annotate clusters, generate summary data, create heatmaps and graphs (with stats)
From here, we may decide to annotate our clusters (e.g. clusters 1 and 5 become "B cells", etc), create some summary statistics (proportion of each population, total cells of each population per sample, MFI of each marker on each population, etc), and then great some graphs (with statistics) and heatmaps. More information on these processes can be found on the Spectre Home Page.
Where to next?
Now that you've completed the Spectre tutorial, have a look at our workflow types on the Spectre Home Page.