Skip to content

10x VisiumHD Starter Tutorial

Input Data

The input data originates from the mouse hippocampus and is extracted from an official release of mouse brain SGE data.

File Format

Visium HD slides use a 2×2 µm grid of barcoded squares (square_002um) for high-resolution spatial gene mapping. Use filtered_feature_bc_matrix to only process tissue-associated signals.

ATTENTION

The file‑format examples below use a sample Visium HD dataset. Paths, IDs, and values are illustrative and may not match the dataset used in this tutorial.

SGE comprises several key files as below:

filtered_feature_bc_matrix/barcodes.tsv.gz – spatial barcode for tissue locations 
1
2
3
s_002um_00639_00600-1
s_002um_00923_01639-1
s_002um_01050_01530-1
  • Column 1: Spatial barcodes corresponding to specific locations on the tissue section.
filtered_feature_bc_matrix/features.tsv.gz – feature metadata 
1
2
3
ENSMUSG00000051951  Xkr4    Gene Expression
ENSMUSG00000025900  Rp1     Gene Expression
ENSMUSG00000025902  Sox17   Gene Expression
  • Column 1: Feature ID
  • Column 2: Feature symbol
  • Column 3: Feature type
filtered_feature_bc_matrix/matrix.mtx.gz – expression count matrix 
1
2
3
4
5
6
%%MatrixMarket matrix coordinate integer general
%
19059 869411 11376563
3606 1 1
8957 1 1
9733 1 1
  • Header: Initial lines form the header, declaring the matrix's adherence to the Market Matrix (MTX) format, outlining its traits. This may include comments (lines beginning with %) for extra metadata, all marked by a “%”.
  • Dimensions: Following the header, the first line details the matrix dimensions: the count of rows (features), columns (barcodes), and non-zero entries.
  • Data Entries: Post-dimensions, subsequent lines enumerate non-zero entries in seven columns: row index (feature index), column index (barcode index), and one value presenting the expression count per barcode per feature.
tissue_positions.parquet – spatial barcode metadata 
1
2
barcode                 in_tissue   array_row   array_col   pxl_row_in_fullres  pxl_col_in_fullres
s_002um_00434_01637-1   1           434         1637        3396.371014         9125.919898
  • barcode: Unique spatial barcode associated with each capture spot.
  • in_tissue: Binary flag (1 = in tissue, 0 = background) indicating whether the spot falls within the tissue boundary.
  • array_row, array_col: Integer indices representing the position of the spot on the capture array grid.
  • pxl_row_in_fullres, pxl_col_in_fullres: Floating point coordinates locating the spot in full-resolution tissue image pixels.
scalefactors_json.json – pixel-to-micrometer scaling factors 
1
2
3
4
5
6
7
8
9
{
    "spot_diameter_fullres": 7.303953797779634,
    "bin_size_um": 2.0,
    "microns_per_pixel": 0.2738242950835738,
    "regist_target_img_scalef": 0.2505533,
    "tissue_lowres_scalef": 0.02505533,
    "fiducial_diameter_fullres": 1205.1523766336395,
    "tissue_hires_scalef": 0.2505533
}
  • spot_diameter_fullres: Estimated diameter of a barcoded spot in full-resolution pixels.
  • bin_size_um: Physical size (in micrometers) of the smallest bin, typically 2.0 µm for Visium HD.
  • microns_per_pixel: Resolution of the full-res image, used to convert pixel distances to micrometers.
  • regist_target_img_scalef: Scaling factor applied during image registration to the target image.
  • tissue_lowres_scalef: Downscaling factor from full-res to low-resolution tissue image.
  • fiducial_diameter_fullres: Diameter of fiducial markers in full-resolution pixels, useful for alignment.
  • tissue_hires_scalef: Downscaling factor from full-res to high-resolution tissue image.

Data Access

The example data is hosted on Zenodo.

Follow the commands below to download the example data.

1
2
3
4
work_dir=/path/to/work/directory
cd $work_dir
wget  https://zenodo.org/records/17953582/files/visiumhd_starter.raw.tar.gz 
tar -zxvf visiumhd_starter.raw.tar.gz

Set Up the Environment

Pre-installed tools

Please ensure you have installed all required tools (See Installation).

Define paths to all required binaries and resources. Optionally, specify a fixed color map for consistent rendering.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
# ====
# Replace each placeholder with the actual path on your system.  
# ====

