Fullscope

Fullscope is the reference software for Fullscope-seq, a full-length, single-molecule, large-field-of-view spatial transcriptomics method. The software processes Stereo-seq-compatible long-read data from concatenated cDNA segmentation through spatial CID assignment and optional transcript annotation.

Associated paper:

Liu H, Hong Y, Zhang YS, et al. Full-length single-cell spatial transcriptomics reveals spatial and cell-type-specific transcript isoforms in the primate brain. Nature Methods (2026). https://doi.org/10.1038/s41592-026-03174-y

What is included

• A C++23 core for:
  • programmed-concatemer FASTQ segmentation;
  • CID extraction from FASTQ or BAM;
  • fast and precise CID-index construction;
  • error-tolerant CID mapping.
• Portable command-line wrappers for:
  • FASTQ/BAM input;
  • Stereo-seq barcode-index preparation;
  • splice-aware alignment;
  • optional Bambu or IsoQuant transcript annotation;
  • merging transcript assignments with spatial coordinates;
  • single-sample and Slurm batch execution.
• Small test data and a smoke test.
• Analysis notebooks used for the associated study.

Workflow

concatenated long-read FASTQ or BAM
|
v
cDNA segmentation (C++)
|
+----------+-----------+
| |
v v
CID extraction/mapping splice-aware alignment
| |
| Bambu or IsoQuant
+----------+-----------+
|
v
spatially resolved transcript assignments

Installation

Recommended: conda or mamba

Fullscope is supported on 64-bit Linux. The build requires a C++23 compiler, CMake, SeqAn3, cereal and HTSlib. The supplied core environment installs the build and command-line dependencies; a complete environment with the optional R/Bambu stack is also provided.

git clone https://github.com/wwei-lab/Fullscope.git
cd Fullscope
mamba env create -f environment-core.yml
conda activate fullscope
bash install.sh --prefix "$CONDA_PREFIX"

If mamba is unavailable, replace the first command with:

conda env create -f environment-core.yml

The core environment supports segmentation, CID processing, and alignment. To also install the optional R/Bambu transcript-annotation dependencies, create the complete environment instead:

mamba env create -f environment.yml
conda activate fullscope
bash install.sh --prefix "$CONDA_PREFIX"

IsoQuant is kept in a small separate environment to avoid changing the tested R/Bioconductor dependency set used by Bambu. Install it once and provide its executable to Fullscope:

mamba env create -f environment-isoquant.yml
ISOQUANT_BIN="$(conda run -n fullscope-isoquant which isoquant.py)"

Confirm the installation:

fullscope --help
fullscope segment --help
fullscope --version

Build with an existing environment

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel 8
cmake --install build --prefix "$HOME/.local"export PATH="$HOME/.local/bin:$PATH"

Smoke test

The bundled smoke test runs segmentation on 20 reads and does not require a reference genome or Stereo-seq mask:

bash tests/smoke_test.sh "$(command -v fullscope)"

A successful run ends with Smoke test passed.

HTSlib or zlib detection errors

If an older or manually assembled Conda environment reports that htslib or its zlib dependency is missing, repair the active environment and rebuild:

mamba install -c conda-forge -c bioconda htslib zlib
rm -rf build
bash install.sh --prefix "$CONDA_PREFIX"

Fullscope 1.2.1 and later also fall back to locating the HTSlib headers and shared library directly when a usable Conda installation is present but its pkg-config metadata is incomplete.

Quick start

1. Segmentation only

Use this mode to validate installation or to split concatenated cDNA reads before downstream processing:

fullscope segment \
--raw-fq reads.fastq \
--out results/sample_fragment.fastq \
--threads 8

The packaged adapter and anchor FASTA files are used automatically. Override them only when the library design differs:

fullscope segment \
--raw-fq reads.fastq \
--out results/sample_fragment.fastq \
--adapter-fa custom_adapters.fa \
--anchor-fa custom_anchor.fa \
--segthreshold 0.15 \
--threads 8

2. Complete workflow from FASTQ

Full CID-index creation requires ST_BarcodeMap, which is maintained separately and is not bundled with Fullscope.

fullscope run \
--sample sample01 \
--outdir results/sample01 \
--raw-fq reads.fastq.gz \
--stereoindex sample01.barcodeToPos.h5 \
--barcode-map /path/to/ST_BarcodeMap \
--genome reference/genome.fa \
--gtf reference/genes.gtf \
--threads 32

