Skip to content

Quick Start: Run Locally

This quick start runs run_together with a local installation of CartLoader, on the same two examples as the Docker quick start.

Use Cases

Use a local installation to follow the latest code on GitHub, to modify CartLoader, or when Docker is not available.

Requirements

  • CartLoader and its tools installed and built as described in the Installation Guide, including bash build.sh in submodules/.
  • For the second example: about 10 GB of free disk (a 1.5 GB download plus about 8 GB of outputs); it took about 11 minutes on a 12-core laptop with --threads 4 -j 4.

Question

Check the Installation

Activate the environment you installed CartLoader into, then check that every dependency is found:

1
python installation/check_dependencies.py    # run from the cartloader repository

run_together uses the tools built under submodules/ (punkst, spatula, pmpoint, tippecanoe, pmtiles, geotiff2pmtiles), so you never pass tool paths to it.

After updating CartLoader, reinstall and rebuild

The pipeline expects the Python packages and tool versions pinned by the repository. After git pull, reinstall the Python dependencies and rebuild the submodules; otherwise a step may fail with a missing-package error (for example requires the 'imagecodecs' package), an "unknown option" error, or a usage message: 

1
2
3
uv pip install -e ".[ai]"                 # or: python -m pip install -e ".[ai]"
git submodule update --init --recursive
cd submodules && bash build.sh

Example 1: Mouse Hippocampus (Seq-Scope)

Input

Download the starter dataset, a mouse hippocampus SGE already converted to the FICTURE-compatible transcript format by sge_convert:

1
2
3
4
5
work_dir=/path/to/work/directory
mkdir -p ${work_dir} && cd ${work_dir}

wget https://zenodo.org/records/17953582/files/seqscope_starter.std.tar.gz
tar -xzf seqscope_starter.std.tar.gz      # creates ./sge/
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

Run

1
2
3
4
5
6
7
8
cartloader run_together \
    --platform seqscope \
    --in-transcript ./sge/transcripts.unsorted.tsv.gz \
    --out-dir ./out/seqscope_hippo \
    --id seqscope_hippo \
    --width 18 \
    --n-factor 6,12 \
    --threads 4 -j 4
Option Meaning
--platform seqscope Use the Seq-Scope platform profile for defaults.
--in-transcript An already-converted transcript TSV, so the SGE conversion step is skipped.
--out-dir, --id Output directory and the sample ID used to name the packaged assets.
--width, --n-factor FICTURE hexagon width (µm) and the number(s) of factors; one model per combination.
--threads, -j Threads per job and number of parallel jobs.

The deployable result is out/seqscope_hippo/cartl/seqscope_hippo/: a catalog.yaml plus the PMTiles it references. See Outputs for the full layout.

Example 2: Xenium Human Kidney (full pipeline)

This example starts from raw Xenium output, so every stage runs: SGE conversion, FICTURE, two cell analyses (CartLoader's own, from the Xenium cell boundaries, and an import of the Xenium Ranger clusters), the DAPI image, and packaging.

Input

A human kidney section from GSE264334, repackaged in the standard Xenium output layout and hosted on the AWS Open Data Registry (no AWS account needed):

1
2
3
4
5
6
7
# with the AWS CLI
aws s3 cp --no-sign-request \
  "s3://cartostore/data/batch=2026_05/xenium-geo-public-dataset-collection/xenium-human-kidney-igan-bull2024-20260516/gse264334-reformatted.tar.gz" .
# or with curl
curl -O "https://cartostore.s3.amazonaws.com/data/batch=2026_05/xenium-geo-public-dataset-collection/xenium-human-kidney-igan-bull2024-20260516/gse264334-reformatted.tar.gz"

tar -xzf gse264334-reformatted.tar.gz    # creates gse264334-reformatted/

Run

1
2
3
4
5
6
7
cartloader run_together \
    --platform 10x_xenium \
    --in-dir ./gse264334-reformatted \
    --out-dir ./out/gse264334 \
    --id gse264334 \
    --bin-count 50 \
    --threads 4 -j 4

Without --width/--n-factor, the Xenium profile's defaults apply (12 µm hexagons; 12, 24, and 48 factors). --bin-count 50 groups genes into 50 bins for the point layers instead of the default 500, which makes packaging faster for a quick test. The deployable result is out/gse264334/cartl/gse264334/.

Interrupted or failed run?

Rerun the same command: finished steps are skipped. Add --restart to rebuild everything. See Resume or Restart.

Next Steps