BSTVDJ Pipeline User Guide

1 Introduction

To date, spatial transcriptomics has achieved major advances in scientific research and plays a very important role in revealing tissue development and disease mechanisms, but its application in the field of immune repertoire research remains limited, with few published results. The lack of corresponding technology products has constrained research in spatial immunomics.

The immune repertoire consists of T-cell receptors (TCRs) and B-cell receptors (BCRs), enabling the immune system to recognize and respond to a wide range of antigens. This diversity is generated during the maturation of T cells and B cells through the rearrangement of variable (V), diversity (D) and joining (J) segments, forming unique and heritable TCR and BCR sequences. Upon antigen recognition, T cells and B cells undergo clonal expansion, a hallmark of immune activation that can be analyzed by TCR and BCR sequencing. The composition and organization of the immune repertoire differ markedly across tissue environments, highlighting the importance of studying the immune repertoire in a spatial context. In addition, spatial analysis of the immune repertoire can reveal the mechanisms by which antigen-specific immune responses are coordinated within tissues, providing key insights into antigen recognition and immune system development. Developing spatial immune repertoire technology is therefore an important step toward advancing basic immunology research and unlocking new clinical applications.

Now the BMK spatial immune repertoire product developed by BMK Manufacturing will fill this technology gap. The BMK spatial immune repertoire chip can simultaneously capture 3′-end transcriptome information as well as full-length B-cell receptor (BCR) and T-cell receptor (TCR) sequences on the original slide.

The BMK single-cell-level spatial immune repertoire product addresses the transcriptome and tissue morphology as a whole, achieving high-fidelity localization and spatial lineage tracing of B-cell and T-cell clones in human lymphoid tissues and tumor tissues. It may advance our understanding of lymphocyte spatial dynamics in various clinically relevant phenomena such as infection, vaccination and cancer.

2 Environment Configuration

2.1 Conda installation

Download:
wget https://repo.anaconda.com/miniconda/Miniconda3-py39_4.12.0-Linux-x86_64.sh

Run after the download completes (install by following the prompts)
sh Miniconda3-py39_4.12.0-Linux-x86_64.sh

After installation, run the following commands
source ~/.bashrc

2.2 Conda environment configuration

conda create -n (environment name) python=3.9
Activate the environment:
conda activate (environment name)

Add a mirror source
conda config –add channels https://mirrors.bfsu.edu.cn/anaconda/cloud/bioconda/
conda config –add channels https://mirrors.bfsu.edu.cn/anaconda/cloud/conda-forge/
conda config –add channels https://mirrors.bfsu.edu.cn/anaconda/pkgs/free/
conda config –add channels https://mirrors.bfsu.edu.cn/anaconda/pkgs/main/

View mirror sources
conda config –show channels

2.3 Install python modules

conda install numpy=1.23.4
conda install opencv=4.7.0 #cv2 version 4.0 or later
conda install pandas=2.2.2 #pandas version 1.5.0 or later
conda install matplotlib=3.8.4
conda install tqdm=4.66.4
conda install tifffile
conda install seaborn=0.12.2
conda install pytorch=2.1.1
conda install cellpose=2.2.3 #cellpose version less than 3.0

2.4 Install a specific R version (v4.2)

conda install -c conda-forge r-base=4.2

2.5 Install R packages

conda install -c conda-forge r-matrix=1.5.4
conda install -c conda-forge r-seuratobject=4.1.3
conda install -c conda-forge r-seurat=4.3.0
conda install -c conda-forge r-tibble=3.2.1
conda install -c conda-forge r-broom=1.0.5
conda install -c conda-forge r-purrr=1.0.1
conda install -c conda-forge r-cowplot=1.1.1
conda install -c conda-forge r-cluster=2.1.4
conda install -c conda-forge r-ggpubr=0.6.0
conda install -c conda-forge r-htmlwidgets=1.6.2
conda install -c conda-forge r-dplyr=1.1.0
conda install -c conda-forge r-kableextra=1.3.4
conda install -c conda-forge r-knitr=1.42
conda install -c conda-forge r-rmarkdown=2.20
conda install -c conda-forge r-optparse=1.7.3
conda install -c conda-forge r-plotly=4.10.4
conda install -c conda-forge r-shiny=1.8.0
conda install -c conda-forge r-patchwork=1.2.0
conda install -c conda-forge r-reshape2=1.2.0
conda install -c conda-forge r-htmltools=0.5.4
conda install -c conda-forge r-tibble=3.2.0
conda install -c conda-forge r-viridis=0.6.4
conda install -c conda-forge r-ggplot2=3.4.0
conda install -c conda-forge r-crosstalk=1.2.0
install.packages(‘DT’)

2.6 Install other software

conda install bioconda seqkit
conda install bioconda::igblast
conda install -c conda-forge imagemagick

3 Configuration File