Both uncompressed FASTQ and .fastq.gz input are accepted. Gzipped input is decompressed into the sample output directory before C++ processing.

3. Complete workflow from BAM

fullscope run \
--sample sample01 \
--outdir results/sample01 \
--input-bam reads.bam \
--stereoindex sample01.barcodeToPos.h5 \
--barcode-map /path/to/ST_BarcodeMap \
--genome reference/genome.fa \
--gtf reference/genes.gtf \
--threads 32

4. Add transcript annotation and spatial merge

fullscope run \
--sample sample01 \
--outdir results/sample01 \
--raw-fq reads.fastq.gz \
--stereoindex sample01.barcodeToPos.h5 \
--barcode-map /path/to/ST_BarcodeMap \
--genome reference/genome.fa \
--gtf reference/genes.gtf \
--run-bambu \
--merge-annot \
--threads 32

Use IsoQuant instead of Bambu by selecting --run-isoquant. Fullscope runs reference-annotation quantification (--no_model_construction) and retains IsoQuant's assignment class for every read:

fullscope run \
--sample sample01 \
--outdir results/sample01 \
--raw-fq reads.fastq.gz \
--stereoindex sample01.barcodeToPos.h5 \
--barcode-map /path/to/ST_BarcodeMap \
--genome reference/genome.fa \
--gtf reference/genes.gtf \
--run-isoquant \
--isoquant-bin "$ISOQUANT_BIN" \
--merge-annot \
--threads 32

To compare annotators without repeating segmentation, CID mapping, or genome alignment, reuse the existing checkpoints:

fullscope run \
--annotation-only \
--sample sample01 \
--outdir results/sample01 \
--fqalign results/sample01/Alignment/sample01_ont.sorted.bam \
--cidmap results/sample01/CIDmap/sample01 \
--genome reference/genome.fa \
--gtf reference/genes.gtf \
--run-isoquant \
--isoquant-bin "$ISOQUANT_BIN" \
--merge-annot \
--threads 32

Configuration

For repeated runs, copy the portable example and fill in local reference paths:

cp fullscope_toolkit/config/config.example.env site.env

Then run:

fullscope run \
--config-env site.env \
--sample sample01 \
--outdir results/sample01 \
--raw-fq reads.fastq.gz \
--stereoindex sample01.barcodeToPos.h5

Command-line flags take precedence over values loaded from the configuration file.

Main workflow options

Option	Description
--sample NAME	Sample identifier; required.
--outdir PATH	Sample output directory; required.
--raw-fq PATH	Input FASTQ or FASTQ.GZ.
--input-bam PATH	Input BAM; used when FASTQ is not supplied.
--stereoindex PATH	Stereo-seq barcodeToPos.h5 mask.
--genome PATH	Reference genome FASTA.
--gtf PATH	Gene annotation GTF.
--barcode-map PATH	ST_BarcodeMap executable.
--threads N	Worker threads; default is 32 or SLURM_CPUS_PER_TASK.
--segthreshold X	Segmentation error threshold; default is 0.15.
--adapter-fa PATH	Override the packaged adapter FASTA.
--anchor-fa PATH	Override the packaged anchor FASTA.
--segment-only	Stop after cDNA segmentation.
--annotation-only	Reuse --fqalign and --cidmap and run only annotation/merge.
--fragment-out PATH	Explicit segmentation output path.
--skip-index	Reuse an existing precise CID index.
--skip-fastq	Reuse an existing converted/decompressed FASTQ.
--run-bambu	Run Bambu transcript annotation.
--run-isoquant	Run IsoQuant reference-isoform annotation; mutually exclusive with --run-bambu.
--isoquant-bin PATH	IsoQuant executable; defaults to isoquant in PATH.
--isoquant-output-dir PATH	IsoQuant output root; default OUTDIR/IsoQuant.
--isoquant-prefix NAME	IsoQuant output prefix; default sample name.
--isoquant-genedb-output PATH	Local cache for IsoQuant's converted GTF database.
--isoquant-assignments PATH	Override the expected IsoQuant read_assignments.tsv.gz checkpoint.
--isoquant-read-info PATH	Legacy alias for --isoquant-assignments.
--isoquant-max-coverage-small-chr N	Small-chromosome coverage threshold; default -1 disables IsoQuant downsampling so all reads are retained.
--bambu-min-read-length N	Minimum query length retained for Bambu; default 200.
--bambu-max-read-length N	Maximum query length retained for Bambu; default 20,000.
--bambu-bam PATH	Explicit filtered BAM checkpoint/output path.
--skip-bambu-filter	Disable the default primary-mapped/read-length filter.
--merge-annot	Merge selected annotator assignments with spatial CID results.
--config-env PATH	Load site-specific defaults.
--version	Print the toolkit version.

