云生信学生物信息学

kallisto bustools上游计数教程:化学版本、参考和资源验证

作者:发布于 2026-11-20更新于 2026-11-15约 8 分钟阅读
计数先核对化学规则

计数先核对化学规则:确认barcode与UMI;固定参考和版本;生成两套矩阵;稀疏检查标签维度
本文操作与检查路径示意。

kallisto bustools上游计数首先要确认文库化学方案。读段顺序、barcode长度和UMI位置错误,可能产生文件却丢失大量有效分子。本文固定kb-python 0.31.0,以标准10x 3′ v3双端文库和常规转录本参考为例,不把单核含内含子或RNA velocity路线混入同一个默认命令。

先核对三个版本层次

保存kb-python、其实际调用的kallisto与bustools版本,以及参考来源和化学规则。kb可以使用随包提供的程序,PATH中另一个kallisto版本不一定就是实际运行版本,因此还需读取kb运行记录。先用kb –list核对支持的technology,不按FASTQ文件名猜建库类型。该固定版本展示清单后返回1,代码仅在状态和清单内容均符合时继续,不一般性忽略报错。

对象 本例规则 项目核对
技术名 10xv3 真实建库说明是否一致
R1 16 nt barcode与12 nt UMI 读段长度及顺序是否正确
R2 cDNA 未与R1或其他样本交换
参考 同组装FASTA与GTF生成常规索引 记录基因与转录本版本
过滤 保留unfiltered,并另产filtered 细胞判定仍需后续质控

在新目录建立并记录参考

下例路径和两线程都是演示,输入文件须真实存在。使用已验证的kb环境,不在正式共享环境临时升级。若采用预建索引,必须取得匹配t2g,不能从另一个注释版本借用;本例展示自建以便明确来源。

set -euo pipefail
mkdir kb-check
cd kb-check
python -c 'import importlib.metadata; print(importlib.metadata.version("kb-python"))' \
  > kb-version.txt
status=0
kb --list > technologies.txt 2> technologies.log || status=$?
test "$status" -eq 1
grep -q "^List of supported single-cell technologies" technologies.txt
grep -Ei "^10xv3[[:space:]]" technologies.txt
sha256sum /ref/genome.fa /ref/genes.gtf > reference.sha256
kb ref -i index.idx -g t2g.txt -f1 transcriptome.fa \
  /ref/genome.fa /ref/genes.gtf > ref.log 2>&1
test -s index.idx; test -s t2g.txt
gzip -t /data/S01_R1.fastq.gz /data/S01_R2.fastq.gz
/usr/bin/time -v -o count.time kb count \
  -i index.idx -g t2g.txt -o S01 -x 10xv3 -t 2 --filter bustools \
  /data/S01_R1.fastq.gz /data/S01_R2.fastq.gz > count.log 2>&1

核对矩阵标签,避免直接转成稠密数组

继续在kb-check执行,需要Python 3、SciPy和NumPy。这条标准路线输出cells_x_genes,行对应barcode、列对应基因;检查维度时按这个方向核对。代码只读取稀疏数据,不把细胞乘基因矩阵整体转成dense。

from pathlib import Path
from scipy.io import mmread
import numpy as np
for group in ("counts_unfiltered", "counts_filtered"):
    d = Path("S01") / group
    prefix = d / "cells_x_genes"
    a = mmread(str(prefix) + ".mtx").tocoo()
    bc = Path(str(prefix) + ".barcodes.txt").read_text().splitlines()
    genes = Path(str(prefix) + ".genes.txt").read_text().splitlines()
    assert a.shape == (len(bc), len(genes)), "维度与标签不一致"
    assert len(set(bc)) == len(bc) and all(bc), "barcode重复或为空"
    assert len(set(genes)) == len(genes) and all(genes), "基因标签重复或为空"
    assert np.isfinite(a.data).all() and (a.data >= 0).all(), "异常计数"
    print(group, a.shape, "非零项", a.nnz, "总计数", a.data.sum())

再读取run_info.json、kb_info.json和count.log,确认实际命令、映射和barcode处理情况。保留校正使用的on-list及版本信息,核对filtered的barcode属于unfiltered。BUS是中间记录,不等同完成barcode校正、UMI去重后的细胞基因矩阵;不能只检查output.bus存在就宣布上游成功。

区分技术失败与细胞判定

barcode匹配率异常先查化学方案、R1/R2顺序和长度,再查on-list是否适用,不直接放宽细胞过滤。filtered细胞数与预期差异大时,联合未过滤矩阵的UMI分布、背景和文库记录复查;默认过滤不是已经完成双细胞、低质量细胞和污染评估。

多lane同一文库可按官方输入规则组织,独立文库使用不同输出目录,不能把相同barcode跨文库直接视为同一细胞。单核或需要nascent/mature计数时,应重新选择参考workflow和配套参数,再验证输出层,不能事后把本例计数表改名获得。

另给每个文库登记输入read对数、成功处理量、校正后barcode数、未过滤与过滤后矩阵形状,以及总UMI口径。若同一参考下filtered基因标签顺序改变,不能直接按列位置拼接,应按标识对齐;跨文库细胞名加文库前缀后再合并,保留可追溯的原barcode。化学方案升级后重新核对规则,不沿用旧批次的简写作判断。

用count.time记录单任务RSS与时间,另测排序临时盘高水位。对有代表性的文库试跑后再决定队列并发,避免多个任务同时排序耗尽内存或工作盘;完整环境、参考和化学规则清单比单一CPU核数更有助于复现。

参考资料

需要额外算力时

适用前提:文库类型与工具支持范围已确认,缺少兼容环境或运行资源。如需额外资源,可评估服务器租赁及按需环境部署。咨询时说明软件版本、任务规模和使用期限,配置与支持范围另行确认。

咨询本任务的服务器配置

咨询本任务的服务器配置

留下手机号,我们会结合本文任务与您沟通服务器配置和报价。

也可联系云生信企业微信客服,说明本文任务。

把知识用于当前任务

下一步可以直接开始分析

按研究目标查找在线工具、课程、计算资源或完整分析服务。

按目标找方案仍有疑问,联系客服 ↗