haojiawu / cellscopes.jl

A Julia package for single cell and spatial data analysis

CellScopes.jl

CellScopes.jl is a toolkit built using the Julia programming language, designed for the analysis of single cell and spatial transcriptomic data. It offers a range of functionalities including data normalization, dimensional reduction, cell clustering and visualization, all tailored to various types of data generated by scRNA-seq, scATAC-seq, Visium, Xenium, Slide-seq, MERFISH, seqFISH, STARmap and Cartana. The current version of CellScopes.jl is structured as follows:

1. Installation

1.1. Julia

1.1.1. Install Julia 1.7.3

To install CellScopes.jl, you will need to have Julia 1.6 or higher installed. It is recommended to use Julia 1.7.3 or higher to avoid issues with dependencies. Here we will show how to install Julia in the Linux system.

Assume you have access to the directory /home/users/doe. Here is how to install Julia 1.7.3.

cd /home/users/doe/
wget https://julialang-s3.julialang.org/bin/linux/x64/1.7/julia-1.7.3-linux-x86_64.tar.gz
tar xvf julia-1.7.3-linux-x86_64.tar.gz

Then add Julia to PATH. Assume you have a ~/.bashrc file, then append the following code to the end of the ~/.bashrc file.

export PATH=/home/users/doe/julia-1.7.3/bin:$PATH

To implement your changes, either open a new login session or reload the .bashrc via

source ~/.bashrc

1.1.2. Install CellScopes and dependencies

To install all of the necessary dependencies, run the following command line in Julia. Note that this will not install the unregisterd package Leiden.jl, which you may need to install manually from the GitHub repository first.

using Pkg;
Pkg.add(url="https://github.com/bicycle1885/Leiden.jl") # Install the unregistered dependency Leiden.jl
Pkg.add(url="https://github.com/TheHumphreysLab/CellScopes.jl") # Install CellScopes.jl

1.2. Docker

Alternatively, you can use Docker. It contains executable cellscopes to run CellScopes from CLI, as well as IJulia installation to use CellScopes with Jupyter. The repo will be updated if newer versions are ready.

docker pull thehumphreyslab/cellscopes

docker run -it --rm thehumphreyslab/cellscopes

The container's Port ID for cellscopes is 5237. A tutorial for connecting to Docker Jupyter Notebook on the remote server from a local terminal can be found here.

2. Tutorials

CellScopes supports analysis for single-cell RNA sequencing (scRNA-seq), single-cell ATAC-seq (scATAC-seq), Visium, Slide-seq, Cartana, MERFISH, seqFISH, STARmap and Xenium datasets. For more information, please refer to the tutorials provided below.
a. dRNA HybISS by Cartana: https://github.com/HaojiaWu/CellScopes.jl/tree/main/docs/cartana_tutorial
b. scRNA-seq: https://github.com/HaojiaWu/CellScopes.jl/tree/main/docs/scRNA_tutorial
c. scATAC-seq: https://github.com/HaojiaWu/CellScopes.jl/tree/main/docs/scATAC_tutorial
d. 10x Visium: https://github.com/HaojiaWu/CellScopes.jl/tree/main/docs/visium_tutorial
e. 10x Xenium: https://github.com/HaojiaWu/CellScopes.jl/tree/main/docs/xenium_tutorial
f. MERFISH: https://github.com/HaojiaWu/CellScopes.jl/tree/main/docs/MERFISH_tutorial
g. Slide-seq: https://github.com/HaojiaWu/CellScopes.jl/tree/main/docs/SlideSeq_tutorial
h. seqFISH: https://github.com/HaojiaWu/CellScopes.jl/tree/main/docs/seqfish_tutorial
i. STARmap: https://github.com/HaojiaWu/CellScopes.jl/tree/main/docs/starmap_tutorial

