Pixel-Seq Starter Tutorial

Input Data

Since the Pixel-Seq publication provides SGE data only from the mouse olfactory bulb and parabrachial nucleus — neither of which includes the hippocampus — we extract a subregion from the olfactory bulb as the input for this tutorial.

File Format

The Pixel-Seq SGE includes one tab-delimited text file, where each row represents a unique RNA molecule detected within a defined field of view (FOV), with associated genomic and spatial metadata.

TSV file format

FOVx  FOVy  xcoord     ycoord     UMIs     SpatialBarcode            MapStrand  Chrom  Start      STARmapping        Counts  geneID              geneName  bioType                 intronRatio
017   005   26691.5    5786.5     TAACGAA  AAGGTTCATACCTACGACTGTTAA  16         1      24613729   150M               1       ENSMUSG00000101111  Gm28437   unprocessed_pseudogene  0.00
016   007   27590.25   4639.0815  TAATATA  AATGGCGCATTTTGCTGTTTAGGC  16         2      39001628   138M2341N12M       1       ENSMUSG00000062997  Rpl35     protein_coding          0.00
018   006   25099.945  5621.8335  AGTTGTA  CTGCATATGTGTCACCTAGGTAGC  16         1      24615767   150M               1       ENSMUSG00000101249  Gm29216   unprocessed_pseudogene  0.00

• FOVx, FOVy: Field-of-view indices indicating the imaging tile coordinates in the x and y directions.
• xcoord, ycoord: Spatial coordinates (in microns or pixels).
• UMIs: Unique molecular identifier (UMI) sequence.
• SpatialBarcode: Spatial barcode capturing the location and identity.
• MapStrand: Indicates the strand orientation of the mapped read.
• Chrom, Start: Chromosome number and start position of the mapped read on the genome.
• STARmapping: Alignment pattern (CIGAR string) from the STAR aligner indicating how the transcript maps to the genome.
• Counts: Number of times the UMI/gene combination was observed.
• geneID, geneName: Ensembl gene ID and gene symbol.
• bioType: Gene biotype.
• intronRatio: Fraction of UMI counts assigned to intronic regions.

Data Access

The example data is hosted on Zenedo ().

Follow the commands below to download the example data.

work_dir=/path/to/work/directory
cd $work_dir
wget  https://zenodo.org/records/15786632/files/pixelseq_starter.raw.tar.gz 
tar --strip-components=1 -zxvf pixelseq_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.

# ====
# 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:

# Unique identifier for your dataset
DATA_ID="pixelseq_hippo"                # change this to reflect your dataset name
PLATFORM="pixel_seq"                    # platform information
SCALE=3.076923                        # 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 Pixel-Seq?

In Pixel-Seq publication:

"Because polonies have varied sizes and shapes, to maximize the feature resolution we developed a base-calling pipeline to determine the major barcode species in each pixel (0.325 * 0.325 mm2) of gel images to construct a spatial barcode map".

Accordingly, we defined scale as 1/0.325 = 3.076923

SGE Format Conversion

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

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.

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)

