Skip to content

StereoSeq Starter Tutorial

Input Data

The input data represents mouse hippocampus. For demonstration purposes, we selected the adult mouse brain coronal section from the official release and extracted only the hippocampus region. The full-section data sourced from the Stereo-seq platform, as part of the MOSTA project.

File Format

The StereoSeq SGE includes one tab-delimited “Bin1” gene expression matrix file:

TSV File Format

1
2
3
4
geneID          x       y       MIDCounts
0610005C13Rik   6632    9074    1
0610005C13Rik   8651    8935    1
0610005C13Rik   7228    12814   2
  • "geneID": gene symbols
  • "x": x coordinates of each DNB on the captured chip
  • "y": y coordinates of each DNB on the captured chip
  • "MIDCounts": the number of UMI for each gene at each DNB

Data Access

The example data is hosted on Zenedo ().

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/15786632/files/stereoseq_starter.raw.tar.gz 
tar --strip-components=1 -zxvf stereoseq_starter.raw.tar.gz

Set Up the Environment

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 the fixed color map for rendering. cartloader provides a fixed color map at cartloader/assets/fixed_color_map_256.tsv.

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

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

Define data ID and analysis parameters:

1
2
3
4
5
6
7
8
# Unique identifier for your dataset
DATA_ID="stereoseq_hippo"                # change this to reflect your dataset name
PLATFORM="bgi_stereoseq"                 # platform information
SCALE=2                                  # scale from coordinate to micrometer

# 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 StereoSeq?

According to the StereoSeq paper, the technology features spot sizes of approximately 220 nanometers in diameter with center-to-center distances of about 500 nanometers. Thus, each pixel corresponds to approximately 0.5 micrometers. The scaling factor from coordinate to um is defined as 2.

SGE Format Conversion

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
cartloader sge_convert \
  --makefn sge_convert.mk \
  --platform ${PLATFORM} \
  --in-csv ./input.tsv.gz \
  --units-per-um ${SCALE} \
  --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-csv required string Path to the input TSV/CSV file
--units-per-um required float Scale to convert coordinates to microns (default: 1.0)
--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)

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
cartloader run_ficture2 \
  --makefn run_ficture2.mk \
  --main \
  --in-transcript ./sge/transcripts.unsorted.tsv.gz \
  --in-feature ./sge/feature.clean.tsv.gz \
  --in-minmax ./sge/coordinate_minmax.tsv \
  --cmap-file ${cmap} \
  --exclude-feature-regex '^(mt-.*$|Gm\d+$)' \
  --out-dir ./ficture2 \
  --width ${train_width} \
  --n-factor ${n_factor} \
  --spatula ${spatula} \
  --ficture2 ${punkst} \
  --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 Compilation

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
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}
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
# AWS S3 target location for cartostore
AWS_BUCKET="EXAMPLE_AWS_BUCKET"         # replace EXAMPLE_AWS_BUCKET with your actual S3 bucket name

cartloader upload_aws \
  --in-dir ./cartload2 \
  --s3-dir "s3://${AWS_BUCKET}/${DATA_ID}" \
  --aws ${aws} \
  --n-jobs ${n_jobs}
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
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 \
  --create-new-deposition \
  --title  "Yur 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 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 produced by FICTURE using a training width of 18, 12 factors, a fit width of 18, and an anchor resolution of 6.

FICTURE cmap

