云生信学生物信息学

建立样本列表并限制每个任务的CPU与内存

作者:发布于 2026-11-16更新于 2026-11-15约 9 分钟阅读
多个样本,先列清单再限并发

多个样本,先列清单再限并发:核对文库与FASTQ前缀;给每次运行唯一ID;限制任务数和单任务申请;逐个检查日志与输出
本文操作与检查路径示意。

多样本同时运行Cell Ranger时,最容易混淆的是样本输入和资源总量。一个任务申请的核心与内存看起来合适,多个任务一起启动却可能互相争用工作盘或触发作业限制。先把样本关系写清,再给并发设置上限,比不断复制终端命令更容易追踪失败。

先确认哪些文件属于同一文库

本例限定当前v10.1命令文档所述的普通3′/5′Gene Expression count。来自同一文库不同lane的FASTQ不应随意拆成独立生物样本;不同文库组合或Flex须按官方选择pipeline和配置。先用单个代表样本确认流程正确,再做批量。

清单列 填写要求 检查方法
run_id 本次运行唯一名称 不能重复,也不复用失败目录
fastq_dir 实际FASTQ目录 路径存在且当前账号可读
prefix 该文库FASTQ样本前缀 与文件名及送样表逐项对应
参考与版本 本批固定或明确分组 不能混用不同参考而只保留一个标签

将下表保存为真正制表符分隔的samples.tsv,不要用空格凑列。目录和前缀均是示意值,需要替换。跨批次同名样本应有清楚的运行ID,但不能用改名掩盖文库身份。

run_id	fastq_dir	prefix
sampleA_run01	/absolute/fastq/libraryA	LibraryA
sampleB_run01	/absolute/fastq/libraryB	LibraryB

用显式上限组织任务

下面Python脚本只使用标准库,调用已安装的Cell Ranger。先设置参考、输出目录、任务并发数及每任务申请值;这些数值必须根据实际获配额度和单样本试跑确定。脚本不会安装软件,也不自动判断整机资源是否足够。

import csv, os, re, subprocess
from pathlib import Path
from concurrent.futures import ThreadPoolExecutor

ref = Path(os.environ["CR_REF"]).resolve(strict=True)
root = Path(os.environ["CR_RUN_ROOT"]).resolve()
jobs = int(os.environ["CR_JOBS"])
cores = int(os.environ["CR_CORES"])
memory = int(os.environ["CR_MEM_GB"])
assert min(jobs, cores, memory) > 0
rows = list(csv.DictReader(open("samples.tsv", encoding="utf-8", newline=""), delimiter="\t"))
assert rows and len({r["run_id"] for r in rows}) == len(rows)
for row in rows:
    assert re.fullmatch(r"[A-Za-z0-9_-]+", row["run_id"])
    assert Path(row["fastq_dir"]).is_dir() and row["prefix"]
root.mkdir(parents=True, exist_ok=True)
logs = root / "logs"
logs.mkdir(exist_ok=True)

def run(row):
    name = row["run_id"]
    if (root / name).exists():
        raise RuntimeError("运行目录已存在:" + name)
    command = ["cellranger", "count", "--id=" + name,
               "--transcriptome=" + str(ref),
               "--fastqs=" + str(Path(row["fastq_dir"]).resolve()),
               "--sample=" + row["prefix"], "--create-bam=true",
               "--localcores=" + str(cores), "--localmem=" + str(memory)]
    with (logs / (name + ".stdout.txt")).open("w") as out, \
         (logs / (name + ".stderr.txt")).open("w") as err:
        result = subprocess.run(command, cwd=root, stdout=out, stderr=err)
    (logs / (name + ".exit-code.txt")).write_text(str(result.returncode))
    return name, result.returncode

failed = []
with ThreadPoolExecutor(max_workers=jobs) as pool:
    for name, code in pool.map(run, rows):
        print(name, code, flush=True)
        if code != 0:
            failed.append(name)
if failed:
    raise SystemExit("failed runs: " + ", ".join(failed))

每任务申请不等于整机保障

本地--localcores和--localmem用于流水线申请安排,不是给每个进程单独建立硬隔离。多个独立Cell Ranger实例不会替你协调本批的全部资源。需要同时预算活跃任务、系统与其他用户、输入参考读取、临时文件和最终结果,不能只把任务数乘核心数就开跑。

在共享服务器、容器或Slurm里,按获配资源而不是主机总量计算。不要把此脚本再放进多层并发循环,使实际并发变成外层乘内层。集群jobmode应使用平台认可的调度方式,避免绕过其资源规则。

逐个验收,失败不自动当成功

脚本为每个运行保存独立退出码和日志。先检查非零退出任务,再核对普通count的官方报告和矩阵输出是否完整,样本名、输入规模与预期一致。零退出码不能代替数据质量判断;只有输出目录而没有合格结果,也不能算完成。

遇到失败,先查该样本日志。参考错误应修正输入,OOM需核对本批聚合占用,磁盘争用需检查工作盘。保留已完成结果与失败现场,按当前版本规则决定恢复还是新运行,不要不加区分重跑整批。批处理稳定后,再用实际完成时间与并发峰值安排下一批。

正式提交前可以先只保留清单中的一个样本运行,核对命令、日志位置和结果身份;确认后再恢复完整清单。清单本身也应保留一份副本,后续补跑只列失败项,并为新运行保留可区分的标识,避免把已完成结果覆盖。

需要额外算力时

适用前提:需要批量任务且总资源超过当前可用容量。如需额外资源,可评估按任务测算的CPU服务器租赁。咨询时说明软件版本、任务规模和使用期限,配置与支持范围另行确认。

咨询本任务的服务器配置

咨询本任务的服务器配置

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

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

参考与版本核对

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

把知识用于当前任务

下一步可以直接开始分析

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

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