####data (BCR third-generation sequencing data and TCR third-generation sequencing data)
CCS_IG /path/IG.ccs.fastq.gz
CCS_TR /path/TR.ccs.fastq.gz

## AllheStat.py (tissue identification parameter; provide at least one of the HE staining image and the tissue fluorescence image)
HE /path/to/HE.tif

## out put (output directory and output file prefix)
OUTDIR /path/to/result/dir/
PREFIX outfile-prefix

## fastq2BcUmi
Threads 16 ## Threads
BCType V2 ## barcode version type (usually the V2 version)
CHIP S1000 ##S1000/S3000

####BSTMatrix
LinkBcChip /path/03.LinkBcChip/ ## second-generation bc position folder
CellSplit /path/07.CellSplit/ ## second-generation cell segmentation folder

##enviroment python; if not provided, the version in the system environment is used (comment out the following parameters if not provided)
PYTHON /path/to/python/dir/

4 Pipeline Description

The pipeline consists of 5 steps, as follows:

Step 1: Identify the barcodes and UMIs in the fastq data, identify the barcode information of the fluorescence data and map it to positions on the chip, and process the HE images;
Step 2: Identify the immune repertoire genes of BCR and TCR (V, D, J, C), CDR3aa, etc.;
Step 3: Build expression matrices of different clonotypes at different levels and at the cell level;
Step 4: Basic statistics such as clonotypes (compatible with tools such as vdjtools);
Step 5: Web report and backup of results.
-c config.txt Data configuration file
-s Step selection. 0 runs all steps 1–5; individual steps can also be selected and run separately, with multiple steps separated by ”,”.

Reference commands:

./vdjMatrixPB -c config.txt -s 0
./vdjMatrixPB -c config.txt -s 1,2,3,4,5

vdjMatrixPB

Description:
Version:v1.0.0

Usage:
-c config <file> must be given
-s run step <int> must be given
step number:
0: run all step
1: run BSTMatrixPB
2: run IgBlast
3: run CreateMatrix
4: run Basic stat
5: run web report

-h Help document

5 Description of Results