In addition to these standalone CellScopes analyses, we also provide tutorials how CellScopes can interact with other popular tools such as Seurat, Scanpy and tools for gene imputation and spot deconvolution.
j. Conversion of Scanpy AnnData to CellScopes Objects: https://github.com/HaojiaWu/CellScopes.jl/tree/main/docs/scanpy_conversion
k. Conversion of Seurat Objects to CellScopes Objects: https://github.com/HaojiaWu/CellScopes.jl/tree/main/docs/seurat_conversion
l. Gene imputation using SpaGE, tangram and gimVI: https://github.com/HaojiaWu/CellScopes.jl/tree/main/docs/gene_imputation

Finally, we also provide tutorials for incorporating high-resolution H&E and nuclei staining images for Visium and Xenium data visualization.
m. Visium data visualization with a high-resolution H&E image: https://github.com/HaojiaWu/CellScopes.jl/tree/main/docs/Visium_more_viz
n. Xenium data visualization with a high-resolution H&E/DAPI image: https://github.com/HaojiaWu/CellScopes.jl/tree/main/docs/Xenium_more_viz

3. Citation

If the tool is helpful to your study, please consider citing our paper:
https://www.nature.com/articles/s41467-024-45752-8
Nature Communications. 2024 Feb 15;15(1):1396.
Wu H, Dixon EE, Xuanyuan Q, Guo J, Yoshimura Y, Debashish C, Niesnerova A, Xu H, Rouault M, Humphreys BD.
High resolution spatial profiling of kidney injury and repair using RNA hybridization-based in situ sequencing.

4. Contact

For more information, please contact The Humphreys Lab or follow our Twitter account @HumphreysLab

cellscopes.jl's Issues

savings images from the julia command line? how to reload xenium CellScopes object?

Two questions:

1. Is there anyway to save CellScopes figures from the julia command line as a pdf or svg for instance?
2. How do I properly reload a CellScopes jld2 object?

cs.scRNAObject(raw_counts) not finished in hours

Hello everyone,

Thank you for the great package, I am looking forward to working with CellScopes and Julia more (MLE Mixed models being absent in Python to my knowledge and my data being too large for R :P).

I have an issue constructing the scRNAObject. The function does not finish after hours, even when running over night.
previously I constructed the Raw count object from a sparse matrix, gene_names and cell_names.

obj = cs.RawCountObject(transpose(counts), obs.UMIs, var.Column1)
pbmc = cs.scRNAObject(obj)

I am working with a dataset of 380k cells that I preprocessed and annotated in Python. I saved the counts matrix (thats why I had to transpose, coming from scanpy) and gene and cell annotations.
When loading/converting from .h5ad I had the same issue of the function never ending.

adata = cs.from_scanpy("scVI-integrated.h5ad"; data_type="scRNA", anno="cell_type")

Looking at the 400k cell tutorial, it seemed like creating the object should be quite fast.

Did I forget about something?

(Julia 1.8.1, only installed Gadfly, removed Gadfly, install MatrixMarket, CSV, DataFrames and SingleCellProjection, in addition to CellScopes. Am quite new to Julia).

Thank you for any help :)

Issue of Conversion of Seurat object to CellScopes object

Hello CellScopes team,

I've encountered an issue when I tried to convert an Seurat Object to CellScopes object.

Here is the traceback:

But I'm sure that the name of assay in the rds file I used is "RNA", and it's also an Seurat Object.

I'm new to Julia and couldn't figure out which steps I missed or how to solve this error. I'm running Julia v1.9.3 on Macbook. Hope you can help.

Best,
Emily

Request for Adding Support for loading CosMx dataset

Dear developers,

Thank you for very useful tools. The visualization feature, in particular, is highly appealing and has brought significant value to my work.

I would like you to request the addition of support for the CosMx dataset.
Dataset can be downloaded from here:
https://nanostring.com/products/cosmx-spatial-molecular-imager/ffpe-dataset/human-liver-rna-ffpe-dataset/

Thank you for considering my request.

Best regards,
Ayumu

Installation issue (dependency error).

Hello CellScopes team,