_{¹: 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.

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:

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

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.

Factor	RGB	Weight	PostUMI	TopGene_pval	TopGene_fc	TopGene_weight
0	255,101,101	0.25229	2026474	Dbi,Cox6c,Cst3,Cox4i1,Rpl37,Rps23,Rps13,Rps19,Vps8,Rpl32,Uqcrb,Rps23-ps1,Rpl41,Atp5md,Rps27a,Rpl39,Mt3,Rpl13,Fth1,Rpl35	C230013L11Rik,Asb5,Arhgap27os1,Pdgfrb,Kcp,Ccl4,Xylt1,Cmpk2,9430091E24Rik,Zfx,Afap1l1,Cobll1,1110046J04Rik,Nde1,Mob1a,Ccl12,Slc14a1,Atp13a4,Armt1,Zfp78	Dbi,Atp5md,Cox6c,Cst3,Tmsb4x,Ndufa4,Cox4i1,Rpl41,Uqcrb,Vps8,Rpl37,Mt3,Atp5mpl,Rps23,Rpl32,Fth1,Rps23-ps1,Cox7a2,CT010467.1,Rps27a
1	237,238,0	0.1761	1414501	Pcp4,Calm2,Itm2b,Snap25,Ddx5,Ss18l2,Gad1,Slc25a3,Hnrnph1,Mdh1,Psma1,Sf3b1,Gpsm1,Aldoa,Grin2a,Ptpro,Focad,Ckb,Hnrnpm,Srsf5	Myo19,Adamts15,Exoc8,Esm1,Snora31,Pcdhb7,Osgin2,Tmem28,Hmgxb4,Pcdhb11,Bod1l,Zfp951,Ppp1r21,Rbm19,Ovgp1,Tmco6,Mroh8,Atp10a,Zbtb6,Fgf16	Pcp4,Calm2,Tmsb4x,Atp5md,Ubb,Ndufa4,Cox7a2,Atp5o,Ckb,Cox4i1,Cox6c,Calm1,Dynll1,Mdh1,Atp5mpl,Itm2b,Ndufb4,Eif1,Snap25,Rpl41
2	101,255,101	0.12776	1026174	Rps25,Pcp4,Rps27,Rps15a,Rpl34,Dynll1,Gas5,Rps24,Rps27rt,Uqcrh,Rps7,Rps14,Rpl36a,Rpl7,Timm8b,Rpl30,Sec61g,Krt10,Atp5l,Ndrg3	Pkp2,Arrdc4,Xlr,Ccdc116,Mchr1,AV039307,A830031A19Rik,Fam183b,Myl2,R3hcc1l,Ikzf2,Birc5,Dok2,Cdc42ep5,Smad4,Frmd8os,Zfp85os,A830073O21Rik,Ccdc177,Rbm43	Pcp4,Rps25,Rps15a,Rps27,Atp5md,Dynll1,Rps24,Rps14,Gas5,Rpl34,Uqcrh,Atp5l,Tmsb4x,Rpl41,Rps23,Rpl37,Rpl36,Rpl37a,Rpl32,Ndufa4
4	101,101,255	0.10851	871555	Cpe,Cck,Ly86,Nmb,Stmn2,Stmn3,Doc2g,Sparcl1,Spp1,Pfn2,Gabra1,Hsp90aa1,Mgst3,Id2,Ptprd,A2ml1,Rab3b,Chgb,Cdhr1,Atp6ap1l	Fam111a,1700101I11Rik,Susd5,Olfr110,C230034O21Rik,Glra2,Col9a1,Myom1,Lrrc75b,Hsf4,Dpys,Cd207,Plcl1,Adam19,Sema3d,Kng1,Hs3st4,Samsn1,Pou3f1,1700086P04Rik	Ndufa4,Atp5md,Stmn3,CT010467.1,Atp5g1,Cst3,Mgst3,Cox7a2,Ubb,Cpe,Cox4i1,Tmsb4x,Mdh1,Calm1,Cck,Vps8,Mt3,Cox6c,Ly86,Uqcrh
3	101,254,255	0.1012	812851	Ptgds,Hbb-bs,Hba-a2,Hba-a1,S100a5,Gng13,Hbb-bt,Fabp7,Apod,Npy,Tmsb4x,Prdx1,Crip1,Apoe,Mt1,S100a8,Mgp,Atox1,Ptn,Acbd7	Lsp1,Olfr1463,Galnt4,Lsr,Hacd4,Thbs2,Gjb2,Sntb1,Ogn,Car13,Dapl1,S100a8,A930037H05Rik,Slc22a6,Grap,Tagln,Ninj2,Igf2,Mfap5,Zc3hav1l	Ptgds,Hbb-bs,Hba-a2,S100a5,Hba-a1,Tmsb4x,Gng13,Fabp7,Dbi,Hbb-bt,Mt1,Rpl41,Cst3,Apoe,Fth1,Prdx1,Mt3,Atp5md,Vps8,Calm1
5	255,101,254	0.09759	783886	Atp5mpl,Uqcrb,Cox7b,Fkbp3,Calb2,Atp5j,Ctsl,Bmerb1,Oaz1,Polr2k,Canx,Ly6g6e,Trh,Ldhb,Vip,Vsnl1,Ndfip1,Nrsn1,Dynlrb1,Gpx4-ps2	2410080I02Rik,Slc24a5,Rapgef3os2,Sycp2,Zfp984,Gpr176,Zfp455,A430018G15Rik,4933412E12Rik,1700047F07Rik,Sowahc,Carns1,Larp1b,Rom1,Slc30a3,Zfp959,Ddx10,Gpr22,Zfp217,Pgm3	Atp5mpl,Uqcrb,Atp5md,Ndufa4,Cst3,S100a5,CT010467.1,Cox7b,Atp5j,Ubb,Cox6c,Rpl41,Uqcr11,Uqcr10,Mt3,Tmsb4x,Atp5o,Ldhb,Cox4i1,Cox7a2
6	255,178,101	0.08203	658867	Igf2bp3,Ogt,Ints6l,Trim9,Mrgbp,Meg3,Tmem29,Pfkp,Clk1,Snhg11,Clk4,Pcp4l1,R3hdm1,Malat1,Atxn7l2,Ckb,Arsb,Matk,Uqcrq,Nptn	Thg1l,Lrrc19,BC024063,Pcdhb8,Utp14b,3110053B16Rik,Bloc1s6os,Ccdc142os,Zbtb26,Nfe2l3,Rgs16,Papolg,Zfp747,Wnt10b,C130073E24Rik,Il20ra,Zfp960,Cenpq,Ascc3,Hcfc2	Ndufa4,Uqcrq,Ckb,Atp5md,Cox6c,Meg3,Cox4i1,Atp5mpl,Ubb,Pcp4,Tmsb4x,Snhg11,Calm2,Uqcr10,Mt3,Uqcrb,CT010467.1,Mt1,Uqcrh,Cox7a2
7	178,255,101	0.02197	176451	Psma4,Smim26,Manf,Ankhd1,Gng11,Skp1a,Ndufa12,Arpc5l,Prdx4,Celrr,Snhg1,Nol7,Eif4a2,Dcun1d1,Mrpl57,Zswim6,Utp15,Med19,Psd3,Pot1b	Cryba4,Wipf1,Tes3-ps,Pot1b,Rnf225,Celrr,D730044K07Rik,4933424L21Rik,Pigw,Pih1d2,Ccdc190,Sec24d,Pcdhb17,Utp15,Mis12,Asb16,Smad2,Dcun1d1,Cst12,6330549D23Rik	Atp5md,Ndufa12,Cox7a2,Rpl31,Ndufb1-ps,Ndufb4,Dynlrb1,Cst3,Cox7c,Fau,Tmsb4x,CT010467.1,Cox7b,Skp1a,Rpl26,Cox6c,Rpl41,Rps24,Slirp,Smim26
8	0,223,95	0.02035	163444	Calm2,Pcp4,Rbbp8,Pcmtd2,Rpl35a,Ak6,Dlx6os1,Immp1l,Top2b,Zfp281,S100a10,Rasa2,Vamp4,Tiam1,Rpn2,Ndufa8,Pak1ip1,Ik,Sft2d3,Psma3	Kirrel2,Slc46a2,Ripk4,Gpr50,9430083B18Rik,Kcnj8,Cdh9,Zfp992,Rbbp8,9230112E08Rik,Znf41-ps,Socs4,Asic3,Plxna4os1,Pdp2,Stat5a,Zfp281,Tfap4,Spdya,Fpgt	Pcp4,Calm2,Rpl35a,Tmsb4x,Atp5mpl,S100a10,Ndufa4,Cox6c,Rps8,Rpl41,Ndufa8,Atp5md,Uqcr11,Immp1l,Rpl37a,Cox7a2,Ckb,Ndufs4,Abcb10,Uqcrq
9	101,178,255	0.00875	70293	Brcc3,Tmsb15l,Rbis,Vps13c,Eid1,Tmsb15b2,Dnajb4,Arpp21,Tent2,Rab10os,Mrpl33,Efr3b,Krt12,Uba3,Arhgap5,Magee1,Cdv3,Steap2,Arsg,Polr3d	Olfm5,Samd11,Vps13c,Zkscan4,Gabrg1,2310034G01Rik,Efcab11,Qrfpr,A230065N10Rik,Prss35,Arsg,Fam199x,Prim2,Fam163a,Npy5r,Acsl5,Klhl28,Tent2,A330041J22Rik,Sertm1	Rbis,Atp5h,Mrpl33,Tmsb15l,Brcc3,Ndufa11,Ubb,Arpp21,Fth1,Atp5md,Tmsb4x,2610001J05Rik,Ndufa4,Dnaja1,Krt12,Ubl5,Polr2j,Cox6c,Slc25a5,Fcf1
10	178,101,255	0.00327	26268	4930522L14Rik,Ano4,Ccdc82,Ctxn2,Trdn,Pdzd8,Dtnbos,Arhgef26,Ephx2,Itgav,Mgat5,Casp1,Zfp950,Crh,Tm2d1,Zfp637,Trim2,Tmem167,Capza2,Gpr135	5430403G16Rik,Dtnbos,4930522L14Rik,Arhgef26,Usp27x,Trdn,Tbc1d10c,Ccdc82,Zfp51,Pdzd8,Gpr135,Wfdc1,Ephx2,4921504A21Rik,Crh,Pou3f4,Ttll3,1700102H20Rik,P2ry14,Gas1	Ndufs5,Tmem167,Cox5b,Ndufs5-ps,Ndufab1,Tm2d1,Cox6c,Itgav,Zbtb20,Ctxn2,Capza2,Cycs,Trim2,Ano4,Cops5,Selenow,Atp5md,Zfp637,Uqcrb,Zcchc18
11	255,153,204	0.00018	1416	1700019G24Rik,Slc26a7,Tmem132cos,Ggh,Pdgfd,Peli2,Reln,Ddit4l,Ifitm1,Lrrfip1,Gin1,Polr2m,Arsk,Map7,Secisbp2l,Lrrcc1,Neu1,Prdm16,Zfp292,Ubxn7	Tmem132cos,1700019G24Rik,Slc26a7,Pdgfd,Ddit4l,Arsk,Ifitm1,Lrrcc1,Peli2,Ggh,Prdm16,Lrrfip1,Map7,Secisbp2l,Polr2m,Gin1,Zfp292,Ubxn7,Neu1,Reln	Reln,Gin1,Ggh,Polr2m,Peli2,Lrrfip1,Slc26a7,1700019G24Rik,Secisbp2l,Gad1,Ifitm1,Map7,Neu1,Selenow,Tmem132cos,Ubl5,Pdgfd,Ddit4l,Penk,Elob

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

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