Run fullscope run --help for the complete parser-supported interface, including explicit intermediate-file overrides.

Unified command

Fullscope has one public command with two processing modes:

fullscope run [options] complete spatial-transcriptomics workflow
fullscope segment [options] cDNA segmentation only

For convenience, complete-workflow options can also be passed directly, for example fullscope --sample sample01 .... The compiled C++ engine is installed as an internal component and is not part of the public command-line interface.

Starting with version 1.2.0, fullscope run replaces fullscope-ont, and fullscope segment replaces fullscope-segment.

The toolkit uses the precise build_idx p and map_p path by default.

Slurm

The packaged Slurm script intentionally contains no cluster-specific partition or memory setting. Supply those values through FULLSCOPE_SBATCH_ARGS:

FULLSCOPE_SBATCH_ARGS="--partition=compute --mem=300G --cpus-per-task=32" \
fullscope-submit \
--sample sample01 \
--outdir results/sample01 \
--raw-fq reads.fastq.gz \
--stereoindex sample01.barcodeToPos.h5 \
--config-env site.env

For multiple samples:

cp fullscope_toolkit/config/samples.example.tsv samples.tsv
fullscope-batch \
--config-env site.env \
--samples samples.tsv \
--sbatch-extra "--partition=compute --mem=300G"

Outputs

A complete run creates:

results/sample01/
Index/ CID whitelist and precise index
Fqsegment/ segmented full-length cDNA reads
CIDextract/ per-read CID candidates
CIDmap/ mapped spatial CIDs
Alignment/ splice-aware BAM and index
Bambu-filtered primary mapped BAM and filter counts
Bambu/ optional transcript assignments
IsoQuant/ optional read assignments, normalized QS, and class summary
raw_fastq/ BAM-converted or decompressed FASTQ, when needed
*_fsraw_merged_data.qs
*_fsraw_merged_data_uniquereads.qs
*_isoquant_fsraw_merged_data.qs
*_isoquant_fsraw_merged_data_uniquereads.qs

The two .qs matrices contain transcript/gene annotation and spatial x, y coordinates. IsoQuant's all-assignment matrix preserves multiple candidate rows and assignment-type metadata for ambiguous reads. The corresponding uniquereads matrix retains reads mapping to exactly one distinct transcript, matching the existing Bambu merge rule. An assignment_summary.tsv file reports read, gene, and transcript counts by IsoQuant assignment class.

For a direct Bambu/IsoQuant ambiguity comparison, run the installed helper:

Rscript "$CONDA_PREFIX/share/fullscope/scripts/compare_isoform_assignments.R" \
results/sample01/Bambu/sample01_trans_total_anno.qs \
results/sample01/IsoQuant/sample01_trans_total_anno.qs \
results/sample01/sample01_bambu_vs_isoquant.tsv \
sample01

Repository layout

Fullscope/
scripts/src/ C++ implementation
scripts/include/ C++ headers
fullscope_toolkit/
bin/ user-facing command wrappers
scripts/ workflow, Slurm and R scripts
config/ portable configuration examples
refdata/ default adapter and anchor sequences
testdata/ small smoke-test FASTQ
tests/smoke_test.sh
analysis_script/ study analysis notebooks
Segmentation_script/ legacy segmentation workflow
CMakeLists.txt
environment.yml
install.sh

Reuse notes

• Fullscope does not bundle reference genomes, gene annotations, Stereo-seq mask files or ST_BarcodeMap.
• Memory and runtime depend on read count, CID-whitelist size, thread count and the selected long-read platform. Validate a small subset before a full run.
• The bundled smoke data validates installation and segmentation, not a biological end-to-end result.
• Preserve the editable configuration used for each run and record the Fullscope version with fullscope --version.

Archived version

The code associated with the publication is archived at Zenodo.

License

Fullscope is distributed under the Apache License 2.0.