Support homeCloud AnalysisTutorials
Uploading a Custom Reference for Linux

Uploading a Custom Reference for Linux

In addition to the pre-built human and mouse reference packages available in Cloud Analysis, you can upload and use your own custom references in your Cloud Analysis projects.

To use custom references in your analyses, you must upload the the entire output directory produced from running the appropriate mkref pipeline. For the latest details on what is supported, see Analysis and Supported Products.

Each uploaded custom reference will be stored at no cost for 365 days. If you would like to store your custom references past the free storage limit, you can opt-in to ongoing paid storage at $0.02/GB per month.

The steps are operating system dependent. Please select the tab for your operating system below to continue.

Use our command line tool to upload custom references to your account. To download and view a tutorial on running commands, visit the 10x Genomics Cloud CLI Documentation page.

To upload a custom reference you must use the 10x Genomics Cloud CLI version 1.1.0 or above. You can verify the version using the txg --version command.

Before you upload, make sure your reference meets the requirements:

  • It was generated using a supported pipeline.
  • All the files are contained in a single folder, either compressed as a single tar archive file (.tar.gz/.tgz) or uncompressed.
  • All the required files are present. The list of required files can be found here.

Before the upload begins, the 10x Genomics Cloud CLI will verify that your reference meets the above requirements.

Use the command below to upload:

./txg references upload [insert path to reference]

Example upload commands

To upload an uncompressed directory:

./txg references upload /user.name/references/GRCz11/

To upload a tar compressed archive (.tar.gz/.tgz):

./txg references upload /user.name/references/GRCz11.tar.gz

Enter your access token

If this is your first time using the uploader, you will be prompted to provide an access token, which verifies your identity. The access token can be found in your Account Settings.

If you have provided a path to an uncompressed directory, you will see a message similar to the following:

Verifying all required files are present... All required files are present. You are required to upload a compressed directory (.tar.gz). 10x Genomics Cloud CLI can create a compressed version of the directory for you. Compression could take several minutes. Estimated size: Up to 8.5 GB on /Users/path/to/directory/ Would you like to proceed with compressing the directory? To cancel, press Ctrl+C. Proceed? [y/N]

After successfully creating the compressed directory, you will see a message similar to the following:

You are about to upload 1 custom reference directory to your 10x Genomics Cloud account. Custom reference name: "name-of-reference-directory" Reference type: [GEX or VDJ] Cell Ranger mkref version: cellranger-X.Y.Z /Users/path/to/compressed/reference (8.5 GB) Total: 8.5 GB To proceed and delete the compressed directory after uploading, type y. To proceed with the upload and keep the compressed directory, type k. To cancel, type N. Proceed? [y/k/N]

You will receive an email once the upload is complete. The email will be sent to the address associated with your 10x Genomics account.

Once the upload is complete, you can begin to use the reference in analyses in any of your projects. You can also record important details about the reference in Cloud Analysis including the organism, a description, and build notes.

We require that you upload the entire output directory produced from running mkref. Selected examples are shown below.

Gene expression references generated by Cell Ranger / Space Ranger mkref

└─ /mkref output/ ├── reference.json ├── /pickle/1 │ └── genes.pickle1 ├── /genes/ │ └── genes.gtf ├── /star/ │ ├── chrLength.txt │ ├── chrName.txt │ ├── chrNameLength.txt │ ├── chrStart.txt │ ├── exonGeTrInfo.tab │ ├── exoninfo.tab │ ├── geneinfo.tab │ ├── Genome │ ├── genomeParameters.txt │ ├── SA │ ├── SAindex │ ├── sjdbinfo.txt │ ├── sjdbList.fromGTF.out.tab │ ├── sjdbList.out.tab │ └── transcriptinfo.tab └── /fasta/ ├── genome.fa.fai └── genome.fa
The /pickle/ directory and the genes.pickle file is only required for references produced with Cell Ranger v3.1 and 4.0. The /pickle/ directory is deprecated in newer versions of Cell Ranger.

V(D)J references generated by Cell Ranger mkrefvdj

└─ /mkvdjref output/ ├── reference.json └── /fasta/ ├── supp_regions.fa └── regions.fa

Multiome references generated by Cell Ranger ARC mkref

/mkref output/ ├── fasta │ ├── genome.fa │ ├── genome.fa.amb │ ├── genome.fa.ann │ ├── genome.fa.bwt │ ├── genome.fa.fai │ ├── genome.fa.pac │ └── genome.fa.sa ├── genes │ └── genes.gtf.gz ├── reference.json ├── regions │ ├── motifs.pfm # present if motifs file was supplied │ ├── transcripts.bed │ └── tss.bed └── star ├── chrLength.txt ├── chrNameLength.txt ├── chrName.txt ├── chrStart.txt ├── exonGeTrInfo.tab ├── exonInfo.tab ├── geneInfo.tab ├── Genome ├── genomeParameters.txt ├── SA ├── SAindex ├── sjdbInfo.txt ├── sjdbList.fromGTF.out.tab ├── sjdbList.out.tab └── transcriptInfo.tab

Additional Files

If you provide files beyond the required files (for example, a README file), the files will be uploaded and stored with your reference on Cloud Analysis. Please check and ensure that you only provide files that you wish to include with your custom reference.