Skip to content

🚀 Quick Start: Run with Docker

This tutorial walks through the CartLoader workflow — all packaged inside a prebuilt Docker image with dependencies and input data included.

Use Cases

This is the fastest and simplest way to try CartLoader — no setup, installation, or data download required.

Requirements

Users will need to:

Set Up Docker

If you are new to Docker, please refer to the Docker documentation for installation and basic usage.

Verify whether Docker is properly set up on your system: 

1
2
3
4
5
# Check if Docker is installed and show its version
docker --version

# Test if Docker can successfully run a container
docker run hello-world

If these commands fail, install Docker in your system.

Input Data

The input is an mouse hippocampus SGE in a FICTURE-compatible format compatible, prepared by sge_convert in CartLoader .

File Format

transcripts.unsorted.tsv.gz: transcript-indexed SGE in TSV 
1
2
3
4
X        Y        gene     count
295.29   1422.35  Myo3a    0
1745.54  1110.72  Med14    1
1745.54  1110.72  Ntpcr    1
  • X: X coordinates in um
  • Y: Y coordinates in um
  • gene: gene symbols
  • count: expression count per pixel per gene
feature.clean.tsv.gz: UMI counts on a per-gene basis in TSV 

1
2
3
4
gene           gene_id             count
Gm29155        ENSMUSG00000100764  1
Pcmtd1         ENSMUSG00000051285  431
Gm26901        ENSMUSG00000097797  1
* gene: gene symbols * gene_id: gene IDs * count: expression count per gene

coordinate_minmax.tsv: X Y min/max coordinates 
1
2
3
4
xmin    0.14
xmax    2359.90
ymin    0.23
ymax    1439.95
  • xmin xmax: min and max X coordinates in um
  • ymin ymax: min and max Y coordinates in um

Data Access

Input data already included

The example dataset is preloaded in the Docker image — no need to download separately.

If needs, it is also available on Zenodo: DOI: 10.5281/zenodo.15701393

Set Up the Environment

Fixed paths in the Docker Image

Tools and dependencies have fixed paths in the Docker image (e.g., /usr/local/bin/pmtiles), which are used directly in the commands below. Skip specifying them manually.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
# ====
# 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

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

# Unique identifier for your dataset
DATA_ID="seqscope_hippo"                # change this to reflect your dataset name
PLATFORM="seqscope"                     # 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)

FICTURE Analysis

Compute spatial factors using punkst (FICTURE2 mode). See more details in Reference page.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
docker run -it --rm \
  -v $(pwd):/data \
  weiqiuc/cartloader:20250708b \
  run_ficture2 \
    --makefn run_ficture2.mk \
    --main \
    --in-transcript /app/data/sge/transcripts.unsorted.tsv.gz \
    --in-feature /app/data/sge/feature.clean.tsv.gz \
    --in-minmax /app/data/sge/coordinate_minmax.tsv \
    --cmap-file /app/cartloader/assets/fixed_color_map_256.tsv \
    --exclude-feature-regex '^(mt-.*$|Gm\d+$)' \
    --out-dir /data/ficture2 \
    --width ${train_width} \
    --n-factor ${n_factor} \
    --ficture2 /app/cartloader/submodules/punkst \
    --spatula /app/cartloader/submodules/spatula/bin/spatula \
    --n-jobs ${n_jobs} \
    --threads ${n_jobs}
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
24
25
26
27
28
29
# Example: with FICTURE outputs
docker run -it --rm \
  -v $(pwd):/data \
  weiqiuc/cartloader:20250708b \
  run_cartload2 \
    --makefn run_cartload2.mk \
    --fic-dir /data/ficture2 \
    --out-dir /data/cartload2 \
    --id ${DATA_ID} \
    --spatula /app/cartloader/submodules/spatula/bin/spatula \
    --pmtiles /usr/local/bin/pmtiles \
    --tippecanoe /usr/local/bin/tippecanoe \
    --n-jobs ${n_jobs} \
    --threads ${n_jobs}

# Example: SGE-only packaging
docker run -it --rm \
  -v $(pwd):/data \
  weiqiuc/cartloader:20250708b \
  run_cartload2 \
    --makefn run_cartload2.mk \
    --sge-dir /data/sge_convert \
    --out-dir /data/cartload2 \
    --id ${DATA_ID} \
    --spatula /app/cartloader/submodules/spatula/bin/spatula \
    --pmtiles /usr/local/bin/pmtiles \
    --tippecanoe /usr/local/bin/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
 9
10
11
# AWS S3 target location for cartostore
AWS_BUCKET="EXAMPLE_AWS_BUCKET"         # replace EXAMPLE_AWS_BUCKET with your actual S3 bucket name

docker run -it --rm \
  -v $(pwd):/data \
  weiqiuc/cartloader:20250708b \
  upload_aws \
    --in-dir /data/cartload2 \
    --s3-dir "s3://${AWS_BUCKET}/${DATA_ID}" \
    --aws /usr/local/bin/aws \
    --n-jobs ${n_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
10
11
12
zenodo_token=/path/to/zenodo/token/file    # replace /path/to/zenodo/token/file by path to your zenodo token file

docker run -it --rm \
  -v $(pwd):/data \
  weiqiuc/cartloader:20250708b \
  upload_zenodo \
    --in-dir /data/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.