- 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 3’ Single Cell Gene Expression dataset (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
To load the package, run:
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 be
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.
After installation, you will need to load LoupeR into your workspace by running:
This command will prompt you to run
Please call `setup()` to agree to the EULA before continuing
# Running setup setup()
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 [email protected]
LoupeR provides two commands for converting single cell data in R to
create_loupe. This tutorial describes these two commands and provides downloadable demo Seurat objects to help users get familiar with the commands.
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
create_loupe_from_seurat( obj, output_dir = NULL, output_name = NULL, dedup_clusters = FALSE, executable_path = NULL, force = FALSE )
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 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.
create_loupe is the parent command that is invoked by the
create_loupe offers more control over the clusters and projections included in the CLOUPE file. This command requires additional components (such as a count matrix, clusters, and projections) as inputs.
create_loupe( count_mat, clusters = list(), projections = list(), output_dir = NULL, output_name = NULL, executable_path = NULL, force = FALSE, seurat_obj_version = NULL )
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. 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_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)
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")