Factor RGB Weight PostUMI TopGene_pval TopGene_fc TopGene_weight
0 255,101,101 0.17583 6349542 Apoe,Cst3,Clu,Slc1a2,Shank1,Tubb2a,Sst,Gnb1,Mfge8,Slc1a3,Fam107a,Aldoc,Cspg5,Ptn,Mt2,Prkar1b,Mt1,Scg3,Ptms,Pkm Naip2,Fam167b,Ifi47,Pyroxd2,Pctp,Rrad,Itpripl1,Chst14,Arhgef5,Mhrt,Rbpjl,Gsdmd,Zc3h12a,2310040G24Rik,Cd101,Gchfr,Wdfy4,Rtp1,Fmo2,Krt73 Apoe,Cst3,Slc1a2,Mt1,Actb,Clu,Rpl41,Tubb2a,Tmsb4x,Shank1,Cox8a,Ptms,Snap25,Sparcl1,Cdk8,Rplp1,Aldoc,Pkm,Ppm1e,Itm2c
3 101,254,255 0.13679 4939649 Olfm1,Enc1,Cox5b,Timm8b,Cox6c,Rps21,Cox7a2,Nsg2,Hras,Rps15,Rps17,Cox4i1,Cox8a,Pfn2,Rps15a,Serinc1,Rpl32,Caly,Sub1,Selenow Plet1os,AC113587.1,CT025678.1,C4bp,Myh1,AC161607.1,Fut2,1110006O24Rik,Drd4,Adamts14,Acp7,Prss57,Il17re,Fam229a,Mutyh,Fstl3,Retn,Itga10,0610038B21Rik,Tbc1d10c Tmsb4x,Olfm1,Calm1,Cox6c,Rpl41,Cox4i1,Cox8a,Ubb,Rplp1,Nrgn,Nme7,Fth1,Cox5b,Rtn1,Cox7a2,Rps21,Ndufa4,Calm2,Serinc1,Ptms
1 237,238,0 0.13387 4834133 Nrgn,Tmsb4x,Hpca,Calm2,Cck,Snca,Crym,Ywhab,Ywhah,Nptxr,Cpne6,Dynll1,Selenow,Neurod6,Pde1a,Rtn1,Calm1,Rab6a,Chgb,Lmo4 Lrrn4,Lipg,Zscan2,Krt5,Zfp296,Tymp,Rbm46,Tnfrsf8,Tmem54,5330429C05Rik,Sfrp4,Rln1,A330070K13Rik,Vgll3,Maats1,2410080I02Rik,Slc9a4,Slc23a3,Tbata,Neurod6 Tmsb4x,Nrgn,Calm2,Calm1,Cdk8,Hpca,Snap25,Fth1,Cck,Actb,Rtn1,Ppp3ca,Cpe,Ywhab,Olfm1,Selenow,Snca,Stmn3,Rpl41,Cox6c
4 101,101,255 0.13059 4715949 Lars2,Cdk8,Gphn,Zc3h7a,Cd44,Jarid2,Camk1d,Cmss1,Map1b,Calb2,Hsp90aa1,Nefm,Nap1l5,D130009I18Rik,Ttc3,Rab3c,Tmtc2,Hspa8,Il31ra,Impact Cnga4,Hist1h4c,Ahnak2,2310068J16Rik,B930036N10Rik,Adrb3,Chodl,Actc1,C330018A13Rik,Slc35d3,Zfp114,Hmga2,Fam72a,6430573P05Rik,Atp8b3,Cfap57,Dmrtb1,Crb3,Hist1h4d,Alox8 Cdk8,Lars2,Gphn,Camk1d,Zc3h7a,Jarid2,Cmss1,Cd44,Il31ra,Calm1,Hspa8,Nme7,Snap25,Calm2,Map1b,Hsp90ab1,Stmn3,Ubb,Atp1a3,Gnas
2 101,255,101 0.10222 3691317 Ppp3ca,Ncdn,Pcp4,Olfm1,Dgkh,Adcy1,Rfx3,Synpr,Camk2b,C1ql2,2010300C02Rik,Prox1,Ppp1r1a,Ppfia2,Fam163b,Ahcyl2,Wipf3,Sema5a,C1ql3,Tmsb4x AC118542.1,Nhlh1,Card14,Pla2g2f,Unc13d,Neurog2,Ccdc33,Eomes,Hist1h1d,Hbq1a,Dsp,4930529K09Rik,Lct,AI463170,Rtl3,Rcvrn,Fam160a1,Kif2c,Avp,E130111B04Rik Tmsb4x,Cdk8,Olfm1,Ppp3ca,Fth1,Ncdn,Pcp4,Calm1,Malat1,Actb,Eef1a1,Nrgn,Rpl41,Calm2,Lars2,Ubb,Gphn,Bex2,Camk2b,Rplp1
5 255,101,254 0.08664 3128701 Plp1,Mbp,Mobp,Fth1,Mal,Ptgds,Mag,Cldn11,Cdk8,Pvalb,Trf,Cnp,Qdpr,S100b,Sept4,Mog,Scd2,Sparc,Tspan2,Enpp2 Sox14,5033421B08Rik,Klk6,Asb4,Slc45a3,Hotairm1,Tfap2b,Ctxn3,Rapgef3os2,BC039966,Tex52,C1ql4,Tnfrsf11b,Mab21l2,Lpo,Six3,Il17rb,Tnni1,Emilin2,Serpinb1a Plp1,Cdk8,Fth1,Mbp,Mobp,Ptgds,Lars2,Gphn,Cox4i1,Zc3h7a,Camk1d,Mt1,Sparcl1,Rpl41,Scd2,Ckb,Mal,Tmsb4x,Rpl13a,Mag
7 178,255,101 0.0697 2516994 Mt1,Apoe,Mt2,Cst3,Dbi,Ptgds,Fth1,Aldoc,Ndrg2,Atp1a2,Apod,Cpe,Rps27,Prdx6,Mgp,Agt,S100a13,Cd81,Clu,Rps16 Foxf1,Fgfbp1,Vwa7,Nfatc4,Tnni2,Rassf9,Foxd1,Chrnb3,Irf7,Nid1,Actg2,Inmt,Cav3,Pm20d1,Apoc3,Dennd1c,Tbx1,Mrc1,Siglece,Cyp1b1 Mt1,Apoe,Fth1,Cst3,Cdk8,Cpe,Ptgds,Tmsb4x,Mt2,Actb,Rpl41,Aldoc,Rps27,Plp1,Mbp,Rplp1,Sparcl1,Dbi,Clu,Atp1a2
6 255,178,101 0.06447 2328254 Malat1,Rbfox1,Meg3,Kcnip4,Dlg2,Csmd1,Nrg3,Tenm2,Lrrtm4,Opcml,Fam155a,Lsamp,Fgf14,Nlgn1,Ube3a,Nrxn3,Il1rapl1,Lingo2,Lrp1b,Celf2 Vmn2r86,4930532I03Rik,Pcdhga11,Sorbs2os,Speer4b,Plxna4os2,Olfr1564,Macrod2os2,A730009L09Rik,Pkhd1l1,Zfp955a,Gpr171,Nrg3os,Gdap10,1700026F02Rik,Angptl3,9530059O14Rik,Zfp551,5031415H12Rik,Far1os Malat1,Meg3,Cdk8,Kcnip4,Rbfox1,Lsamp,Dlg2,Nrg3,Csmd1,Tenm2,Celf2,Lrrtm4,Opcml,Cadm2,Nlgn1,Nrxn3,Fam155a,Lrp1b,Ptprd,Nrxn1
8 0,223,95 0.04764 1720217 Camk1d,Il31ra,Lars2,Gphn,Cd44,Prkcd,Ntng1,Pcdh9,Pcp4,Rora,Cmss1,Kcnc2,Plekhg1,Zc3h7a,Jarid2,Synpo2,Fgfr2,Zic1,Ptpn4,Tnnt1 Abhd12b,Vipr2,Ly6g6d,Mctp2,Gpat2,Gckr,Nod2,Smpx,Synpo2,Lpar3,Tnnt1,Rassf6,Atp2a1,Prkcd,Gtf2a1l,6330576A10Rik,Slain1os,Tmcc3os,Slitrk6,Mrvi1 Camk1d,Lars2,Gphn,Il31ra,Cdk8,Cd44,Cmss1,Zc3h7a,Malat1,Jarid2,Pcp4,Pcdh9,Kcnip4,Plp1,Meg3,Fgfr2,Rora,Syt1,Nrxn1,Tmtc2
9 101,178,255 0.03287 1187102 Malat1,Lsamp,Gpc5,Npas3,Ntm,Nrxn1,Slc1a2,Msi2,Rora,Trpm3,Mdga2,Neat1,Mertk,Wdr17,Macf1,Gabrb1,Slc4a4,Ctnnd2,Pitpnc1,Nfia Sfn,AB124611,Mettl11b,Ribc2,Atp13a4,Ttll8,Gpc5,C030018K13Rik,Gli2,Map3k19,4930401C15Rik,Aox1,0610005C13Rik,Rnf17,Sox6,Npas3,Fignl2,9430041J12Rik,Gli3,Gsap Malat1,Lsamp,Cdk8,Slc1a2,Gpc5,Nrxn1,Ntm,Apoe,Rora,Npas3,Pcdh9,Cst3,Zbtb20,Slc1a3,Mdga2,Trpm3,Atp1a2,Macf1,Qk,Mt1
11 255,153,204 0.01217 439414 Sst,Zcchc12,Npy,Nxph1,Tmem91,Dlk1,Cbln2,Gpx3,Slc6a3,Gad2,Ngb,Calca,Ddc,Cort,Pth2,Nap1l5,Slc18a2,Exosc5,Sncg,Tmsb10 Styxl1,4933402D24Rik,Fam167a,Slc12a1,A930024N18Rik,Fam71f2,1700086P04Rik,4632428C04Rik,B430218F22Rik,Ghrh,4930558K02Rik,H2-M3,1500015L24Rik,A230020J21Rik,Cabcoco1,Gpr183,Srpx,C1s1,Calca,Rac2 Sst,Bex2,Npy,Nap1l5,Zwint,Tubb2a,Uchl1,Cdk8,6330403K07Rik,Stmn1,Rps5,Zcchc12,Tmsb10,Lrba,Gad1,Nxph1,Gad2,Ndufa4,Rtn1,Gap43
10 178,101,255 0.0072 260001 Hbb-bs,Hba-a1,Hba-a2,Hbb-bt,Ptgds,Myoc,Gfap,Igkc,Apex2,Igha,Alas2,Igf2,Fam46c,A2m,Apod,Ube2l6,Fmod,Ifitm3,Aspg,Pf4 Hba-a1,Hba-a2,Hbb-bt,Hbb-bs,Chad,Igkc,Alas2,Lyve1,Igha,Fam46c,Myoc,Slc6a12,Aspg,Isg20,Timp1,Slfn2,Lcn2,Fmod,Pf4,A2m Hbb-bs,Hba-a1,Hba-a2,Ptgds,Hbb-bt,Cdk8,Fth1,Mt1,Tmsb4x,Gfap,Apod,Apoe,Camk1d,Mbp,Rpl41,Rplp1,Lars2,Plp1,Mt2,Actb

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.15824948.

These datasets can also be loaded directly using the following catalog YAML file:
https://zenodo.org/records/15824949/catalog.yaml