> For the complete documentation index, see [llms.txt](https://academy.dnanexus.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://academy.dnanexus.com/public-datasets-on-the-dnanexus-platform/single-cell/nf-core-scrnaseq.md). # nf-core/scrnaseq ## Necessary Disclaimers and Legal The user is responsible for reviewing and complying with the license requirements of the software, and data referenced in this documentation. Users are responsible for the costs associated with analyzing data, software and its storage in their project spaces. Instance type availability and pricing are subject to the contract between the user or the user’s organization and DNAnexus. ## Citations for nf-core/scrnaseq nf-core is a community-driven collection of curated bioinformatics pipelines built with Nextflow, providing standardized, scalable, and portable workflows for reproducible analysis across diverse computing environments. If you use nf-core/scrnaseq, please cite the pipeline using [nf-core/scrnaseq](https://nf-co.re/scrnaseq/4.1.0/docs/usage). Additional references for integrated tools are listed in the pipeline’s [CITATIONS.md](https://github.com/nf-core/scrnaseq/blob/4.1.0/CITATIONS.md). The following dataset was used in this documentation as an example run: * [GSE174609](https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GSE174609): Lee H et al. J Transl Med. 2022;20(1):504. PMID: [36329504](https://pubmed.ncbi.nlm.nih.gov/36329504/). ## Overview nf-core/scrnaseq is a bioinformatics pipeline for processing 10x Genomics single-cell RNA-seq data. The pipeline supports multiple aligners, including: * STAR / STARsolo * Cell Ranger * Kallisto + BUStools * SimpleAF (Alevin-Fry) For further details on nf-core/scrnaseq, please consult the official Nextflow [documentation](https://nf-co.re/scrnaseq/4.1.0/docs/usage/) and [GitHub](https://github.com/nf-core/scrnaseq/tree/4.1.0) repository. ## Where to Access on DNAnexus The nf-core/scrnaseq folder on DNAnexus is organized as follows: ``` scrnaseq/ ├── dataset/ # Input datasets for the pipeline ├── example_results/ # Example output results from completed runs ├── references/ # Reference genomes and annotation files ├── soft_configs/ # Resources & tool configuration files └── scrnaseq_v4.1.0 # Nextflow applet ``` 1. Applet: scrnaseq\_v4.1.0: nf-core/scrnaseq version 4.1.0, available on the platform. 2. Datasets: Five datasets are provided for testing the pipeline, ranging from small test profiles to a real multi-sample study. See the Example Datasets section below for further details. 3. References: To prevent runtime downloads, pre-downloaded reference genomes for human and mouse are provided based on [igenome.config](https://github.com/nf-core/scrnaseq/blob/f7bf36d7c7e4bddc5302c3facd8d19ca83e22226/conf/igenomes.config#L25). Human FASTA and GTF files were sourced from [GENCODE release 44](https://ftp.ebi.ac.uk/pub/databases/gencode/Gencode_human/release_44/), while mouse references were obtained from [GENCODE release 33](https://ftp.ebi.ac.uk/pub/databases/gencode/Gencode_mouse/release_M33/). ``` references/ ├── GRCh38_GENCODE_release_44/ # Human GRCh38, GENCODE release 44 ├── GRCm39_GENCODE_release_33/ # Mouse GRCm39, GENCODE release 33 ├── igenomes_GRCh37/ # Human GRCh37 (iGenomes) ├── igenomes_GRCh38/ # Human GRCh38 (iGenomes) ├── igenomes_GRCm38/ # Mouse GRCm38 (iGenomes) ├── igenomes_hg19/ # Human hg19 (iGenomes) ├── igenomes_hg38/ # Human hg38 (iGenomes) └── igenomes_mm10/ # Mouse mm10 (iGenomes) ``` 4. Soft configuration files: Five configuration files are provided as examples for users to adapt for their own runs: two GPU configs for CellBender (Driver R470 and R535), one for the GSE174609 dataset run, and two for Cell Ranger Count and Cell Ranger Multi workflows. 5. Example results: Example outputs from completed pipeline runs are provided for reference, covering the minimal test profile, full test profile, pbmc8k with multiple aligners (Cell Ranger, Kallisto, SimpleAF), Cell Ranger ARC, Cell Ranger Multi, and the GSE174609 real dataset run. ## Copying applet and data into a project To use the datasets and applet, first copy them from the public project into your own project: 1. Create a new project billed to your organization. See [Setting Up a Project](https://academy.dnanexus.com/overview-of-the-platform/setting-up-a-project) for instructions. 2. Go to the Resources tab and find the project "Public Datasets AWS US East". Navigate to scrnaseq folder. 3. Select the folders and files you need. 4. Click Copy from the top right menu and select the project you created in Step 1. 5. Go to your project to start running the pipeline. ## Prepare your input ### Sample sheet The pipeline requires a .csv sample sheet with the following format: ``` sample,fastq_1,fastq_2,expected_cells pbmc8k,/path/to/pbmc8k_S1_L007_R1_001.fastq.gz,/path/to/pbmc8k_S1_L007_R2_001.fastq.gz,10000 pbmc8k,/path/to/pbmc8k_S1_L008_R1_001.fastq.gz,/path/to/pbmc8k_S1_L008_R2_001.fastq.gz,10000 ``` Please refer to samplesheet\_pbmc\_GSE174609.csv in the dataset/pbmc\_GSE174609/ folder for a complete example. Important: If you copy data from the public dataset into your destination project, you must update the file paths in the sample sheet to point to your project's local path. To simplify sample sheet preparation, you can use the scrnaseq\_samplesheet\_builder\_v0.1.1 applet: a no-code GUI that validates inputs and resolves file references into DNAnexus paths automatically. See the [CSV Builder User Guide](/public-datasets-on-the-dnanexus-platform/csv-builders-for-nextflow-pipelines/csv-builder-for-scrnaseq.md) for details. ### Soft configuration files A Nextflow soft configuration file allows users to customize pipeline resource settings such as CPU, memory, and queue size without modifying the pipeline source code. On DNAnexus, one or more soft config files can be passed via -inextflow\_soft\_confs. Five configuration files are provided as examples in the soft\_configs/ folder: ``` soft_configs/ ├── soft_config_pbmc_GSE174609.config # Resources config for GSE174609 run (STAR, H5AD conversion, queueSize=20) ├── soft_config_cellranger_count.config # Resources config for Cell Ranger Count ├── soft_config_cellranger_multi.config # Resources config for Cell Ranger Multi ├── soft_config_gpu_R470.config # GPU config for CellBender (Driver R470) └── soft_config_gpu_R535.config # GPU config for CellBender (Driver R535) ``` For more information about determining instance type or resources for child jobs, please refer to [Instance Type Determination](https://documentation.dnanexus.com/user/running-apps-and-workflows/running-nextflow-pipelines) from DNAnexus website. ## Example dataset Several datasets are provided for testing the nf-core/scrnaseq: * pbmc\_1k\_v3: 1k PBMC dataset. * pbmc8k: 8k PBMC dataset. * cellrangerarc\_test\_dataset: Dataset for testing the Cell Ranger ARC workflow. ``` dataset/ ├── cellrangerarc_test_dataset/ # Test dataset for Cell Ranger ARC ├── pbmc8k/ # PBMC 8k dataset ├── pbmc_1k_v3/ # PBMC 1k dataset (v3 chemistry) ├── pbmc_GSE174609/ # Real PBMC dataset (multi-sample study) └── scrnaseq_test_profile/ # Small dataset for test_profile.config ``` ### PBMC Dataset (GSE174609) PBMC scRNA-seq data from paired pre-/post-treatment periodontitis patients and healthy donors ([GEO](https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GSE174609)). 12 samples total with \~10,000 expected cells per sample. Multiple batches and conditions make this dataset suitable for testing integration methods. Used here as a real-data example for a full pipeline run with STARsolo. The sample sheet is samplesheet\_pbmc\_GSE174609.csv. ## Running the pipeline ### Minimal test To quickly validate the pipeline, simply run it with -profile test,docker. This built-in test profile uses a small dataset consisting of two samples (X and Y), aligned to mouse chromosome 19 (GRCm38). The pipeline is configured to use the STAR aligner with the 10XV2 protocol, and the CellBender step is disabled #### Run via UI 1. Click the applet scrnaseq\_v4.1.0 and click Run.
2. Provide a Job Name and choose output destination. 3. Under the NEXTFLOW OPTIONS section, enter -profile test,docker in the Nextflow Run Options box. 4. Under the COMMON section, enter scrnaseq\_test as the output directory name. 5. Click Start Analysis to launch the pipeline. #### Run via command line ``` dx run project-xxx:/scrnaseq/scrnaseq_v4.1.0 \ -ioutdir='scrnaseq_test' \ -inextflow_run_opts='-profile test,docker' \ --destination 'project-xxx:/scrnaseq/results' \ --priority high \ --name "scrnaseq_test" \ -y ``` Replace project-xxx with your DNAnexus project ID. ### Run with GSE174609 For real data testing, we used a PBMC scRNA-seq dataset from paired pre-/post-treatment periodontitis patients and healthy donors (GSE174609). Key parameters used in this run: * STARsolo was used instead of Cell Ranger, as it is permissively licensed, faster, and requires less memory. * The protocol was set to 10XV3, which is required for STARsolo (it does not support auto-detection like Cell Ranger). * GRCh38 GENCODE v44 references were used with igenomes\_ignore=true. This is because the prebuilt STAR index from iGenomes was generated with an older STAR version (2.7.4a), which is incompatible with the STAR version used in this pipeline (2.7.10b). As a result, the pipeline must build the index directly from the provided FASTA and GTF files. In addition, iGenomes references are considered outdated for many nf-core pipelines (). * CellBender was skipped in this run, as empty droplet filtering is handled in nf-core/scdownstream. If needed, CellBender can be run later using the generated count matrices. * Use head job instance type: “mem1\_ssd2\_v2\_x16” to avoid low-storage error due to the large number of child jobs. * Use the config file soft\_config\_pbmc\_GSE174609.config to specify resources for selected modules. Please refer to the Soft Configuration section for more details. ``` dx run project-xxx:/scrnaseq/scrnaseq_v4.1.0 \ -ioutdir='scrnaseq_pbmc_GSE174609' \ -iinput='project-xxx:/scrnaseq/dataset/pbmc_GSE174609/samplesheet_pbmc_GSE174609.csv' \ -ialigner='star' \ -iprotocol='10XV3' \ -ifasta='project-xxx:/scrnaseq/references/GRCh38_GENCODE_release_44/GRCh38.primary_assembly.genome.fa' \ -igtf='project-xxx:/scrnaseq/references/GRCh38_GENCODE_release_44/gencode.v44.primary_assembly.annotation.gtf' \ -iskip_cellbender=true \ -iigenomes_ignore=true \ -inextflow_run_opts='-profile docker' \ -inextflow_soft_confs='project-xxx:/scrnaseq/soft_configs/soft_config_pbmc_GSE174609.config' \ --destination 'project-xxx:/scrnaseq/examples_results' \ --priority high \ --name "scrnaseq_pbmc_GSE174609" \ --instance-type mem1_ssd2_v2_x16 \ -y ``` Replace project-xxx with your DNAnexus project ID or Public Dataset project. #### Run with parameter file As an alternative to passing parameters directly via the command line, users can create a JSON parameter file and pass it using -inextflow\_params\_file. This is useful for managing complex runs with many parameters. Create a file params.json with the following content: ``` { "outdir": "scrnaseq_pbmc_GSE174609", "input": "project-xxx:/scrnaseq/dataset/pbmc_GSE174609/samplesheet_pbmc_GSE174609.csv", "aligner": "star", "protocol": "10XV3", "fasta": "project-xxx:/scrnaseq/references/GRCh38_GENCODE_release_44/GRCh38.primary_assembly.genome.fa", "gtf": "project-xxx:/scrnaseq/references/GRCh38_GENCODE_release_44/gencode.v44.primary_assembly.annotation.gtf", "skip_cellbender": true, "igenomes_ignore": true } ``` Upload param.json to DNAnexus project, then run: ``` dx run project-xxx:/scrnaseq/scrnaseq_v4.1.0 \ -inextflow_params_file='project-xxx:/scrnaseq/params/params.json' \ -inextflow_run_opts='-profile docker' \ -inextflow_soft_confs='project-xxx:/scrnaseq/soft_configs/soft_config_pbmc_GSE174609.config' \ --destination 'project-xxx:/scrnaseq/examples_results' \ --priority high \ --name "scrnaseq_pbmc_GSE174609" \ --instance-type mem1_ssd2_v2_x16 \ -y ``` Replace project-xxx with your DNAnexus project ID or Public Dataset project. Refer to [DNAnexus official document](https://documentation.dnanexus.com/user/running-apps-and-workflows/running-nextflow-pipelines) for more detail. ## Understanding the Output The output files will be placed in the outdir directory specified when running the pipeline. Please refer to the [nf-core/scrnaseq official documentation](https://nf-co.re/scrnaseq/4.1.0/docs/output/) for a full description of all output files. ## Technical Considerations ### Head job storage/memory issue Due to the large number of child jobs, the default instance for the head job may run into a low-storage error. The error message is: Cause of Failure Please consult the job log; the job's reported error could not be parsed from the file job\_error.json Warning: Low disk space during this job. Solution: Use an instance with higher storage for the head job instead of the default instance. When running the pipeline with dx run, specify a larger instance using the --instance-type option. ### iGenomes/STAR Compatibility When the --genome parameter is specified (e.g., genome = 'GRCh38'), the pipeline automatically retrieves reference files (FASTA, GTF, STAR index, etc.) from the iGenomes configuration. However, this can lead to compatibility issues when using the STAR aligner because the prebuilt STAR index provided by iGenomes may have been generated using an older STAR version. STAR requires that the genome index and runtime version match exactly. Example error: `EXITING because of FATAL ERROR: Genome version: 20201 is INCOMPATIBLE with running STAR version: 2.7.10b` Solution: We recommend providing FASTA and GTF files and rebuilding the STAR index to avoid compatibility issues. When specifying FASTA and GTF using --fasta and --gtf, disable iGenomes by setting -iigenomes\_ignore=true. ### FASTA and GTF chromosome naming convention FASTA and GTF files should be downloaded from the same sources. If you use the FASTA file from Ensembl and the GTF file from GENCODE. These files have different naming conventions, with GENCODE using chr prefixes (chr1, 2) while Ensembl doesn’t (1, 2). To fix this, you can check example script: cat Homo\_sapiens.GRCh38.dna.primary\_assembly.fa | sed -E 's/^>(\S+).\*/>\1 \1/' | sed -E 's/^>(\[0-9]+|\[XY]) />chr\1 /' | sed -E 's/^>MT />chrM /' > Homo\_sapiens.GRCh38.dna.primary\_assembly\_chr\_labeled.fa Without fixing this difference, mixing Ensembl FASTA and GENCODE GTF will cause a silent error where scrnaseq completes without failure, and with a high rate of reads aligned to the genome (\~90%), but almost no reads mapped to genes (< 0.01%) and near-empty count matrices. This can be verified in the gtf\_gene\_filter step log with very few matching sequences between GTF and FASTA files. ``` INFO: Extracted 578 / 3424772 lines from gencode.v44.primary_assembly.annotation.gtf matching sequences in Homo_sapiens.GRCh38.dna.primary_assembly.fa ``` The STAR summary file should also be checked to see the numbers of reads mapped to genes. This is the summary file before fixing this error: Reads Mapped to Gene: Unique Gene,0.000101811 ### Queue Size Configuration The queueSize parameter controls how many tasks are executed in parallel by the Nextflow executor. On DNAnexus, this corresponds to the number of subjobs created simultaneously by the pipeline’s head job (default: 5). If you have more than 5 samples and want to allow more parallel jobs, include queueSize in the soft configuration file. For example: queueSize = 20 allows up to 20 subjobs to run in parallel: ``` executor { queueSize = 20 } ``` ### GPU instance Only one module uses GPU: CELLBENDER\_REMOVEBACKGROUND. Users can skip it with skip\_cellbender=true. If running CellBender, GPU is strongly recommended as CPU execution can take up to 7 hours (default 150 epochs). On DNAnexus, both Driver R470 and R535 are supported. Two configuration files are provided: * soft\_config\_gpu\_R470.config: for Driver R470 * soft\_config\_gpu\_R535.config: for Driver R535 Note: ext.use\_gpu = true must be included in the config to enable GPU usage. Without this line, the module will not use the GPU even if a GPU instance is selected. ``` docker { enabled = true runOptions = '-u $(id -u):$(id -g)' } process { withLabel: 'process_gpu' { machineType = 'mem2_ssd2_gpu1_v2_x8' containerOptions = '--gpus all' ext.use_gpu = true } } ```