🚀 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.
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 |
|
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
: X coordinates in umY
: Y coordinates in umgene
: gene symbolscount
: 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 symbols
* gene_id
: gene IDs
* count
: expression count per gene
coordinate_minmax.tsv
: X Y min/max coordinates
1 2 3 4 |
|
xmin
xmax
: min and max X coordinates in umymin
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 |
|
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 |
|
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
Compilation¶
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 |
|
Parameter | Required | Type | Description |
---|---|---|---|
--fic-dir |
required | string | Path to the input directory containing FICTURE2 output |
--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 |
--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: 1 ) |
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 |
|
Parameter | Required | Type | Description |
---|---|---|---|
--in-dir |
required | string | Path to the input directory containing the cartloader compilation 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 10 11 12 13 |
|
Parameter | Required | Type | Description |
---|---|---|---|
--in-dir |
required | string | Path to the input directory containing the cartloader compilation 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 the catalog.yaml file generated in run_cartload2 . If absent, will use the catalog.yaml in the input directory specified by --in-dir . |
|
--zenodo-token |
required | string | Path to your Zenodo access file |
--create-new-deposition |
flag | a new Zenodo deposition will be created. | |
--title |
required | string | Required if --create-new-deposition . 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.
Spatial Factor Inference from FICTURE
¶
Below is an example of spatial factor inference results from FICTURE
using a training width of 18, 12 factors, a fit width of 18, and an anchor resolution of 6.
Factor | RGB | Weight | PostUMI | TopGene_pval | TopGene_fc | TopGene_weight |
---|---|---|---|---|---|---|
0 | 255,101,101 | 0.57145 | 2577934 | Snap25,Cck,Hpca,Syt1,Atp1b1,Selenow,Ywhah,Scg5,Cnih2,Atp1a3,Vsnl1,Gnas,Cpe,Prkcb,Stmn2,Atp2b1,Gng3,Prkcg,Snrpn,Norad | Nr2c1,Calca,Wdr91,Ccbe1,Esyt1,Epha3,Slc9a4,Thap7,Mapk11,Klk8,Arhgef6,1110018N20Rik,Iba57,Klk10,Gjd2,Leng9,Zbtb46,Slc9a2,Akr1c18,Dlx6os1 | Snap25,Tmsb4x,Atp1b1,Actb,Cpe,Ywhah,Nrgn,Ppp3ca,Selenow,Calm1,Atp1a3,Calm2,Fth1,Rtn1,Cox8a,Gnas,Camk2a,Norad,Aldoa_v1,Ndrg4 |
1 | 237,238,0 | 0.15458 | 697338 | Ppp3ca,Nrgn,Ptk2b,Olfm1,Ppp3r1,Gria2,Ncdn,Nsf,Syne1,Snca,Chn1,Tmsb4x,Rasgrf1,Grin2a,Enc1,Kalrn,Wasf1,Camk2b,Calm2,Epha7 | Vwa8,Zfp583,Sppl2b,Faap24,Recql5,A230051N06Rik,Ints6l,Rnaseh2b,Strada,Scnn1a,Snhg17,Prelid3a,Grhl1,Icam4,Slc44a5,Tyw1,Parp8,Asb11,Vipr1,Zfp668 | Ppp3ca,Nrgn,Tmsb4x,Actb,Snap25,Atp1b1,Olfm1,Ywhah,Calm2,Ncdn,Rtn1,Ptk2b,Calm1,Ppp3r1,Actg1,Chn1,Fth1,Ndrg4,Fkbp1a,Cfl1 |
2 | 101,255,101 | 0.116 | 523314 | Cst3,Glul,Slc1a2,Mt1,Apoe,Sparcl1,Aldoc,Clu,Atp1a2,Slc1a3,Camk2a,Ndrg2,Gfap,Mt2,Gpr37l1,Atp1b2,Fam107a,Prdx6,Bc1,Plpp3 | Pdk4,Bgn,Unc93b1,Rfx4,Ccr5,Phkg1,Slc38a3,Pax6,Chil1,Gli3,Thbs4,Ppp1r18,Sh3pxd2b,Lyz2,Cpt1a,Aif1,Pdlim4,Cd33,Lcat,Arhgef19 | Cst3,Glul,Slc1a2,Sparcl1,Camk2a,Cpe,Mt1,Apoe,Mbp,Fth1,Aldoc,Clu,Ttr,Camk2n1,Ckb,Ddn,Rps29,Atp1a2,Scd2,Mt3 |
3 | 101,254,255 | 0.09284 | 418815 | Fam163b,Prox1,Adcy1,Stxbp6,C1ql2,Btbd3,Synpr,Sema5a,Dsp,Eef1a1,Ncdn,Jun,Lrrtm4,Rfx3,Olfm1,Dgkh,Marcksl1,Ncald,Pitpnm2,Nrgn | Il20rb,Tdo2,Col22a1,C1ql2,St3gal1,Plk5,Dsp,Prox1os,Fam163b,Prox1,Rph3al,H2bc6,Lrrtm4,Mcm6,Khdrbs2,Vwa3b,Prdm5,Npnt,Dact1,Stxbp6 | Nrgn,Eef1a1,Ncdn,Olfm1,Ppp3ca,Actb,Tmsb4x,Calm1,Camk2a,Sparcl1,Atp1b1,Adcy1,Fam163b,Tspan7,Ndrg4,Rplp1,Arf3,Camk2n1,Rpl17,Ptk2b |
4 | 101,101,255 | 0.03885 | 175240 | Plp1,Mbp,Gatm,Mobp,Cnp,Cldn11,Fth1,Car2,Ermn,Cryab,Qdpr,Tubb4a,Trf,Plekhb1,Qki,Tspan2,Mal,Bcas1,Tmem88b,Septin4 | Insc,Creb5,Tmem125,Trim36,Hapln2,Pde1c,Gjc2,Prr5l,Gjc3,Sec14l5,Gatm,Nkx6-2,Tmem88b,Adamts4,Plekhh1,Ermn,Plp1,Trim59,Plekhg3,Enpp6 | Mbp,Plp1,Fth1,Mobp,Ptgds,Actb,Gatm,Tubb4a,Cnp,Car2,Cldn11,Tpt1,Scd2,Glul,Qdpr,App,Qki,Ptma,Malat1,Lars2 |
5 | 255,101,254 | 0.02347 | 105862 | Ttr,Ptgds,Enpp2,Tac2,Gng8,Sostdc1,Ecrg4,Zic1,Calb2,Nnat,Dcn,Tmem212,Adcyap1,Gpr151,2900040C04Rik,Necab2,Apod,Nhlh2,Pou4f1,Ace | Tmem212,Kcne2,Cldn2,Dcn,Septin10,Col8a2,Pou4f1,Nhlh2,Gng8,Wif1,Chrna3,Adcyap1,Folr1,Col1a2,Clec3b,Gng14,Sostdc1,Foxc1,Ecrg4,Tac2 | Ttr,Ptgds,Enpp2,Apoe,Cpe,Pcp4,Actb,Eef1a1,Nnat,Psap,Fth1,Tpt1,Cst3,Dbi,Atp1b1,Cox8a,Sparcl1,Clu,Rpl23,Cox7c |
6 | 255,178,101 | 0.00163 | 7366 | Nkx2-2,Abtb2,Myo1d,C030029H02Rik,Pogk,Dusp16,Smco3,Gjb1,Ldlrad3,Rhobtb3,Lrrc8c,Cdr2,Piga,Tjap1,Carns1,Gpt,Prim1,Sh3gl3,Plk3,Cerox1 | Nkx2-2,Abtb2,C030029H02Rik,Myo1d,Dusp16,Smco3,Gjb1,Pogk,Prim1,Ldlrad3,Plk3,Vgll4,Carns1,Gpt,Letm2,Cdr2,Piga,Fign,Lmln,Tjap1 | Mbp,Fth1,Pogk,Malat1,Qdpr,Plp1,Myo1d,Tubb4a,Abtb2,Rps27a,Rhobtb3,Glul,Gatm,Nkx2-2,Sh3gl3,Alkbh5,C030029H02Rik,Smco3,Tpt1,Gjb1 |
7 | 178,255,101 | 0.00073 | 3290 | Sst,Crhbp,Npy,Cort,Reln,Uhrf1bp1,Rab3b,2310010J17Rik,Elfn1,Lypd6b,Lgals1,Rpp25,Gad2,Cdh13,Clic5,Cenpf,Dlx1,Bcam,Foxred2,Sec14l5 | Sst,Uhrf1bp1,Crhbp,Cort,Reln,Lypd6b,2310010J17Rik,Elfn1,Rab3b,Npy,Clic5,Rpp25,Cenpf,Bcam,Lgals1,Sec14l5,Dlx1,Foxred2,Gpc3,Cdh13 | Sst,Npy,Crhbp,Atp1b1,Reln,Cort,Zwint,Gad2,Rab3b,Syt1,2310010J17Rik,Snap25,Sparcl1,Atp1a3,Oxr1,Scg2,Mdh1,Atp6v0c,Atp6v1e1,Vgf |
9 | 101,178,255 | 0.0004 | 1817 | Hba-a2,Hbb-bs,Hba-a1,Hbb-bt,Tent5c,Polr2l,Aven,Tinagl1,Map2k3,Rgs6,Bst2,Zfp318,Stk40,Plekha8,Ube2l6,Rad50,Slc12a4,Kank2,Srgap1,Klf2 | Hba-a1,Hbb-bs,Hbb-bt,Hba-a2,Tent5c,Polr2l,Aven,Tinagl1,Map2k3,Rgs6,Bst2,Slc12a4,Stk40,Ube2l6,Plekha8,Kank2,Rad50,Zfp318,Prtg,Srgap1 | Hba-a2,Hbb-bs,Hba-a1,Hbb-bt,Polr2l,Atp1b1,Camk2a,Plekhb1,Tent5c,Rpl31,Praf2,Tpd52,Ptgds,Ddn,Fth1,Calm3,Rpl38,Mobp,Psme3,Mkrn1 |
8 | 0,223,95 | 5e-05 | 214 | Sass6,Recql5,Jmjd4,A230072C01Rik,Zfp583,Eef1akmt2,Rnaseh2b,Orc6,Akap10,Mak16,Slc25a35,Dclre1b,C130074G19Rik,Fbxw4,Arhgap10,Il17ra,Zbtb2,Katnip,Hook2,Ints6l | Sass6,Recql5,Jmjd4,A230072C01Rik,Zfp583,Rnaseh2b,Eef1akmt2,Akap10,Orc6,Slc25a35,Dclre1b,C130074G19Rik,Mak16,Arhgap10,Il17ra,Fbxw4,Katnip,Zbtb2,Hook2,Ints6l | Sass6,Recql5,Jmjd4,Cst3,Mak16,A230072C01Rik,Orc6,Tmsb4x,Zfp583,Hexb,Eef1akmt2,Capzb,Gabarapl1,Mdh2,Odc1,Rpl6,Olfm1,Rps8,Golga1,Zfp106 |
Packed SGE and Spatial Factor Outputs from run_cartload2
¶
The packed SGE data and spatial factor inferences generated by FICTURE
are available in PMTile format on Zenodo: DOI:10.5281/zenodo.15759403.
These datasets can also be loaded directly using the following catalog YAML file:
https://zenodo.org/records/15802634/catalog.yaml