I have encountered a dependency error while installing the CellScope package – Unsatisfiable requirements for package ImageTransformations. Here is the traceback:

ERROR: Unsatisfiable requirements detected for package ImageTransformations [02fcd773]:
 ImageTransformations [02fcd773] log:
 ├─possible versions are: 0.2.0-0.10.0 or uninstalled
 ├─restricted by compatibility requirements with Colors [5ae59095] to versions: 0.8.1-0.10.0 or uninstalled
 │ └─Colors [5ae59095] log:
 │   ├─possible versions are: 0.9.0-0.12.10 or uninstalled
 │   └─restricted to versions 0.12 by Baysor [cc9f9468], leaving only versions: 0.12.0-0.12.10
 │     └─Baysor [cc9f9468] log:
 │       ├─possible versions are: 0.6.2 or uninstalled
 │       └─Baysor [cc9f9468] is fixed to version 0.6.2
 ├─restricted by compatibility requirements with Augmentor [02898b10] to versions: 0.5.0-0.8.13, leaving only versions: 0.8.1-0.8.13
 │ └─Augmentor [02898b10] log:
 │   ├─possible versions are: 0.6.0-0.6.6 or uninstalled
 │   └─restricted to versions * by CellScopes [708d50d9], leaving only versions: 0.6.0-0.6.6
 │     └─CellScopes [708d50d9] log:
 │       ├─possible versions are: 0.1.0 or uninstalled
 │       └─CellScopes [708d50d9] is fixed to version 0.1.0
 └─restricted by compatibility requirements with Images [916415d5] to versions: 0.9.0-0.9.5 — no versions left
   └─Images [916415d5] log:
     ├─possible versions are: 0.17.3-0.26.0 or uninstalled
     ├─restricted to versions * by CellScopes [708d50d9], leaving only versions: 0.17.3-0.26.0
     │ └─CellScopes [708d50d9] log: see above
     ├─restricted by compatibility requirements with Colors [5ae59095] to versions: 0.19.3-0.26.0 or uninstalled, leaving only versions: 0.19.3-0.26.0
     │ └─Colors [5ae59095] log: see above
     └─restricted by compatibility requirements with ImageMorphology [787d08f9] to versions: 0.25.0-0.25.3 or uninstalled, leaving only versions: 0.25.0-0.25.3
       └─ImageMorphology [787d08f9] log:
         ├─possible versions are: 0.1.0-0.4.5 or uninstalled
         └─restricted to versions 0.3 by Baysor [cc9f9468], leaving only versions: 0.3.0-0.3.2
           └─Baysor [cc9f9468] log: see above

I am only starting with Julia and I couldn't figure where these requirements are stated explicitly, nor how to fix the issue. I am running Julia v1.9.3. and installing the package using instructions from readme.

Best regards,
Vasily

"StackOverflowError" happened in "normalize_object"

Hello CellScopes team,

There was an issue when I ran the "normalize_object" function. The test data I used is an imaging-based spatial transcriptomic data downloaded from GEO (GSE227044). I'm running Julia v1.10 on MacBook. Here is the code:

genes = count_df.gene
cells = string.(names(count_df)[2:end])
count_df = count_df[!, 2:end]
count_df = convert(SparseMatrixCSC{Int64, Int64},Matrix(count_df))
raw_count = cs.RawCountObject(count_df, cells, genes)
count_molecules.cell = string.(count_molecules.cell)
count_cells.cell = string.(count_cells.cell)
sham = cs.CartanaObject(count_molecules, count_cells, raw_count; prefix = "sham", min_gene = 0, min_cell = 3)
sham = cs.normalize_object(sham)

Here is the traceback:

