
<LinkableSection id={"background"} title={"Background"}>

`bamtofastq` is a tool for converting 10x Genomics BAM files back into FASTQ files that can be used as inputs to re-run analysis. The FASTQs will be output into a directory structure identical to the `mkfastq` or `bcl2fastq` tools, so they are ready to input into the next pipeline (e.g. `cellranger count`, `spaceranger count`).

10x Genomics pipelines require FASTQs (with embedded barcodes) as input, so we developed `bamtofastq` to help users who want to reanalyze 10x Genomics data but only have access to BAM files. For example, some users may want to store BAM files only. Others might have downloaded our BAM data from NCBI SRA. The location of the 10x Genomics barcode varies depending on product and reagent version. `bamtofastq` determines the appropriate way to construct the original read sequence from the sequences and tags in the BAM file.

`bamtofastq` works with BAM files output by the following 10x Genomics pipelines:

- `cellranger` ([see exceptions below](#issues))
- `cellranger-atac`
- `cellranger-arc`
- `cellranger-dna`
- `spaceranger`
- `longranger`

</LinkableSection>

<LinkableSection id={"download"} title={"Download and installation"}>

`bamtofastq` is available for Linux and is compatible with RedHat/CentOS 5.2 or later, and Ubuntu 8.04 or later.

- `bamtofastq` comes pre-bundled with the latest versions of the Cell Ranger, Cell Ranger ARC, Cell Ranger ATAC, and Space Ranger pipelines. You can find the executable in the `/lib/bin` folder within the installation, e.g. `cellranger-x.y.z/lib/bin/bamtofastq`. Once your pipeline is installed and on your `PATH`, you can run `[pipeline] bamtofastq`, (e.g. `cellranger bamtofastq`, `spaceranger bamtofastq`).
- You can also [download bamtofastq from github](https://github.com/10XGenomics/bamtofastq/releases).

`bamtofastq` is a single executable that can be run directly and requires no compilation or installation. Place the executable file in a directory that is on your `PATH`, and make sure to `chmod 700` to make it executable.

</LinkableSection>

<LinkableSection id={"running"} title={"Running the tool"}>

10x Genomics BAMs produced by Cell Ranger v1.2+, Cell Ranger ATAC v1.0+, Cell Ranger ARC v1.0+, Space Ranger v1.0+, Cell Ranger DNA v1.0+, and Long Ranger v2.1+ contain header fields that permit automatic conversion to the correct FASTQ sequences. BAMs produced by older 10x Genomics pipelines may require special arguments or have some caveats, see [known issues](#issues) for details.

The FASTQ files output by `bamtofastq` contain the same set of sequences that were input to the original pipeline run, although the original order will not be preserved. 10x Genomics pipelines are generally insensitive to the order of the input data, so you can expect nearly identical results when re-running pipelines with `bamtofastq` outputs.

The usage of the `bamtofastq` command is as follows:

```
bamtofastq [options] [bam-path][output-path]
```

Replace `[bam-path]` with the path to the input BAM, `[output-path]` with the path to the output directory, and include any relevant `[options]` ([listed below](#options)). For example, if your BAM file is located at `/path/to/mydata.bam`, you want the output in `/path/to/home/directory`, and you want to use eight threads, the command would be:

```
bamtofastq --nthreads=8 /path/to/mydata.bam /path/to/home/directory
```

You can also print the options from the command line:

```
bamtofastq --help
```

Run times for full-coverage WGS BAMs may be several hours.

</LinkableSection>

<LinkableSection id={"options"} title={"Options"}>

`bamtofastq` options:

| Option                | Description                                                                                                                    |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `--nthreads=n`        | Threads to use for reading BAM file. Default: 4                                                                                |
| `--locus=locus`       | Optional. Only include read pairs mapping to locus. Use `chrom:start-end` format.                                              |
| `--reads-per-fastq=N` | Number of reads per FASTQ chunk. Default: 50000000                                                                             |
| `--gemcode`           | Convert a BAM produced from GemCode data (Longranger 1.0 - 1.3)                                                                |
| `--lr20`              | Convert a BAM produced by Longranger 2.0                                                                                       |
| `--cr11`              | Convert a BAM produced by Cell Ranger 1.0-1.1                                                                                  |
| `--bx-list=L`         | Only include BX values listed in text file `L`. Requires BX-sorted and indexed BAM file (see Long Ranger support for details). |
| `--help`              | Show the help screen                                                                                                           |

</LinkableSection>

<LinkableSection id={"issues"} title={"Known issues and limitations"}>

- BAMs produced for TCR or BCR data, by aligning to a V(D)J reference with `cellranger vdj` or `cellranger multi`, are not supported by `bamtofastq`.
- Special tags included by 10x Genomics pipelines are required to reconstruct the original FASTQ sequences correctly. If your BAM file lacks the appropriate headers, you will get an error message: `WARNING: no @RG (read group) headers found in BAM file.`
- A common problem is using **edited** BAM files from SRA that are missing tags produced by Cell Ranger.
- You need the BAM file from the section labeled **Original Format** on the SRA downloads page.
- Here is an example of a [SRA dataset with the **Original Format** BAM available](https://trace.ncbi.nlm.nih.gov/Traces/sra/?run=SRR7276476).
- Only the **Original Format** BAM files have the necessary BAM tags preserved to work correctly with `bamtofastq`.
- The latest versions of `cellranger`, `cellranger-atac`, `cellranger-arc`, `cellranger-dna`, and `longranger` generate BAM files that automatically reconstruct complete FASTQ files representing all input reads. BAMs produced by older versions of `cellranger` and `longranger` have some caveats, listed below:

| Package          | Version       | Pipelines                   | Extra Arguments | Complete FASTQs                                                                                                           |
| ---------------- | ------------- | --------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Cell Ranger      | 1.3+          | count                       | none            | Yes                                                                                                                       |
| Cell Ranger      | 1.2           | count                       | none            | Reads without a valid barcode will be absent from FASTQ. (These reads are ignored by Cell Ranger)                         |
| Cell Ranger      | 1.0-1.1       | count                       | `--cr11`        | Reads without a valid barcode will be absent from FASTQ. (These reads are ignored by Cell Ranger)                         |
| Cell Ranger ARC  | 1.0.0+        | count                       | none            | Any sequenced bases in the i5 index read that are not part of the 10x Genomics barcode are dropped from the FASTQ output. |
| Cell Ranger ATAC | 1.0.0+        | count                       | none            | Any sequenced bases in the i5 index read that are not part of the 10x Genomics barcode are dropped from the FASTQ output. |
| Cell Ranger DNA  | 1.0.0+        | cnv                         | none            | Yes                                                                                                                       |
| Long Ranger      | 2.1.3+        | wgs, targeted, align, basic | none            | Yes                                                                                                                       |
| Long Ranger      | 2.1.0 - 2.1.2 | wgs, targeted               | none            | Yes                                                                                                                       |
| Long Ranger      | 2.0           | wgs, targeted               | `--lr20`        | Yes                                                                                                                       |
| Long Ranger      | 2.0.0 - 2.1.2 | align, basic                | Not Supported   | N/A                                                                                                                       |
| Long Ranger      | 1.3 (GemCode) | wgs, targeted               | `--gemcode`     | Reads without a valid barcode will be absent from FASTQ. This will result in a ~5-10% loss of coverage.                   |

</LinkableSection>


Converting 10x Genomics BAM Files to FASTQ


<LinkableSection id={"guide"} title={"Citation guidelines"}>

To cite 10x Genomics datasets, User Guides, Demonstrated Protocols, Technical Notes, Application Notes, or 10x Genomics software, use the following formats:

### **Datasets**

_PBMCs from C57BL/6 mice (v1, 150x150)_, Single Cell Immune Profiling Dataset by Cell Ranger v3.1.0, 10x Genomics, (2019, July 24).

### **User Guides/Demonstrated Protocols**

_Chromium Single Cell V(D)J Reagent Kits with Feature Barcoding technology for Cell Surface Protein_, Document Number CG000186 Rev A, 10x Genomics, (2019, July 25).

Document and Revision Numbers (e.g., CG000186 Rev A) are located on the cover page in User Guides and Technical Notes. Other literature lists the part number in the copyright note at the bottom of the last page.

### **Technical Notes/Application Notes**

_Technical Note – Resolving Cell Types as a Function of Read Depth and Cell Number_, Document Number CG000148, 10x Genomics, (2019, April 30).

### **10x Genomics software**

Use the following format when citing 10x Genomics software:

- 10x Genomics Software Name and Version x.y.z

For example:

- 10x Genomics Cell Ranger v7.1.0
- 10x Genomics Space Ranger v3.0.0
- 10x Genomics Loupe Browser v8.0.0

**Note**: When citing software, be sure to specify the relevant software version number.

### **10x Genomics Cloud Analysis**

To cite datasets generated in 10x Genomics Cloud Analysis, use the following format:

- 10x Genomics Software Name and Version x.y.z using 10x Genomics Cloud Analysis

For example:

- 10x Genomics Cell Ranger v5.0.1 using 10x Genomics Cloud Analysis
- 10x Genomics Cell Ranger v4.0.0 using 10x Genomics Cloud Analysis

### **Citations for 10x Genomics publications**

#### Cell Ranger

Zheng, G. X. Y. et al. (2017). Massively parallel digital transcriptional profiling of single cells. _Nature Communications_ **8**: 1-12, [doi:10.1038/ncomms14049](https://doi.org/doi:10.1038/ncomms14049)

#### Cell Ranger ATAC

Satpathy, A. T. et al. (2019). Massively parallel single-cell chromatin landscapes of human immune cell development and intratumoral T cell exhaustion. _Nature Biotechnology_ **37**: 925-936, [doi:10.1038/s41587-019-0206-z](https://doi.org/10.1038/s41587-019-0206-z)

#### Xenium Onboard Analysis / Xenium Explorer

Janesick, A. et al. (2023). High resolution mapping of the tumor microenvironment using integrated single-cell, spatial and in situ analysis. _Nature Communications_ **14**: 8353, [doi:10.1038/s41467-023-43458-x](https://doi.org/10.1038/s41467-023-43458-x)

#### Supernova

Weisenfeld, N. L. et al. (2017). Direct determination of diploid genome sequences. _Genome Research_ **27**: 757-767, [doi:10.1101/gr.214874.116](https://doi.org/10.1101/gr.214874.116)

#### Long Ranger

Marks, P. et al. (2019). Resolving the full spectrum of human genome variation using Linked-Reads. _Genome Research_ **29**: 635-645, [doi:10.1101/gr.234443.118](https://doi.org/10.1101/gr.234443.118)

</LinkableSection>

<LinkableSection id={"trademark-use"} title={"Use of 10x Genomics trademarks and images"}>

No trademark ™ or registered trademark ® symbol is required when solely using the name of 10x Genomics or any of its products in a citation. However, for any other use of 10x Genomics’ [trademarks](/legal/legal-notices#trademarks), logos, graphics, figures, or other images, you must obtain prior written permission and follow all guidelines from 10x Genomics for such use, unless otherwise permitted by copyright and trademark law. To seek permission, please send a copy of your proposed use to copyright@10xgenomics.com.

</LinkableSection>


10x Genomics Citations


<LinkableSection id={"background"} title={"Background"}>

`index-hopping-filter` is a tool that filters index-hopped reads from a set of demultiplexed samples. The tool detects and removes likely index hopped reads from demultiplexed FASTQs, and in turn emits new, filtered, FASTQs with similar file and directory layout as the inputs, suitable for use with `cellranger count` and `cellranger vdj`.

Note: Currently `index-hopping-filter` only supports samples produced by 3' Single Cell Gene Expression, 5' Single Cell Immune Profiling, Flex, and Single Cell ATAC solutions. It cannot be used on Spatial Gene Expression samples.

Index hopping is a known phenotype that can impact any pooled samples sequenced on Illumina platforms utilizing both patterned flow cells and exclusion amplification chemistry (i.e. HiSeqX, HiSeq3000/4000, NovaSeq).

Below is some literature from Illumina outlining the background behind index hopping:

- [Effects of Index Misassignment on Multiplexing and Downstream Analysis](https://www.illumina.com/content/dam/illumina-marketing/documents/products/whitepapers/index-hopping-white-paper-770-2017-004.pdf)
- [Minimize index hopping in multiplexed runs](https://www.illumina.com/science/education/minimizing-index-hopping.html)

To reduce and filter hopped sample indexes, we recommend the following library preparation best practices for any indexed sequencing library:

- Remove free adapters from library preps
- Ensure no sign of leftover primers or adaptors are present when performing post Library Construction QC (BioAnalyzer/TapeStation/Fragment Analyzer)
- Only pool libraries before sequencing
- A final 1.0X SPRI can be performed on these pooled libraries to remove any traces of free adaptors
- Use Unique Dual Indexes vs. Single indexed libraries or Combinatorial Dual Indexes - Unique Dual Indexes will be available for Single Cell Gene Expression, Single Cell Immune Profiling, and Spatial Gene Expression Products. Visium - Q4 2019, SC GEX and IP with full software support - mid 2020

10x created `index-hopping-filter` to reduce the number of index-hopped reads reaching downstream analysis. It detects, from whole flow cells, duplicate library molecules appearing in more than one sample. Reads determined to be so duplicated are removed. A sample where the molecule is present with a high read count indicates the molecule is from that sample, and reads of that molecule are not removed.

Some index hopped library molecules are only observed in incorrect samples and thus cannot be detected as index hopped. For this reason, the tool mitigates but cannot eliminate all index hopped reads. In our testing, using samples sequenced to the recommended sequencing reads per cell, `index-hopping-filter` removes >70% of index hopped reads compared to a dual-indexed ground truth. At lower sequencing depths, or if less than all samples from a flow cell are used, a smaller fraction of index hopped reads will be detected. The following graph depicts the sensitivity (over a whole flow cell) of `index-hopping-filter` to reads from invading barcodes compared to a dual-indexed dataset as a function of sequencing depth.

<Flex justifyContent={"center"}>
<Image src={"https://cdn.10xgenomics.com/image/upload/v1689029709/software-support/Cell%20Ranger/ihf-inv-sens.png"} width={"400px"} length={"400px"} />
</Flex>

</LinkableSection>

<LinkableSection id={"download"} title={"Download and installation"}>

`index-hopping-filter` is available for Linux and is compatible with Redhat/CentOS 5.2 or later, and Ubuntu 8.04 or later.

[Download index-hopping-filter v1.1](https://github.com/10XGenomics/index_hopping_filter/releases/download/v1.1.0/index-hopping-filter)

`index-hopping-filter` is a single executable that can be run directly and requires no compilation or installation. Place the executable in a directory on your `PATH` and make sure to `chmod 700` to make it executable.

</LinkableSection>

<LinkableSection id={"run-tool"} title={"Running the tool"}>

The `mkfastq` subcommand of `cellranger` produces FASTQ files directly usable by `index-hopping-filter`. If you have configured the IEM SampleSheet.csv or `cellranger mkfastq` simple CSV to uniquely identify distinct 10x libraries, then you can use the `cellranger mkfastq` output directory as input to `index-hopping-filter filter`.

</LinkableSection>

<LinkableSection id={"inputs"} title={"Inputs"}>

#### Inputs of `index-hopping-filter` (10x Single Cell Gene Expression or Immune Profiling)

`index-hopping-filter`’s two subcommands both accept as input either a `cellranger mkfastq` output path or an `index-hopping-filter` configuration CSV. This CSV file must conform to the following schema, where `SampleId` must be an integer in the range `[0, 65534]`.

| R1                             | R2                             | SampleId |
| ------------------------------ | ------------------------------ | -------- |
| `/path/to/sample1/R1.fastq.gz` | `/path/to/sample1/R2.fastq.gz` | 1        |
| `/path/to/sample2/R1.fastq.gz` | `/path/to/sample2/R2.fastq.gz` | 2        |

#### Inputs of `index-hopping-filter` (10x Single Cell ATAC)

`index-hopping-filter`’s two subcommands both accept as input either a `cellranger mkfastq` output path or an `index-hopping-filter` configuration CSV. This CSV file must conform to the following schema, where `SampleId` must be an integer in the range `[0, 65534]`. Compared to the configuration CSV for 10x Single Cell Gene Expression or Immune Profiling solutions, this configuration CSV requires an additional `R3` column, and the `--atac` flag must be provided to the subcommand.

| R1                             | R2                             | R3                             | SampleId |
| ------------------------------ | ------------------------------ | ------------------------------ | -------- |
| `/path/to/sample1/R1.fastq.gz` | `/path/to/sample1/R2.fastq.gz` | `/path/to/sample1/R3.fastq.gz` | 1        |
| `/path/to/sample2/R1.fastq.gz` | `/path/to/sample2/R2.fastq.gz` | `/path/to/sample2/R3.fastq.gz` | 2        |

</LinkableSection>

<LinkableSection id={"outputs"} title={"Outputs"}>

#### Outputs of `index-hopping-filter mkcsv`

`index-hopping-filter mkcsv` produces a configuration CSV to `stdout` based on the input. Redirect `stdout` to a file (e.g. `index-hopping-filter mkcsv /path/to/mkfastq/outs 1>config.csv`) and modify it as needed.

#### Outputs of `index-hopping-filter filter`

| Outputs                 | Description                                                                                           |
| ----------------------- | ----------------------------------------------------------------------------------------------------- |
| outs/fastq_path         | Directory containing emitted FASTQs with suspect index hopped reads removed.                          |
| outs/web_summary.html   | An HTML web summary that describes the number and percentage of reads removed per sample.             |
| outs/filtered_reads.csv | A CSV file describing the starting number of reads and the number of reads removed for each SampleId. |
| \_log                   | A log file for diagnostic purposes.                                                                   |

</LinkableSection>

<LinkableSection id={"options"} title={"Options"}>

### index-hopping-filter mkcsv

| Option            | Description                                          |
| ----------------- | ---------------------------------------------------- |
| `-a`, `--atac`    | Generate a configuration csv for 10x scATAC-seq data |
| `-h`, `--help`    | Prints help information                              |
| `-v`, `--version` | Prints version information                           |

### index-hopping-filter filter

| Option             | Description                                                 |
| ------------------ | ----------------------------------------------------------- |
| `-a`, `--atac`     | Provide if you are running 10x scATAC-seq data              |
| `-n`, `--nthreads` | Maximum number of threads to use (default: number of cores) |
| `-h`, `--help`     | Prints help information                                     |
| `-v`, `--version`  | Prints version information                                  |

</LinkableSection>

<LinkableSection id={"issues"} title={"Known issues"}>

### Product compatibility

`index-hopping-filter` currently only works with 10x Single Cell Gene Expression, 10x Single Cell Immune Profiling, and 10x Single Cell ATAC solutions. Future versions may include support for other products.

### Multiple FASTQs from the same GEM wells

Correctly specifying `SampleId` is important. If multiple samples drawn from the same underlying 10x GEM well are passed into `index-hopping-filter` with distinct `SampleIds`, then `index-hopping-filter` will detect many reads as index hopped and remove them. This scenario arises when e.g. sequencing Immune Profiling-enriched libraries alongside the Gene Expression libraries from which they were derived. To avoid these false positive index hopping calls, use `index-hopping-filter mkcsv` to construct an initial configuration CSV, providing the `cellranger mkfastq` output directory as input. Next, modify the CSV to give demultiplexed samples derived from the same 10x GEM well a common `SampleId` value in the CSV.

</LinkableSection>


Mitigating Index Hopped Reads In Silico


<LinkableSection id={"overview"} title={"Overview"}>

Updated: July 22, 2022

In 10x Genomics whole transcriptome Gene Expression data, intronic mapped reads account for 20-40% of the reads. These reads were not counted by default in past versions of Cell Ranger. Recent data has indicated that intronic reads are [usable data](/support/universal-three-prime-gene-expression/documentation/steps/sequencing/interpreting-intronic-and-antisense-reads-in-10-x-genomics-single-cell-gene-expression-data) (they arise from poly-A tracts in the transcripts, and are not generated via priming from genomic DNA). Including intronic reads, for both cellular and nuclei samples, could lead to higher sensitivity (higher UMI counts, more genes per cell) and less wasted sequencing.

This [Technical Note](/support/universal-three-prime-gene-expression/documentation/steps/sequencing/interpreting-single-cell-gene-expression-data-with-and-without-intronic-reads) demonstrates how including intronic reads in Cell Ranger analysis resulted in more usable data and higher sensitivity for Single Cell 3’ and 5’ Gene Expression cellular datasets. In addition, for a Single Cell 3' Gene Expression 10k peripheral blood mononuclear cell (PBMC) dataset, cell type annotation and differential gene expression analyses were comparable with or without intronic reads.

<SupportCallout level={"info"}>
<Text as={"span"}>New in Cell Ranger v7.0: Intronic reads are counted by default for whole transcriptome gene expression data.</Text>
</SupportCallout>
<br />

To empower our customers with higher sensitivity, Cell Ranger **v7.0 and later** include intronic reads **by default** towards UMI counting. Intronic reads can be included manually in your analysis with Cell Ranger **v5.0 - 6.1** with the following options:

- If you are running the [cellranger count pipeline](/support/software/cell-ranger/latest/analysis/running-pipelines/cr-gex-count), you can add the `--include-introns` flag to the command.
- If you are running the `cellranger multi` pipeline for [3' Single Cell Gene Expression products](/support/software/cell-ranger/latest/analysis/running-pipelines/cr-3p-multi) or [5' Single Cell Immune Profiling products](/support/software/cell-ranger/latest/analysis/running-pipelines/cr-5p-multi), you can add `include-introns,true` to the `[gene-expression]` section of Multi Config CSV.

If you have any concerns or questions, please reach out to the 10x Genomics support team at support@10xgenomics.com.

</LinkableSection>

<LinkableSection id={"faq"} title={"Frequently asked questions"}>

- [Why should I include introns for my single cell whole transcriptome gene expression data analysis?](https://kb.10xgenomics.com/hc/en-us/articles/4998628924429)
- [Should I reanalyze my previous single cell data, if I have not included introns before?](https://kb.10xgenomics.com/hc/en-us/articles/4998627635213)
- [Are there any biases introduced by using intronic reads?](https://kb.10xgenomics.com/hc/en-us/articles/4998683531661)
- [I do not want to include intronic reads in my analysis. Can I do that in the upcoming Cell Ranger?](https://kb.10xgenomics.com/hc/en-us/articles/4998749959949)
- [Can I sequence less if I use intronic mode?](https://kb.10xgenomics.com/hc/en-us/articles/4998812429837)
- [Can I aggr data run with and without introns?](https://kb.10xgenomics.com/hc/en-us/articles/4998854073741)
- [Should I include introns for Targeted Gene Expression data analysis?](https://kb.10xgenomics.com/hc/en-us/articles/5078928864909)

</LinkableSection>

<LinkableSection id={"datasets"} title={"Example datasets"}>

- [10k Human PBMCs, 3' v3.1, Chromium X (without intronic reads)](/datasets/10k-human-pbmcs-3-v3-1-chromium-x-without-introns-3-1-high)
- [10k Human PBMCs, 3' v3.1, Chromium X (with intronic reads)](/datasets/10k-human-pbmcs-3-v3-1-chromium-x-with-intronic-reads-3-1-high)
- [20k Mixture of NSCLC DTCs from 7 donors, 3' v3.1 (without intronic reads)](/datasets/20-k-mixture-of-nsclc-dt-cs-from-7-donors-3-v-3-1-3-1-standard-6-1-0)
- [20k Mixture of NSCLC DTCs from 7 donors, 3' v3.1 (with intronic reads)](/datasets/20k-mixture-of-nsclc-dtcs-from-7-donors-3-v3-1-with-intronic-reads-3-1-standard)
- [10k Human PBMCs, 5' v2.0, Chromium X (without intronic reads)](/datasets/10k-human-pbmcs-5-v2-0-chromium-x-without-intronic-reads-2-standard)
- [10k Human PBMCs, 5' v2.0, Chromium X (with intronic reads)](/datasets/10k-human-pbmcs-5-v2-0-chromium-x-with-intronic-reads-2-standard)
- [10k Bone Marrow Mononuclear Cells (BMMNCs), 5' v2.0 (without intronic reads)](/datasets/10k-bone-marrow-mononuclear-cells-bmmncs-5-v2-0-without-intronic-reads-2-standard)
- [10k Bone Marrow Mononuclear Cells (BMMNCs), 5' v2.0 (with intronic reads)](/datasets/10k-bone-marrow-mononuclear-cells-bmmncs-5-v2-0-with-intronic-reads-2-standard)

</LinkableSection>


Recommendation on Including Introns for Gene Expression Analysis


This page describes how authorized customers and partners can quickly and efficiently send large datasets, such as BCL, FASTQ, and BAM files, to 10x Genomics. This approach makes it easy to use multi-stream transfers to ensure optimal and secure utilization of your Internet connection. Redstone uploads to Amazon Web Services S3 which is secured using SSL during transport.

<LinkableSection id={"prep-data"} title={"Prepare your data"}>

**Illumina BCL data**

- Please archive the BCL folder into a single file, **but do not include thumbnail images**.

In the following example, replace the strings with the specifics of your run. `/mnt/runs` should be replaced with the parent folder that contains your Illumina run folders.

```
tar -czvf H3NVFBBXX.tar.gz -C /mnt/runs --exclude=Thumbnail_Images 150929_ST-K00126_0004_AH3NVFBBXX
```

**FASTQ or BAM data**

- If you are sending multiple files, please archive them into a single ZIP or GZipped TAR (`.tgz`) file.

In the following example for a FASTQ directory, replace the strings with the specifics of your run. `/fastq/directory` should be replaced with actual directory that contains your FASTQ files.

```
tar -czvf compressed-fastqs.tar.gz /fastq/directory
```

- If your FASTQ files are already individually compressed (`.gz` extension) then you do not need to compress the entire archive. Similarly, BAM files are already inherently compressed. In this case, simply tar the files together and omit the `z` option to compress.

In the following example for a FASTQ directory, replace the strings with the specifics of your run. `/fastq/directory` should be replaced with actual directory that contains your FASTQ files. The difference here is omitting a 'z' from the tar command.

```
tar -cvf allfastqs.tar /fastq/directory
```

**Imaging data**

- If you are sending multiple files, please archive them into a single ZIP or GZipped TAR (`.tgz`) file.
- Please transfer the bright-field H&E TIFF imaging files for analysis. Images should be one per sample, not slide, and should be named in such a way as to make it clear what sample is in a given image.
- Please send images with the following convention: `<slide_serial_number>-<capture_area>.tif`

```
Example Slide: Lot# V19L22, ID# 001.
The four capture areas (from top to bottom) would be submitted as images named:
V19L22-001-A1.tif
V19L22-001-B1.tif
V19L22-001-C1.tif
V19L22-001-D1.tif
```

**The remaining steps are operating system dependent. Please select the link (right) for your operating system to continue.**

</LinkableSection>

<LinkableSection id={"linux-extra"} title={"Linux"}>

</LinkableSection>

<LinkableSection id={"linux-download-tool"} nested={true} title={"Download the Linux upload tool"}>

10x Genomics provides an easy-to-use multi-stream upload tool called Redstone. If you installed Cell Ranger v4 or higher, the Redstone executable is already located in the Cell Ranger install path `cellranger-x.y.z/lib/bin/redstone` and need not be installed again. You may add this path to your `.bashrc` using `export PATH=/path/to/cellranger-x.y.z/lib/bin:$PATH` or type in the full path on your command prompt to call Redstone.

The download link below is for the Linux version, compatible with RedHat/CentOS 5.2 or later, and Ubuntu 8.04 or later:

- [Download Redstone 2.1.0 For Linux](https://cf.10xgenomics.com/misc/redstone)

**Redstone is a single 9MB executable that can be run directly** and requires no compilation or installation. Place the executable file in a directory that is on your `PATH`. For this Linux version please make sure to `chmod 700` to make it executable.

</LinkableSection>

<LinkableSection id={"linux-upload"} nested={true} title={"Upload your file"}>

Make sure to perform this step from a computer with an unencumbered path to your Internet connection. That means hard-wired 1GbE or 10GbE connections, and not Wi-Fi.

Please also ensure the time/date are set correctly on your system, which is required for security reasons. If your clock is mis-set, you will encounter a `RequestTimeTooSkewed` error.

To run Redstone, just pass it your email address, the email address of the recipient at 10x Genomics, and the name of the file to be uploaded. The entries for email addresses and file name must be customized before running.

```
redstone --from=your@email.edu --to=support@10xgenomics.com H3NVFBBXX.tar.gz
Uploading file...
Size: 10,773,244,733 bytes
50% [=============>            ]  5,386,622,366   376.79Mb/s eta 1m 54s
```

If you are transferring files to Customer Support, please use `--to=support@10xgenomics.com` as the recipient e-mail address.

</LinkableSection>

<LinkableSection id={"mac-extra"} title={"Mac"}>

</LinkableSection>

<LinkableSection id={"mac-download-tool"} nested={true} title={"Download the Mac upload tool"}>

10x Genomics provides an easy-to-use multi-stream upload tool called Redstone. The link below is for the macOS version.

- [Download Redstone 2.1.0 For Mac](https://cf.10xgenomics.com/misc/redstone-mac)

#### Download redstone-mac and open a terminal window

After you click the link to download redstone, the executable will download to your Downloads folder. Right click on the file and select Open. You will likely see this message on a pop-up window:

> macOS cannot verify the developer of “redstone-mac”. Are you sure you want to open it?

Click Open. It is not a .dmg file so the installer will try to open the application in your default text editor. This file is not human-readable so you can close it. However, this step is necessary because it changes how the macOS gatekeeper views the file, from unsafe to safe.

Next, use the terminal program on your Mac to open a terminal window. A window will open with a prompt that looks something like this:

```
user.name@computer:~$
```

#### Make redstone-mac executable

Use the `chmod` command to make the redstone-mac file executable.

```
user.name@computer:~$ chmod 700 Downloads/redstone-mac
```

#### Move redstone-mac to Applications

Move the redstone program to the Applications folder on your computer using the `mv` command.

```
user.name@computer:~$ mv Downloads/redstone-mac /Applications
```

#### Add redstone-mac to the PATH

Next we need to add redstone to your `PATH` using the `export` command. This will allow you to type redstone-mac on the command line to run the program.

```
user.name@computer:~$ export PATH=/Applications:$PATH
```

#### Run redstone-mac to get the usage

Now if you type `redstone-mac` on the command line and push enter it will print the usage statement. The usage statement will contain a pattern for building the command you will use to transfer your data.

```
user.name@computer:~$ redstone-mac
Usage:
    redstone --from=EMAIL --to=EMAIL  [options]
    redstone -h | --help | --version
```

</LinkableSection>

<LinkableSection id={"mac-transfer"} nested={true} title={"Transfer files on Mac"}>

#### Transfer a single file

If you are sending a single file, such as a tissue optimization cDNA footrpint tiff, you would replace file in the usage statement above with a "path" to the file. A "path" is the series of folders that you would go through on your computer to get to the file. A trick that works on macOS is to find the folder you want to send in finder and drag and drop it into the terminal window. If I wanted to send an image downloaded from a shared drive into the Downloads folder, the command would look like this:

```
user.name@computer:~$ redstone-mac --from=your@email.edu --to=support@10xgenomics.com /Users/username/Downloads/V19L22-001-A1.tif
Uploading file...
Size: 10,773,244,733 bytes
 50% [=============>            ]  5,386,622,366   376.79Mb/s eta 1m 54s
```

#### Transfer a compressed directory of files

If you are sending a compressed directory of files, like you would have if you compressed multiple images using the `tar` command described in "Prepare Your Data" above, the final command will have the same structure as sending a single file and may look like this:

```
user.name@computer:~$ redstone-mac --from=your@email.edu --to=support@10xgenomics.com /Users/username/Downloads/H3NVFBBXX.tar.gz
Uploading file...
Size: 10,773,244,733 bytes
 50% [=============>            ]  5,386,622,366   376.79Mb/s eta 1m 54s
```

If you are transferring files to Customer Support, please use `--to=support@10xgenomics.com` as the recipient e-mail address.

</LinkableSection>

<LinkableSection id={"windows-extra"} title={"Windows"}>

</LinkableSection>

<LinkableSection id={"windows-download-tool"} nested={true} title={"Download the Windows upload tool"}>

10x Genomics provides an easy-to-use multi-stream upload tool called Redstone. The link below is for the windows version:

- [Download Redstone 2.1.0 For Windows](https://cf.10xgenomics.com/misc/redstone.exe)

#### Download redstone.exe and open a command prompt window

After you click the link to download redstone, the executable will download to your Downloads folder. Do _NOT_ click on the downloaded file. Installation does not require the windows installer, it will give an error. Instead do the following:

Use the Command Prompt app to open a Command prompt. You can find Command Prompt by searching for it in the start menu search bar. A window will open with a prompt that looks something like this:

```
C:\Users\username>
```

#### Run redstone-exe from the command prompt to get the usage statement

Now if you type `downloads\redstone.exe` on the command line and push enter it will print the usage statement. The usage statement will contain a pattern for building the command you will use to transfer your data.

```
C:\Users\username> Downloads\redstone.exe
Usage:
    redstone --from=EMAIL --to=EMAIL  [options]
    redstone -h | --help | --version
```

</LinkableSection>

<LinkableSection id={"windows-transfer"} nested={true} title={"Transfer files on Windows"}>

#### Transfer a Single File

To transfer a file the first step is to change directories to the directory that contains the file you want to transfer using the `cd` command. If the file is in the Downloads directory the cd command would look like this:

```
C:\Users\username> cd \Users\username\Downloads
```

The `redstone.exe` command would then start with a path to the Redstone executable followed by the `--to=` and `--from=` email addresses and ending with the name of the file that you want to transfer. The command would look like this:

```
C:\Users\username> \Users\username\Downloads\redstone.exe --from=your@email.edu --to=support@10xgenomics.com V19L22-001-A1.tif
Uploading file...
Size: 10,773,244,733 bytes
 50% [=============>            ]  5,386,622,366   376.79Mb/s eta 1m 54s
```

If you are transferring files to Customer Support, please use `--to=support@10xgenomics.com` as the recipient e-mail address.

</LinkableSection>

<LinkableSection id={"windows-troubleshoot"} nested={true} title={"Troubleshooting"}>

Error Message: 'redstone.exe' is not recognized as an internal or external command, operable program or batch file.

This error indicates that redstone.exe program did not download properly, the full path to redstone.exe was not provided at the command prompt, or the name of the executable was misspelled. Please try one of these solutions:

- Check the spelling of the executable name
- Run redstone.exe using a full path (Downloads\redstone.exe)
- Click on the download link again to download the executable again

</LinkableSection>


Data Transfers to 10x Genomics


```
aligner
ANTIBODY_bc_bases_with_q30_frac
ANTIBODY_bc_bases_with_q30_in_gel_bead_frac
ANTIBODY_bc_bases_with_q30_in_probe_frac
ANTIBODY_chemistry
ANTIBODY_feature_reads_in_cells
ANTIBODY_filtered_bcs_transcriptome_union
ANTIBODY_frac_feature_reads_usable
ANTIBODY_good_bc_frac
ANTIBODY_good_bc_in_gel_bead_frac
ANTIBODY_good_bc_in_probe_frac
ANTIBODY_good_umi_frac
ANTIBODY_multi_cdna_pcr_dupe_reads_frac
ANTIBODY_multi_filtered_bcs
ANTIBODY_multi_filtered_bcs_median_counts
ANTIBODY_multi_usable_reads_per_filtered_bc
ANTIBODY_read_bases_with_q30_frac
ANTIBODY_reads_lost_to_aggregate_GEMs
ANTIBODY_reads_per_cell
ANTIBODY_recognized_feature_bc_frac
ANTIBODY_recognized_feature_bc_frac_in_filtered_barcodes
ANTIBODY_total_read_pairs
ANTIBODY_total_read_pairs_in_filtered_barcodes
ANTIBODY_umi_bases_with_q30_frac
ANTIBODY_unprocessed_read_pairs
ANTIGEN_bc_bases_with_q30_frac
ANTIGEN_bc_bases_with_q30_in_gel_bead_frac
ANTIGEN_bc_bases_with_q30_in_probe_frac
ANTIGEN_chemistry
ANTIGEN_feature_reads_in_cells
ANTIGEN_good_bc_frac
ANTIGEN_good_umi_frac
ANTIGEN_multi_cdna_pcr_dupe_reads_frac
ANTIGEN_multi_filtered_bcs
ANTIGEN_multi_filtered_bcs_median_counts
ANTIGEN_multi_usable_reads_per_filtered_bc
ANTIGEN_read_bases_with_q30_frac
ANTIGEN_reads_per_cell
ANTIGEN_total_read_pairs
ANTIGEN_total_read_pairs_in_filtered_barcodes
ANTIGEN_umi_bases_with_q30_frac
ANTIGEN_unprocessed_read_pairs
avx
bc_bases_with_q30_frac
bc_bases_with_q30_in_gel_bead_frac
bc_bases_with_q30_in_probe_frac
bin_filesystem
cgroup_memory_hard_limit
cgroup_memory_soft_limit
chain
check_library_compatibility
chemistry
chemistry_name
container
core_hours
cores_per_socket
cpu_mfg
create_bam
CRISPR_bc_bases_with_q30_frac
CRISPR_bc_bases_with_q30_in_gel_bead_frac
CRISPR_bc_bases_with_q30_in_probe_frac
CRISPR_chemistry
CRISPR_feature_bc_extracted_frac
CRISPR_feature_bc_extracted_frac_in_filtered_barcodes
CRISPR_feature_reads_in_cells
CRISPR_frac_cells_with_multiple_protospacer
CRISPR_frac_cells_with_protospacer
CRISPR_frac_feature_reads_usable
CRISPR_good_bc_frac
CRISPR_good_bc_in_gel_bead_frac
CRISPR_good_bc_in_probe_frac
CRISPR_good_umi_frac
CRISPR_multi_cdna_pcr_dupe_reads_frac
CRISPR_multi_filtered_bcs
CRISPR_multi_filtered_bcs_median_counts
CRISPR_multi_usable_reads_per_filtered_bc
CRISPR_read_bases_with_q30_frac
CRISPR_reads_per_cell
CRISPR_recognized_feature_bc_frac
CRISPR_recognized_feature_bc_frac_in_filtered_barcodes
CRISPR_total_read_pairs
CRISPR_total_read_pairs_in_filtered_barcodes
CRISPR_umi_bases_with_q30_frac
CRISPR_unprocessed_read_pairs
CRISPR_unrecognized_feature_bc_frac
CRISPR_unrecognized_feature_bc_frac_in_filtered_barcodes
Custom_bc_bases_with_q30_frac
Custom_bc_bases_with_q30_in_gel_bead_frac
Custom_bc_bases_with_q30_in_probe_frac
Custom_chemistry
Custom_feature_reads_in_cells
Custom_good_bc_frac
Custom_good_umi_frac
Custom_multi_cdna_pcr_dupe_reads_frac
Custom_multi_filtered_bcs
Custom_multi_filtered_bcs_median_counts
Custom_multi_usable_reads_per_filtered_bc
Custom_read_bases_with_q30_frac
Custom_reads_per_cell
Custom_total_read_pairs
Custom_total_read_pairs_in_filtered_barcodes
Custom_umi_bases_with_q30_frac
Custom_unprocessed_read_pairs
denovo
disk_hwm
distro
emptydrops_minimum_umis
enable-tsne
error
estimated_gdna_content
estimated_gdna_unspliced_threshold
event_count
expect_cells
failed_stage
feature_r1_length
feature_r2_length
filter_aggregates
filtered_bcs_transcriptome_union
filtered_reads_per_filtered_bc
filter_high_occupancy_gems
filter_probes
force_cells
gene_expression_r1_length
gene_expression_r2_length
GEX_chemistry
glibc
global_minimum_umis
good_bc_frac
good_umi_frac
IGH_vdj_assembly_prod_cdr_bc_frac
IGH_vdj_assembly_umis_per_cell_median
IGH_vdj_recombinome_mapped_reads_frac
IGK_IGH_vdj_assembly_contig_pair_productive_full_len_bc_frac
IGK_vdj_assembly_prod_cdr_bc_frac
IGK_vdj_assembly_umis_per_cell_median
IGK_vdj_recombinome_mapped_reads_frac
IGL_IGH_vdj_assembly_contig_pair_productive_full_len_bc_frac
IGL_vdj_assembly_prod_cdr_bc_frac
IGL_vdj_assembly_umis_per_cell_median
IGL_vdj_recombinome_mapped_reads_frac
include_introns
jobmode
kernel
median_genes_per_singlet
median_umi_per_singlet
memgb
memory
min_assignment_confidence
min_contig_length
min_crispr_umi
min-crispr-umi
multi_cdna_pcr_dupe_reads_frac
multi_filtered_bcs_conf_mapped_barcoded_reads_cum_frac
multiplet_filter
MULTIPLEXING_bc_bases_with_q30_frac
MULTIPLEXING_bc_bases_with_q30_in_gel_bead_frac
MULTIPLEXING_bc_bases_with_q30_in_probe_frac
MULTIPLEXING_chemistry
MULTIPLEXING_feature_reads_in_cells
MULTIPLEXING_good_bc_frac
MULTIPLEXING_good_umi_frac
MULTIPLEXING_multi_cdna_pcr_dupe_reads_frac
MULTIPLEXING_read_bases_with_q30_frac
MULTIPLEXING_reads_per_cell
MULTIPLEXING_total_read_pairs
MULTIPLEXING_umi_bases_with_q30_frac
MULTIPLEXING_unprocessed_read_pairs
multi_raw_vdj_paired_clonotype_diversity
multi_transcriptome_conf_mapped_reads_frac_in_filtered_barcodes
multi_transcriptome_half_mapped_reads_frac_in_filtered_barcodes
multi_transcriptome_mapped_reads_frac_in_filtered_barcodes
multi_transcriptome_split_mapped_reads_frac_in_filtered_barcodes
multi_transcriptome_targeted_conf_mapped_reads_frac_in_filtered_barcodes
multi_vdj_assembly_contig_pair_productive_full_len_bc_count
multi_vdj_assembly_contig_pair_productive_full_len_bc_frac
multi_vdj_recombinome_mapped_reads_frac
no_bam
no_libraries
normalize
nosecondary
nthreads
pipestance_filesystem
processor_count
process_ulimit
r1_length
r2_length
read_bases_with_q30_frac
reads_per_cell
runtime
shared_contig_filter
singlets_assigned_to_other_samples
singlets_assigned_to_this_sample
skip_cell_annotation
skip_clonotyping
socket_count
subcommand
total_cell_associated_partitions
total_genes_detected
total_read_pairs
total_read_pairs_in_filtered_barcodes
total_singlets
transparent_huge_pages
TRA_TRB_vdj_assembly_contig_pair_productive_full_len_bc_frac
TRA_vdj_assembly_prod_cdr_bc_frac
TRA_vdj_assembly_umis_per_cell_median
TRA_vdj_recombinome_mapped_reads_frac
TRB_vdj_assembly_prod_cdr_bc_frac
TRB_vdj_assembly_umis_per_cell_median
TRB_vdj_recombinome_mapped_reads_frac
TRD_vdj_assembly_prod_cdr_bc_frac
TRD_vdj_assembly_umis_per_cell_median
TRG_TRD_vdj_assembly_contig_pair_productive_full_len_bc_frac
TRG_vdj_assembly_prod_cdr_bc_frac
TRG_vdj_assembly_umis_per_cell_median
umi_baseline_filter
umi_bases_with_q30_frac
unprocessed_read_pairs
utime
vdj_assemblable_read_pairs_per_filtered_bc
VDJ_bc_bases_with_q30_frac
VDJ_B_chemistry
VDJ_chemistry
vdj_filtered_bcs
vdj_filtered_bcs_cum_frac
vdj_good_bc_frac
VDJ_read_bases_with_q30_frac
VDJ_T_chemistry
VDJ_T_GD_chemistry
vdj_total_raw_read_pairs_per_filtered_bc
VDJ_total_read_pairs
VDJ_umi_bases_with_q30_frac
VDJ_unprocessed_read_pairs
vmem_ulimit
```

Human Readable List of Telemetry Metrics Collected by Cell Ranger Pipelines

A set of analysis pipelines that perform sample demultiplexing, barcode processing, single cell 3' and 5' gene counting, V(D)J transcript sequence assembly and annotation, and Feature Barcode analysis from single cell data.

Overview

Getting Started

Supported Libraries

Download Center

Cloud Analysis

Cell Ranger Commands

Analysis

Tutorials

Algorithms

Advanced

Troubleshooting

Miscellaneous

Release Notes

Glossary

Datasets

Loupe Browser

Cell Ranger

Installation

Get Started with Cell Ranger

Convert BCL to FASTQ with Cell Ranger mkfastq

mkfastq

Cell Ranger mkfastq

Analyze Gene Expression and Feature Barcode data with Cell Ranger count

count

Cell Ranger count

aggr

Cell Ranger aggr

Rerun secondary analysis for a completed cellranger count or aggr run with different parameters

reanalyze

Cell Ranger reanalyze

Build a custom reference using Cell Ranger mkref

mkref

Cell Ranger mkref

Analyze cell multiplexing data with Cell Ranger multi

multi

Cell Ranger multi for 3' Cell Multiplexing

Analyze V(D)J and 5' GEX with Cell Ranger multi

multi for V(D)J

Cell Ranger multi for Immune Profiling

Analyze your GEX + VDJ + B cell Antigen Capture libraries with Cell Ranger multi

Cell Ranger multi for BEAM-Ab

Analyze your GEX + VDJ + T cell Antigen Capture libraries with Cell Ranger multi

Cell Ranger multi for BEAM-T

Analyze V(D)J libraries with Cell Ranger vdj

Cell Ranger vdj

Capturing Neutrophils in 10x Single Cell Gene Expression Data

Capturing neutrophils

Capturing Neutrophils

Analyze scRNA-Seq Data From a Publication Using 10x Software

Data analysis

Example Data Analysis

Analysis and visualization of data in the tumor microenvironment application note using the Loupe and Loupe V(D)J Browsers

Characterize tumor cells

Tumor Microenvironment Data Analysis and Visualization

Understand pipeline telemetry data collection and learn how to disable it if needed

Cell Ranger Pipeline Telemetry

View all tutorials

Learn more about input files required to run Cell Ranger

Inputs

List of Inputs

Generating FASTQs

Specifying FASTQs

A CSV file used to indicate the input FASTQ files for libraries in a Feature Barcode experiment.

Libraries CSV

A CSV file used to indicate the molecule structure and unique Feature Barcode sequence of each feature present in the experiment.

Feature Reference CSV

A CSV files that specifies parameters required to run cellranger multi

Multi Config CSV

Custom Reference with mkref

Custom V(D)J Reference

Running Pipelines

Choosing a pipeline

GEX + Antibody/CRISPR (count)

VDJ-T/B only (vdj)

3'/5' Sample Multiplexing (multi)

VDJ + GEX + Antibody/CRISPR/BEAM (multi)

Flex (multi)

Aggregate Multiple Samples (aggr)

Cell Annotation (annotate)

Custom Analysis (reanalyze)

Learn more about the output files generated by Cell Ranger

Outputs

Web Summary

Metrics

Feature-Barcode Matrices

Molecule Info (H5)

Secondary Analysis

Results of aggr

Gene Expression

Antibody Capture

CRISPR Guide Capture

Sample Multiplexing

VDJ-T/B

VDJ + GEX + BEAM

Flex

What is Cell Ranger?

<Flex flexDirection={'column'} gap={'0.5rem'}><div><Text as={'span'} size={'small'} weight={'medium'}>{'Starting with v9.0, anonymized telemetry data is collected and sent to 10x Genomics. '}</Text><Anchor href={'https://10xgen.com/pipeline-telemetry'}><Text as={'span'} color={'inherit'} size={'small'} weight={'medium'}>{'Learn how to disable.'}</Text></Anchor></div><Text as={'p'} size={'small'} weight={'medium'}>Fixed RNA Profiling has been renamed Flex. All future updates, documentation, and support will reference Flex.</Text><Text as={'p'} size={'small'} weight={'medium'}>The cellranger mkfastq pipeline is deprecated and will be removed in a future release. Please use Illumina’s BCL Convert to generate Cell Ranger-compatible FASTQ files.</Text></Flex>

We provide resources from protocols, user guides, and free-to-use analysis tools

Algorithms overview

Advanced pipeline content for Cell Ranger.

Browse Q&As from the 10x Genomics support team.

View terms and definitions relevant to Single Cell products.

Access free public Chromium data from 10x Genomics.

A collection of introductions, tutorials, and blogs for data analysis beyond software.

Analysis Guides

Loupe Browser is a desktop application that allows you to interactively visualize data.