10xgenomics / louper

Convert Seurat objects to 10x Genomics Loupe files.

Convert Seurat objects to 10x Genomics Loupe files.

● How To Use ● Installation ● Tutorials ● Loupe Browser Compatibility ● Troubleshooting

loupeR creates a 10x Genomics Loupe file from a Seurat object. 10x Genomics Loupe Browser can visualize single-cell and spatial data from 10x Genomics. Only single-cell gene expression datasets are supported.

How to Use

Converting a Seurat object to a Loupe file is as simple as the following:

# import the library
library("loupeR")

# convert the SeuratObject named `seurat_obj` to a Loupe file
create_loupe_from_seurat(seurat_obj)

Use the function create_loupe if you need more control in the clusters and projections that included in the Loupe file.

# import the library
library("loupeR")

# Gene Expression RNA assay
assay <- seurat_obj[["RNA"]]

# get counts matrix from either the old or newer formats of assay
counts <- counts_matrix_from_assay(assay)

# convert the count matrix, clusters, and projections into a Loupe file
create_loupe(
    counts,
    clusters = select_clusters(seurat_obj),
    projections = select_projections(seurat_obj)
)

Additionally, use the utility function read_feature_ids_from_tsv to read the Ensemble ids from the 10x dataset. A Seurat object will only have imported the feature names or ids and attached these as rownames to the count matrix. In order for the Ensemble id links to work correctly within Loupe Browser, one must manually import them and include them.

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

Installation

HDF5

Before using loupeR, make sure that your system has installed HDF5. The HDF5 organization requires registration before being able to download the installer. Below are some other 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

Installing loupeR from prebuilt bundle

In RStudio, or your R shell, run the following to install this package.

# install dependencies
if (!require("hdf5r")) install.packages("hdf5r")
if (!require("Seurat")) install.packages("Seurat")

# install platform specific source package
os <- sub("Darwin", "macOS", Sys.info()["sysname"])
url <- paste0("https://github.com/10XGenomics/loupeR/releases/latest/download/loupeR_", os, ".tar.gz")
install.packages(url, repos = NULL, type = "source")

Installing loupeR using the remotes package

Another installation option is to use the remotes package to directly install loupeR and its dependencies. The installed package won't include the prebundled louper executable, so you must invoke the loupeR::setup() function which will go and download it.

remotes::install_github("10XGenomics/loupeR")
loupeR::setup()

Loupe Browser Compatibility

With new versions of the Loupe Browser, new version of LoupeR need to be released. The table below shows version requirements between the two.

LoupeR Version	Loupe Browser Version
v1.0.x	Loupe Browser >= 7.0
v1.1.x	Loupe Browser >= 8.0

Tutorials

• Demo notebook with basic processing of an example 10x dataset

Troubleshooting

For more in depth documentation and support please head to our support page or send an email to [email protected]

Additionally, we have provided utility functions to help gather useful information when contacting support or creating a Github issue.

# import the library
library("loupeR")

# print extra debug information
create_bugreport_from_seurat(seurat_obj)

louper's Issues

loupeR with SingleCellExperiment

This is not a big issue, but a small enhancement request. Would be nice to add a function equivalent to create_loupe_from_seurat() but to create a loupe file from a SingleCellExperiment (sce) from Bioconductor. Or at least add some comments about it in the manual. Having a look at the expected input from create_loupe it was quite easy to work around thought. So I leave here the code I used.

## the cluster selection has some requirements, modify the function to work with sce 
select_clusters_sce <- function(obj) {
  # create list
  clusters <- list()
  # Use all factors and character vectors from colData
  for (name in names(colData(obj))) {
    data <- colData(obj)[[name]]
    
    if (is.factor(data)) {
      clusters[[name]] = data
    } else if (is.character(data)) {
      clusters[[name]] = factor(data)
    }
  }
  return(clusters)
}

