BSTVDJ软件流程说明

1 前言

截至目前，空间转录组技术在科学研究中已获得重大进展，特别是在揭示组织发育和疾病机理方面扮演了非常重要的角色，但在免疫组库领域的研究应用仍然较少，成果尚不丰硕。相应技术产品的缺乏限制了空间免疫组的研究。

免疫受体库（immune repertoire）由T细胞受体（TCRs）和B细胞受体（BCRs）组成，使免疫系统能够识别并响应广泛的抗原。这种多样性是在T细胞和B细胞成熟过程中通过可变（V）、多样性（D）和连接（J）片段的重排产生的，形成独特且可遗传的TCR和BCR序列。当识别抗原后，T细胞和B细胞会经历克隆扩增，这是免疫激活的标志，可以通过TCR和BCR测序进行分析。免疫受体库的组成和组织在不同组织环境中存在显著差异，这突显了在空间环境中研究免疫受体库的重要性。此外，免疫受体库的空间分析能够揭示抗原特异性免疫反应在组织内的协调机制，为理解抗原识别和免疫系统发育提供关键见解。因此，开发空间免疫受体库技术是推进基础免疫学研究并解锁新的临床应用的重要一步。

现在，百创智造开发的百创空间免疫组产品，将填补这一技术缺口。百创空间免疫组芯片可以实现在原片上同时捕获得到3’端转录组信息以及全长B细胞受体（BCR）和T细胞受体（TCR）序列。

百创单细胞级空间免疫组产品解决了整个转录组和组织形态学问题，实现了人类淋巴组织和肿瘤组织中B细胞和T细胞克隆的高保真定位和空间谱系追踪。有可能促进我们对各种临床相关现象（如感染、疫苗接种和癌症）中淋巴细胞空间动力学的理解。

2 环境配置

2.1 Conda安装

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

下载完成之后运行（按提示安装）
sh Miniconda3-py39_4.12.0-Linux-x86_64.sh

安装完成后执行以下命令
source ~/.bashrc

2.2 Conda环境配置

conda create -n (环境名) python=3.9
激活环境：
conda activate (环境名)

添加镜像源
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/

查看镜像源
conda config –show channels

2.3 安装python模块

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 安装指定R版本（v4.2）

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

2.5 安装R包

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 安装其它软件

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

3 配置文件

####data（BCR三代测序数据和TCR三代测序数据）
CCS_IG /path/IG.ccs.fastq.gz
CCS_TR /path/TR.ccs.fastq.gz

## AllheStat.py（组织识别参数 HE 染色图片和组织荧光图片至少给一个）
HE /path/to/HE.tif

## out put(输出目录及输出文件前缀)
OUTDIR /path/to/result/dir/
PREFIX outfile-prefix

## fastq2BcUmi
Threads 16 ##线程
BCType V2 ##barcode 版本类型(一般为 V2 版本)
CHIP S1000 ##S1000/S3000

####BSTMatrix
LinkBcChip /path/03.LinkBcChip/ ##二代bc位置文件夹
CellSplit /path/07.CellSplit/ ##二代细胞分割文件夹

##enviroment python, 如不提供则使用系统环境中的版本(不提供请注释掉以下参数)
PYTHON /path/to/python/dir/

4 流程说明

流程分为 5个步骤 ，如下所示:

步骤1：识别 fastq 数据中的barcode和umi，识别荧光数据的barcode信息并对应到芯片上位置, 处理HE图片;
步骤2：识别BCR和TCR的免疫组基因（V D J C）, CDR3aa等;
步骤3：构建不同level以及细胞水平的不同克隆型表达矩阵;
步骤4：克隆型等基本统计（适配vdjtools等工具）;
步骤5：网页报告以及备份结果。
-c config.txt 数据配置文件
-s 步骤选择，0为运行1-5所有步骤，也可选择个别步骤单独运行 ，多个步骤中间使用”,”分隔 。

参考命令：

./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 结果说明

