> For the complete documentation index, see [llms.txt](https://help.dragen.illumina.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.dragen.illumina.com/dragen-v4.6/product-guides/dragen-v4.6/dragen-single-cell-pipeline/dragen-scrna-other.md). # Other scRNA Prep The DRAGEN scRNA Pipeline can process multiplexed single-cell RNA-Seq data sets from reads to a cell-by-gene expression matrix. The pipeline is compatible with library designs that have one read in a fragment matched to a transcript and the other containing a cell barcode and a unique molecular identifier (UMI). The pipeline includes the following functions: * Cell-barcode + UMI extraction and error correction for each read * RNA-Seq (splice-aware) alignment and matching to annotated genes * UMI counting per cell and gene to measure gene expression * Sparse matrix, molecule info (HDF5 file), h5ad, and QC metrics outputs * Feature counting, such as with cell-surface proteins ![](https://400428970-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS6tWlZO1JqcbWYgnhR2X%2Fuploads%2Fgit-blob-1a4ff97572d5ba2df1f06b4e9ad0b2c50810e9df%2FscRNAworkflow.png?alt=media) The functionality and options related to alignment and gene annotation are identical to the RNA-Seq pipeline (run in single-end read mode). For more information, see [DRAGEN RNA Pipeline](/dragen-v4.6/product-guides/dragen-v4.6/dragen-rna-pipeline.md). None of the other DRAGEN RNA-Seq modules (variant calling, splice variant calling, gene fusion calling and transcript-level gene expression quantification) are supported for Single-Cell RNA. Note: Illumina Single Cell 3' RNA Prep using PIPseq technology utilizes a novel method for molecular counting \[1]. While file inputs and outputs are similar, the sequences described below as UMIs are used as binning indexes (BIs), and molecules are identified by a combination of BIs and intrinsic molecular identifiers (IMIs). The single-cell RNA pipeline is adapted to process these sequences when PIPseq mode is enabled with `--scrna-enable-pipseq-mode=true`. Furthermore, some arguments such as barcode positions, barcode whitelist and trimming are set automatically in PIPseq mode as well. Please see the [Illumina Single-Cell RNA DRAGEN Analysis Workflow](/dragen-v4.6/product-guides/dragen-v4.6/dragen-single-cell-pipeline/dragen-scrna-illumina.md) page for more information. ## Input Files ### Alignment Reference Use a standard DRAGEN RNA reference genome or hashtable for the scRNA Pipeline. Recommended references (found on the [DRAGEN Product Files](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html) page) include the linear hg38 v5 hashtable, the linear v5 versions of the hg19 and hs37d5 hashtables, and the linear hg38-mm39 v5 hashtable for barnyard datasets. The reference is provided with the `--ref-dir` (`-r`) option. Custom references can be built using `--ht-build-rna-hashtable=true` (see the [DRAGEN Prepare a Reference Genome](/dragen-v4.6/product-guides/dragen-v4.6/dragen-reference-support/prepare-a-reference-genome.md) page for more details on creating a reference hashtable). The pipeline also requires a gene annotation file in GTF format, provided with the `--annotation` (`-a`) option. Recommended annotation files include the gencode v44 and the gencode hg38\_v44+mm39\_vM30 annotation files (available on the [DRAGEN Product Files](https://support.illumina.com/sequencing/sequencing_software/dragen-bio-it-platform/product_files.html) page as well). It is recommended to exclude from the analysis pseudogenes and other entries that may overlap with protein-coding genes and reduce mapping accuracy. This can be done by setting the `--scrna-filter-gene-biotypes` option to true, which will automatically exclude the following biotypes: * shortRNA * microRNA * rRNA * pseudogenes ### Read Input The DRAGEN scRNA Pipeline requires both the transcript sequence and the barcode+UMI sequence for each fragment (read) as input. The pipeline typically expects read input as either FASTQ files or in a FASTQ list. The transcript sequence is typically provided in read 2 (R2) and the cell-barcode and binning index (BI) will be provided in read 1 (R1). Alternatively, the cell-barcode and BI can be provided in the read name (QNAME). The transcript sequence is aligned to the genome to determine the expressed gene, the barcode+UMI sequence is split into the single-cell barcode to identify the unique cell, and a single-cell UMI for unique molecule quantification. #### FASTQ Input If only a single pair of FASTQ files will be run, then FASTQ file input can be used. FASTQ file 1 typically contains the barcode and UMI sequences and FASTQ file 2 contains the transcript sequence (this is enabled using the `--umi-source read1` option). The read group sample name (RGSM) and read group ID (RGID) should be set as well (to be used when labeling samples in output files). ``` --fastq-file1 --fastq-file2 --RGSM --RGID --umi-source read1 ``` Alternatively, the barcode and UMI can be provided in the read names of the transcript reads in a single FASTQ file. See below for details on adding the barcode and BI to the read name (using the `--umi-source qname` option). ``` --fastq-file1 --umi-source qname --RGSM --RGID ``` #### FASTQ List Input A single-cell RNA fastq-list file is a CSV file with the following mandatory columns: | Column | Description | | ----------- | ----------------------------------------------------------------------------------- | | `RGID` | Read group ID | | `RGSM` | Read group sample | | `RGLB` | Read group library | | `Lane` | Sequencing lane | | `Read1File` | Read 1 FASTQ file (usually FASTQ file with reads containing cell-barcodes and UMIs) | | `Read2File` | Read 2 FASTQ file (usually transcript reads) | For example: ``` RGID,RGSM,RGLB,Lane,Read1File,Read2File rna1,sample1,illumina1,1,scRNA1.R1.fastq.gz,scRNA1.R2.fastq.gz rna2,sample1,illumina1,2,scRNA2.R1.fastq.gz,scRNA2.R2.fastq.gz ``` FASTQ list options: ``` --fastq-list --fastq-list-sample-id (must be provided if there are multiple samples in the FASTQ list) --umi-source=read1 (if the cell-barcode and UMI is provided in read 2 instead, then this should be changed to read2) ``` The same FASTQ list option can be used if the barcodes and UMIs are provided in the read names. ``` --fastq-list --fastq-list-sample-id (must be provided if there are multiple samples in the FASTQ list) --umi-source qname --ignore-input-mate=read1 ``` #### UMIs in the Read Name If barcode and UMI sequences are provided in the read name, then follow these steps: * Provide the transcript reads as a single-end FASTQ file with the Barcode+UMI sequence in the eighth field of the read-name line. * Separate sequences using a colon. ``` @VH00284:510:AACJNNCHV:1:1101:64888:1151:AGAGGAGTGATGGATGAAGAGTGGGTTTCGAGACAAAGAGTTCAC 2:N:0:GTGCAGACAG+ACGGATGGTA TGCACTGACTGCTCTTCCGAAGGTCCGGAGTTCAAATCCCAGCAACCACATGGTGGCTCACAACCATCCGTA + ;CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC ``` In the example, the sequence starting with AGA is the barcode+UMI read, the sequences beginning with GTG and ACG are the i7 and i5 sequences, respectively, and the sequence starting with TGCA is the transcript read sequence. These FASTQ files can be generated by bclConvert and bcl2fastq using the UMI settings to define the single-cell barcode+UMI read. If using BCL Convert, enter the barcode/UMI information using the `OverrideCycles` setting. For more information, see the *BCL Convert Software Guide (document # 1000000094725)*. Note: BCL Convert refers to the entire single-cell barcode+UMI sequence as the UMI. The resulting file can be provided as fastq file 1 using FASTQ input or fastq file 2 using FASTQ list input. This option is also compatible with BAM files using the following options: ``` --bam-input $PATH --umi-source qname ``` #### Using Multiple Libraries The scRNA pipeline can process a single biological sample per DRAGEN run by default. To process multiple single-cell libraries together, split the single sample into multiple single-cell libraries with a unique set of cells in each. DRAGEN keeps the cells (barcodes and UMIs) from each library separate and provides merged outputs across all. Read groups are used to specify the library for each FASTQ file using the RGLB attribute. **Example FASTQ list CSV file for multiple libraries:** ```bash RGID,RGSM,RGLB,Lane,Read1File,Read2File rna1,sample1,illumina1,1,scRNA1.R1.fastq.gz,scRNA1.R2.fastq.gz rna2,sample1,illumina1,2,scRNA2.R1.fastq.gz,scRNA2.R2.fastq.gz rna3,sample1,illumina2,3,scRNA3.R1.fastq.gz,scRNA3.R2.fastq.gz rna4,sample1,illumina2,4,scRNA4.R1.fastq.gz,scRNA4.R2.fastq.gz ``` Notes: * The RGID is referred to as the "read group" of the input file * The RGSM values should match for all reads to be processed in a single DRAGEN run * The RGLB values should match for all reads to be analyzed together (the results will be combined into a single metrics output file). There are two separate libraries here so two metrics files will be produced. ## DRAGEN Single-cell Usage The DRAGEN scRNA workflow is enabled with the options `--enable-rna=true --enable-single-cell-rna=true`. The following is an example command line. ```bash /opt/dragen/$VERSION/bin/dragen \ # DRAGEN install path --ref-dir= \ # path to DRAGEN linear hashtable --intermediate-results-dir= \ # optional; e.g. SSD /staging --output-directory= \ --output-file-prefix= \ # Inputs --fastq-list= \ # FASTQ list CSV or FASTQ file input can be provided # Mapper --annotation-file= \ # GTF gene annotation file --enable-map-align=true \ # optional; default=true; needed for FASTQ input --enable-sort=true \ # optional; default=true # Single cell options --enable-rna=true \ --enable-single-cell-rna=true \ --umi-source=read1 \ --scrna-barcode-position \ # see Barcode Position below on details for the format --scrna-umi-position \ # see Barcode Position below on details for the format --scrna-barcode-sequence-list # see Known Barcode Lists below on details for the format ``` #### Additional Options The following are additional options you can use to configure the Single-Cell RNA Pipeline settings. * `--rna-library-type` --- Set the orientation of transcript reads relative to the genomes. Enter `SF` for forward, `SR` for reverse, or `U` for unstranded. The default is `SF`. * `--enable-map-align-output` --- Save the output BAM. The default is false. See the [BAM File Output](#bam-file) section for more details. * `--single-cell-threshold` --- Set the cell filtering method. Available options are `fixed`, `ratio`, and `inflection`. The default is `ratio`. See [Cell Filtering](#cell-filtering) for more details. * `--scrna-min-mapq` --- Sets the minimum MAPQ threshold for reads to be counted. * `--scrna-count-introns` --- Include intronic reads in gene expression estimation. The default is `true`. * `--qc-enable-depth-metrics` --- Set to `false` to disable depth metrics for faster run time. The default is `true`. * `--bypass-anchor-mapping` --- Set to `true` to disable RNA anchor (two-pass) mapping for increased performance. The default is `false`. * `--scrna-global-umi` --- Set to `true` to require UMIs to be unique across all genes in a cell. Only the gene with the highest count will be considered for each UMI per cell. This option also causes all mappings of a read to be counted. The default is `false`. ### Barcode Position By default the scRNA workflow assumes that the overall barcode/UMI sequence is made up of a single-cell barcode (possibly split into multiple blocks) and a single UMI. Enter the following command to define the location of the single-cell barcode and single-cell UMI in the barcode read: ``` --scrna-barcode-position [++...][(:-)|(:+)] --scrna-umi-position ``` `blockPos` describes the offset of the first and last inclusive base of the block and is formatted as `_`. For example, for a library with a 16 bp cell-barcode followed by a 10 bp UMI, use: `--scrna-barcode-position 0_15 --scrna-umi-position 16_25`. For a library with the cell-barcode split into three blocks of 9 bp separated by fixed linker sequences and an 8 bp UMI, use: `--scrna-barcode-position=0_8+21_29+43_51 --scrna-umi-position=52_59`. By default, the barcode position is assumed to be indicated on the forward strand. To explicitly specify the forward strand, use: `--scrna-barcode-position 0_15:+` or `--scrna-barcode-position=0_8+21_29+43_51:+`. To explicitly specify the reverse strand, use: `--scrna-barcode-position 0_15:-` or `--scrna-barcode-position=0_8+21_29+43_51:-`. UMI position can also be specified for feature reads, which are reads with a sequence tag specific to a feature (eg, cell-surface protein or antibody). When the feature-specific UMIs are located on Read 2, you can use `--scrna-feature-barcode-r2umi=0_11` to specify a 12 bp feature UMI at the beginning of each feature read. ### Known Barcode Lists You can provide a list of cell barcode sequences to include using the following command: ``` --scrna-barcode-sequence-list ``` In the case where the `--scrna-barcode-position` parameter is not split into multiple blocks (see the [Barcode Position](#barcode-position) section) the file must contain one possible cell barcode sequence per line. Alternatively, when the barcode position is split into multiple blocks, the file must contain a list composed by multiple sections (one for each block): each section must indicate the possible cell-barcode block sequences for the corresponding block. Each section should start with a line with prefix `#-`. For example, ``` #-Block1 ... #-Block2 ... ``` The input file can also be provided compressed with gzip (`*.txt.gz`). During cell-barcode error correction, any observed barcodes that do not match a sequence specified in the file are considered errors. If possible, the barcodes are corrected to a similar allowed sequence. See [Barcode Error Correction](#barcode-error-correction) for more information. Barcodes that cannot be corrected are filtered out. ### Barcode error correction Cell-barcode sequences from the input reads are error-corrected based on their frequency, and optionally through a list of expected cell-barcode sequences. A cell-barcode sequence is corrected into another cell-barcode sequence if they differ only by one base (a Hamming distance of 1) and: * Either the corrected cell-barcode is at least two times more frequent across all input reads * Or the corrected cell-barcode is on the list of expected cell-barcode sequences, but the original cell-barcode is not When corrected, all the original cell-barcode reads are assigned to the corrected cell-barcode. The sequence error correction scheme is similar to the directional algorithm described in (Smith, Heger and Sudbery, 2020)\[2]. To avoid overcounting UMIs based on sequence errors, UMI error correction is performed using the same algorithm. UMIs are corrected for all reads within the same cell-barcode mapping to the same gene. ### Mapping The DRAGEN RNA mapper is used to map all of the transcript reads to the reference genome. Note that normally the barcode and UMI sequences are extracted from R1 and only the R2 reads are passed to the mapper. Therefore the mapper considers them to be single-ended reads labeled as R1 in the mapping metrics. Further information on the DRAGEN RNA mapper can be found on the [RNA alignment](/dragen-v4.6/product-guides/dragen-v4.6/dragen-rna-pipeline/rna-alignment.md) page. DRAGEN is also introducing support for the STAR aligner in DRAGEN 4.5 as an alternative to the DRAGEN RNA mapper. Further information on STAR aligner support can be found in the [STAR aligner](#star-aligner) section. Each read is mapped to the reference and then matched to genes based on where it aligns. If the read matches to the exons of a gene, then it is classified as an exon-matching read. Otherwise it is given another classification. DRAGEN scRNA currently only includes the primary alignment of each read (assigned randomly by the mapper if there are multiple alignments with identical scores). Secondary and supplementary alignments are skipped (but they are still included in the BAM output). The possible classifications for each read (based on its primary alignment) are: * Unique exon matching --- reads that overlap with gene exons by at least 50% of read length * Unique intron matching --- reads that overlap with the gene by at least 20% of read length * Mitochondrial --- reads that map to the mitochondrial genome * Filtered antisense --- reads that overlap a gene on the opposite strand defined by the library type * Filtered ambiguously matching --- reads that match to multiple genes * Filtered low MAPQ --- reads with low MAPQ (below 1 by default) that map ambiguously * Filtered non-matching --- reads that do not map to any genes For the remainder of the pipeline, only the unique exon matching, unique intron matching, and mitochondrial reads (together referred to as "mapped reads") are counted toward the molecule counts of each barcode. The other "filtered" reads will be included in the "Total" reads per barcode but not counted towards the molecule counts of each gene. If `--scrna-count-introns=false` is set, then intron reads will also be considered "filtered" rather than "mapped". The total number of reads in each classification can be found in the `.scRNA_metrics.csv` file as described in the [Read Matching Metrics](#read-matching-metrics) section. #### Biotype Filtering Add the argument `--scrna-filter-gene-biotypes=true` to exclude pseudogene, shortRNA and rRNA biotypes during mapping. ### Transcript Counting DRAGEN scRNA performs UMI correction per cell-barcode and gene as described in the [Barcode error correction](#barcode-error-correction) section. Then the corrected UMIs are deduplicated and counted for each cell-barcode and gene. ### Cell Filtering DRAGEN uses a threshold on the total count of distinct UMIs (or reads) per cell barcode, to determine which barcodes are likely to correspond to single-cells in the original sample, instead of background noise. The threshold is determined based on the distribution of counts along barcodes and on the expected number of true cells in the sample. * `--single-cell-number-cells` --- \[Optional] Sets the expected number of cells. The default is 3000. Adjust this value if using a `fixed` threshold or if the number of called cells deviates from expectation. * `--single-cell-threshold` --- Specifies the method for determining the count threshold value. The available values are `fixed`, `ratio`, or `inflection` (the default is `ratio`). * If using `ratio`, DRAGEN calculates the expected number of cells using `max(T_e, T_m)`. * `T_m` is a threshold based on a fraction of the molecules seen in the most abundant cell-barcodes. If the top decile cell is the cell occurring at the 90th percentile by molecule count, then `T_m` is calculated as 10% of the number of molecules occurring in the top decile cell. * `T_e` is a threshold based on a fraction of the least abundant expected cell. The least abundant expected cell is defined as the cell occurring at the rank of the number of expected cells (e.g. if the number of expected cells is 2,000, then the least abundant expected cell is the cell ranked 2,000th by molecule count abundance). `T_e` is calculated as 50% of the number of molecules found in the least abundant expected cell. * For example, if dataset A is provided to DRAGEN with an expected number of cells of 2,000 and it is found to contain 30,000 cell-barcodes, and the 3,000th most abundant cell(i.e. the top decile cell) has 1,100 molecules while the 2,000th most abundant cell (i.e. the least abundant expected cell) has 3,700 molecules, then `T_m` would be equal to `10% * 1,100 = 110 molecules` and `T_e` would be equal to `50% * 3,700 = 1,850 molecules`. The threshold would then be `max(1,850, 110) = 1,850 molecules`. * If using `inflection`, DRAGEN estimates the count threshold by analyzing inflection points in the cumulative distribution of counts. The second derivatives of the read/UMI counts are used to estimate the inflection point that is chosen as the threshold. * If using `fixed`, the count threshold is set to force the expected number of cells (`--single-cell-number-cells` option), rather than estimating it from the data. The exact number of passing cells might be slightly larger than the number of requested single-cells because several cells in the tail of the count distribution can have the same count. * `--single-cell-threshold-filterby` --- \[Optional] Set the count distribution to consider for cell filtering. Can be either `umi` (default) or `read`. To set a specific, fixed number of cells, rather than use the automatically determined threshold, use the following command: ``` --single-cell-threshold=fixed --single-cell-number-cells=X ``` The command forces DRAGEN to select the top X cells and extra cells with the same number of counts of the last selected cell. ## Outputs Single-cell RNA outputs are found in the standard DRAGEN output location. The files start with a `` which may correspond to `.` in the case of a single library and `..` in the case of multiple libraries. All single-cell RNA output files contain the word `scRNA` in their names. ### Count Files The count files contain the overall molecule counts on a per-cell gene expression level. Counts are reported in two formats: Market Exchange (MEX) and h5ad format. Furthermore, counts are reported for all barcodes (raw) as well as for the set of filtered barcodes that pass the cell filtering threshold. Raw MEX files: * `.scRNA.matrix.mtx.gz` * Count of molecules for each cell/gene pair in sparse matrix format. * `.scRNA.barcodes.tsv.gz` * Barcode sequence for each cell from the matrix. This includes all cell-barcodes. * `.scRNA.features.tsv.gz` * Gene name, ID and feature type for each gene and feature in the matrix. Raw h5ad file: * `.scRNA.h5ad` * Count matrix in AnnData format. Barcodes are stored in the OBS group and genes are stored in the VAR group. Further information on the h5ad format can be found on the [AnnData page](https://anndata.readthedocs.io/en/latest/fileformat-prose.html). * Note: the h5ad output can be disabled with the option `--single-cell-enable-h5ad-output=false` Filtered MEX files (containing only cells that pass the cell filtering threshold): * `.scRNA.filtered.matrix.mtx.gz` * Count of unique MIs for each **passing** cell/gene pair in sparse matrix format. * `.scRNA.filtered.barcodes.tsv.gz` * Cell-barcode sequence for each **passing** cell from the matrix. * `.scRNA.filtered.features.tsv.gz` * Gene name, ID and feature type for each gene and feature in the matrix (identical to `.scRNA.features.tsv.gz`). Filtered h5ad file: * `.scRNA.filtered.h5ad` * Filtered count matrix in AnnData format. Barcodes are stored in the OBS group and genes are stored in the VAR group. Further information on the h5ad format can be found on the [AnnData page](https://anndata.readthedocs.io/en/latest/fileformat-prose.html). * Note: the h5ad output can be disabled with the option `--single-cell-enable-h5ad-output=false` ### BAM file * `--enable-map-align-output=true` --- default is `false` * `--output-format=BAM` --- default is `BAM` A BAM file can be generated by adding in the options above. Note that enabling the BAM output may increase the runtime and memory usage of DRAGEN. All alignments of all of the reads are included in the BAM, with unmapped reads coming at the end. The primary alignment of each read (the only that is considered in the pipeline, see [Mapping](#mapping)) is annotated with single cell-specific BAM tags. The following tags are used: * `CR` --- Uncorrected barcode sequence * `CB` --- Corrected barcode sequence (identical to `CR` if no correction occurred) * `UR` --- Uncorrected BI sequence Non-primary alignments and reads not associated with a barcode will not have any single cell BAM tags. By default, the BAM file will not be sorted but all reads with the same barcode will be grouped together. The following options may be used to force the BAM to be sorted by reference position: `--split-by-cell-barcode=false`. However, this may lead to significant memory issues and is not recommended. If a sorted BAM file is desired, it is recommended to have DRAGEN produce an unsorted BAM and then run `samtools sort input.bam -o output_sorted.bam` to sort by position. Additional metrics related to the mapping of reads to the reference may be found in the `.mapping_metrics.csv` file. Note that the "mapped reads (RNA) to rRNA and filtered" metric in that file only includes non-coding rRNA (it excludes protein-coding ribosomal RNA transcripts), so it is not applicable to single cell RNA analyses. ### Single Cell RNA Metrics The `.scRNA_metrics.csv` file contains per sample single cell RNA metrics. In scRNA, mapped reads are currently reported by default under R1 metrics, irrespective of whether R1 is the read aligned to the transcriptome or the one containing the cell barcode and BI. The single cell RNA metrics file is in CSV format with the following fields: * Metric group * Sample name * Metric name * Metric value * Metric percentage (omitted for some metrics) The single cell RNA metrics are broken down into four metric groups (additional groups are included if certain options are enabled). #### Barcode Read Metrics Barcode read metrics report the breakdown of how many of the input read pairs contain valid barcodes (matching to the acceptable sequence list). The denominator of the metric percentages in this group is "Total input reads". * **Reads missing cellular or molecular barcodes**: The number of reads for which the overall barcode sequence (cell barcode + BI) failed basic checks, e.g. the barcode read was missing or too short. * **Reads with exactly matching barcodes**: The number of reads with barcode sequences that were not altered during error-correction, i.e. the barcode sequence exactly matched a barcode in the sequence list. * **Reads with corrected barcodes**: The number of reads with barcode sequences that were corrected to a valid sequence in the sequence list (within a hamming distance of 1). * **Reads with non-matching barcodes**: The number of reads with barcode sequences that did not match valid sequences in the sequence list, even after barcode correction (within a hamming distance of 1). * **Total input reads**: The total number of reads provided as input for this DRAGEN run. The metric value will be the sum of the above four metrics. * **Total barcoded reads**: The number of reads with valid barcodes that will proceed to the read matching stage. The metric value will be the sum of "Reads with exactly matching barcodes" and "Reads with corrected barcodes". #### Read Matching Metrics Read matching metrics report how many barcoded reads match to genes and how many were filtered due to various reasons. The denominator of the metric percentages in this group is "Total barcoded reads". * **Unique exon matching reads**: The number of reads that uniquely match with >50% overlap to the exon region of a single gene. * **Unique intron matching reads**: The number of reads that do not meet the exon-matching criteria above but map to a single gene with >20% overlap. N.B. if `--scrna-count-introns=false` is set, then this metric will become "Filtered intron matching reads". * **Filtered antisense reads**: The number of reads that overlap a gene on the opposite strand based on the library type of the reads. * **Filtered ambiguously matching reads**: The number of reads that match to multiple genes equally well. * **Filtered low MAPQ reads**: The number of reads that are filtered due to low MAPQ values (default threshold of 4). * **Filtered intergenic reads**: The number of reads that did not map to a genic region. * **Filtered unmapped reads**: The number of reads that failed to map to the reference. * **Mitochondrial reads**: The number of reads that map to mitochondria. * **Mapped reads**: The number of reads considered to be "mapping," i.e. that are found to match to a gene. The metric value will be the sum of "Unique exon matching reads," "Unique intron matching reads", and "Mitochondrial reads". N.B. if `--scrna-count-introns=false` is set, then introns will be excluded. * **Reads processed through mapper**: The total number of reads provided as input to the mapper. The metric value will be the sum of all of the above Read matching metrics excluding "Mapped reads". #### Molecule Count Metrics Molecule count metrics report how many reads and molecules contribute toward the count table. No metric percentages are reported. * **Reads with valid molecular identifier sequences**: The number of reads with exactly matching molecular identifier (MI) sequences (i.e. BI sequences). If no MI correction is enabled, then all counted gene reads will be included here. * **Reads with corrected molecular identifier sequences**: The number of reads with MI sequences that were corrected to a valid sequence. If no MI correction is enabled, then the value will be 0. * **Reads with invalid molecular identifier sequences**: The number of reads that were not counted due to having an invalid MI (BI) sequence. Homopolymer sequences and Ns are examples of invalid MI sequences. If no MI correction is enabled, then the value will be 0. * **Total gene reads**: The total number of gene expression or transcript reads. This value includes both mapped reads and filtered reads and should match the "Reads processed through mapper" metric if all reads had valid BI sequences. * **Total counted gene reads**: The total number of mapped reads with valid barcode and BI sequences. The value includes exon-matching, intron-matching, and mitochondrial reads. * **Total molecules**: The total number of individual molecules found after performing IPM correction on the counted gene reads per unique barcode-BI-IMI combination. * **Sequencing saturation**: The likelihood that if an additional read is sequenced, it would already have been observed. It is calculated as the fraction of "duplicate reads" from the same molecule using the formula 1 - ( "Total molecules" / "Total counted gene reads" ). #### Cell Metrics Cell metrics report on the number of barcodes, passing cells based on the count threshold, and mean and median reads, molecules, and genes per cell. No metric percentages are reported. * **Total unique barcodes**: The total number of unique barcode sequences. * **Passing cell threshold (by molecule/read count)**: The number of molecules or reads required for a barcode to be considered a (passing) cell. N.B. the `--single-cell-threshold-filter-by` option determines whether molecule or read counts are used for this threshold (default: molecule). * **Passing cells**: The total number of cells called (i.e. the number of barcodes that passed the filter threshold). * **Fraction of reads in passing cells**: The fraction of reads that were assigned to passing cells, calculated as total gene reads in passing cells over total gene reads. N.B. total gene reads include filtered reads in the Read matching metrics group. * **Fraction of reads in passing cells that are genic**: The fraction of reads assigned to passing cells that are genic reads i.e. matching to genes, calculated as total counted gene reads in passing cells over total gene reads in passing cells. Genic reads correspond to counted gene reads which include exon-matching, intron-matching, and mitochondrial reads. * **Mean reads per cell (Total input reads / Passing cells)**: The average number of reads per passing cell calculated by dividing "Total input reads" by "Passing cells". * **Median molecules per cell**: The median number of molecules per passing cell based on sorting the passing cells by molecule count. * **Median genes per cell**: The median number of genes per passing cell based on sorting the passing cells by gene count. * **Total genes detected**: The total number of unique genes detected in the passing cells (i.e. the number of genes with at least one molecule in at least one passing cell). ### Per-Read Group Metrics * `.scRNA.read_group_metrics.csv` An additional metrics file is output for each read group provided to DRAGEN in the FASTQ list. These per-read group metrics can be useful for performing QA for each read group. The following metrics are reported for each non-feature read group (with ` -` at the start of each line). The description of each metric matches the corresponding metrics in the Single Cell RNA Metrics section above. * scRNA Barcode Read Metrics * Reads missing cellular or molecular barcodes * Reads with exactly matching barcodes * Reads with corrected barcodes * Reads with non-matching barcodes * Total input reads * Total barcoded reads * scRNA Alignment Metrics * Unique exon matching reads * Unique intron matching reads * Filtered antisense reads * Filtered ambiguously matching reads * Filtered low MAPQ reads * Filtered intergenic reads * Filtered unmapped reads * Mitochondrial reads * Mapped reads * Reads processed through mapper * scRNA Molecule Count Metrics * Total gene reads * Total counted gene reads * Total molecules * Sequencing saturation * scRNA Cell Metrics * Passing cells * Fraction of reads in passing cells * Fraction of reads in passing cells that are genic * Mean reads per cell (Total input reads / Passing cells) * Median molecules per passing cell * Median genes per passing cell See the feature counting and direct capture sections for the per-read group metrics reported for those read groups. ### Barcode Summary File * `.scRNA.barcodeSummary.tsv` The barcode summary file provides a list of all barcodes as well as the number of reads, genes, and molecules in each barcode and its filter status (either `PASS` for above the cell filter threshold or `LOW` for below the threshold). Fields in the barcode summary file: * **ID**: Unique numeric ID for the barcode. The ID corresponds to the line number of that barcode in the MEX output. * **Barcode**: The barcode sequence. * **TotalReads**: Total reads containing the barcode sequence. This includes counted gene reads as well as reads that were filtered for wrong strand, low MAPQ, ambiguously matched or not mapped to a gene. * **GeneReads**: Reads (primary read alignments) that were counted towards a gene. This includes exons, mitochondrial reads, and introns (if `scrna-count-introns=true` which is set by default). * **Molecules**: Total molecule count. * **Genes**: Unique genes detected. * **MitochondrialReads**: Reads mapped to the mitochondrial genome. * **Filter**: Cell-filtering status of the barcode. Possible values are: * **`PASS`**: Barcode passes the cell filter threshold. * **`LOW`**: Barcode count is below the threshold. ### Molecule Info File * `.scRNA.moleculeInfo.h5` The molecule info file provides a summary of the read counts for each barcode, gene, BI and UMI combination. The contents of the HDF5 file can be viewed using [HDFview](https://www.hdfgroup.org/download-hdfview/) or using the `h5dump` command: ```bash h5dump -n .scRNA.moleculeInfo.h5 HDF5 ".scRNA.moleculeInfo.h5" { FILE_CONTENTS { group / dataset /barcode_idx dataset /barcodes dataset /feature_ids dataset /feature_idx dataset /feature_names dataset /umis dataset /read_counts } } ``` * **barcode\_idx**: the barcode index number (Note: this internal value does not match with the barcodes.tsv line number) * **barcodes**: the barcode sequence * **feature\_ids**: the gene or feature ID * **feature\_idx**: the gene or feature index number (Note: this internal value does not match with the features.tsv line number) * **feature\_names**: the gene or feature name * **umis**: the UMI value corresponding to the global position where the read was mapped * **read\_counts**: the number of reads found for the given barcode, gene and UMI The HDF5 file can be further manipulated in python using the [h5py package](https://www.h5py.org/). Below is example code for creating a pandas DataFrame object from the molecule info file. ```python import h5py import pandas as pd h5_file_path = ".scRNA.moleculeInfo.h5" h5_data = {} with h5py.File(h5_file_path, 'r') as h5_file: for key in h5_file: h5_data[key] = h5_file[key][:] fields = ["barcode_idx", "gene_idx", "umis", "read_counts"] df_h5 = pd.DataFrame({key: h5_data[key] for key in fields}) df_h5['barcodes'] = h5_data['barcodes'][df_h5['barcode_idx']] df_h5['feature_ids'] = h5_data['feature_ids'][df_h5['feature_idx']] df_h5['feature_names'] = h5_data['feature_names'][df_h5['feature_idx']] ``` ### Barcode Rank Plot DRAGEN can generate a barcode rank plot with the help of DRAGEN Reports. The `.scRNA.barcodeCounts.txt` file contains the final raw counts of every barcode in decreasing order. The barcode counts file is used by DRAGEN Reports to produce a barcode rank plot (also known as a "knee" plot). If DRAGEN is run on the cloud via BSSH or Platform Core, then DRAGEN Reports will automatically be run and produce the final `report.html` file, which will contain the barcode rank plot on the "Sample Report" page. If DRAGEN is run on-prem, then DRAGEN Reports can be run after DRAGEN single cell RNA has finished running. An example DRAGEN Reports command line is: ```bash dragen-reports -d -o /report.html -m /dragen-reports/manifests/scrna.json ``` The barcode rank plot will appear in the output report.html "Sample Report" page. More information on DRAGEN Reports can be found [here](/dragen-v4.6/product-guides/dragen-v4.6/dragen-reports.md). ### UMAP and Marker Gene Table DRAGEN can also generate a UMAP plot and marker gene table with the help of DRAGEN Reports. Note: both the UMAP plot and marker gene table are only available if DRAGEN Reports is run on the cloud via BSSH or Platform Core. If DRAGEN is run on the cloud via BSSH or Platform Core, then DRAGEN Reports will automatically be run and produce the final `report.html` file. When the file is opened, click the sample name to go to the "Sample Report" page and then click "Single-Cell Clustering". The UMAP Plot and Top Marker Genes table will appear. If DRAGEN is run on-prem, then DRAGEN Reports can be run after DRAGEN single cell RNA has finished running. An example DRAGEN Reports command line is: ```bash dragen-reports -d -o /report.html -m /dragen-reports/manifests/scrna.json ``` The Top Marker Genes table will appear in the output report.html under the "Single-Cell Clustering" tab of the "Sample Report" page. The UMAP plot and marker gene table are not available when running DRAGEN on-prem. More information on DRAGEN Reports can be found [here](/dragen-v4.6/product-guides/dragen-v4.6/dragen-reports.md). ## Feature Counting DRAGEN single cell RNA supports feature counting which can be used to profile the expression of proteins (e.g. antibodies or cell-surface proteins). Feature reads differ from transcript (or gene expression) reads in that their read 2 sequence (R2) contains an oligo tag corresponding to a particular type of protein. Reads marked as feature reads will be matched against the list of feature barcode reference sequences (in contrast to gene expression reads which are matched to genes). Only feature reads matching feature barcode reference sequences will be counted in the final matrix. ### Inputs Feature counting is activated by providing a feature barcode reference file using `--scrna-feature-barcode-reference`. The feature barcode reference file can either be in FASTA format or CSV format (see below for examples). If the feature barcode reference file is provided in FASTA format, then the feature names should be provided in the header and the feature barcode reference sequences should be provided as the sequence. If the feature barcode reference file is provided in CSV format, the following fields should be included: | Header field | Description | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | Feature/gene ID | | name | Feature/gene name | | read | Read that the feature sequence is on (R1 or R2) | | target | (Optional) Target or "hook" sequence (e.g. the protospacer sequence for CROP-seq). If the value is set to "5p", then the target sequence is based on the beginning of the read (default value: "5p") | | position | Starting position of the feature barcode reference sequence relative to the start of the target sequence if present, otherwise the start of read 2 | | sequence | Feature barcode reference sequence | | feature\_type | Name of feature (e.g. Antibody Capture) | When feature counting is used, a FASTQ list is usually provided containing both the gene expression FASTQs and the feature read FASTQs. The read groups (RGIDs) of the feature read input FASTQs must be provided using the `--scrna-feature-barcode-groups=` option (multiple read groups should be comma-separated). See the CRISPR mode examples below for how to provide the read groups to the `--scrna-feature-barcode-groups` option. ### Examples Example feature barcode reference file (FASTA): ``` >ADT_Hu.HLA.DR.DP.DQ_A1018 AGCTACGAGCAGTAG >ADT_Hu.B2M_A0057 CAGCCCGATTAAGGT >ADT_Hu.B7.H4_A0395 TGTATGTCTGCCTTG ``` Example feature barcode reference file (CSV): ``` id,name,read,position,sequence,feature_type ADT_A1018,ADT_Hu.HLA.DR.DP.DQ_A1018,R2,0,AGCTACGAGCAGTAG,Antibody Capture ADT_A0057,ADT_Hu.B2M_A0057,R2,0,CAGCCCGATTAAGGT,Antibody Capture ADT_A0395,ADT_Hu.B7.H4_A0395,R2,0,TGTATGTCTGCCTTG,Antibody Capture ``` Example command line: ```bash dragen \ --fastq-list= \ --ref-dir= \ --annotation-file= \ --output-directory= \ --output-file-prefix= \ --scrna-enable-pipseq-mode=true \ --scrna-feature-barcode-groups= \ --scrna-feature-barcode-reference= \ ``` ### Outputs When feature counting is enabled, DRAGEN produces additional outputs. The features that were found are appended to the end of `.scRNA.features.tsv.gz`. The feature counts for all the barcodes are found in the `.scRNA.matrix.mtx.gz` raw matrix file and the feature counts for the filtered barcodes are found in the `.scRNA.filtered.matrix.mtx.gz` matrix file. Separate feature matrix files will be produced if the following option is enabled: "--scrna-output-split-matrices=true" * `.scRNA.feature_matrix.barcodes.tsv.gz` * `.scRNA.feature_matrix.features.tsv.gz` * `.scRNA.feature_matrix.matrix.mtx.gz` The feature barcode reference file will also be included in the DRAGEN output directory with the name `.feature_barcode_reference` with the corresponding extension for a CSV or a FASTA file (depending on what was provided as input). The molecule info file will also include features and feature counts. The following columns are also added to the `.scRNA.barcodeSummary.tsv` file when feature counting is enabled: * **TotalFeatureReads**: The total number of feature reads found for the barcode sequence (including feature reads that did not successfully match to the feature barcode reference sequence). * **FeatureMolecules**: The number of feature molecules found for the barcode sequence (only including feature reads matching to the feature barcode reference sequence). * **Features**: The total number of features found for the barcode sequence. * **TotalReads**: The sum of TotalGeneReads and TotalFeatureReads for the barcode sequence. * **TotalMolecules**: The sum of Molecules and FeatureMolecules for the barcode sequence. * **TotalGenesAndFeatures**: The sum of Genes and Features for the barcode sequence. #### Feature Metrics When feature counting is enabled, the following feature metrics are also output in `.scRNA_metrics.csv`: The denominator of the metric percentages below is "Total input feature reads". * **Feature reads missing cellular or molecular barcodes**: The number of feature reads for which the overall barcode sequence (cell barcode + BI) failed basic checks, e.g. the barcode was missing or too short. * **Feature reads with exactly matching barcodes**: The number of feature reads with barcode sequences that were not altered during error-correction, i.e. the barcode sequence exactly matched a barcode in the sequence list. * **Feature reads with corrected barcodes**: The number of feature reads with barcode sequences that were corrected to a valid sequence in the sequence list (within a hamming distance of 1). * **Feature reads with non-matching barcodes**: The number of feature reads with barcode sequences that did not match valid sequences in the sequence list, even after barcode correction (within a hamming distance of 1). * **Total input feature reads**: The total number of feature reads provided as input to DRAGEN. The value of this metric will equal the sum of the above four metrics. * **Total barcoded feature reads**: The total number of barcoded feature reads that will proceed to the feature barcode reference sequence matching stage. The denominator of the metric percentages below is "Total barcoded feature reads". * **Feature reads matching feature sequence**: The number of feature reads that match to the feature barcode reference sequences (allowing for a hamming distance of 1). * **Feature reads not matching to features**: The number of feature reads that do not match to the feature barcode reference sequences (even allowing for a hamming distance of 1). This metric is reported only if the target column is not populated. * **Feature reads matching target but not feature sequence**: The number of feature reads that match to the target sequence but do not match to the feature sequence in the feature barcode reference (even allowing for a hamming distance of 1). This metric is reported only if the target column is populated. * **Feature reads not matching target sequence**: The number of feature reads that do not match to the target sequence (even allowing for a hamming distance of 1). This metric is reported only if the target column is populated. * **Total feature reads**: The total number of feature reads processed by the workflow (this should match the "Total barcoded feature reads" metric above). No denominators below * **Feature reads with valid molecular identifier sequences**: The number of feature reads with exactly matching molecular identifier (MI) sequences (i.e. BI sequences). If feature MI correction is not enabled, then all feature reads will be included here. * **Feature reads with corrected molecular identifier sequences**: The number of feature reads with MI sequences that were corrected to a valid sequence. If feature MI correction is not enabled, then the value will be 0. * **Feature reads with invalid molecular identifier sequences**: The number of feature reads that were not counted due to having an invalid MI (BI) sequence. Homopolymer sequences and Ns are examples of invalid MI sequences. If feature MI correction is not enabled, then the value will be 0. * **Total feature molecules**: The total number of feature molecules found. * **Feature sequencing saturation**: The likelihood that if an additional feature read is sequenced, it would already have been observed. It is calculated as the fraction of "duplicate reads" from the same molecule using the formula 1 - ( "Total feature molecules" / "Feature reads matching feature sequence" ). * **Feature reads in passing cells**: The number of feature reads in passing cells. Also includes the percentage of feature reads in passing cells over all feature reads. * **Feature reads matching to features in passing cells**: The number of feature reads matching to feature sequences in passing cells (tag-matching feature reads). Also includes the percentage of feature reads matching to feature sequences in passing cells over all feature reads. * **Mean feature reads per cell (Total input feature reads / Passing cells)**: The average number of feature reads per passing cell calculated by dividing "Total input feature reads" by "Passing cells". * **Median feature molecules per passing cell**: The median number of feature molecules per passing cell based on sorting the passing cells by feature molecule count. * **Median features per passing cell**: The median number of features per passing cell based on sorting the passing cells by feature count. * **Total features in reference**: The total number of features in the feature barcode reference. * **Total features detected**: The total number of unique features detected in the passing cells (i.e. the number of features with at least one molecule in at least one passing cell). Also includes the percentage of features found in passing cells over all features in the feature barcode reference. * **Passing cells with feature reads**: The number of passing cells with at least one feature reads. Also includes the percentage of passing cells with at least one feature read over all passing cells. * **Median feature molecules in passing cells with feature matching reads**: The median number of feature molecules per passing cell that has at least one feature matching read. * **Median features in passing cells with feature matching reads**: The median number of features per passing cell that has at least one feature matching read. When feature counting is enabled, the following per-read group feature metrics are also output in `.scRNA.read_group_metrics.csv` (metrics descriptions match the corresponding metrics above): * Feature reads missing cellular or molecular barcodes * Feature reads with exactly matching barcodes * Feature reads with corrected barcodes * Feature reads with non-matching barcodes * Total input feature reads * Total barcoded feature reads * Feature reads matching feature sequence * Total feature reads * Mean feature reads per cell (Total input feature reads / Passing cells) When feature counting is enabled, the following metrics per-feature type in the feature barcode reference are also output in a `.scRNA.feature_type_metrics.csv` (metrics descriptions match the ones for `.scRNA_metrics.csv` feature metrics): * Feature reads matching feature sequence * Total feature reads * Median feature molecules per passing cell * Median features per passing cell * Total features in reference * Total features detected * Passing cells with feature matching reads * Median feature molecules in passing cells with feature matching reads * Median features in passing cells with feature matching reads ## Direct Capture Mode (previously CRISPR Mode) DRAGEN also supports processing samples from Illumina CRISPR Single Cell kits using PIPseq technology, referred to below as direct capture. Set `--scrna-enable-direct-capture-mode` to true to activate this mode (the previous option `--scrna-enable-pipseq-crispr-mode` is now deprecated but still functions in this release). Activating direct capture mode automatically configures DRAGEN to process direct capture reads containing the guide RNA (gRNA) sequences. This includes handling the offsets in the cell-barcode position for the gRNA reads, transforming the gRNA cell-barcodes to match the gene expression ones, utilizing the "hook and grab" approach for matching the direct capture barcode reference sequences and identifying the gRNA reads, and counting the gRNA reads (disregarding BIs and IMIs). Both gene expression and gRNA reads are processed in a single DRAGEN run. Note: unmapped reads do not contribute to gene expression read counts but are still included in gRNA counts if they match the hook sequence. The “hook and grab” method is a targeted approach for identifying CRISPR perturbation reads. It leverages a conserved sequence within the guide RNA structural region as a “hook” to locate the guide RNA and then “grabs” the specific guide by mapping it to a database of known sequences based on their displacement from the hook. ![](https://400428970-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS6tWlZO1JqcbWYgnhR2X%2Fuploads%2Fgit-blob-e0419f95d2f027ec236fede97869bbb8e7281103%2FHook_and_Grab.png?alt=media) ### Inputs Direct capture mode is activated by setting `--scrna-enable-direct-capture-mode=true` (the previous option `--scrna-enable-pipseq-crispr-mode` is now deprecated but still functions in this release). Direct capture mode requires `--scrna-enable-pipseq-mode` to be set to true as well. Note that when `--scrna-enable-direct-capture-mode` is set to true, the following options are also set automatically: * `--Aligner.aln-min-score=25` * `--scrna-guide-calling-mode=gmm` For a standard direct capture workflow, a FASTQ list is usually provided containing both the gene expression FASTQs and the direct capture FASTQs. The read groups of the direct capture input FASTQs must be provided using the `--scrna-direct-capture-barcode-groups=` option (multiple read groups should be comma-separated). Furthermore, a direct capture barcode reference file must be provided using the `--scrna-direct-capture-barcode-reference` argument. Note that both feature and direct capture barcode reference files and barcode groups can be provided and they will be counted and reported independently. The direct capture barcode reference file should be in CSV format with the following header fields: | Header field | Description | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | id | Feature/gene ID | | name | Feature/gene name | | read | Read that the guide RNA is on (R1 or R2) | | target | Target or "hook" sequence. If the value is set to "5p", then the target sequence is based on the beginning of the read (default value: "5p") | | position | Displacement of the start of the identifying guide RNA sequence relative to the start of the target sequence (can be positive or negative) | | sequence | Guide RNA sequence | | feature\_type | Name of feature (e.g. CRISPR Direct Capture) | **Example FASTQ list CSV file:** ```bash RGID,RGSM,RGLB,Lane,Read1File,Read2File GEX_1,CD20250502_CRISPR_6,20250505_CD_Pool1_Lancelot_CST_47,1,, GEX_2,CD20250502_CRISPR_6,20250505_CD_Pool1_Lancelot_CST_47,2,, CRISPR_1,CD20250502_CRISPR_6,20250505_CD_Pool1_Lancelot_CST_47,1,, CRISPR_2,CD20250502_CRISPR_6,20250505_CD_Pool1_Lancelot_CST_47,2,, ``` Notes: * The RGID is referred to as the "read group" and direct capture RGIDs should be passed to the `--scrna-direct-capture-barcode-groups` option * The RGSM values should match for all reads to be processed in a single DRAGEN run * The RGLB values should match for all reads to be analyzed together (the results will be combined into a single metrics output file) **Example direct capture barcode reference file:** ```bash id,name,read,target,position,sequence,feature_type NegCtrl_0001,NegCtrl_0001,R2,GTTTAAGAGCTATGCT,-20,GTAGCGAACGTGTCCGGCGT,CRISPR Direct Capture IntronCtrl_ALAS1_1,IntronCtrl_ALAS1_1,R2,GTTTAAGAGCTATGCT,-20,GGTGGACATCCACCCCTAAG,CRISPR Direct Capture ACTG1_1,ACTG1_1,R2,GTTTAAGAGCTATGCT,-20,AGCTGTAGCCTCGCTCAGTG,CRISPR Direct Capture IMMP1L_1,IMMP1L_1,R2,GTTTAAGAGCTATGCT,-20,AGTATAGCCAACAAGTCGAA,CRISPR Direct Capture IMMP1L_2,IMMP1L_2,R2,GTTTAAGAGCTATGCT,-20,ATACGTTGGTGGTGTTGTCA,CRISPR Direct Capture ``` **Examples of target, position, and sequence values for common use cases are provided below:** ![](https://400428970-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS6tWlZO1JqcbWYgnhR2X%2Fuploads%2Fgit-blob-7cd7da46fc60e714c1cf50ce403a980e6f42914a%2FHook_and_Grab_examples.png?alt=media) ### Example Command Line ```bash dragen \ --fastq-list= \ --ref-dir= \ --annotation-file= \ --output-directory= \ --output-file-prefix= \ --scrna-enable-pipseq-mode=true \ --scrna-enable-direct-capture-mode=true \ --scrna-direct-capture-barcode-groups=CRISPR_1,CRISPR_2 \ # Assuming the FASTQ list looks like the example CSV file above --scrna-direct-capture-barcode-reference= \ ``` ### Direct Capture Mode Outputs The direct capture features that were found are appended to the end of `.scRNA.features.tsv.gz`. The direct capture feature counts for all the barcodes are found in the `.scRNA.matrix.mtx.gz` raw matrix file and the direct capture counts for the filtered barcodes are found in the `.scRNA.filtered.matrix.mtx.gz` matrix file. Separate direct capture matrix files will be produced if the following option is enabled: "--scrna-output-split-matrices=true" * `.scRNA.direct_capture_matrix.barcodes.tsv.gz` * `.scRNA.direct_capture_matrix.features.tsv.gz` * `.scRNA.direct_capture_matrix.matrix.mtx.gz` The direct capture barcode reference file will also be included in the DRAGEN output directory with the name `.direct_capture_barcode_reference.csv`. The molecule info file will also include direct capture features and direct capture read and molecule counts. The following columns are also added to the `.scRNA.barcodeSummary.tsv` file when direct capture mode is enabled: * **TotalDirectCaptureReads**: The total number of direct capture reads found for the barcode sequence (including direct capture reads that did not successfully match to the direct capture barcode reference sequence). * **DirectCaptureMolecules**: The number of direct capture molecules found for the barcode sequence (only including direct capture reads matching to the direct capture barcode reference sequence). * **DirectCaptureFeatures**: The total number of direct capture features found for the barcode sequence. * **TotalReads**: The sum of TotalGeneReads and TotalDirectCaptureReads (and TotalFeatureReads if present) for the barcode sequence. * **TotalMolecules**: The sum of Molecules and DirectCaptureMolecuels (and FeatureMolecules if present) for the barcode sequence. * **TotalGenesAndFeatures**: The sum of Genes and DirectCaptureFeatures (and Features if present) for the barcode sequence. #### Direct Capture Metrics When direct capture mode is enabled, the following direct capture metrics are also output in `.scRNA_metrics.csv`: The denominator of the metric percentages below is "Total input direct capture reads". * **Direct capture reads missing cellular or molecular barcodes**: The number of direct capture reads for which the overall barcode sequence (cell barcode + BI) failed basic checks, e.g. the barcode was missing or too short. * **Direct capture reads with exactly matching barcodes**: The number of direct capture reads with barcode sequences that were not altered during error-correction, i.e. the barcode sequence exactly matched a barcode in the sequence list. * **Direct capture reads with corrected barcodes**: The number of direct capture reads with barcode sequences that were corrected to a valid sequence in the sequence list (within a hamming distance of 1). * **Direct capture reads with non-matching barcodes**: The number of direct capture reads with barcode sequences that did not match valid sequences in the sequence list, even after barcode correction (within a hamming distance of 1). * **Total input direct capture reads**: The total number of direct capture reads provided as input to DRAGEN. The value of this metric will equal the sum of the above four metrics. * **Total barcoded direct capture reads**: The total number of barcoded direct capture reads that will proceed to the direct capture barcode reference sequence matching stage. The denominator of the metric percentages below is "Total barcoded direct capture reads". * **Direct capture reads matching feature sequence**: The number of direct capture reads that match to the direct capture barcode reference sequences (allowing for a hamming distance of 1). * **Direct capture reads matching target but not feature sequence**: The number of direct capture reads that match to the target sequence but not to the feature sequence in the direct capture barcode reference (even allowing for a hamming distance of 1). * **Direct capture reads not matching target sequence**: The number of direct capture reads that do not match to the target sequence (even allowing for a hamming distance of 1). * **Total direct capture reads**: The total number of direct capture reads processed by the workflow (this should match the "Total barcoded direct capture reads" metric above). No denominators below * **Direct capture tag matching rate**: The fraction of direct capture reads matching feature sequence over the total number of barcoded direct capture reads. * **Direct capture reads with valid molecular identifier sequences**: The number of direct capture reads with exactly matching molecular identifier (MI) sequences (i.e. BI sequences). If feature MI correction is not enabled, then all direct capture reads will be included here. * **Direct capture reads with corrected molecular identifier sequences**: The number of direct capture reads with MI sequences that were corrected to a valid sequence. If feature MI correction is not enabled, then the value will be 0. * **Direct capture reads with invalid molecular identifier sequences**: The number of direct capture reads that were not counted due to having an invalid MI (BI) sequence. Homopolymer sequences and Ns are examples of invalid MI sequences. If feature MI correction is not enabled, then the value will be 0. * **Total direct capture molecules**: The total number of direct capture molecules found. * **Direct capture sequencing saturation**: The likelihood that if an additional direct capture read is sequenced, it would already have been observed. It is calculated as the fraction of "duplicate reads" from the same molecule using the formula 1 - ( "Total direct capture molecules" / "Direct capture reads matching feature sequence" ). * **Direct capture reads in passing cells**: The number of direct capture reads in passing cells. Also includes the percentage of direct capture reads in passing cells over all direct capture reads. * **Direct capture reads matching to features in passing cells**: The number of direct capture reads matching to feature sequences (tag-matching direct capture reads) in passing cells. Also includes the percentage of direct capture reads matching to feature sequences in passing cells over all direct capture reads. * **Mean direct capture reads per cell (Total input direct capture reads / Passing cells)**: The average number of direct capture reads per passing cell calculated by dividing "Total input direct capture reads" by "Passing cells". * **Median direct capture molecules per passing cell**: The median number of direct capture molecules per passing cell based on sorting the passing cells by direct capture molecule count. * **Median direct capture features per passing cell**: The median number of direct capture features per passing cell based on sorting the passing cells by direct capture feature count. * **Total direct capture features in reference**: The total number of direct capture features in the direct capture barcode reference. * **Total direct capture features detected**: The total number of unique direct capture features detected in the passing cells (i.e. the number of direct capture features with at least one molecule in at least one passing cell). Also includes the percentage of direct capture features found in passing cells over all features in the direct capture barcode reference. * **Passing cells with direct capture reads**: The number of passing cells with at least one direct capture reads. Also includes the percentage of passing cells with at least one direct capture read over all passing cells. * **Median direct capture molecules in passing cells with direct capture matching reads**: The median number of direct capture molecules per passing cell that has at least one direct capture matching read. * **Median direct capture features in passing cells with direct capture matching reads**: The median number of direct capture features per passing cell that has at least one direct capture matching read. When direct capture mode is enabled, the following per-read group direct capture metrics are also output in `.scRNA.read_group_metrics.csv` (metrics descriptions match the corresponding metrics above): * Direct capture reads missing cellular or molecular barcodes * Direct capture reads with exactly matching barcodes * Direct capture reads with corrected barcodes * Direct capture reads with non-matching barcodes * Total input direct capture reads * Total barcoded direct capture reads * Direct capture reads matching feature sequence * Total direct capture reads * Direct capture tag matching rate * Mean direct capture reads per cell (Total input direct capture reads / Passing cells) When direct capture mode is enabled, the following metrics per-feature type in the direct capture barcode reference are also output in a `.scRNA.feature_type_metrics.csv` (metrics descriptions match the ones for `.scRNA_metrics.csv` direct capture metrics): * Direct capture reads matching feature sequence * Total direct capture reads * Median direct capture molecules per passing cell * Median direct capture features per passing cell * Total direct capture features in reference * Total direct capture features detected * Passing cells with direct capture matching reads * Median direct capture molecules in passing cells with direct capture matching reads * Median direct capture features in passing cells with direct capture matching reads ### Guide RNA Calling DRAGEN now also supports guide RNA calling - identifying cells that express guide RNA sequences. Although the counts matrix reports how many feature counts were found for each cell, there is a chance that the feature reads happened to match to the feature barcode reference sequence or the feature count was assigned to the cell by chance rather than due to real signal. Guide RNA calling applies an additional filtering step to distinguish between cells truly expressing guide RNA sequences and noise (similar to how cell filtering is performed to distinguish true passing cells from noise). DRAGEN utilizes a Gaussian Mixture Model (GMM) approach to perform guide RNA calling. For each feature, DRAGEN constructs a GMM on the feature counts for the set of cells containing that feature. The GMM has two components: the signal distribution and the noise distribution. The model is simplified by assuming the signal and noise distributions have the same variance. Initial parameters are set based on the threshold that maximizes the likelihood of the model and then the Expectation-Maximization (EM) algorithm (add citation) is used to optimize the parameters. After the model converges to a final set of parameters, a threshold is chosen that maximally separates the signal and noise populations, and each cell is classified as expressing the feature or not. When feature counting is enabled, guide RNA calling can also be enabled by setting `--scrna-guide-calling-mode=gmm`. When direct capture mode is enabled, guide RNA calling using GMMs is automatically enabled with that option. Guide RNA calling can be disabled by setting `--scrna-crispr-guide-calling-mode=none`. #### Guide Calling Outputs If guide RNA calling is enabled, then DRAGEN will generate four additional files: * `.scRNA.positive_cell_guide_assignments.csv` * A CSV file containing all of the passing cells with the following fields: * **cell\_barcode**: The cell barcode sequence. * **num\_features**: The number of features called for the cell (may be 0). * **feature\_call**: A list of all features called for the cell (separated with a "|"). May be empty if num\_features is 0. * **num\_transcripts**: The number of feature counts for each feature for the cell (separated with a "|"). May be empty if num\_features is 0. * **score**: The posterior probability for each feature called for the cell (separated with a "|"). * `.scRNA.singlet_cell_guide_assignments.csv` * A CSV file containing only the cells for which exactly one feature was called, with the following fields: * **cell\_barcode**: The cell barcode sequence. * **feature\_call**: The feature that was called for that cell. * `.scRNA.simple_threshold_guide_assignments.csv` * A CSV file containing guides whose counts exceed the simple global threshold. The threshold can be set using `--scrna-guide-calling-global-count-threshold` (default: 10). * **cell\_barcode**: The cell barcode sequence. * **num\_features**: The number of features called for the cell (may be 0). * **feature\_call**: A list of all features called for the cell (separated with a "|"). May be empty if num\_features is 0. * **num\_transcripts**: The number of feature counts for each feature for the cell (separated with a "|"). May be empty if num\_features is 0. * **score**: The confidence value of a logistic (sigmoid) function in (0.5, 1.0] centered at the threshold for each feature called for the cell (separated with a "|"). * `.scRNA.guide_metrics.csv` * A CSV metrics file containing the following Guide Metrics: * **Passing cells with features**: The total number of passing cells. * **Total cells with one or more features detected**: The number and fraction of total cells with at least one feature passing the guide calling threshold. * **Total cells with two or more features detected**: The number and fraction of total cells with at least two features passing the guide calling threshold. * **Total features in reference**: The total number of features in the feature/direct capture barcode reference file. * **Features in positive cells**: The number and fraction of total features found in cells passing the guide calling threshold. * All of the same metrics as above are also provided per feature type provided in the feature/direct capture barcode reference (e.g. CRISPR Direct Capture). Those metrics are calculated for only that feature type. #### Paired Guide Calling Paired guide calling is now supported. Two things are required to activate it: 1. Add the option `--scrna-enable-paired-guide-calling=true` 2. Add a "guide\_pair\_id" column to the feature/direct capture barcode reference file such that each set of guides to be called together have the same guide pair ID Note: more than two guides can be paired together (there is no limit). If paired guide calling is enabled, then an additional guide assignment file will be output for each method. **Only guide pair IDs for which ALL constituent guides are passing in the same cell will be reported**. * `.scRNA.positive_paired_guide_assignments.csv` * A CSV file containing all of the passing cells with the following fields: * **cell\_barcode**: The cell barcode sequence. * **num\_features**: The number of guide pair IDs for which all of the constituent guides are called for the cell (may be 0). * **feature\_call**: A list of all features called for the cell for which all constituent guides of their guide pair ID are also called (separated with a "|"). May be empty if num\_features is 0. * **num\_transcripts**: The number of feature counts for each feature for the cell (separated with a "|"). May be empty if num\_features is 0. * **score**: The posterior probability for each feature called for the cell (separated with a "|"). * **guide\_pair\_id**: The guide pair ids for the features that are called for the cell (separated with a "|"). * `.scRNA.simple_threshold_paired_guide_assignments.csv` * A CSV file containing guide pair IDs whose counts exceed the simple global threshold. The threshold can be set using `--scrna-guide-calling-global-count-threshold` (default: 10). * **cell\_barcode**: The cell barcode sequence. * **num\_features**: The number of guide pair IDs for which all of the constituent guides are called for the cell (may be 0). * **feature\_call**: A list of all features called for the cell for which all constituent guides of their guide pair ID are also called (separated with a "|"). May be empty if num\_features is 0. * **num\_transcripts**: The number of feature counts for each feature for the cell (separated with a "|"). May be empty if num\_features is 0. * **score**: The confidence value of a logistic (sigmoid) function in (0.5, 1.0] centered at the threshold for each feature called for the cell (separated with a "|"). * **guide\_pair\_id**: The guide pair ids for the features that are called for the cell (separated with a "|"). ## Standalone Cell-filtering Mode DRAGEN supports running cell filtering as a standalone run. If a completed run is found to have used the wrong cell-filtering method or threshold, then standalone cell-filtering mode provides a lightweight method to try different methods and thresholds without having to rerun all of DRAGEN. It bypasses the mapping, counting, and deduplication steps and proceeds directly to cell filtering. It is also possible to perform guide calling after cell filtering mode. #### Command Line Options Standalone cell-filtering mode is enabled using the option: * `--single-cell-enable-cell-filter=true` The input raw matrix files must also be provided using the following options: * `--single-cell-filter-input-directory=` * `--single-cell-filter-input-prefix=` The input raw matrix files must have the following form: * `/.scRNA.barcodes.tsv.gz` * `/.scRNA.features.tsv.gz` * `/.scRNA.matrix.mtx.gz` The existing cell-filtering and guide calling options can be used with standalone cell=filtering mode. It is recommended to set the `--single-cell-number-cells` option so DRAGEN will start with the correct expected number of cells (this can be estimated as the total number of barcodes in the barcodes.tsv file). Example command line for standalone cell-filtering mode: ```bash dragen \ --ref-dir= \ --annotation-file= \ --output-directory= \ --output-file-prefix= \ --single-cell-enable-cell-filter=true \ --single-cell-input-directory= \ --single-cell-input-prefix= \ --single-cell-threshold=fixed \ --single-cell-number-cells=20000 \ ``` Example command line for standalone cell-filtering mode with guide calling: ```bash dragen \ --ref-dir= \ --annotation-file= \ --output-directory= \ --output-file-prefix= \ --single-cell-enable-cell-filter=true \ --single-cell-input-directory= \ --single-cell-input-prefix= \ --single-cell-threshold=fixed \ --single-cell-number-cells=20000 \ --scrna-direct-capture-barcode-reference= \ --scrna-guide-calling-mode=gmm \ ``` ## Fractional Downsampling DRAGEN supports fractional downsampling with PIPseq mode. Fractional downsampling refers to downsampling the input reads are a specified rate. Downsampling is performed randomly on all input reads. Fractional downsampling is enabled with the following options: * `--enable-fractional-down-sampler=true` * `--down-sampler-normal-subsample=` Set the down\_sampling\_rate equal to the desired fraction of reads to keep. For example, a rate of 70% means that 30% of the input reads will be filtered out. More information on DRAGEN fractional downsampling can be found on [this page](/dragen-v4.6/product-guides/dragen-v4.6/dragen-dna-pipeline/downsampling/fractional-downsampler.md). ## Demultiplexing DRAGEN supports different methods of demultiplexing samples. Genotype demultiplexing can be used if a VCF containing variants differentiating the samples of interest is available. Tumor-normal demultiplexing can be used to distinguish between tumor and non-tumor cells. Cell hashing can be used if the samples contain distinguishing oligo-tags (typically in read R2). ### Genotype Demultiplexing Genotype demultiplexing refers to using single nucleotide variants (SNVs) in the samples to differentiate them. A VCF file must be provided with those variants to use genotype demultiplexing. With genotype demultiplexing, DRAGEN assigns sample identity to cells based on the alleles observed in reads in each cell - only SNVs are considered. DRAGEN flags any doublets, such as droplets that contain multiple cells from different individuals. DRAGEN supports two flavors of genotype demultiplexing. *Genotype-based* sample demultiplexing should be used if the VCF file matches the samples in the data set provided to DRAGEN (e.g. if the VCF was generated from matched DNA samples for the same individual). *Genotype-free* sample demultiplexing should be used if the VCF file is derived from a background population corresponding to the samples in the data set - the VCF is not expected to directly match the samples but the variant genotypes in the VCF should appear in the samples at some frequency. #### Command Line Options Genotype-based sample demultiplexing is enabled with the option: * `--scrna-demux-sample-vcf=` - the VCF file should contain the genotypes corresponding to the exact samples provided to DRAGEN. Note: the number of samples for DRAGEN to report is automatically detected from the number of SAMPLE fields in the VCF. Genotype-free sample demultiplexing is enabled with the options: * `--scrna-demux-reference-vcf=` - the VCF file should contain genotypes for the background population from which the samples originated (they do not have to match the samples exactly) * `--scrna-demux-number-samples=` — The number of samples to be detected by DRAGEN. DRAGEN will demultiplex the dataset into this many samples. Additional options: * `--scrna-demux-detect-doublets=` — Enable doublet detection for demultiplexing (set to `true` by default). Example command line for genotype-based sample demultiplexing: ```bash dragen \ --fastq-list= \ --ref-dir= \ --annotation-file= \ --output-directory= \ --output-file-prefix= \ --scrna-enable-pipseq-mode=true \ --scrna-demux-sample-vcf= ``` Example command line for genotype-free sample demultiplexing: ```bash dragen \ --fastq-list= \ --ref-dir= \ --annotation-file= \ --output-directory= \ --output-file-prefix= \ --scrna-enable-pipseq-mode=true \ --scrna-demux-reference-vcf= \ --scrna-demux-number-samples=4 \ --scrna-demux-detect-doublets=false ``` #### Outputs When genotype demultiplexing (demux) is enabled, additional outputs are produced by DRAGEN. Additional columns are added to the barcode summary file and two new files are genereated: a demux TSV file with the number of reads and SNPs used to demultiplex each barcode and a demux metrics file with some summary metrics for the demultiplexed samples. The `.scRNA.barcodeSummary.tsv` file contains the per-cell, barcode summary metrics. When demultiplexing is enabled, this file will have these additional columns describing the sample each barcode is assigned to. See the [Barcode Summary File](#barcode-summary-file) section for more information on the `.scRNA.barcodeSummary.tsv` metrics. | Column | Description | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SampleIdentity` |

The SampleIdentity column will contain one of the following values:

  • sampleX—The particular barcode is uniquely assigned to a sample.
  • AMB(sampleX,sampleY)—The algorithm cannot determine the sample to assign the barcode to.
  • MIX(mixing\_coef*sampleX+(100-mixing\_coef)*sampleY)—The cell barcode is classified as a doublet of sampleX and sampleY. For example, MIX(50*sampleX+50*sampleY).
| | `IdentityQscore` | The IdentityQscore column contains the value used to estimate the confidence of the sample-identity call. After DRAGEN determines the doublet status of the cell as `singlet`, `ambiguous`, or `doublet`, the identity Q-score is defined as -10 \* log10(Probability that the assigned identity is correct, given the second most likely identity and the doublet status). Higher values for the identity Q-score correspond to more confident sample-identity calls. | The `.scRNA.demux.tsv` file contains sample-demultiplexing statistics that were used to infer the sample identity of each cell barcode. | Column | Description | | -------------------------- | -------------------------------------------------------------------------------------------------------------------- | | `Barcode` | The cell barcode associated with the cell. | | `DemuxSNPCount` | The number of SNPs that the reads of the cell barcode intersect. | | `DemuxReadCount` | The number of reads of the cell barcode that intersect at least one SNP. | | `Pure samples` | Samples from the VCF file. | | `BestMixtureIdentity` | Mixture sample with the highest log likelihood. Only available if `--single-cell-demux-detect-doublets=true` is set. | | `BestMixtureLogLikelihood` | The log likelihood of the best mixture sample. Only available if `--single-cell-demux-detect-doublets=true` is set. | The `.scRNA.demuxSamples_metrics.csv` file contains per-sample metrics for each demultiplexed sample, similar to the metrics reported for the overall dataset in `.scRNA_metrics.csv`. | Column | Description | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Passing cells` | The number of cells called (i.e. the number of barcodes that passed the filter threshold). | | `Fraction genic reads in cells` | The fraction of reads assigned to passing cells that are genic reads i.e. matching to genes, calculated as total counted gene reads in passing cells over total gene reads in passing cells. Genic reads correspond to counted gene reads which include exon-matching, intron-matching, and mitochondrial reads. | | `Median reads per cell` | The median number of reads per passing cell based on sorting the passing cells by read count. | | `Median molecules per cell` | The median number of molecules per passing cell based on sorting the passing cells by molecule count. | | `Median genes per cell` | The median number of genes per passing cell based on sorting the passing cells by gene count. | | `Total genes detected` | The total number of unique genes detected in the passing cells (i.e. the number of genes with at least one molecule in at least one passing cell). | #### Sample-Specific FASTQ Output Files If you have enabled either of the sample demultiplexing algorithms, you can output sample-specific FASTQ files after the sample identities for each cell is available using the command line option `--scrna-demux-sample-fastq`. If `gzip` is specified, then the sample-specific output FASTQ files are compressed in gzip format. If `fastq` is specified, then the sample-specific FASTQ files are not compressed. The default option is `none`, which indicates that no sample-specific FASTQ files are produced. ### Tumor/non-tumor Cell Demultiplexing In addition to cell demultiplexing based on sample or population genotypes, there is an additional option to calculate read likelihoods for all scRNA reads conditioned on a given list of SNVs. The SNVs are specified by providing a somatic VCF (typically from a DNA WES tumor-normal somatic VC output). Note that the input VCF is "trusted" completely (ignoring variant call quality). The read-likelihoods are combined at the cell level and used to classify cells as tumor or non-tumor. #### Command-Line Options * `--scrna-demux-tumor-normal-vcf` — A tumor-normal somatic variant call VCF that has tumor and normal sample columns. It is recommended for the VCF to have more than \~100 confident SNVs but that threshold may vary based on the coverage of the scRNA data. Having too few somatic variants runs the risk of not having enough scRNA reads intersecting the SNVs, leading to most cells being unclassified due to insufficient information. * `--scrna-demux-tn-threshold` — The log-likelihood ratio threshold for classifying a cell as tumor or non-tumor. The default value is set to 2.0, but we recommend user to test control samples (e.g. high and low tumor-fraction samples) to find an optimal threshold tailored to their experimental design and sample type. Example DRAGEN Single Cell RNA command line using genotype-based demultiplexing: ```bash dragen \ --fastq-list= \ --ref-dir= \ --annotation-file= \ --output-directory= \ --output-file-prefix= \ --enable-rna=true \ --enable-single-cell-rna=true \ --umi-source=read1 \ --scrna-barcode-position= \ --scrna-umi-position= \ --scrna-barcode-sequence-list= \ --scrna-demux-detect-doublets=false \ --scrna-demux-tumor-normal-vcf= \ --scrna-demux-tn-threshold=2 ``` #### Outputs The output for tumor/non-tumor scRNA cell demultiplexing can be found in the following three files. The `.scRNA.barcodeSummary.tsv` file contains per-cell metrics, including cell barcodes. The following columns contain information on demultiplexing per-cell. See [Barcode Summary File](#barcode-summary-file) for more information on the `.scRNA.barcodeSummary.tsv` metrics. | Column | Description | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SampleIdentity` |

The SampleIdentity column can contain the following values::

  • SNG:TUMOR' or 'SNG:NORMAL—The particular cell (barcode) is uniquely classified as a tumor or non-tumor cell, respectively.
  • AMB(NORMAL,TUMOR)—The algorithm has found variant-supporting reads, but the likelihoods of the cell being tumor or non-tumor are the same, and therefore an ambiguous call is made.
  • NA—The cell barcode has no variant-supporting reads, so there is not enough information to make a classification.
| | `IdentityQscore` | The IdentityQscore column contains the value used to estimate the confidence of the sample identity call. After DRAGEN determines the identity of the cell, the identity Q-score is defined as -10 \* log10(probability of the most likely identity / (probability of the most likely identity + probability of the secound most likely identity)). Higher values of identity Q-score correspond to more confident sample identity calls. | The `.scRNA.demux.tsv` file contains demultiplexing statistics that are used to infer the identity of each cell. Only cells in which variant-supporting reads are found are recorded in this file. | Column | Description | | ---------------- | -------------------------------------------------------------------------- | | `Barcode` | The cell barcode associated with the cell. | | `DemuxSNPCount` | The number of variants that the reads of the cell barcode intersect. | | `DemuxReadCount` | The number of MIs of the cell barcode that intersect at least one variant. | | `NORMAL` | The log-likelihood of the cell being non-tumor | | `TUMOR` | The log-likelihood of a cell being tumor. | The `.scRNA.demuxSamples_metrics.csv` file contains per-cell metrics, similar to the metrics reported for the overall dataset in `.scRNA_metrics.csv`. Ambiguous calls, i.e. 'AMB(NORMAL,TUMOR)', are excluded from the calculation. | Column | Description | | ------------------------------- | ---------------------------------------------------------------------------- | | `Passing cells` | The number of cell barcodes that are PASS. | | `Fraction genic reads in cells` | Fraction of gene-coding reads assigned to PASS cells. | | `Median reads per cell` | Median count of reads per cell that passed the filters. | | `Median molecules per cell` | Median count of MIs per cell that passed the filters. | | `Median genes per cell` | Median count of genes with at least one MI per cell that passed the filters. | ### Cell-Hashing Cell-hashing refers to using oligo-tags usually in read R2 sequences to demultiplex samples. A cell-hashing reference file is required to match those oligo-tags to the corresponding samples. DRAGEN will match each R2 sequence against the cell-hashing reference sequences to determine the sample identity of each barcode. DRAGEN flags any doublets, such as droplets that contain multiple cells from different individuals. The cell-hashing reference file should be a FASTA or CSV file and is specified with the option `--scrna-cell-hashing-reference=`. The format of the file is similar to that required for feature counting (see [Feature Counting](#feature-counting)). If the cell-hashing reference file is provided in FASTA format, then the sample names should be provided in the header and the oligo-tag reference sequences should be provided as the sequence. If the cell-hashing reference file is provided in CSV format, the following fields should be included: * `id` — Sample identifier * `name` — Sample name * `read` — Read that the oligo-tag sequence is on (R1 or R2) * `position` — Starting position of the oligo-tag reference sequence relative to the start of the R1 or R2 sequence (should be >= 0) * `sequence` — DNA sequence of the sample-specific oligo. For example, CAGCCCGATTAAGGT. * `type` — Type of feature (e.g. Cell Hashing) Read groups (RGID) for FASTQ files that contain cell hashing oligos should be specified with the option `--scrna-hto-barcode-groups=`. #### Command Line Options Cell-hashing is enabled with the options: * `--scrna-cell-hashing-reference=` - the FASTA or CSV file with the sample-specific oligo-tags. * `--scrna-hto-barcode-groups=` - the RGIDs of the FASTQ files containing cell hashing reads. Additionally, doublet detection can be enabled/disabled with the following option: * `--scrna-demux-detect-doublets=` — Enable/disable doublet detection for cell-hashing sample demultiplexing (set to `true` by default). Example command line for cell-hashing: ```bash dragen \ --fastq-list= \ --ref-dir= \ --annotation-file= \ --output-directory= \ --output-file-prefix= \ --scrna-enable-pipseq-mode=true \ --scrna-cell-hashing-reference= \ --scrna-hto-barcode-groups= ``` #### Outputs When cell-hashing sample demultiplexing (demux) is enabled, additional outputs are produced by DRAGEN. An additional column is added to the barcode summary file and two new files are genereated: a demux TSV file with the number of reads used to demultiplex each barcode and a demux metrics file with some summary metrics for the demultiplexed samples. The `.scRNA.barcodeSummary.tsv` file contains the per-cell, barcode summary metrics. When demultiplexing is enabled, this file will have an additional column describing the sample each barcode is assigned to. See the [Barcode Summary File](#barcode-summary-file) section for more information on the `.scRNA.barcodeSummary.tsv` metrics. | Column | Description | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SampleIdentity` |

The SampleIdentity column will contain one of the following values:

  • sampleX—The particular barcode is uniquely assigned to a sample.
  • AMB(sampleX,sampleY)—The algorithm cannot determine the sample to assign the barcode to.
  • MIX(mixing\_coef*sampleX+(100-mixing\_coef)*sampleY)—The cell barcode is classified as a doublet of sampleX and sampleY. For example, MIX(50*sampleX+50*sampleY).
| The `.scRNA.demux.tsv` file contains sample-demultiplexing statistics that were used to infer the sample identity of each cell barcode. | Column | Description | | ---------------- | ------------------------------------------ | | `Barcode` | The cell barcode associated with the cell. | | `DemuxReadCount` | Cell-hashing read count for each sample. | The `.scRNA.demuxSamples_metrics.csv` file contains per-sample metrics for each demultiplexed sample, similar to the metrics reported for the overall dataset in `.scRNA_metrics.csv`. | Column | Description | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Passing cells` | The number of cells called (i.e. the number of barcodes that passed the filter threshold). | | `Fraction genic reads in cells` | The fraction of reads assigned to passing cells that are genic reads i.e. matching to genes, calculated as total counted gene reads in passing cells over total gene reads in passing cells. Genic reads correspond to counted gene reads which include exon-matching, intron-matching, and mitochondrial reads. | | `Median reads per cell` | The median number of reads per passing cell based on sorting the passing cells by read count. | | `Median molecules per cell` | The median number of molecules per passing cell based on sorting the passing cells by molecule count. | | `Median genes per cell` | The median number of genes per passing cell based on sorting the passing cells by gene count. | | `Total genes detected` | The total number of unique genes detected in the passing cells (i.e. the number of genes with at least one molecule in at least one passing cell). | ## Splice Junction Counting Splice junction counts can be included to the counts matrix output by setting `--scrna-count-splice-junctions=true`. *Important notes* * Only annotated splice junctions present in the input GTF file are included * Each splice junction appears as a feature with their corresponding deduplicated counts for each cell * Splice junction entries will have the same coordinates appearing as the feature ID and the feature name in the features.tsv file with the feature type "Splice Junction": Example splice junction features: ![](https://400428970-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS6tWlZO1JqcbWYgnhR2X%2Fuploads%2Fgit-blob-ec436477fc48787b53277302b32f8755d2da1da3%2Fsplice_junction_example.png?alt=media) Separate splice junction matrix files will be produced if the following option is enabled: `--scrna-output-split-matrices=true` * `.scRNA.sj_matrix.barcodes.tsv.gz` * `.scRNA.sj_matrix.features.tsv.gz` * `.scRNA.sj_matrix.matrix.mtx.gz` ## STAR Aligner To add optional compatibility with legacy PIPseq workflows, we have included Spliced Transcripts Alignment to a Reference (STAR) as an alternative to the default hardware-accelerated DRAGEN mapper. STAR is an open-source RNA-sequence read mapper, with support for splice-junction and fusion read detection. For further information on STAR mapper: * [Public GitHub page for STAR](https://github.com/alexdobin/STAR) * [User manual for STAR](https://github.com/alexdobin/STAR/blob/master/doc/STARmanual.pdf) While STAR may be run as an independent executable, running STAR as an internal feature from DRAGEN offers simpler and seamless functionality within the scRNA pipeline. *Important notes:* * To run STAR, the Single Cell RNA pipeline must be enabled with either `--enable-single-cell-rna true` or `--scrna-enable-pipseq-mode true`. * STAR uses its own format for reference genome hash tables. This format is both different and incompatible with DRAGEN's reference. When using STAR, both a DRAGEN and a STAR reference must be supplied, and these references must be built from identical whole-genome FASTA files and annotations. If STAR and DRAGEN are given references built from different files, undefined behavior may result. * When running STAR mapper, the following intermediate files will be created: * If a FASTQ list is provided as input and barcode/BI sequences are contained in read R1, then an additional barcode/BI merged FASTQ file will be created with the following name: `.umi_merged.rg_.fastq`. An intermediate FASTQ file will be created for each read group provided. * A BAM file with the name: `.star_mapper.Aligned.out.bam`. This is the output BAM record containing all mapped reads. The following are options for configuring STAR within DRAGEN: * `--single-cell-enable-star-mapper` -- ("true" or "false") Enable STAR and use it for mapping in lieu of the DRAGEN mapper. * `--single-cell-star-mapper-build-reference` -- ("true" or "false") Enable STAR and use it for building STAR-formatted reference genome hash tables. STAR may build a reference and map reads from the same command line. STAR cannot use a DRAGEN-formatted reference. * `--single-cell-star-mapper-reference-dir` -- (***required***, string) Users must supply a directory for STAR-formatted reference genome hash tables. If STAR is building a reference, this directory is where the output reference files will be stored. If the STAR mapper runs from a pre-built reference, this directory is where the mapper looks for the reference files. * `--single-cell-star-mapper-path` -- (*optional*, string) Users may input their own path to a STAR executable. If not supplied, DRAGEN uses an internally-supplied STAR executable. * `--single-cell-star-mapper-options` -- (*optional*, string) Users may manually adjust settings for STAR and overwrite the default settings set by DRAGEN. For a complete list of settings for STAR, [please refer to its user manual](https://github.com/alexdobin/STAR/blob/master/doc/STARmanual.pdf) * `--single-cell-compress-intermediate-fastq` -- (*optional*, "true" or "false", default="false") When a FASTQ list is provided as input and barcode/BI sequences are contained in read R1, intermediate FASTQ files are created. This option enables compressing those intermediate FASTQ files with a ".fastq.gz" format. * `--single-cell-num-parallel-fastq-umis` -- (*optional*, integer, default=4) When a FASTQ list is provided as input and barcode/BI sequences are contained in read R1, intermediate FASTQ files are created. This option sets how many parallel FASTQ files are processed simultaneously. Because STAR uses a different map/align algorithm than DRAGEN, there will be some differences in the read-mapping results and thus in the cell and gene counts results as well. When STAR mode is enabled, the following DRAGEN SW trimmer options are automatically set and DRAGEN will trim the reads before passing them to STAR: * `--trim-adapter-r1-5prime=star_adapters.fasta` - trims the TSO adapter (AGAGTGAATGGG) and Smart PCR adapter (TCAACGCAGAGT) sequences * `--trim-adapter-read1=star_homopolymer_trim.fasta` - trims polyA (AAAAAAAAAAAA) and polyG (GGGGGGGGGGGG) sequences The following STAR options can be added (using the `--single-cell-star-mapper-options` argument) to further align STAR's output to DRAGEN's: * `--alignIntronMax 25000` - limit the maximum intron size to 25,000 bp * `--clip5pNbases 1` - clip one base from the 5' end of read 2 * `--clip3pAdapterSeq polyA` - trim poly-A sequences from 3' end of read 2 ## Command-line Examples Using STAR Example command line for running the STAR mapper with DRAGEN single cell for Illumina Single Cell Prep. ```bash dragen \ --ref-dir=$DRAGEN_REFERENCE \ --annotation-file $REFERENCE_ANNOTATIONS_GTF \ --output-directory $OUTPUT_DIR \ --output-file-prefix $EXPERIMENT_PREFIX \ --fastq-file1 $FASTQ1_FILE \ --umi-source fastq \ --scrna-enable-pipseq-mode true \ --single-cell-enable-star-mapper true \ --single-cell-star-mapper-reference-dir $STAR_REFERENCE ``` Example command line for running the STAR mapper from a FASTQ list CSV with two non-default settings for STAR. ```bash dragen \ --ref-dir=$DRAGEN_REFERENCE \ --annotation-file $REFERENCE_ANNOTATIONS_GTF \ --output-directory $OUTPUT_DIR \ --output-file-prefix $EXPERIMENT_PREFIX \ --fastq-list $FASTQ_CSV_FILE \ --umi-source read1 \ --scrna-enable-pipseq-mode true \ --single-cell-enable-star-mapper true \ --single-cell-star-mapper-reference-dir $STAR_REFERENCE \ --single-cell-star-mapper-options "--alignIntronMax 25000 --clip5pNbases 1" ``` Example command line for creating a STAR reference and running the STAR mapper with DRAGEN single cell for Illumina Single Cell Prep. *Note:* STAR requires an uncompressed annotations file. ```bash dragen \ --ref-dir=$DRAGEN_REFERENCE \ --annotation-file $REFERENCE_ANNOTATIONS_GTF_UNZIPPED \ --ht-reference $REFERENCE_FASTA \ --output-directory $OUTPUT_DIR \ --output-file-prefix $EXPERIMENT_PREFIX \ --fastq-file1 $FASTQ1_FILE \ --fastq-file2 $FASTQ2_FILE \ --umi-source read1 \ --scrna-enable-pipseq-mode true \ --single-cell-star-mapper-build-reference true \ --single-cell-enable-star-mapper true \ --single-cell-star-mapper-reference-dir $STAR_REFERENCE ``` ## Tertiary Analysis We recommend using [Illumina Connected Multiomics](https://help.multiomics.illumina.com/icm) (ICM) for single cell tertiary analysis. [ICM](https://help.multiomics.illumina.com/icm) is a fully-featured tool that allows users to combine and analyze different biological data sets to turn raw samples into published results faster and more easily. ### Loading Count Files to a Dense Matrix Some users might want to explore the output matrix in a human-readable format. There are several tools available including [Illumina Connected Multiomics (ICM)](https://help.multiomics.illumina.com/icm), scanpy, and seurat. To do so, a possible way would be to load the matrix in a "dense" dataframe in Python (similar methodologies can be used in other programming languages). It is important to remember, however, that when possible a "sparse" representation of the matrix is preferable, due to the significant usage of memory and disk space of "dense" matrices. Several tools are available to work efficiently with "sparse" representations of single cell matrices (e.g., `scanpy` in Python). The matrix can be converted into a "dense" representation through two Python modules: `scanpy` and `pandas`. This has been tested with Python 3.9.7, scanpy 1.10.3, pandas 2.2.3. First, it is necessary to install the required libraries: ```bash > pip install -U scanpy pandas ``` Within Python, the matrix can be loaded in "dense" representation using the following commands: ```python # import libraries import pandas as pd import scanpy as sc # define output folder and file prefix output_folder = "output/folder" prefix = "sample_id.scRNA." # load matrix through scanpy adata = sc.read_10x_mtx(output_folder, prefix=prefix) # convert scanpy internal format (AnnData) to dense pandas DataFrame df = pd.DataFrame(adata.X.todense(), index=adata.obs_names, columns=adata.var_names) # save it as CSV file df.to_csv("output_matrix.csv") ``` The matrix can be saved through different output formats (e.g., CSV), although this is not recommended due to high disk usage. ## References 1. Fontanez et al., 2024. Intrinsic molecular identifiers enable robust molecular counting in single-cell sequencing. bioRxiv 2024.10.04.616561. 2. Smith, T., Heger, A. and Sudbery, I., 2020. UMI-Tools: Modeling Sequencing Errors In Unique Molecular Identifiers To Improve Quantification Accuracy. \[PDF] Cold Spring Harbor Laboratory Press. Available at: <[https://www.ncbi.nlm.nih.gov/pmc/articles/PMC5340976/>](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC5340976/>) \[Accessed 15 October 2020]. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.dragen.illumina.com/dragen-v4.6/product-guides/dragen-v4.6/dragen-single-cell-pipeline/dragen-scrna-other.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.