## The other steps are more straightforward
# extract gene expression
counts <- assay(sce, "counts")
# dimesional reduction - I did not bother making the function as usually there are very few reduced dims calculated, just add here any other desired reduced dimension.
red_dim <- list(UMAP=reducedDim(sce, "UMAP"), TSNE=reducedDim(sce,"TSNE") 

## Construct the loupe file
create_loupe(counts, clusters=select_clusters_sce(sce), projections = red_dim)

Error in creating Loupe file: Error in .make_numeric_version(x, strict, .standard_regexps()$valid_numeric_version) : invalid non-character version specification 'x' (type: double)

Hi 10x Team,

First off, thank you for creating the LoupeR function to make working with Seurat + Loupe easier!

Unfortunately, I keep getting the same error:
"Error in .make_numeric_version(x, strict, .standard_regexps()$valid_numeric_version) :
invalid non-character version specification 'x' (type: double)"

Here is a broad overview my pipeline:

1. SpotClean to clean up the unfiltered data
2. Convert from 'Summarized Experiment' (SpotClean pipeline) to Seurat Object
3. Seurat analysis--SCTransform, RunPCA, FindNeighbors, FindClusters, RunUMAP (outputs a 'Large Seurat' object)
4. LoupeR: create_loupe_from_seurat

I'm really not sure what to make of this error message. Any suggestions? Thanks in advance.

Rebecca

How can I covert the .cloupe file into the format Seurat can read?

Dear author:
How can I covert the .cloupe file into the format Seurat can read?

Support Assay5 assays stored in seurat objects

This fails with a missing counts matrix when the assay is of type SeuratObject::Assay5 instead of SeuratObject::Assay

assay <- seurat_obj[["RNA"]]
counts <- assay@counts

For Assay5 it seems we need to grab the data from the layers slot

assay <- seurat_obj[["RNA"]]
counts <- assay@layers[["counts"]]

To get row and col information from .loupe file

Hello,Thanks for providing us such a wonderful tool!
I have difficult in getting the tissue's 'row' and 'col' information from .loupe file.
From .loupe file, we can only download the 'imagerow' and 'imagecol' information.
I wonder if there is someway to get 'row' and 'col' information from .loupe file or how could transfer 'imagerow' and 'imagecol' to 'row' and 'col'.
Thanks! Best wishes!

Is the category number restricted?

Hi,
Thanks for developing this amazing package. I wonder whether the cell labeling is still restricted as in the old Loupe package? (As I remember, I think the old one could only accept less than 100 types)

Include more metadata

Hello! I appreciate your helpful package. I was waiting for it. I've given it a try, and it's been successful. I have a query regarding the process of adding metadata from the Seurat object to a Loupe file. I've observed that not all metadata is included in the Loupe file, but some are. Is there a specific criterion for pre-selecting which metadata to include? Thank you.

Formatting errors

Hello! I'm trying to take a Seurat object made up of 15 samples and explore it in Loupe after I processed, filtered and integrated it in R. Upon running create_loupe() or create_loupe_from_seurat() I get the following errors:

2024/04/15 15:05:07 validating count matrix
Error in create_loupe(count_mat = count_mat, clusters = clusters, projections = projections,  : 
  
It looks like the formatting of your count matrix does not match the required formatting for LoupeR. For further information, please see the documentation: 10xgen.com/louper

There is an issue with the formatting of your barcodes. Barcodes should begin with base pairs and end with an optional hyphen and suffix. For further information, please see the documentation: 10xgen.com/louper

I've explored the documentation and there really isn't anything explaining this error/what the required format is even supposed to be, so I'm quite lost.

could it be that my barcodes, each coming from 1 of 15 samples have the name attached to them at the front of the barcode? eg// 'Fox12-21_AAACCCACAACGCACAG-1' is my first. That's just the default though. I haven't done anything to mess with them. Any advice on how to proceed is much appreicated.

Keep continuous features created in Seurat

Hi,
I have a seurat object where I have calculated cell cycle scores for each cell, but when I convert it to a cloupe object I lose it as well as other continuous variables. Is there a way to keep them so that my collaborators can visualize them?
Thanks

all values must be less than 32767

Hello,

Thank you for providing this amazing tool. I have a Seurat object with approximately 39,259 cells.

However, I encounter an error when using it. Notably, I don't receive this error with smaller objects. Here's the error message:

2023/09/18 11:50:23 Dataset "/clusters/cells/assignments": all values must be less than 32767
Error in create_loupe(assay@counts, clusters = clusters, projections = projections,  :

Attached is the bug report:

> create_bugreport_from_seurat(seurat_integrated)

Metadata:

tool: loupeR
tool_version: 1.0.0
os: macOS Ventura 13.4
system: aarch64-apple-darwin20 (64-bit)
language: R
language_version: 4.3.1
extra:
     loupeR_seurat_version: 4.9.9.9059
     loupeR_seurat_object_version: 4.1.2
     loupeR_hdf5r_version: 1.3.8
     loupeR_hdf5_version: 1.12.2

Selections:

selected assay:
    RNA
selected clusters:
    active_cluster
    orig.ident
    sample
    DoubletFinder_Ann
    cells
    groupg3v1
    groupg3v2
    groupg4v1
    groupg4v2
    Phase
    mitoFr
    integrated_snn_res.0.4
    integrated_snn_res.0.6
    integrated_snn_res.0.8
    integrated_snn_res.1
    integrated_snn_res.1.2
    integrated_snn_res.1.4
    integrated_snn_res.1.6
    integrated_snn_res.1.8
    integrated_snn_res.2
    integrated_snn_res.2.2
    integrated_snn_res.2.4
    integrated_snn_res.2.6
    integrated_snn_res.2.8
    integrated_snn_res.3
    integrated_snn_res.3.2
    integrated_snn_res.3.4
    integrated_snn_res.3.6
    integrated_snn_res.3.8
    integrated_snn_res.4
    integrated_snn_res.4.2
    integrated_snn_res.4.4
    integrated_snn_res.4.6
    integrated_snn_res.4.8
    integrated_snn_res.5
    integrated_snn_res.5.2
    integrated_snn_res.5.4
    integrated_snn_res.5.6
    integrated_snn_res.5.8
    integrated_snn_res.6
    integrated_snn_res.6.2
    SingleR
    ident_v1
    ident_v2
    ident_v3
    pre.ident
    labeled.ident
selected projections:
    umap

Matrix Sampling:

feature count: 29564
barcode count: 39259
feature sampling:
    AC064852.1
    AC005261.2
    AC133634.1
    LEUTX
    PCDH19
    RAB32
    PPIP5K2
    NXPH2
    IFNE
    CNPY4
barcode sampling:
    Chord101_CCTCCAACAGATCATC-1
    Chord10a_TCACACCTCGCGTGCA-1
    Chord89_CTCATTACAAGACTGG-1
    Chord86b_CCTCTCCTCCAAGCCG-1
    Chord101_CGGGCATAGCCATTTG-1
    Chord101_CCATCACCATGTCAGT-1
    Chord104_TCCACGTCAGATACCT-1
    Chord14a_ATGAGTCGTTGCAAGG-1
    Chord86b_ACTTTCACATAGTCGT-1
    Chord101_TGAGTCACATGGTACT-1

Validation:

    count matrix: (VALID)
    clusters:     (VALID)
    projections:  (VALID)
> 

Could you please assist?

Thank you,
Jesus

Creat Loupe file for Visium HD data

Hi, thank you for developing the tool!
I am trying to create a Loupe file from a Seurat object of Visium HD data. However, I got an error "Barcodes should begin with base pairs and end with an optional hyphen and suffix". The thing is, with visium HD, the barcode doesn't format like that. Below is what the barcodes look like. Do you have any thoughts on how to fix it? Thank you so much!!

s_002um_01765_02581-1
s_002um_02207_02353-1
s_002um_01652_02243-1
s_002um_02278_00850-1
s_002um_01548_00633-1
s_002um_02148_02515-1
s_002um_02684_02407-1
s_002um_01016_01060-1

LoupePy

Hi,
Happy to see that loupeR which can convert seurat object to cloupe. Do you plan to develop loupePy to convert scanpy object to cloupe ? Or some python packages to convert mtx data to cloupe directly ?

HDF5 error after joining multi-layer seurat object

I combined my multi-layer seurat object as recommended, but when I try to export it I still get an issue at the hdf5r step. I have hdf5 installed and the package too. this is the error I get.
Error in x$Priority : $ operator is invalid for atomic vectors

Ensembl link failed

Hi 10x team,

Thank you for developing this package.
When we read10x() and then create the seurat object at first, the gene.colum=2 indicated that only the gene symbol (second column) in the "features.tsv.gz" will be used and stored in seurat object.
This led to the Ensembl link to nothing after generating the .cloupe by loupeR. Do you have any suggestions to fix this issue?

dtx <- Read10X(
  data.dir,
  gene.column = 2,
  cell.column = 1,
  unique.features = TRUE,
  strip.suffix = FALSE
)

Thank you.
Phoebe

Issue with Spatial Projection with Visium CytAssist data

Hello,

Firstly, I'd like to express my gratitude for this excellent package and idea. I am working with Spatial Transcriptomics (ST) data and trying to convert my ST object to a Loupe file. I have successfully created a loop file with the UMAP projection by my chosen clusters.

However, it seems I can't utilize the Spatial projection since I couldn't provide the Image file of my Seurat object. Moreover, I can't access the spatial projection for the Protein assay data either. I am sorry if I overlooked but I couldn't find any instructions or code examples in the documentation regarding this. Any assistance on this would be greatly appreciated.

Thank you in advance.

is it possible to create a loupe object with multiple assays?

Thank you for all of your help!
I currently have two assays that I'd like to look into with loupe, one is the normal count assay, and one is the predictions of cell composition for visium spots. The format of the assay is similar to the counts matrix, with spot barcodes x cell type with each cell having a score, also a lot of 0s, similar to count matrix. Is it possible to extract both of these assays simultaneously?

Thanks!

Issue with creating the loupe file - Louper executable failed: status code 1

Hello,

I was trying out the Demo Notebook by copying the code into RStudio. However, whenever I attempted to create .cloupe files from Seurat objects, I would encounter an error.

Output:

create_loupe_from_seurat(seurat_obj, output_name = "louper_test")
2023/12/12 12:07:59 extracting matrix, clusters, and projections
2023/12/12 12:07:59 selected assay: RNA
2023/12/12 12:07:59 selected clusters: active_cluster orig.ident RNA_snn_res.0.5 seurat_clusters
2023/12/12 12:07:59 selected projections: umap
2023/12/12 12:07:59 validating count matrix
2023/12/12 12:07:59 validating clusters
2023/12/12 12:07:59 validating projections
2023/12/12 12:07:59 creating temporary hdf5 file: C:\Users\mv\AppData\Local\Temp\RtmpIBrWva\file78c07bfee36.h5
2023/12/12 12:08:04 invoking louper executable
2023/12/12 12:08:04 running command: "C:\Users\mv\AppData\Roaming\R\data\R\loupeR\louper.exe create --input=C:\Users\mv\AppData\Local\Temp\RtmpIBrWva\file78c07bfee36.h5 --output=C:\Users\mv\Desktop\louper_test.cloupe"
Usage:
louper create --input=INPUT --output=OUTPUT_PATH [-f | --force] [--name=NAME] [--description=DESCRIPTION]
louper -h | --help
louper --version
Error in create_loupe(counts, clusters = clusters, projections = projections, :
It looks like there was an issue with creating the loupe file. For further information, please see the documentation: 10xgen.com/louper
Louper executable failed: status code 1

I could successfully run the rest of the code from the notebook (even producing the plot). When running create_bugreport_from_seurat(seurat_obj), I get this:

Metadata:

tool: loupeR
tool_version: 1.0.1
os: Windows 11 x64 (build 22621)
system: x86_64-w64-mingw32/x64 (64-bit)
language: R
language_version: 4.3.2
extra:
loupeR_seurat_version: 5.0.1
loupeR_seurat_object_version: 5.0.1
loupeR_hdf5r_version: 1.3.8
loupeR_hdf5_version: 1.8.16

Selections:

selected assay:
RNA
selected clusters:
active_cluster
orig.ident
RNA_snn_res.0.5
seurat_clusters
selected projections:
umap

Matrix Sampling:

feature count: 32285
barcode count: 7377
feature sampling:
Dennd2c
5730460C07Rik
Phldb2
Yif1b
Pkmyt1
D130009I18Rik
Gm47922
Gm38839
CR974586.5
Olfr291
barcode sampling:
CTCATTAGTAACAGTA-1
GTTTACTCAACCCTCT-1
CCGATGGTCATGCCCT-1
TGAGCATAGATAGTGT-1
TTACAGGTCCGTGCGA-1
CAGTTAGCAAGTCCAT-1
GAATCACGTCTGTGTA-1
GCGTTTCCACCCTGTT-1
GTCTAGAGTGCCTATA-1
AACAGGGTCGGCAGTC-1

Validation:

count matrix: (VALID)
clusters:     (VALID)
projections:  (VALID)

If anyone has any suggestions on what I could do to fix this, I would greatly appreciate it.

Thanks in advance.

counts_matrix_from_assay() function doesn't exist

In the README for this package there are the following lines to extract the count data for the create_loupe() function:

# get counts matrix from either the old or newer formats of assay
counts <- counts_matrix_from_assay(assay)

However, after loading the LoupeR package it says this function doesn't exist. In the tutorials the following is utilized, which does work:

# Get the count matrix from a Seurat object:
count_mat <- seurat_obj@assays$RNA@counts

It looks like there was an issue with creating the loupe file.

Hi all,
currently, I have a problem in exporting Seurat project into .cloupe file for Loupe app using LoupeR package.
By running the guilting on test data, I did not have any problem. (https://github.com/10XGenomics/loupeR/blob/main/R/lib.R).
However, when I tried on my data (multiome ATAC GEX Seq), it showed an error in creating the loupe file. (Please see attachment).
Does anyone have an idea? I would appreciate it. Thanks.

DefaultAssay(e145) <- "RNA"
create_loupe_from_seurat(e145, output_name = "e145_DE_R")

2023/12/15 13:18:53 extracting matrix, clusters, and projections
2023/12/15 13:18:53 selected assay: RNA
2023/12/15 13:18:53 selected clusters: active_cluster orig.ident wsnn_res.0.8 seurat_clusters celltype
2023/12/15 13:18:53 selected projections: umap.rna umap.atac wnn.umap
2023/12/15 13:18:53 validating count matrix
2023/12/15 13:18:53 validating clusters
2023/12/15 13:18:53 validating projections
2023/12/15 13:18:53 creating temporary hdf5 file: C:\Users\nguyeh4w\AppData\Local\Temp\RtmpWwRPKc\filecaa81a7e627a.h5
2023/12/15 13:18:54 invoking louper executable
2023/12/15 13:18:55 running command: "C:\Users\nguyeh4w\AppData\Roaming\R\data\R\loupeR\louper.exe create --input=C:\Users\nguyeh4w\AppData\Local\Temp\RtmpWwRPKc\filecaa81a7e627a.h5 --output=C:\Users\nguyeh4w\Data\AG Tuoc offline\Projects\2023-10-16_SingleCellATAC\Analysis_Results\e145\Duy's code\e145_DE_R.cloupe"
Usage:
louper create --input=INPUT --output=OUTPUT_PATH [-f | --force] [--name=NAME] [--description=DESCRIPTION]
louper -h | --help
louper --version
Error in create_loupe(counts, clusters = clusters, projections = projections, :

It looks like there was an issue with creating the loupe file. For further information, please see the documentation: 10xgen.com/louper

Louper executable failed: status code 1

Support for Exporting Spatial Plots to Loupe Browser Format

Dear 10X Team,

I've been using loupeR for exporting Seurat objects to Loupe Browser but noticed it only exports UMAP plots. My work involves 10X Visium spatial data, and having the spatial plots in Loupe Browser is crucial for me.

Is there a way to include spatial plots in the export process, or plans to add this feature? Any advice or workaround would be greatly appreciated.

Thanks for your support and the great work on loupeR.

Best,
Betul

Feature request: Import cluster colors

May I nominate this feature - ideally via a vector or list of hex values external to Seurat, solely to avoid Seurat's choice of not-so-easy-to distinguish colors.

Thanks in advance!

Expression Distribution (Violin plots) remains empty

Hi,

Thanks for making this tool available - most parts work on first attempt ;-)
However, the 'Expression Distribution' panel remains empty. Only horizontal gridlines and y-axis labels are visible, even if I choose highly expressed genes/features.
The 'Differential Expression Output' panel shows gene names in both the Feature Table and the Heatmap, indicating that Loupe has recognised the gene symbols/names

Is this 'expected behaviour'?

Add end to end tests with a mocked louper_executable

Merge annotated spatial information from 10X Visium into cloupe visualizer

Basically, our issue is that we had some data loss and lost the H&E image files and are now reliant on the cloupe outputs to visualize the tissue.

1. Is there a way to extract the high resolution image in the cloupe file? It is higher resolution than the hiresimage.png file.
   or
2. Is there a way for me to upload seurat meta features into an existing cloupe file? For example extract a table with the visium spot barcodes x annotated features from the Seurat object then upload/merge it with the cloupe file?

In reviewing issue #38, it seems like 2. is not currently supported, but in case there is a way to achieve 1. I thought i'd open another issue.

Thank you so much!!

Features not showing up as gene names

Hi!

I've been trying to use Loupe and it seems like a very nice tool so far. One of the problems I'm having though is that when I convert my Seurat Umap to the Loupe format and try to visualize the features, they appear as the regions of the genome and not with their names.

If I visualize those same genes in R with FeaturePlot() I can input the gene names and I get a results, so the information should be within the data I give Loupe. How can I fix this? Here is an example of he options for features I get within Loupe Browser 7:

Chr2-10023-10889
Gene
Feature_4934

Thank you for the help!

Barcodes should begin with base pairs and end with an optional hyphen and suffix

Dears,
The error in the title is thrown with this debugging after calling
create_bugreport_from_seurat(cds)

Metadata:
  
tool: loupeR
tool_version: 1.1.0
os: CentOS Linux 7 (Core)
system: x86_64-conda-linux-gnu (64-bit)
language: R
language_version: 4.3.3
extra:
     loupeR_seurat_version: 5.0.3
     loupeR_seurat_object_version: 5.0.2
     loupeR_hdf5r_version: 1.3.10
     loupeR_hdf5_version: 1.14.3
  
Selections:
  
selected assay:
    RNA
selected clusters:
    active_cluster
    orig.ident
    Phase
    old.ident
    RNA_snn_res.0.5
    seurat_clusters
    RNA_snn_res.0.6
    RNA_snn_res.1
    cell.type
    cell.supertype
    RNA_snn_res.1.2
    RNA_snn_res.1.5
    integrated_snn_res.0.5
    integrated_snn_res.0.7
    integrated_snn_res.1
    cell.type2
    pleura.types1
    cell_clusters_ok
    orig.ident_cell_clusters_ok
selected projections:
    umap
  
Matrix Sampling:
  
feature count: 18722
barcode count: 1075
feature sampling:
    SNUPN
    KRT5
    AL355802.2
    CRIPT
    SLC25A13
    SERTAD2
    ANG
    NT5DC3
    CHST13
    TSSC4
barcode sampling:
CAATACGGTTGCTCGG_1
    TACACGATCTGCCAGG_1
    CGCGGTATCCAAACTG_1
    ACGCCGAGTCTCCCTA_1
    ACAGCCGAGTGCGTGA_1
    GGATGTTGTTACGCCG_1
    ACCCACTTCAAAGTAG_1
    ATGGGAGGTACACCGC_1
    CGATCGGCAGATAATG_1
    CTTTCAAGTGAGTAAT_1
  
Validation:
  
    count matrix: (VALID)
    clusters:     (VALID)
    projections:  (VALID)

cds@version
[1] ‘5.0.2’

While for another object no error is thrown with this debug: (which looks pretty similar to me...)

Metadata:
  
tool: loupeR
tool_version: 1.1.0
os: CentOS Linux 7 (Core)
system: x86_64-conda-linux-gnu (64-bit)
language: R
language_version: 4.3.3
extra:
     loupeR_seurat_version: 5.0.3
     loupeR_seurat_object_version: 5.0.2
     loupeR_hdf5r_version: 1.3.10
     loupeR_hdf5_version: 1.14.3
  
Selections:
  
selected assay:
    RNA
selected clusters:
    active_cluster
    orig.ident
    Phase
    old.ident
    RNA_snn_res.1
    seurat_clusters
    RNA_snn_res.0.5
    RNA_snn_res.0.4
    cell.type
    cell.supertype
    RNA_snn_res.0.1
    RNA_snn_res.0.2
    RNA_snn_res.0.3
    RNA_snn_res.0.6
    RNA_snn_res.0.7
    RNA_snn_res.0.8
    RNA_snn_res.0.9
    RNA_snn_res.1.2
    RNA_snn_res.1.1
    RNA_snn_res.0.95
    RNA_snn_res.0.99
    RNA_snn_res.1.5
    RNA_snn_res.0.15
    integrated_snn_res.0.5
    integrated_snn_res.0.1
    integrated_snn_res.0.09
    cell.clusters
selected projections:
    umap
  
Matrix Sampling:
feature count: 18758
barcode count: 8005
feature sampling:
    UBL4A
    MEGF8
    APPL2
    ADIPOR2
    NGFRAP1
    PLEK
    XYLB
    FAM91A1
    ZNHIT1
    IL1A
barcode sampling:
    CGCGTTTGTGTCCTCT_1
    TCGTACCAGGATATAC_5
    TGCACCTTCACCCGAG_5
    AGGGATGCAACTGCTA_5
    GATGAGGTCAATAAGG_5
    TGAGAGGTCACTCTTA_5
    CACATTTTCCTCCTAG_5
    GCTTCCATCTAACGGT_3
    TCAGCAAAGATCACGG_5
    TTCTACAGTGAGGGTT_1
  
Validation:
  
    count matrix: (VALID)
    clusters:     (VALID)
    projections:  (VALID)
> cds2@version
[1] ‘5.0.2’

Why is that?
Thanks

sessionInfo()
R version 4.3.3 (2024-02-29)
Platform: x86_64-conda-linux-gnu (64-bit)
Running under: CentOS Linux 7 (Core)
  
Matrix products: default
BLAS/LAPACK: /home/garciamanteiga.jose/.conda/envs/sceasy/lib/libopenblasp-r0.3.27.so;  LAPACK version 3.12.0
  
locale:
 [1] LC_CTYPE=en_US.utf-8       LC_NUMERIC=C
 [3] LC_TIME=en_US.utf-8        LC_COLLATE=en_US.utf-8
 [5] LC_MONETARY=en_US.utf-8    LC_MESSAGES=en_US.utf-8
 [7] LC_PAPER=en_US.utf-8       LC_NAME=C
 [9] LC_ADDRESS=C               LC_TELEPHONE=C
[11] LC_MEASUREMENT=en_US.utf-8 LC_IDENTIFICATION=C
  
time zone: Europe/Rome
tzcode source: system (glibc)
  
attached base packages:
[1] stats     graphics  grDevices utils     datasets  methods   base
  
other attached packages:
[1] Seurat_5.0.3       SeuratObject_5.0.2 sp_2.1-4           loupeR_1.1.0

feature_ID instead ENSEMBL ID in .cloupe file

Hello,

when I use create_loupe_from_seurat() or create_loupe() the created .cloupe file contains "feature_ID" instead "ENSEMBL IDs".

What is wrong here?

Lets search for

• Sox17: https://www.ensembl.org/Multi/Search/Results?q=feature_6 --> should be: ENSG00000164736
• Xkr4: https://www.ensembl.org/Multi/Search/Results?q=feature_1 --> should be: ENSG00000206579

The "feature_ID" matches with the row number of the dgCMatrix.

The imported dgCMatrix (outs/filtered_feature_bc_matrix.h5) always contains only gene names or, if no gene name is available, the ENSEMBL ID.
In the *.gtf file, the gene names and ENSEBML ID are stored together or the ENSEMBL ID is stored twice if the gene name is missing.

I am unsure whether this is a bug in the R package loupeR or not, since the SeuratObject nor the dgCMatrix does not contain the ENSEMBL ID for each gene name. This would mean that the user has to take care of adjusting the dgCMatrix stored in the SeuratObject himself.

A solution could be to give the function create_loupe_from_seurat() a *.gtf file or a two-column *.csv file (e.g. read_gtf=), which then replaces the line number (aka feature_ID) for the respective gene names/ENSEMBL-IDs with the ENSEMBL-ID stored in the *.gtf file. This will not work from the dgCMatrix alone.

The .cloupe file created by cellranger count probably uses information from the *.gtf file.

The data set shown in the screenshot was created according to the 10X tutorial.
https://www.10xgenomics.com/support/software/loupe-browser/tutorials/lb-louper

I thank you in advance for your support.

> head(test_object@assays$RNA@counts)
6 x 7377 sparse Matrix of class "dgCMatrix"
  [[ suppressing 53 column names ‘AAACCCAAGGCATCAG-1’, ‘AAACCCAAGGTTCACT-1’, ‘AAACCCACAAAGGCTG-1’ ... ]]
                                                                                                                     
Xkr4    3 3 9 12 19 8 2 1 . 5 . . 3 4 4 8 5 6 . 3 2 2 . 25 2 . . 2 . 1 18 8 . . 15 . 8 4 4 1 21 4 1 . 11 3 . 2 . . 18
Gm1992  . . 1  .  . . . . . . . . . 1 . 2 1 . . . . . .  3 . . . . . 4  2 . . .  3 . . . . .  . 1 . .  2 . . . . .  2
Gm19938 . . 3  1  . . . . . 1 . . 2 1 1 . 2 . . 1 . . .  1 . . . 1 . .  1 1 . .  . . . . . 1  1 . . .  1 . . . . 1  1
Gm37381 . . .  .  . . . . . . . . . . . . . . . . . . .  . . . . . . .  . . . .  . . . . . .  . . . .  . . . . . .  .
Rp1     . . .  .  . . . . . . . . . . . . 1 . . . . . .  . . . . . . .  . . . .  . . . . . .  . . . .  . . . . . .  .
Sox17   . . .  .  . . . . . . . . . . . . . . . . . . .  . . . . . . .  . . . .  . . . . . .  . . . .  . . . . . .  .
                   
Xkr4    13 3 ......
Gm1992   . . ......
Gm19938  1 . ......
Gm37381  . . ......
Rp1      . . ......
Sox17    . . ......

 .....suppressing 7324 columns in show(); maybe adjust 'options(max.print= *, width = *)'
 ..............................

Accept EULA in headless mode

How can I confirm loupeR::setup() in headless mode (e.g. HPC cluster) with yes?

?loupeR::setup() does not give any hints for this.

Creating Loupe from Seurat with spatial information

Hi,
I want to create the loupe file based on my processed Seurat object with spatial infomation, while I do not found the option of loading spatial location in the create_loupe_from_seurat or any relative function. How am I suppose to create a loupe object with the spatial information and combine with my edited metadata?

create_loupe_from_seurat() error: Barcodes should begin with base pairs and end with an optional hyphen and suffix

Hi, I have met the same problem in #8 . just like this:

2024/01/31 19:35:59 extracting matrix, clusters, and projections
2024/01/31 19:36:00 selected assay: RNA
2024/01/31 19:36:00 selected clusters: active_cluster orig.ident CellType_Category Manuscript_Identity Subclass_Cell_Identity Disease_Identity Subject_Identity Library_Identity
2024/01/31 19:36:00 selected projections: umap
2024/01/31 19:36:00 validating count matrix
2024/01/31 19:36:17 validating clusters
2024/01/31 19:36:17 validating projections
2024/01/31 19:38:10 validating input file: /tmp/Rtmprv06ee/file162c3d8c257d.h5
2024/01/31 19:38:12 Dataset "/matrix/barcodes": There is an issue with the formatting of your barcodes.
Barcodes should begin with base pairs and end with an optional hyphen and suffix.
For further information, please see the documentation: 10xgen.com/louper
Error in create_loupe(assay@counts, clusters = clusters, projections = projections,  :

It looks like there was an issue with creating the loupe file. For further information, please see the documentation: 10xgen.com/louper

Louper executable failed: status code 1
Calls: create_loupe_from_seurat -> create_loupe
Execution halted

I try to Rename cell names but not work, could you tell me how to fix it ?
#=============
This is my create_bugreport_from_seurat() result:

Metadata:

tool: loupeR
tool_version: 1.0.1
os: CentOS Linux 7 (Core)
system: x86_64-pc-linux-gnu (64-bit)
language: R
language_version: 4.2.1
extra:
     loupeR_seurat_version: 4.3.0
     loupeR_seurat_object_version: 5.0.1
     loupeR_hdf5r_version: 1.3.6
     loupeR_hdf5_version: 1.10.7

Selections:

selected assay:
    RNA
selected clusters:
    active_cluster
    orig.ident
    CellType_Category
    Manuscript_Identity
    Subclass_Cell_Identity
    Disease_Identity
    Subject_Identity
    Library_Identity
selected projections:
    umap

Matrix Sampling:

feature count: 42628
barcode count: 243472
feature sampling:
    RBM14
    MARK1
    LINC00857
    ENSG00000259536
    ENSG00000241183
    WDR24
    HOTTIP
    TRMT12
    ENSG00000273138
    LINC00476
barcode sampling:
    TCACAAGGTATGAATG-051I_a
    CTTCTCTTCAGTGCAT-051I
    CGGAGCTGTTACAGAA-59I
    CGCTGGACATAAGACA-92C
    TTATGCTCAGCAGTTT-158I_b
    GCTTGAAAGCTAACTC-133C_a
    GCATGATTCTAGAGTC-209I_a
    CTACACGACGCTCTTC-040I_b
    GTAACGTCAAGTTGTC-208C
    AGATTGCGTTCCGGCA-145I_a

Validation:

    count matrix: (VALID)
    clusters:     (VALID)
    projections:  (VALID)

Thanks a lot

Originally posted by @liangyuli12138 in #8 (comment)

Normalized data

Thanks for developing this tool! This is the crucial piece Loupe Browser was missing in order to use it in combination with more advanced analysis.
However, I am a bit disappointed regarding the normalisation. I see the Cloupe file can only store the raw counts, and Loupe Browser does a rather simple normalisation. It would be great if the "data" slot and/or the SCTransform assay could be added and then made available in the "scale value" drop-down menu on top of the available "Log" and "LogNorm".

Creating Loupe file from Seurat fails in R 4.4.0

The function create_loupe_from_seurat() fails in R 4.4.0 (working fine in previous versions) when referencing .make_numeric_version with the following error:

extracting matrix, clusters, and projections
Error in .make_numeric_version(x, strict, .standard_regexps()$valid_numeric_version) :
invalid non-character version specification 'x' (type: double)

Error in select_assay(obj) : no slot of name "counts" for this object of class "Assay5"

Hello,

Firstly, thank you for creating this package. It is exactly what I am looking for if I can get it to work.

I get the error below upon calling the create_loupe_from_seurat method:

Error in select_assay(obj) : 
  no slot of name "counts" for this object of class "Assay5"

My matrix is not generated by cellranger but by epi2me-labs/wf-single-cell workflow using nanopore data, so I've only used the counts matrix as input for the Seurat object. Irrespective of this, even when I try calling create_loupe_from_seurat using 10X data, like in the demo tutorial you link to in the README, I get the same error. This makes me wonder if there is something peculiar about my loupeR or Seurat installation. I'd appreciate any help to resolve this.

I'm running (if this helps):
R version 4.3.2 (2023-10-31)
Platform: x86_64-pc-linux-gnu (64-bit)
Running under: Ubuntu 20.04.6 LTS
other attached packages:
[1] hdf5r_1.3.8 loupeR_1.0.1 dplyr_1.1.4 cowplot_1.1.1 ggplot2_3.4.4 Seurat_5.0.1 SeuratObject_5.0.1
[8] sp_2.1-2

Thank you

Error in self$set_size(size) : HDF5-API Errors: error #000: /tmp/hdf5-20240208-26272-vz5oib/hdf5-1.14.3/src/H5T.c in H5Tset_size(): line 2317: size must be positive

Hello, I am getting this error when running this on my Visium object.
I have checked that the seruat object version is >5

my code is:
for (i in sample_IDs_list) { print(i) filename=paste0(i, "_anno") #print(filename) tmp_obj=obj_list[[i]] print(Version(tmp_obj)) #tmp_obj<-UpdateSeuratObject(tmp_obj) create_loupe_from_seurat(obj=tmp_obj, output_dir="/Box/Spatial_Data/Annotated_cloupe", output_name=filename) break }

When I inspect the counts slot via tmp_obj@assys$RNA@counts I can see a matrix with counts. How do I extract this matrix?

how to query DEG for a single cell-cluster across treatment/genotype

hello
awesome tool for converting Seurat_Objects into a .cloupe file, will come in handy for collaborations

i used the 'create_loupe_from_seurat( )' function and got the .cloupe file

i can run the DEG within loupe browser to query between 2 clusters, but can not compare a single cell cluster across treatment groups (in my case CTRL and treatment).
i know that I can do DEG on a cell-cluster in Seurat, but was wondering if loupe browser had this capability
thx
Bryant

Image is missing, when using visium data.

When using Visium data, after format conversion, the image is lost. Can you provide a method to retain the image?

create_loupe_from_seurat() error: Barcodes should begin with base pairs and end with an optional hyphen and suffix

Hi,

I tried to convert 10x formatted matrix files (barcodes.tsv.gz, features.tsv.gz, matrix.mtx.gz; example files are here) into cloupe file. The code I used is as below.

library(Seurat)
library(loupeR)
sp6_data <- Read10X(data.dir = "/path/to/above/example/files", gene.column = 1)
pbmc=CreateSeuratObject(counts = sp6_data, min.cells = 3, min.features = 200)
pbmc <- ScaleData(pbmc, verbose = FALSE)
pbmc <- FindVariableFeatures(object = pbmc)
pbmc <- RunPCA(pbmc, features = VariableFeatures(object = pbmc))
pbmc <- RunUMAP(pbmc, dims = 1:10)
pbmc <- FindNeighbors(pbmc, dims = 1:30)
pbmc <- FindClusters(pbmc, resolution = 0.8)
loupe_sp6<-create_loupe_from_seurat(pbmc,output_name="loupe_sp6_from_seurat")

The last step showed an error:

2023/10/05 02:13:22 extracting matrix, clusters, and projctions
2023/10/05 02:13:22 selected assay: RNA
2023/10/05 02:13:22 selected clusters: active_cluster orig.ident RNA_snn_res.0.8 seurat_clusters
2023/10/05 02:13:22 selected projections: umap
2023/10/05 02:13:22 validating count matrix
2023/10/05 02:13:22 validating clusters
2023/10/05 02:13:22 validating projections
2023/10/05 02:13:24 validating input file: /tmp/Rtmp59LgRw/file11a41805552.h5
2023/10/05 02:13:26 Dataset "/matrix/barcodes": There is an issue with the formatting of your barcodes.  
Barcodes should begin with base pairs and end with an optional hyphen and suffix.
For further information, please see the documentation: 10xgen.com/louper
Error in create_loupe(assay@counts, clusters = clusters, projections = projections,  : 
  
It looks like there was an issue with creating the loupe file. For further information, please see the documentation: 10xgen.com/louper

Louper executable failed: status code 1

My barcodes were formatted with something like "AAACCCAAGGCATCAG-1", complying with "Barcodes should begin with base pairs and end with an optional hyphen and suffix". Why this error? Thanks in advance.

loupeR in a Docker/Singularity container

Dear 10X team,
I was wondering whether it would even be legal to include loupeR into a Docker container to run a Nextflow pipeline and output the Cloupe file (from a Seurat object, so the cloupe files generated by CellRanger are not what I mean).
If I interpret the license correctly (point 3), it is not
https://github.com/10XGenomics/loupeR/blob/main/LICENSE

I would be thankful for any advice how this can be solved (if it can). If the only way is to ask the end user of the pipeline to install loupeR and run setup(), then this is the way to go.

thanks a lot!
Sergej

How to get expression matrix from cloupe file in R or Loupe browser?

I get a few cloupe(Visium) files from research paper, but i can only get coordinate data from Loupe browser.