10x Genomics Support/Loupe Browser/Tutorials/

LoupeR to Generate CLOUPE files from Seurat Objects

LoupeR is available for download on the 10x Genomics LoupeR GitHub page.
  • 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)
Important
LoupeR is an R package designed to empower community tool users and developers to incorporate Loupe Browser for data exploration and collaboration. The documentation and code provided here is for instructional purposes only. 10x Genomics does not support issues such as installing R or data wrangling (formatting data).

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:

  • macOS with Homebrew: brew install hdf5
  • windows with vcpkg: .\vcpkg install hdf5

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.

  1. 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 loupeR_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')
  1. 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 [email protected]

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,
    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

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. 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,
    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.
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)

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")