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. Additional references for integrated tools are listed in the pipeline’s CITATIONS.md.
The following dataset was used in this documentation as an example run:
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 and GitHub repository.
Where to Access on DNAnexus
The nf-core/scrnaseq folder on DNAnexus is organized as follows:
Applet: scrnaseq_v4.1.0: nf-core/scrnaseq version 4.1.0, available on the platform.
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.
References: To prevent runtime downloads, pre-downloaded reference genomes for human and mouse are provided based on igenome.config. Human FASTA and GTF files were sourced from GENCODE release 44, while mouse references were obtained from GENCODE release 33.
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.
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:
Create a new project billed to your organization. See Setting Up a Project for instructions.
Go to the Resources tab and find the project "Public Datasets AWS US East". Navigate to scrnaseq folder.
Select the folders and files you need.
Click Copy from the top right menu and select the project you created in Step 1.
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:
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 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:
For more information about determining instance type or resources for child jobs, please refer to Instance Type Determination 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.
PBMC Dataset (GSE174609)
PBMC scRNA-seq data from paired pre-/post-treatment periodontitis patients and healthy donors (GEO). 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
Click the applet scrnaseq_v4.1.0 and click Run.
Provide a Job Name and choose output destination.
Under the NEXTFLOW OPTIONS section, enter -profile test,docker in the Nextflow Run Options box.
Under the COMMON section, enter scrnaseq_test as the output directory name.
Click Start Analysis to launch the pipeline.
Run via command line
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 (https://nf-co.re/docs/usage/reference_genomes).
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.
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:
Upload param.json to DNAnexus project, then run:
Replace project-xxx with your DNAnexus project ID or Public Dataset project. Refer to DNAnexus official document 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 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.
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:
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.
Last updated