Result/
├── 01.BSTMatrixPb ##步骤1目录输出结果
│ ├── xx ##IG和TR分析目录
│ │ ├── 01.cutread1 ##read1识别切割过滤短序列
│ │ │ └── xx.cut.ccs.fastq ##切割read1以及过滤掉短序列的数据
│ │ ├── 02.fastq2BcUmi ##序列barcode及umi检测结果目录
│ │ │ ├── xx.bc_dist ##不同barcode检测统计文件
│ │ │ ├── xx.bc_stat ##不同barcode检测统计文件
│ │ │ ├── xx.bc_type_cor.info ##V2AB barcode矫正信息文件
│ │ │ ├── xx.bc_type_cor.umi ##V2AV barcode矫正后reads对应的barcode类型及umi文件
│ │ │ ├── xx.bc_umi_read.tsv ##barcode类型、对应的umi及reads数统计文件
│ │ │ ├── xx.bc_umi_read.tsv.id ##barcode类型、对应的umi及reads id文件
│ │ │ ├── xx.filter ##没有完整识别出barcode的reads信息文件
│ │ │ ├── xx.full_stat ##barcode类型对应的reads数、umi数文件
│ │ │ ├── xx.id_map ##id编号对应关系文件
│ │ │ ├── xx.qual.stat ##reads统计文件
│ │ │ ├── xx.select_id ##完整识别出barcode和UMI的reads id文件
│ │ │ ├── xx.stat ##barcode检测统计文件
│ │ │ ├── xx.umi ##reads对应的barcode类型及umi文件
│ │ │ └── xx.umi_cor.info ##umi校正信息文件
│ │ ├── 03.LinkBcChip ##barcode空间定位结果目录
│ │ │ ├── xx.barcode_pos.tsv ##barcode类型对应的芯片位置文件
│ │ │ ├── xx.barcode.tsv ##芯片对应的barcode类型文件
│ │ │ └── ngsbcpos.tsv ##二代barcode位置文件
│ │ ├── 04.AllheStat ##组织表达分析结果目录
│ │ │ ├── allhe ##组织区域信息目录
│ │ │ │ ├── he_roi_small.png ##HE组织区域识别后png图片文件
│ │ │ │ ├── he_roi.tif ##HE组织区域识别后tif图片文件
│ │ │ │ ├── roi_heAuto.json ##组织区域json文件
│ │ │ │ └── stat.txt ##组织区域统计文件
│ │ │ ├── heAuto_level_matrix ##组织区域不同分辨率水平barcode位置目录
│ │ │ │ └── subdata ##组织区域不同分辨率水平barcode位置目录
│ │ │ └── level_matrix ##芯片不同分辨率水平表达矩阵目录
│ │ │ └── level_* ##芯片不同分辨率水平表达矩阵目录
│ │ └── XX ##原始表达矩阵结果目录
│ │ ├── barcode_pos.tsv ##barcode及对应芯片位置文件
│ │ └── barcode.tsv ##barcode文件
├── 02.IgBlast ##步骤2目录输出结果
│ ├── xx ##IG和TR免疫组分析结果
│ ├── xx.barcode.cdr3aa.xls ##barcode水平下CDR3aa结果
│ ├── xx.barcode.chain.xls ##barcode水平下不同链结果
│ ├── xx.barcode.Productive.xls ##barcode水平下功能性结果
│ ├── xx.barcode.stat.xls ##barcode水平下统计结果
│ ├── xx.blast.xls ##IgBlast分析原始结果（airr格式）
│ ├── xx.ccs.stat ##ccs数据基本统计结果
│ ├── xx.fa ##ccs数据fasta格式
│ ├── xx.read.clontype.xls ##reads水平克隆型结果
│ ├── xx.read.result.xls ##reads水平整理结果
│ ├── xx.read.stat.xls ##reads水平统计结果
│ └── xx.valid.barcode ##有效barcode信息
├── 03.Matrix ##步骤3目录输出结果
│ ├── xx.XX ##IG/TR结果
│ ├── Cell ##细胞分割水平结果
│ │ ├── Cell.csv ##细胞水平克隆型结果(csv格式)
│ │ ├── Cell_matrix ##细胞水平克隆型矩阵结果
│ │ │ ├── barcodes_pos.tsv.gz ##细胞水平位置文件
│ │ │ ├── barcodes.tsv.gz ##细胞水平barcode文件
│ │ │ ├── features.tsv.gz ##细胞水平克隆型文件
│ │ │ ├── he_roi_small.png ##he小图
│ │ │ └── matrix.mtx.gz ##细胞水平矩阵文件
│ │ ├── Cell.rds ##细胞水平克隆型rds文件
│ │ ├── Cellsum.csv ##细胞水平克隆型累积求和文件
│ │ ├── xx.Cell.cdr3aa.xls ##细胞水平下CDR3aa结果
│ │ ├── xx.Cell.chain.xls ##细胞水平下不同链结果
│ │ ├── xx.Cell.Productive.addCgene.xls ##细胞水平下功能性结果(添加了C区基因)
│ │ ├── xx.Cell.Productive.xls ##细胞水平下功能性结果
│ │ ├── xx.Cell.stat.xls ##细胞水平下统计结果
│ │ └── xx.read.addCell.result.xls ##细胞水平下整理结果
│ ├── Cell.xls ##barcode和细胞ID对应关系
│ ├── L* ##不同level水平结果
│ │ ├── L*.csv ##不同level水平克隆结果(csv格式)
│ │ ├── L*_matrix ##不同level水平克隆型矩阵结果
│ │ │ ├── barcodes_pos.tsv.gz ##不同level水平位置文件
│ │ │ ├── barcodes.tsv.gz ##不同level水平barcode文件
│ │ │ ├── features.tsv.gz ##不同level水平克隆型文件
│ │ │ ├── he_roi_small.png ##he小图
│ │ │ └── matrix.mtx.gz ##不同level水平矩阵文件
│ │ ├── L*.rds ##不同level水平克隆型rds文件
│ │ ├── xx.L*.cdr3aa.xls ##不同level水平CDR3aa结果
│ │ ├── xx.L*.chain.xls ##不同level水平不同链结果
│ │ ├── xx.L*.Productive.addCgene.xls ##不同level水平功能性结果(添加了C区基因)
│ │ ├── xx.L*.Productive.xls ##不同level水平功能性结果
│ │ ├── xx.L*.stat.xls ##不同level水平统计结果
│ │ └── xx.read.addL*.result.xls ##不同level水平下整理结果
│ └── L*.xls ##barcode和不同level对应关系
├── 04.Basic_stat ##步骤4目录输出结果
│ └── xx ##IG和TR克隆型统计结果(适配vdjtools分析工具)
│ ├── *.clonotype.xls ##克隆型结果
│ └── xx.chain.clonotype.num.xls ##轻重链克隆型数量统计
├── 05.Web_Report ##步骤5目录输出结果
│ ├── Readme.txt ##Readme文件
│ ├── result ##结果目录
│ │ └── xx ##IG/TR结果文件
│ │ ├── clonotype ##克隆型结果
│ │ ├── rds ##rds结果
│ │ ├── xx.blast.xls ##IgBlast分析免疫组原始结果
│ │ ├── xx.Cell.Productive.xls ##细胞水平下功能性结果
│ │ ├── xx.Cell.Productive.addCgene.xls ##细胞水平下功能性结果(添加了C区基因)
│ │ └── xx.read.result.xls ##IgBlast分析整理结果
│ └── xx.report.html ##报告
└── config.txt ##配置文件