Result/
├── 01.BSTMatrixPb ## Step 1 output directory
│ ├── xx ## IG and TR analysis directory
│ │ ├── 01.cutread1 ## read1 identification, trimming and short-sequence filtering
│ │ │ └── xx.cut.ccs.fastq ## Data after trimming read1 and filtering out short sequences
│ │ ├── 02.fastq2BcUmi ## Sequence barcode and UMI detection result directory
│ │ │ ├── xx.bc_dist ## Statistics file of the different barcodes detected
│ │ │ ├── xx.bc_stat ## Statistics file of the different barcodes detected
│ │ │ ├── xx.bc_type_cor.info ## V2AB barcode correction information file
│ │ │ ├── xx.bc_type_cor.umi ## File of barcode types and UMIs corresponding to reads after V2AV barcode correction
│ │ │ ├── xx.bc_umi_read.tsv ## Statistics file of barcode types with their corresponding UMIs and read counts
│ │ │ ├── xx.bc_umi_read.tsv.id ## File of barcode types with their corresponding UMI and read IDs
│ │ │ ├── xx.filter ## File of reads whose barcodes were not fully identified
│ │ │ ├── xx.full_stat ## File of read and UMI counts for each barcode type
│ │ │ ├── xx.id_map ## File of ID number correspondence
│ │ │ ├── xx.qual.stat ## reads statistics file
│ │ │ ├── xx.select_id ## File of read IDs with fully identified barcodes and UMIs
│ │ │ ├── xx.stat ## barcode detection statistics file
│ │ │ ├── xx.umi ## File of barcode types and UMIs corresponding to reads
│ │ │ └── xx.umi_cor.info ## UMI correction information file
│ │ ├── 03.LinkBcChip ## barcode spatial localization result directory
│ │ │ ├── xx.barcode_pos.tsv ## File of chip positions corresponding to barcode types
│ │ │ ├── xx.barcode.tsv ## File of barcode types corresponding to the chip
│ │ │ └── ngsbcpos.tsv ## Second-generation barcode position file
│ │ ├── 04.AllheStat ## tissue expression analysis result directory
│ │ │ ├── allhe ## tissue region information directory
│ │ │ │ ├── he_roi_small.png ## png image file after HE tissue region identification
│ │ │ │ ├── he_roi.tif ## tif image file after HE tissue region identification
│ │ │ │ ├── roi_heAuto.json ## tissue region json file
│ │ │ │ └── stat.txt ## tissue region statistics file
│ │ │ ├── heAuto_level_matrix ## directory of barcode positions at different resolution levels for the tissue region
│ │ │ │ └── subdata ## directory of barcode positions at different resolution levels for the tissue region
│ │ │ └── level_matrix ## directory of expression matrices at different chip resolution levels
│ │ │ └── level_* ## directory of expression matrices at different chip resolution levels
│ │ └── XX ## raw expression matrix result directory
│ │ ├── barcode_pos.tsv ## File of barcodes and their corresponding chip positions
│ │ └── barcode.tsv ## barcode file
├── 02.IgBlast ## Step 2 output directory
│ ├── xx ## IG and TR immune repertoire analysis results
│ ├── xx.barcode.cdr3aa.xls ## CDR3aa results at the barcode level
│ ├── xx.barcode.chain.xls ## Results for different chains at the barcode level
│ ├── xx.barcode.Productive.xls ## Productive results at the barcode level
│ ├── xx.barcode.stat.xls ## Statistics at the barcode level
│ ├── xx.blast.xls ## Raw IgBlast analysis results (airr format)
│ ├── xx.ccs.stat ## Basic statistics of the CCS data
│ ├── xx.fa ## CCS data in fasta format
│ ├── xx.read.clontype.xls ## Clonotype results at the reads level
│ ├── xx.read.result.xls ## Collated results at the reads level
│ ├── xx.read.stat.xls ## Statistics at the reads level
│ └── xx.valid.barcode ## Valid barcode information
├── 03.Matrix ## Step 3 output directory
│ ├── xx.XX ## IG/TR results
│ ├── Cell ## Cell segmentation level results
│ │ ├── Cell.csv ## Clonotype results at the cell level (csv format)
│ │ ├── Cell_matrix ## Clonotype matrix results at the cell level
│ │ │ ├── barcodes_pos.tsv.gz ## cell-level position file
│ │ │ ├── barcodes.tsv.gz ## cell-level barcode file
│ │ │ ├── features.tsv.gz ## cell-level clonotype file
│ │ │ ├── he_roi_small.png ## thumbnail of the HE image
│ │ │ └── matrix.mtx.gz ## cell-level matrix file
│ │ ├── Cell.rds ## cell-level clonotype rds file
│ │ ├── Cellsum.csv ## cell-level clonotype cumulative sum file
│ │ ├── xx.Cell.cdr3aa.xls ## CDR3aa results at the cell level
│ │ ├── xx.Cell.chain.xls ## Results for different chains at the cell level
│ │ ├── xx.Cell.Productive.addCgene.xls ## Productive results at the cell level (with C-region genes added)
│ │ ├── xx.Cell.Productive.xls ## Productive results at the cell level
│ │ ├── xx.Cell.stat.xls ## Statistics at the cell level
│ │ └── xx.read.addCell.result.xls ## Collated results at the cell level
│ ├── Cell.xls ## Correspondence between barcodes and cell IDs
│ ├── L* ## Results at different levels
│ │ ├── L*.csv ## Clonotype results at different levels (csv format)
│ │ ├── L*_matrix ## Clonotype matrix results at different levels
│ │ │ ├── barcodes_pos.tsv.gz ## position file at different levels
│ │ │ ├── barcodes.tsv.gz ## barcode file at different levels
│ │ │ ├── features.tsv.gz ## clonotype file at different levels
│ │ │ ├── he_roi_small.png ## thumbnail of the HE image
│ │ │ └── matrix.mtx.gz ## matrix file at different levels
│ │ ├── L*.rds ## clonotype rds file at different levels
│ │ ├── xx.L*.cdr3aa.xls ## CDR3aa results at different levels
│ │ ├── xx.L*.chain.xls ## Results for different chains at different levels
│ │ ├── xx.L*.Productive.addCgene.xls ## Productive results at different levels (with C-region genes added)
│ │ ├── xx.L*.Productive.xls ## Productive results at different levels
│ │ ├── xx.L*.stat.xls ## Statistics at different levels
│ │ └── xx.read.addL*.result.xls ## Collated results at different levels
│ └── L*.xls ## Correspondence between barcodes and different levels
├── 04.Basic_stat ## Step 4 output directory
│ └── xx ## IG and TR clonotype statistics (compatible with the vdjtools analysis tool)
│ ├── *.clonotype.xls ## Clonotype results
│ └── xx.chain.clonotype.num.xls ## Clonotype count statistics for heavy and light chains
├── 05.Web_Report ## Step 5 output directory
│ ├── Readme.txt ## Readme file
│ ├── result ## result directory
│ │ └── xx ## IG/TR result file
│ │ ├── clonotype ## Clonotype results
│ │ ├── rds ## rds results
│ │ ├── xx.blast.xls ## Raw immune repertoire results from IgBlast analysis
│ │ ├── xx.Cell.Productive.xls ## Productive results at the cell level
│ │ ├── xx.Cell.Productive.addCgene.xls ## Productive results at the cell level (with C-region genes added)
│ │ └── xx.read.result.xls ## Collated results from IgBlast analysis
│ └── xx.report.html ## Report
└── config.txt ## Configuration file