Submitting spatial transcriptomics data

Here you can find information about depositing Spatial Transcriptomics (ST) data into the BIA, paying special attention to the challenges related to these datasets. You can learn more about depositing ST data on EMBL-EBI resources here: https://www.ebi.ac.uk/spatial-transcriptomics/submit

1. Register an account

You will need to register for a BioStudies account. You can sign up here and then return to this guide.

2. What ST datasets can I submit to the BIA?

The appropriate archive to submit spatial transcriptomics data depends on the technology used. Sequencing-based and imaging-based spatial transcriptomics data follow different submission routes, as described below.

Deposition of imaging-based spatial transcriptomics data to the BIA:

All data (including sequencing) obtained using imaging-based spatial transcriptomics technologies (e.g. CosMx, MERSCOPE, or Xenium technologies) should be deposited into the BioImage Archive.

Importantly, for these datasets to be reusable they should contain, as a minimum, the following files:

• Expression matrix - containing transcriptional profiles (or necessary files to construct it, such as SpaceRanger output files)
• Cell metadata file - cell information such as quality control measures, or metrics like aspect ratio or area
• Cell polygons - polygons determining cell boundaries
• Immunofluorescence images - raw and/or preprocessed fluorescence images (used for segmentation)
• Segmentation masks - raster images with segmentation masks encoded
• Transcript positions - coordinates of each detected transcript
• Probe panel - machine-readable list of probe sequences, gene targets, and barcodes We also encourage deposition of any additional files that may be important to reproduce the submitted experiments, for example field of view positions, transformation data, gene panel metadata, or analysis summary files.

For any program code accompanying your study, it is best to upload that code to a specialised repository (e.g. GitHub or GitLab), and then add a link to it in your submission, which you will be able to do during the submission process.

Deposition of sequencing-based spatial transcriptomics data to ArrayExpress:

Data obtained using sequencing-based spatial transcriptomics methods (e.g. GeoMx or Visium technologies) should be submitted to ArrayExpress via Annotare.

3. File formats and file size considerations

You can submit your data in any format that you have. We encourage the use of open file formats that do not require proprietary software, to increase the reuse potential of the dataset. For images, in general, it is best to use widely supported community standard formats (e.g. OME-TIFF, OME-NGFF/OME-Zarr, or SpatialData Object) if possible. If you are submitting SpatialData Objects, please look for more instructions in the section Submitting SpatialData Objects. For image annotations and supplementary data (such as tables of features or measurements), use standardised formats, such as CSV, where possible. For large tabular data files (like transcript positions that can have millions of rows), we recommend Parquet to facilitate downstream analysis. If you are submitting Zarr or OME-Zarr files, please check this page with additional considerations.

We do not have restrictions on the total size of the datasets submitted to the BIA. If your dataset is larger than a few TB, please get in touch with us so we can prepare for your submission. Regarding file sizes, we cannot support single files larger than 2TB, and would recommend keeping individual files under 100GB as that will make the upload process faster and less prone to errors.

4. Prepare your data

Now, organise your data for submission. Your data files should be in a single directory tree with a logical hierarchical file structure. Please note that the file paths will not be directly visible on the entry’s web page, therefore if there is embedded information in the directory structure, please put that information as metadata in the file list (see section File level metadata).

Please note that some special characters are not allowed in directory and file names. Please only use the following allowed characters to name your files:

• Any alphanumeric character, a-z | A-Z | 0-9
• Any of the following special characters, !-_.*’()
  • Exclamation point !
  • Hyphen -
  • Underscore _
  • Period .
  • Asterisk *
  • Single quote ‘
  • Open parenthesis (
  • Close parenthesis )
  • Space ​

5. Upload your data

We support data upload through multiple methods, each recommended depending on the size of your submission. You can find detailed information about how to upload your data in section 3 here.

6. Prepare your file list

