CSV Builder for 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.
Overview
Preparing a samplesheet input file for nf-core/scrnaseq requires understanding the pipeline's input schema, writing file paths in the correct DNAnexus format, and ensuring all values pass validation. This process is time-consuming and error-prone, especially for new users.
The CSV Builder for nf-core/scrnaseq is a lightweight GUI applet on DNAnexus that helps users create a pipeline-ready samplesheet without any programming. It validates inputs against the pipeline schema, converts selected files into the correct dx:// file path format automatically, supports both manual entry and prefilled metadata (.csv) upload, and saves the output samplesheet directly to the user's DNAnexus project.
This applet targets nf-core/scrnaseq v4.1.0 and accepts paired-end FASTQ files as input. The required and optional columns are:
Column name
Format
Required
Constraint
sample
string
Yes
Must contain no spaces.
fastq_1
string
Yes
Must contain no spaces.
Must have extension '.fq.gz' or '.fastq.gz'
fastq_2
string
Yes
Must contain no spaces.
Must have extension '.fq.gz' or '.fastq.gz'
fastq_barcode
string
No
File-path like string
expected_cells
integer
No
seq_center
string
No
sample_type
string
No
Must be one of these options: "atac", "gex"
feature_type
enum
No
Must be one of these options: "gex", "vdj", "ab", "crispr", "cmo".
Official nf-core documentation: https://nf-co.re/scrnaseq/4.1.0/docs/usage.
Interface Overview
The applet has two tabs: INPUTS and OUTPUTS. All configuration is done in the INPUTS tab.
prefilled samplesheet uploads an existing .csv file containing sample names and file references. Use this when you have already prepared a metadata file.
fastq_1 selects one or more Read 1 FASTQ files directly from DNAnexus. Use this when you do not have a prefilled samplesheet.
fastq_2 selects one or more Read 2 FASTQ files directly from DNAnexus. Each file must correspond to the file selected in fastq_1 at the same position.
scrnaseq pipeline version displays the pipeline version the applet validates against. Currently fixed at 4.1.0.
REQUIRED COLUMNS accepts values for required columns not covered by your input source, such as sample.
OPTIONAL COLUMNS accepts values for optional columns such as expected_cells, seq_center, sample_type, and feature_type.
OUTPUT SAMPLESHEET NAME sets the name of the output .csv file. If left empty, defaults to sample_sheet.csv.
Copying the applet and example dataset into a project
To get started, copy the applet and example dataset from the public project into your own project space.
Create a project for your analysis, billed to your own organization. Tutorials on how to set up a project can be found on this page
Navigate to the Resources tab and locate the project titled "Public Datasets AWS US (East)", then go to nf-core_input_csv_builder.
Next, go to folderproteinfold_csv_builder, then select the applet scrnaseq_samplesheet_builder_v0.1.1, and the scrnaseq_example.
Click Copy in the top-right menu and select the project created in Step 1.
Return to your project space to begin using the applet.
Quick start
Launch the applet scrnaseq_samplesheet_builder_v0.1.1 from the DNAnexus GUI.
Click the fastq_1 field and navigate to nf-core_input_csv_builder/scrnaseq_example/fastq/. Select the Read 1 FASTQ file.
Click the fastq_2 field and select the corresponding Read 2 FASTQ file.
In the REQUIRED COLUMNS section, enter the sample name in the sample field.
Provide output name and use the default instance to launch the job
The job takes approximately 2 minutes. Once the job is complete, verify the following:
Job status shows Done
Log file contains no errors or warnings related to the samplesheet
Output CSV columns match the v4.1.0 schema (sample, fastq_1, fastq_2)
To confirm the output samplesheet works with the pipeline, run a quick verification using nf-core/scrnaseq v4.1.0 with the test and docker profiles.
For more detailed examples including prefilled samplesheets, folder input, and error scenarios, see the Example jobs section.
Input flow
The applet supports three ways to provide input data:
Prefilled samplesheet: upload an existing CSV file that follows the scrnaseq schema. The applet will parse and validate the file, resolve all file references into dx:// paths, and produce the final output samplesheet.
Manual input: enter data directly into the applet. Values can be provided as an array (multiple values separated by commas) or as a constant (a single value replicated across all rows). FASTQ files can also be selected directly from DNAnexus.
Folder input: provide a DNAnexus folder path containing FASTQ files. The applet will automatically pair R1 and R2 files based on their filenames, without requiring the user to map them manually.
File path format
For supported file path formats, see File path format in the CSV Builder for nf-core/proteinfold guide.
Example runs
To follow along with the examples in this guide, we have prepared a dedicated folder on DNAnexus at nf-core_input_csv_builder/scrnaseq_example containing the following:
fastq: sample FASTQ files used as input
metadata_example: example prefilled samplesheets
samplesheet_output: expected output samplesheets for reference
Example 1: Providing input via prefilled samplesheet
Scenario: A user has already prepared a CSV file with sample names and FASTQ file references and wants to use it directly as input to the applet.
Here is an example
sample,fastq_1,fastq_2
S10,S10_L001_R1_001.fastq.gz,S10_L001_R2_001.fastq.gz
SRR8599150,/nf-core_input_csv_builder/scrnaseq_example/fastq/SRR8599150_S1_L001_R1_001.sub5000.fastq.gz,/nf-core_input_csv_builder/scrnaseq_example/fastq/SRR8599150_S1_L001_R2_001.sub5000.fastq.gz
The prefilled file shows different file path formats supported by the applet including absolute paths, file name. The prefilled file may contain any number of additional columns, the applet will automatically keep only the columns required by the pipeline schema and drop the rest.
Note: Users can use file-id and the applet will find the file and provide full dx: path or users can provide full path (dx://…)
Expected output: scrnaseq_v4.1.0_samplesheet.csv in /nf-core_input_csv_builder/scrnaseq_example/samplesheet_output/
sample,fastq_1,fastq_2
S10,dx://project-xxx:/nf-core_input_csv_builder/scrnaseq_example/fastq/S10_L001_R1_001.fastq.gz,dx://project-xxx:/nf-core_input_csv_builder/scrnaseq_example/fastq/S10_L001_R2_001.fastq.gz
SRR8599150,dx://project-xxx:/nf-core_input_csv_builder/scrnaseq_example/fastq/SRR8599150_S1_L001_R1_001.sub5000.fastq.gz,dx://project-xxx:/nf-core_input_csv_builder/scrnaseq_example/fastq/SRR8599150_S1_L001_R2_001.sub5000.fastq.gz
Steps:
Click to prefilled samplesheet box and choose your metadata (csv) file
Leave required columns empty because it will use information in the metadata
Name your output csv: It can be scrnaseq_v4.1.0_samplesheet.csv or scrnaseq_v4.1.0_samplesheet. If you leave this box empty, it will use default name: samplesheet
Choose output destination
Use default instance and launch the job
Runtime: 2 minutes
Successful job checklist:
Job status shows Done
Log file contains no errors or warnings related to the samplesheet
Output CSV columns match the v4.1.0 schema (sample, fastq_1, fastq_2)
Example 2: Provide FASTQ folder, sample name and optional columns
Scenario: A user provides a DNAnexus folder containing FASTQ files and wants the applet to automatically pair R1 and R2 files. In addition, the user manually enters the sample name and expected cell count for each sample. This example replicates the samplesheet from nf-core/scrnaseq: https://github.com/nf-core/scrnaseq/blob/4.1.0/assets/samplesheet.csv
Steps:
Copy the full path of the folder containing your FASTQ files. Note that when using the folder option, the applet will include all FASTQ files in the folder and automatically pair R1 and R2 files. For example, if the folder contains two samples (Sample_X and Sample_Y) across two lanes, the applet will pair them accordingly.
Fill in the required fields including fastq_folder, sample name, expected_cells, and output file name.
Select output destination, use the default instance and launch the job
Expected output
R1 and R2 files are automatically paired based on their filenames
The output samplesheet contains one row per lane per sample, with sample, fastq_1, fastq_2, and expected_cells columns populated
All file references are resolved to dx:// paths
Run verification with nf-core/scrnaseq version 4.1.0 successfully.
dx run project-J5Xqzy009Qz80FqQpy7QGKfV:/scrnaseq/scrnaseq_v4.1.0 \
-ioutdir='scrnaseq_v410' \
-iinput='project-J5Xqzy009Qz80FqQpy7QGKfV:/nf-core_input_csv_builder/scrnaseq_example/sample_sheet_output/samplesheet.csv' \
-inextflow_run_opts='-profile test,docker' \
--destination 'project-J5Xqzy009Qz80FqQpy7QGKfV:/users/ivy/test_csv_builder/test_06_05_26/' \
--priority high \
--name "scrnaseq_test_csv_builder" \
-y
Negative cases
Example 3: Upload CSV with multiple files with same name in project
Scenario: A user uploads a prefilled samplesheet using filename only for fastq_1 and fastq_2, but multiple files with the same name exist in the project. The applet cannot resolve the file path and logs a warning.
For example, there are several files: SRR8599150_S1_L001_R1_001.sub5000.fastq.gz in project
Expected output
Job completes successfully
Validation logs "Found 2 files" for both fastq_1 and fastq_2
Example 4: Upload prefilled samplesheet CSV with R1 file assigned to both fastq_1 and fastq_2
Scenario: A user accidentally assigns the same R1 file to both fastq_1 and fastq_2 in the prefilled samplesheet instead of providing the correct R2 file. The applet will still generate the output samplesheet but will log a validation warning indicating that the file assigned to fastq_2 does not contain R2 in its filename.
Expected output
Job completes successfully
The log file contains a validation warning: "File name must contain 'R2'" for fastq_2
The output samplesheet is generated with the incorrect file reference included
Users are responsible for correcting the file assignment before running the pipeline
For technical considerations, limitations, and troubleshooting that apply to all CSV builder applets, see Technical Considerations.
Last updated