Celescope needs an improved documentation/manual

[wendelljpereira]

We have recently acquired some of the single-cell kits from Singleron in the USA and are now ready for the data analysis.

I have to say that I do not remember ever seeing software from a commercial product with such poor documentation. There is no clear guidance on executing the analysis, what parameters can be modified, and what is happening under the hood.

Other companies that provide single-cell technologies are much better in this regard. I tried other three providers and could always run their code without issues, while am waisting time trying to figure our how to run Celescope in our server.

Best Regards,
Wendell

[zhouyiqi91]

Hi Wendell,
Sorry for the inconvenience, celescope's documentation really needs to be improved.
Assume that you need to use the rna pipeline.
In celescope V1 version we need to combine each tools so here is a slightly more detailed step-by-step explanation.
https://github.com/singleron-RD/CeleScope/blob/v1.15.0/docs/rna/multi_rna.md
In celescope V2 version, we use STARSolo and STARsolo does all the heavy lifting (demultiplexing and error correction of barcodes and UMI, mapping, quantification), so the entire rna pipeline is basically a wrapper of STARsolo.
After STARsolo generates the expression matrix, scanpy is used for clustering and dimensionality reduction. The specific code is here
https://github.com/singleron-RD/CeleScope/blob/master/celescope/tools/analysis_wrapper.py
Additionally, we are rewriting all pipelines in Nextflow. Hopefully this will make the workflow more transparent to users and produce better documentation.
Sorry again for the inconvenience. If you have more questions about installing and running celescope, I'd be happy to answer them.

[zhouyiqi91]

Hi Wendell, I just created a repo for analyzing singleron RNA data based on nf-core scrnaseq best practice, hope you find this useful.
https://github.com/zhouyiqi91/scrnaseq

[wendelljpereira]

Hi @zhouyiqi91,

Thanks for the additional links and information. I managed to start my runs and am waiting in the outputs, but will look into the nf-core pipeline for the analysis of my next datasets.

Best Regards,
Wendell

[hyjforesight]

Hello @zhouyiqi91
Thanks for developing this amzing pipeline.
I'm using v2.1.0, but the tutorial (https://cn.singleronbio.com/product/detail-29.html) is for v1.

Hi Wendell, Sorry for the inconvenience, celescope's documentation really needs to be improved. Assume that you need to use the rna pipeline. In celescope V1 version we need to combine each tools so here is a slightly more detailed step-by-step explanation. https://github.com/singleron-RD/CeleScope/blob/v1.15.0/docs/rna/multi_rna.md In celescope V2 version, we use STARSolo and STARsolo does all the heavy lifting (demultiplexing and error correction of barcodes and UMI, mapping, quantification), so the entire rna pipeline is basically a wrapper of STARsolo. After STARsolo generates the expression matrix, scanpy is used for clustering and dimensionality reduction. The specific code is here https://github.com/singleron-RD/CeleScope/blob/master/celescope/tools/analysis_wrapper.py Additionally, we are rewriting all pipelines in Nextflow. Hopefully this will make the workflow more transparent to users and produce better documentation. Sorry again for the inconvenience. If you have more questions about installing and running celescope, I'd be happy to answer them.

Based on these comments, I assume that the workflow for v2 is celescope rna mkref first, then celescope rna starsolo. Is it correct?
Coud you plz also let me know what celescope rna sample, celescope rna analysis, and celescope rna cells are used for?

Thank you!

[zhouyiqi91]

• sample: add sample infomation to the HTML report.
• analysis: scanpy analysis.
• cells: optional. After completing the multi_rna pipeline, running celescope rna cells allows you to reperform cell calling on the existing results, apply forced cell count, gene count filtering, and mitochondrial filtering.

BTW, we are rewriting CeleScope pipelines using nextflow to achieve better scalability and reproducibility. We recommend using nf-celescope whenever possible.

[hyjforesight]

Hi @zhouyiqi91
Thank you for the response. I've finished celescope rna sample, celescope rna starsolo, and celescope rna analysis pipelines. However, celescope rna cells generates error. Could you plz let me know what the right argument for --root_dir is?

cd /home/hyj/MC_834223/
celescope rna cells --root_dir /home/hyj/outs/filtered/ --genomeDir /home/hyj/reference/celescope/human/ --outdir /home/hyj/MC_834223/cells/ --sample R-2021-1-19 --thread 96
CeleScope version: 2.1.0 Args: Namespace(subparser_assay='rna', force_cells=0, soloCellFilter='', root_dir='/home/hyj/outs/filtered/', max_mito=1.0, min_gene=0, genomeDir='/home/hyj/reference/celescope/human/', outdir='R-2021-1-19/cells', sample='R-2021-1-19', thread='96', debug=False, func=<function cells at 0x7f69063b20d0>)
2025-01-19 14:27:41,608 - celescope.tools.cells.run - INFO - start...
2025-01-19 14:27:41,608 - celescope.tools.matrix.from_matrix_dir - INFO - start...
Traceback (most recent call last):
  File "/home/hyj/anaconda3/envs/celescope/bin/celescope", line 8, in <module>
    sys.exit(main())
  File "/home/hyj/anaconda3/envs/celescope/lib/python3.9/site-packages/celescope/celescope.py", line 57, in main
    args.func(args)
  File "/home/hyj/anaconda3/envs/celescope/lib/python3.9/site-packages/celescope/tools/cells.py", line 262, in cells
    runner.run()
  File "/home/hyj/anaconda3/envs/celescope/lib/python3.9/site-packages/celescope/tools/utils.py", line 50, in wrapper
    result = func(*args, **kwargs)
  File "/home/hyj/anaconda3/envs/celescope/lib/python3.9/site-packages/celescope/tools/cells.py", line 246, in run
    filtered = CountMatrix.from_matrix_dir(self.old_filtered_matrix)
  File "/home/hyj/anaconda3/envs/celescope/lib/python3.9/site-packages/celescope/tools/utils.py", line 50, in wrapper
    result = func(*args, **kwargs)
  File "/home/hyj/anaconda3/envs/celescope/lib/python3.9/site-packages/celescope/tools/matrix.py", line 103, in from_matrix_dir
    raise FileNotFoundError(f"{matrix_dir} does not exist")
FileNotFoundError: R-2021-1-19/cells/../outs/filtered does not exist

Thank you!

Please disregard this comment. I figured it out.

[zhouyiqi91]

The root_dir is the directory where run.sh is located. The output directory for each sample is root_dir/{sample_name}.

By default, root_dir is "./". So if you run celescope rna cells in the root_dir, you don't need to specify --root_dir.