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 on their system (see Set Up Docker guide).

Question

• I am not sure whether to run with Docker or run locally. Which one should I choose?

---

Install 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:

# 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 on your system.

---

Set Up Environment

Fixed paths in the Docker Image

Tools and dependencies have fixed paths in the Docker image (for example, /usr/local/bin/pmtiles).

DO NOT modify paths of tools and dependencies manually.

# ====
# Replace user-specific placeholders with actual paths on your system.
# ====
work_dir=/path/to/work/directory                        # path to work directory that contains the downloaded input data
cd $work_dir

# The following paths are fixed inside Docker. Do not modify them.
spatula=/app/cartloader/submodules/spatula/bin/spatula  # path to spatula executable
punkst=/app/cartloader/submodules/punkst                # path to FICTURE2 (punkst) executable
tippecanoe=/usr/local/bin/tippecanoe                    # path to tippecanoe executable
pmtiles=/usr/local/bin/pmtiles                          # path to pmtiles executable
aws=/usr/local/bin/aws                                  # path to AWS CLI binary

# (Optional) Define path to color map. 
cmap=/app/cartloader/assets/fixed_color_map_256.tsv     # 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.

# Docker tag 
docker_tag=20260306

---

Prepare Input

Data Access

Input data already included

The example dataset is preloaded in the Docker image, so there is no need to download it separately.

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

File Format

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

transcripts.unsorted.tsv.gz: transcript-indexed SGE in TSV

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

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

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

Define ID and Parameters

# Number of jobs
n_jobs=10                                # If not specified, 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 values are provided)

---

SGE Format Conversion

The example dataset is already provided in FICTURE-compatible SGE format, so this conversion step is not required in this quickstart.

---

FICTURE Analysis

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

docker run -it --rm \
  -v $(pwd):/data \
  weiqiuc/cartloader:${docker_tag} \
  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 ${cmap} \
    --exclude-feature-regex '^(mt-.*$|Gm\d+$)' \
    --out-dir /data/ficture2 \
    --width ${train_width} \
    --n-factor ${n_factor} \
    --ficture2 ${punkst} \
    --spatula ${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)

_{¹: CartLoader requires the user to specify at least one action. Available actions include: --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.

docker run -it --rm \
  -v $(pwd):/data \
  weiqiuc/cartloader:${docker_tag} \
  run_cartload2 \
    --makefn run_cartload2.mk \
    --fic-dir /data/ficture2 \
    --out-dir /data/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 UploadsZenodo Uploads

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

# AWS S3 target location 
S3_DIR=/s3/path/to/s3/dir              # Recommend to use DATA_ID as directory name, such as s3://bucket_name/test-data

docker run -it --rm \
  -v $(pwd):/data \
  weiqiuc/cartloader:${docker_tag} \
  upload_aws \
  --in-dir /data/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

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

zenodo_token=/path/to/zenodo/token/file    # replace /path/to/zenodo/token/file with the path to your Zenodo token file

docker run -it --rm \
  -v $(pwd):/data \
  weiqiuc/cartloader:${docker_tag} \
  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

• 

  ---

  View/Explore

  The outputs are available in both CartoScope and Zenodo.

  Explore in CartoScope

  Download from Zenodo

See output details in the reference pages for run_ficture2 and run_cartload2.