You will need a “table of contents” for your image files, called a “file list” in the submission tool here. The purpose of the file list is to link specific files to your submission and to provide information about the individual files (see section File level metadata).

You can find further information about the file list and how to create it at the file list help page.

7. Submission

Provide Study level metadata

To provide general metadata about the study, images, and annotations, you can use the web form in our submission tool. First, you will need to create a submission here. Make sure you select the BioImages template when creating a new submission. You will have to fill in all of the required metadata fields before submitting.

Please make sure you specify what ST technology was used for both acquisition and analysis (including versions). If any data has been pre-processed, please describe your pre-processing pipeline in the Image Analysis metadata module.

If your study includes imaging-based spatial transcriptomics data submitted to the BioImage Archive alongside related data deposited in other archives, you should link the related accessions in the Linked Information section of the submission tool. This allows users to discover all datasets associated with the same study. Submission S-BIAD1415 is an example of how to link depositions of other data types with a BIA submission. You can find more information about linking information here.

Provide File level metadata

Some metadata that changes among the files of a study component, or of an annotations section, needs to be given at the file level. This metadata should be added in the relevant row for a given file in the file list.

For example, the file list of submission S-BIAD1182 details what fluorescent labels and RNA targets are used in each image.

Please, use ontologies and controlled vocabularies for the values of the additional metadata where possible. This will improve the findability and interoperability of your data.

As much as possible, we highly recommend that you include the additional metadata described here in your file list.

If you are submitting annotations, e.g. segmentation masks, point annotations etc., you will need to add one or more Annotations sections to your submission. For this section you will need a separate file list which contains the paths to the annotation files, and should also include a “source image” column to reference the original image that has been annotated. You can find a template for the annotations file list here.

Submitting SpatialData Objects

A SpatialData Object is a Zarr based file format with json metadata at the top level. It usually contains multiple subdirectories:

• images/ - can contain one or more raster image (e.g. H&E, staining)
• labels/ - raster image (segmentation mask)
• points/ - point coordinates (e.g. transcripts)
• shapes/ - geometric shapes (e.g. cell segmentations, ROIs)
• tables/ - anndata objects (gene expressions, cell types etc)

Submission of SpatialData objects

The spatialdata objects should be zipped at the top level, e.g. mysdata.zarr.zip. You can use the following command to zip your spatialdata files with no compression (replace mysdata.zarr.zip and mysdata.zarr/ with the name of your spatialdata object):

zip -0 -r mysdata.zarr.zip mysdata.zarr/

The submission must have:

• A Study Component which includes the biosample, specimen and imaging metadata (see REMBI Lab Guide and REMBI Model Reference for more guidance)
• Annotation component(s) for annotation (segmentation, labels etc) metadata (see MIFA metadata for more guidance). One annotation component for different annotation types is enough if they were produced using the same method/software and same criteria, coverage etc.
• A column in the Study Component filelist to say which file/files are SpatialData objects
• The file lists should have additional columns listing what’s inside the spatialdata, i.e. components of the spatialdata object.

If you have a Vitessce config file, you can also upload and submit that by including it in the Study Component filelist.

Examples of File Lists for Study and Annotations component for SpatialData Object submissions

• Filelist template for Study Component (please delete the examples when submitting): Spatialdata_filelist_example
• Filelist template for Annotation component (please delete the examples when submitting): Spatialdata_annotation_filelist_example

8. Complete your submission

Once you have filled in all the necessary fields in the web forms the validation panel on the left should indicate “all ok”. When that is the case, you can click on “Submit”.

After your submission is loaded into the BioImage Archive database, it will be assigned a unique BioImage Archive accession number (i.e., dataset identifier).

It is important to note that your submission will be private, and other people will not be able to see it, until the release date you have set. The accession number will be the same before and after making the dataset public and will not change even if revisions are necessary. Details on how to access and share your study with others will be available in a confirmation window and will also be sent via email. A private link will be available for you to share your dataset with reviewers and collaborators before the release date.