work_dir=/path/to/work/directory        # path to work directory that contains the downloaded input data
cd $work_dir

# Define paths to required binaries and resources
spatula=/path/to/spatula/binary         # path to spatula executable
punkst=/path/to/punkst/binary           # path to FICTURE2 (punkst) executable
tippecanoe=/path/to/tippecanoe/binary   # path to tippecanoe executable
pmtiles=/path/to/pmtiles/binary         # path to pmtiles executable
aws=/path/to/aws/cli/binary             # path to AWS CLI binary

# (Optional) Define path to color map. 
cmap=/path/to/color/map                 # Path to fixed color map. `CartLoader` includes one at cartloader/assets/fixed_color_map_256.tsv.

# Number of jobs
n_jobs=10                               # If not specified, the number of jobs defaults to 1.

# Activate the bioconda environment
conda activate ENV_NAME                 # replace ENV_NAME with your conda environment name

Define data ID and analysis parameters:

1
2
3
4
5
6
7
# Unique identifier for your dataset
DATA_ID="visiumhd_hippo"                 # change this to reflect your dataset name
PLATFORM="10x_visium_hd"                 # platform information

# LDA parameters
train_width=18                           # define LDA training hexagon width (comma-separated if multiple widths are applied)
n_factor=6,12                            # define number of factors in LDA training (comma-separated if multiple n-factor are applied)

How to Define Scaling Factors for Visium HD?

10x Visium HD includes a scalefactors_json.json file that provides pixel-to-micrometer scaling information. CartLoader can directly accept this file via the --scale-json option and will automatically compute the appropriate scaling factor, omitting manually calculate and specify --units-per-um.

Alternatively, users may bypass the JSON file by directly providing a value through the --units-per-um option.

SGE Format Conversion

Convert the raw input to the unified SGE format. See more details in its Reference page.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
cartloader sge_convert \
  --makefn sge_convert.mk \
  --platform ${PLATFORM} \
  --in-mex ./raw \
  --in-parquet ./raw/tissue_positions.parquet \
  --scale-json ./raw/scalefactors_json.json \
  --out-dir ./sge \
  --exclude-feature-regex '^(BLANK|NegCon|NegPrb)' \
  --sge-visual \
  --spatula ${spatula} \
  --n-jobs ${n_jobs}
Parameter Required Type Description
--platform required string Platform (options: 10x_visium_hd, seqscope, 10x_xenium, bgi_stereoseq, cosmx_smi, vizgen_merscope, pixel_seq, generic)
--in-mex required string Path to the input MEX directory containing gene × barcode matrix
--in-parquet required string Path to the tissue_positions.parquet file with spatial barcode metadata
--scale-json required 1 string Path to the scalefactors_json.json file for coordinate scaling (or use --units-per-um to specify directly)
--out-dir required string Output directory for the converted SGE files
--makefn string File name for the generated Makefile (default: sge_convert.mk)
--exclude-feature-regex regex Pattern to exclude control features
--sge-visual flag Enable SGE visualization step (generates diagnostic image) (default: FALSE)
--spatula string Path to the spatula binary (default: spatula)
--n-jobs int Number of parallel jobs for processing (default: 1)

1: To define the scaling factor, CartLoader requires either a JSON file (via --scale-json) or a direct scale value using --units-per-um. When using --scale-json, make sure the JSON file has microns_per_pixel information.

FICTURE Analysis

Parameter Required Type Description
--main required 1 flag Enable CartLoader to run all five steps
--in-transcript required string Path to input transcript-level SGE file
--out-dir required string Path to output directory
--width required int or comma-separated list LDA training hexagon width(s)
--n-factor required int or comma-separated list Number of LDA factors
--makefn string File name for the generated Makefile (default: run_ficture2.mk )
--in-feature string Path to input feature file
--in-minmax string Path to input coordinate min/max file
--cmap-file string Path to color map file
--exclude-feature-regex regex Pattern to exclude features
--spatula string Path to the spatula binary (default: spatula)
--ficture2 string Path to the punkst directory (defaults to punkst repository within submodules directory of CartLoader)
--n-jobs int Number of parallel jobs (default: 1)
--threads int Number of threads per job (default: 1)

