hubmap-xenium-submitter

This tools is a set of scripts meant to organize 10x Genomics Xenium outputs into a data package that is compliant with the HuBMAP spatial transcriptomics xenium data schema.

Environment

Set up a conda environment with the include environment.yml file.

conda env create -f environment.yml

Usage

These are the usage docs for the directory conversion python script, which provides the following core functions:

1. organization of existing elements of the OBA Xenium product
2. generation of elemnents that can be derived from the OBA product
3. integration of unassimilated elements that can't be derived

A hacky bash loop is also included as a companion to this python script that can work over this script for multiple directories.

usage: hubmap_dir_conversion_v3.6.py [-h] --input INPUT --output OUTPUT --sample SAMPLE
                                     [--microscope-hardware MICROSCOPE_HARDWARE]
                                     [--microscope-settings MICROSCOPE_SETTINGS] [--overlay-image OVERLAY_IMAGE]
                                     [--tissue-boundary TISSUE_BOUNDARY] [--markers MARKERS]
                                     [--additional-panels ADDITIONAL_PANELS] [--custom-probes CUSTOM_PROBES]
                                     [--custom-probes-bed CUSTOM_PROBES_BED] [--custom-genes CUSTOM_GENES]
                                     [--probes PROBES] [--examples] [--validate-only] [--update] [--verbose]

Organize Xenium data products for HuBMAP submission compliance

options:
  -h, --help            show this help message and exit
  --examples            Show detailed usage examples and exit
  --validate-only       Only validate existing output directory without reorganizing
  --update              Update existing output directory with newly provided files
  --verbose, -v         Enable verbose logging output

required arguments:
  --input INPUT, -i INPUT
                        Path to Xenium output directory (e.g., output-SAMPLE123__timestamp)
  --output OUTPUT, -o OUTPUT
                        Path to output directory for HuBMAP-compliant structure
  --sample SAMPLE, -s SAMPLE
                        Sample identifier/name for file naming

optional arguments:
  --microscope-hardware MICROSCOPE_HARDWARE
                        Path to microscope_hardware.json file (required for HuBMAP submission)
  --microscope-settings MICROSCOPE_SETTINGS
                        Path to microscope_settings.json file (from micro-meta app)
  --overlay-image OVERLAY_IMAGE
                        Path to overlay image file (JPEG or TIFF) used for ROI selection
  --tissue-boundary TISSUE_BOUNDARY
                        Path to tissue boundary GeoJSON file
  --markers MARKERS     Path to markers.csv file (morphology markers description)
  --additional-panels ADDITIONAL_PANELS
                        Path to additional_panels_used.csv file
  --custom-probes CUSTOM_PROBES
                        Path to custom_probe_set.csv file
  --custom-probes-bed CUSTOM_PROBES_BED
                        Path to custom_probe_set.bed file
  --custom-genes CUSTOM_GENES
                        Path to custom_gene_list.csv file
  --probes PROBES       Path to probes.csv file (probe panel description)

For detailed usage examples, run: python xenium_hubmap_organizer.py --examples

This script organizes Xenium spatial transcriptomics data according to HuBMAP
directory schema v3.6. It takes a standard Xenium output directory and reorganizes
the files into the required HuBMAP structure with proper validation.

Required inputs:
- Xenium output directory (standard structure from Xenium Onboard Analysis)

Optional but recommended for HuBMAP submission:
- microscope_hardware.json file (generated using micro-meta app)

The script will:
1. Create HuBMAP-compliant directory structure
2. Copy and organize files to appropriate locations
3. Convert transcript data to required format
4. Generate channel metadata for OME-TIFF files with proper Xenium channel configuration
5. Validate output against schema requirements
6. Generate detailed validation report

Contact HuBMAP Consortium Help Desk (help@hubmapconsortium.org) for assistance
with generating microscope metadata files using the micro-meta app.