julia> sham = cs.normalize_object(sham)
ERROR: StackOverflowError:
Stacktrace:
[1] promote_type(::Type, ::Type, ::Type, ::Type, ::Vararg{Type}) (repeats 7394 times)
@ Base ./promotion.jl:299
[2] hcat(::SparseVector{…}, ::SparseVector{…}, ::SparseVector{…}, ::Vararg{…})
@ SparseArrays /Applications/Julia1.10.app/Contents/Resources/julia/share/julia/stdlib/v1.10/SparseArrays/src/sparsevector.jl:1109
[3] #normalize_object#57
@ ~/.julia/packages/CellScopes/oYdMu/src/scrna/processing.jl:5 [inlined]
[4] normalize_object(ct_obj::CellScopes.RawCountObject; scale_factor::Int64, norm_method::String, pseudocount::Int64)
@ CellScopes ~/.julia/packages/CellScopes/oYdMu/src/scrna/processing.jl:10
[5] normalize_object
@ ~/.julia/packages/CellScopes/oYdMu/src/scrna/processing.jl:9 [inlined]
[6] normalize_object(sc_obj::CellScopes.CartanaObject; scale_factor::Int64, norm_method::String, pseudocount::Int64)
@ CellScopes ~/.julia/packages/CellScopes/oYdMu/src/scrna/processing.jl:16
[7] normalize_object(sc_obj::CellScopes.CartanaObject)
@ CellScopes ~/.julia/packages/CellScopes/oYdMu/src/scrna/processing.jl:15
[8] eval
@ ./boot.jl:385 [inlined]
[9] include_string(mapexpr::typeof(REPL.softscope), mod::Module, code::String, filename::String)
@ Base ./loading.jl:2076
[10] invokelatest(::Any, ::Any, ::Vararg{Any}; kwargs::@Kwargs{})
@ Base ./essentials.jl:892
[11] invokelatest(::Any, ::Any, ::Vararg{Any})
@ Base ./essentials.jl:889
[12] inlineeval(m::Module, code::String, code_line::Int64, code_column::Int64, file::String; softscope::Bool)
@ VSCodeServer ~/.vscode/extensions/julialang.language-julia-1.75.2/scripts/packages/VSCodeServer/src/eval.jl:263
[13] (::VSCodeServer.var"#67#72"{…})()
@ VSCodeServer ~/.vscode/extensions/julialang.language-julia-1.75.2/scripts/packages/VSCodeServer/src/eval.jl:181
[14] withpath(f::VSCodeServer.var"#67#72"{…}, path::String)
@ VSCodeServer ~/.vscode/extensions/julialang.language-julia-1.75.2/scripts/packages/VSCodeServer/src/repl.jl:274
[15] (::VSCodeServer.var"#66#71"{…})()
@ VSCodeServer ~/.vscode/extensions/julialang.language-julia-1.75.2/scripts/packages/VSCodeServer/src/eval.jl:179
[16] hideprompt(f::VSCodeServer.var"#66#71"{…})
@ VSCodeServer ~/.vscode/extensions/julialang.language-julia-1.75.2/scripts/packages/VSCodeServer/src/repl.jl:38
[17] (::VSCodeServer.var"#65#70"{…})()
@ VSCodeServer ~/.vscode/extensions/julialang.language-julia-1.75.2/scripts/packages/VSCodeServer/src/eval.jl:150
[18] with_logstate(f::Function, logstate::Any)
@ Base.CoreLogging ./logging.jl:515
[19] with_logger
@ ./logging.jl:627 [inlined]
[20] (::VSCodeServer.var"#64#69"{VSCodeServer.ReplRunCodeRequestParams})()
@ VSCodeServer ~/.vscode/extensions/julialang.language-julia-1.75.2/scripts/packages/VSCodeServer/src/eval.jl:255
[21] #invokelatest#2
@ ./essentials.jl:892 [inlined]
[22] invokelatest(::Any)
@ Base ./essentials.jl:889
[23] (::VSCodeServer.var"#62#63")()
@ VSCodeServer ~/.vscode/extensions/julialang.language-julia-1.75.2/scripts/packages/VSCodeServer/src/eval.jl:34
Some type information was truncated. Use show(err) to see complete types.

I'm a fresh man to Julia and I've tried my best to solve the error which didn't work. Hope you can give me some help.

Best,
Pedro