1: CartLoader requires the user to specify at least one action. Available actions includes: --tile to run tiling step; --segment to run segmentation step; --init-lda to run LDA training step; --decode to run decoding step; --summary to run summarization step; --main to run all above five actions.

CartLoader Asset Packaging

Generate pmtiles and web-compatible tile directories. See more details in Reference page.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# Example A: With FICTURE outputs (integrates factors + joins)
cartloader run_cartload2 \
  --makefn run_cartload2.mk \
  --fic-dir ./ficture2 \
  --out-dir ./cartload2 \
  --id ${DATA_ID} \
  --spatula ${spatula} \
  --pmtiles ${pmtiles} \
  --tippecanoe ${tippecanoe} \
  --n-jobs ${n_jobs} \
  --threads ${n_jobs}

# Example B: SGE-only (package molecules without FICTURE)
cartloader run_cartload2 \
  --makefn run_cartload2.mk \
  --sge-dir ./sge_convert \
  --out-dir ./cartload2 \
  --id ${DATA_ID} \
  --spatula ${spatula} \
  --pmtiles ${pmtiles} \
  --tippecanoe ${tippecanoe} \
  --n-jobs ${n_jobs} \
  --threads ${n_jobs}
Parameter Required Type Description
--out-dir required string Path to the output directory for PMTiles and web tiles
--id required string Dataset ID used for naming outputs and metadata
--fic-dir string Path to FICTURE outputs (enables factor layers + molecule–factor joins)
--sge-dir string Path to SGE outputs from sge_convert (enables SGE-only packaging)
--in-sge-assets string File name of SGE assets JSON/YAML in --sge-dir (default: sge_assets.json)
--in-fic-params string File name of FICTURE params JSON/YAML in --fic-dir (default: ficture.params.json)
--makefn string File name for the generated Makefile (default: run_cartload2.mk)
--spatula string Path to the spatula binary (default: spatula)
--pmtiles string Path to the pmtiles binary (default: pmtiles)
--tippecanoe string Path to the tippecanoe binary (default: tippecanoe)
--n-jobs int Number of parallel jobs (default: 1)
--threads int Number of threads per job (default: 4)

Upload to Data Repository

Choose a data repository to host/share your output

CartLoader supports two upload options (AWS and Zenodo) for storing PMTiles of SGE and spatial factors in a data repository.

Choose the one that best suits your needs.

AWS Uploads

Upload the generated CartLoader outputs to your designated AWS S3 directory:

1
2
3
4
5
6
7
8
# AWS S3 target location for cartostore
S3_DIR=/s3/path/to/s3/dir              # Recommend to use DATA_ID as directory name, such as s3://bucket_name/xenium-v1-humanlung-cancer-ffpe

cartloader upload_aws \
  --in-dir ./cartload2 \
  --s3-dir "${S3_DIR}" \
  --aws ${aws} \
  --n-jobs ${n_jobs}
Parameter Required Type Description
--in-dir required string Path to the input directory containing the CartLoader asset packaging output
--s3-dir required string Path to the target S3 directory for uploading
--aws string Path to the AWS CLI binary
--n-jobs int Number of parallel jobs

Zenodo Uploads

Upload the generated CartLoader outputs to your designated Zenodo deposition or a new deposition.

1
2
3
4
5
6
7
8
9
zenodo_token=/path/to/zenodo/token/file    # replace /path/to/zenodo/token/file by path to your zenodo token file

cartloader upload_zenodo \
  --in-dir ./cartload2 \
  --upload-method catalog \
  --zenodo-token $zenodo_token \
  --title  "Your Title" \
  --creators "Your Name" \
  --description "This is an example description"
Parameter Required Type Description
--in-dir required string Path to the input directory containing the CartLoader asset packaging output
--upload-method required string Method to determine which files to upload. Options: all to upload all files in --in-dir; catalog to upload files listed in a catalog YAML file; user_list to upload files explicitly listed via --in-list
--catalog-yaml string Required if --upload-method catalog. Path to catalog.yaml generated in run_cartload2. If absent, uses the catalog in the input directory specified by --in-dir.
--zenodo-token required string Path to your Zenodo access token file
--title required string Required when creating a new deposition (i.e., if --zenodo-deposition-id is omitted). Title for the new Zenodo deposition.
--creators required list of str List of creators in "Lastname, Firstname" format.

Output Data

See more details of output at the Reference pages for run_ficture2 and run_cartload2.