- Learn about 10x Genomics’ LoupeR (an R package) to convert Seurat objects into CLOUPE files
- Download the LoupeR package
- Run LoupeR commands in RStudio with downloadable examples
- Familiarity with the R programming language
- Working installation of R
- Familiarity with installing R packages
- A 10x Genomics Gene Expression dataset (must be 3', 5', or Flex - other types of data are not supported)
10x Genomics’ LoupeR is an R package that works with Seurat objects to create a .cloupe file. The .cloupe file can then be imported into Loupe Browser v7.0 for data visualization and further exploration.
LoupeR makes it easy to explore:
- Data from a standard Seurat pipeline
- Data generated from advanced analysis that contains a count matrix, clustering, and projections
A Seurat object serves as a container for single cell gene expression datasets that can be parsed by R.
It stores all the information for a given single cell analysis including data (count matrix), annotations, and analyses (PCA or clustering results) from a single cell gene expression dataset.
10x Genomics does not provide support for the creation of Seurat objects.
Before using the LoupeR package, your system must have HDF5 installed. The HDF Group requires registration before downloading the installer.
There are more convenient methods for installing HDF5, if you happen to have these package managers installed:
You will also need to download and install the following R packages:
install.packages("hdf5r")
install.packages('Seurat')
install.packages("remotes") # If you want to intall the package remotely
You will only need to run the installation commands once. However, you may need to load the LoupeR package into your R environment every time you start a new workspace (depending on how you invoke the louper command).
To load the package, run:
library(loupeR)
There are two ways to download and install the LoupeR package.
- LoupeR is available for download on the 10x Genomics LoupeR GitHub page. Find the version that you want and download the platform-specific
loupeR_PLATFORM.tar.gz. For example, on macOS, the filename would beloupeR_macOS.tar.gz.
In RStudio (or R shell), run the following to install this package:
install.packages(PATH_TO_TAR_GZ, repos = NULL, type ='source')
- Install LoupeR using the remotes package to directly install LoupeR and its dependencies. The installed package will not include the pre-bundled LoupeR executable, so you must invoke the loupeR::setup() function which will go and download it.
remotes::install_github("10xGenomics/loupeR")
loupeR::setup()
After installation, you will need to load LoupeR into your workspace by running:
library(loupeR)
This command will prompt you to run setup():
Please call `setup()` to agree to the EULA before continuing
# Running setup
setup()
Type y and ENTER to agree to 10x's EULA.
> setup()
EULA
Do you accept the End-User License Agreement fount at https://10xgen.com/EULA (y/yes or n/no):
You are now ready to use LoupeR. For further installation support, email support@10xgenomics.com
LoupeR provides two commands for converting single cell data in R to .cloupe files: create_loupe_from_seurat and create_loupe. This tutorial describes these two commands and provides downloadable demo Seurat objects to help users get familiar with the commands.
The create_loupe_from_seurat function can be used to convert a Seurat Object to a CLOUPE file. It passes the active counts matrix, reductions, and factors found in meta.data to create a CLOUPE file. Please note that only the count matrix (RNA assay) will be used to generate the CLOUPE file. SC transformations, integrated or other assays will not be stored in the Loupe file. Refer to the support page to learn about how Loupe visualizes count data.
If you have a Seurat object (let's call it seurat_obj), run:
create_loupe_from_seurat(seurat_obj)
USAGE:
create_loupe_from_seurat(
obj,
output_dir = NULL,
output_name = NULL,
dedup_clusters = FALSE,
feature_ids = NULL,
executable_path = NULL,
force = FALSE
)
ARGUMENTS:
obj a Seurat Object
output_dir optional directory where the CLOUPE file will be written
output_name optional name of the CLOUPE file with the extensions not included.
dedup_clusters optional logical that will try to deduplicate all clusters that are numerically the same
feature_ids optional character vector that specifies the feature ids of the count matrix. Typically, these are the Ensembl ids.
executable_path optional path to the louper executable.
force optional logical as to whether we should overwrite an already existing file
Example dataset and R command
10x Genomics has created this example Seurat object from on a publicly available 10x dataset.
Customize and run this R script
# Load the Seurat object
seurat_obj <- readRDS("/path/to/test_object.RDS")
# Run the command
create_loupe_from_seurat(seurat_obj, output_name = "loupe_from_seurat_test")
You should see a file called loupe_from_seurat_test.cloupe in your working directory.
The function create_loupe is the parent command that is invoked by the create_loupe_from_seurat command. create_loupe offers more control over the clusters and projections included in the CLOUPE file.
Unlike create_loupe_from_seurat, which is tailored for Seurat outputs, create_loupe can be used to import data from sources other than Seurat, making it versatile for various workflows.
This command requires additional components (such as a count matrix, clusters, and projections) as inputs.
USAGE
create_loupe(
count_mat,
clusters = list(),
projections = list(),
output_dir = NULL,
output_name = NULL,
feature_ids = NULL,
executable_path = NULL,
force = FALSE,
seurat_obj_version = NULL
)
ARGUMENTS
count_mat a sparse dgCMatrix
clusters list of factors that hold information for each barcode
projections list of matrices, all with dimensions (barcodeCount x 2)
output_dir optional directory where the Loupe file will be written
output_name optional name of the Loupe file with the extensions not included
feature_ids optional character vector that specifies the feature ids of the count matrix. Typically, these are the Ensembl ids.
executable_path optional path to the louper executable.
force optional logical as to whether we should overwrite an already existing file
seurat_obj_version optional string that holds the Seurat Object version. It is useful for debugging compatibility issues.
Helper functions to extract clusters and projections
LoupeR's helper functions select_clusters and select_projections can be used to extract clusters and projections, respectively, from a Seurat object. Usage is shown here:
clusters <- select_clusters(seurat_obj)
projections <- select_projections(seurat_obj)
The helper function read_feature_ids_from_tsv can be used to read the Ensembl ids from the 10x dataset. Usage is shown here:
# import the library
library("loupeR")
# Gene Expression RNA assay
assay <- seurat_obj[["RNA"]]
# A character vector of ensemble ids.
feature_ids <- read_feature_ids_from_tsv("PATH_TO_10X_DATA/features.tsv.gz")
create_loupe_from_seurat(seurat_obj, feature_ids = feature_ids)
Example dataset and R command
10x Genomics has created example projections and clusters for the same example Seurat object used to demo the create_loupe_from_seurat command. Download these two files and load them into your working directory. Alternatively, you may use the helper functions described above to extract these files (instead of downloading the examples we created).
Then customize and run this R script:
# Load the Seurat object:
seurat_obj <- readRDS("/path/to/test_object.RDS")
# Get the count matrix from a Seurat object:
count_mat <- seurat_obj@assays$RNA@counts
# Load the clusters file
clusters <- readRDS("/path/to/clusters.RDS")
# Load the projections file
projections <- readRDS("/path/to/projections.RDS")
# Run create_loupe
create_loupe(count_mat = count_mat, clusters = clusters, projections = projections, output_name = "create_loupe_test")