云生信学生物信息学

在兼容环境中构建、验证并复用参考索引

作者:发布于 2026-11-16更新于 2026-11-15约 6 分钟阅读
参考索引要构建,也要验收

参考索引要构建,也要验收:固定FASTA、GTF及软件版本;在独立目录保留构建日志;用同物种匹配样例跑通;交付版本路径与验收记录
本文操作与检查路径示意。

配套的FASTA和GTF已经核对后,可以把参考构建组织成一次可交接的任务:固定输入、独立输出、记录资源、用适配样本验证,最后再提供给其他项目复用。这样能够减少反复建索引,也能在结果异常时查清究竟使用了哪一版参考。

固定输入,创建新的构建位置

下面限定Gene Expression的mkref,参数按当前v10.1官方文档核对;旧版本先查本地帮助。输入示例为未压缩文件。参考名称应包含你能识别的组装或注释标签,不要让不同版本都叫“latest”,也不要在成员正在使用的目录内直接替换文件。

set -u
: "${REF_FASTA:?填写已核对的FASTA路径}"
: "${REF_GTF:?填写配套GTF路径}"
: "${REF_NAME:?填写新的参考名称}"
: "${REF_THREADS:?填写获配线程数}"
: "${REF_MEM_GB:?填写经确认的构建内存参数}"
case "$REF_NAME" in *[!A-Za-z0-9_-]*|"") exit 2;; esac
case "$REF_THREADS:$REF_MEM_GB" in *[!0-9:]*|:*|*:) exit 2;; esac
test "$REF_THREADS" -gt 0 && test "$REF_MEM_GB" -gt 0 || exit 2
test -r "$REF_FASTA" && test -r "$REF_GTF" || exit 2
test ! -e "$REF_NAME" || exit 2
mkdir -p build-logs
sha256sum "$REF_FASTA" "$REF_GTF" > "build-logs/$REF_NAME.inputs.sha256"
cellranger --version > "build-logs/$REF_NAME.version.txt"
/usr/bin/time -v -o "build-logs/$REF_NAME.time.txt" \
  cellranger mkref --genome="$REF_NAME" --fasta="$REF_FASTA" \
  --genes="$REF_GTF" --nthreads="$REF_THREADS" --memgb="$REF_MEM_GB" \
  > "build-logs/$REF_NAME.stdout.txt" 2> "build-logs/$REF_NAME.stderr.txt"
status=$?
printf '%s\n' "$status" > "build-logs/$REF_NAME.exit-code.txt"
test "$status" -eq 0

输出由新参考名称创建在当前工作目录。线程和内存值应符合任务及平台额度;mkref的构建参数不能直接用count的本地申请参数替代。GNU time需可用,其记录仅是资源观察的一部分,多进程聚合需求还要结合平台统计。

构建结束后验收两个层次

先检查退出码、构建日志及该版本预期目录。参考元数据、序列与索引应齐全可读;不要把“生成了一个文件夹”当作完成。随后用同物种、同类建库且已经核对输入的代表样本,验证该参考能被实际pipeline加载,并检查输出是否合理。

验收层次 需要证据 不能替代的内容
输入可追溯 FASTA/GTF版本、来源及校验值 名称相似不足以证明配套
构建正常结束 退出码、日志和预期参考文件 空目录或部分索引不算完成
pipeline可用 匹配样例的完整运行记录 软件安装自检不验证自建参考
结果适配 样本身份、比对与计数等检查 成功运行不自动证明注释合适

Cell Ranger自带的安装测试只验证其规定的示例环境,不能代替你新建参考的验证。拿不匹配物种的公共FASTQ做检查也没有相同意义。样例规模可以小,但必须能触及你准备复用的参考和计算步骤;数据质量异常仍需单独调查。

把验证过的路径交给下一次运行

在普通Gene Expression count中,使用明确参考目录作为--transcriptome值,并记录同一Cell Ranger版本及样本选择参数。首次使用新参考时,比较官方报告、期望基因与矩阵等结果,不应只确认参数能解析。不同建库、复杂文库或VDJ需按其适用工具链选择参考。

若必须修正注释或升级软件,建立新的版本目录并重新验收。旧项目记录完整路径和参考标识,尽量避免解析到会变化的软链接。共享参考可按管理规则设为普通成员只读,更新由指定人员维护,权限实现由平台管理员确认。

保留能复用也能追查的交付物

保存构建命令、软件版本、输入来源与校验值、日志、资源记录和样例验收说明。索引兼容性应以实际版本文档及验证为准,不假设所有新旧软件都能无条件互用。稳定参考可供多个任务复用;工作盘、备份和长期保留则应单独规划,避免删除构建现场后只剩一个来源不明的目录。

需要额外算力时

适用前提:文件与注释问题处理后仍缺兼容环境或计算资源。如需额外资源,可评估服务器租赁及按需环境部署。咨询时说明软件版本、任务规模和使用期限,配置与支持范围另行确认。

咨询本任务的服务器配置

咨询本任务的服务器配置

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

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

参考与版本核对

按文中适用环境运行,所用版本与参数以实际安装环境和对应官方文档为准。

把知识用于当前任务

下一步可以直接开始分析

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

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