云生信学生物信息学

整理代码、参数、数据字典和最小复现实例

作者:发布于 2026-11-19更新于 2026-11-15约 6 分钟阅读
毕业交接要能独立跑通

毕业交接要能独立跑通:按结果整理输入与参数;补字段单位和数据来源;交付有断言的最小实例;接手人独立复现再验收
本文操作与检查路径示意。

学生毕业交接,应该让下一位成员在没有原作者口头补充的情况下完成一个明确的小任务。只留下几十个脚本和一个最终图,不容易知道入口、参数、样本及中间结果。本篇整理代码、数据字典和最小复现实例,先证明交接链可用,再验证正式分析范围。

交接清单围绕一个明确结果

为每个主要结果写清输入来自哪里、哪条命令生成、用了什么参考与参数、预期输出在哪里。原始数据与敏感样本按项目权限存放,不为了方便打包进公开仓库。不能把真实样本换成演示数据后仍保留原结果说明,让接手人误以为已复现正式结论。

材料 应包含 接手人怎样检查
README 研究范围、入口、顺序、失败处理 按文档能开始,无私人home依赖
代码与参数 批准提交、配置、随机种子 命令与结果能对应
数据字典 字段名、类型、单位、允许缺失及来源 样本与分组可解释
环境与参考 R/工具/包锁、系统依赖、库版本和校验 独立副本可加载
最小实例 获准小输入及可核对预期输出 运行成功且断言通过

做一个有输入和断言的交接小例

新建handoff-demo,内建example和scripts目录。下面保存为example/mini.csv;数据是纯教学合成,value单位为counts,不对应真实实验。正式数据字典应逐列说明样本命名、单位和缺失值,而不把空白分组自动补为对照。

sample,value
S1,1
S1,2
S2,3
S2,4

把以下保存为scripts/check_handoff.R,从handoff-demo根目录执行Rscript –vanilla scripts/check_handoff.R。只用base R,输出目录必须全新;脚本拦截缺列、非有限值与预期不符,并留下实际结果和R版本。这验证的是交接入口,不是任何差异分析或生物学假设。

args <- commandArgs(trailingOnly=TRUE)
out <- if(length(args)==0L) "check-output" else args[[1]]
stopifnot(length(args)<=1L, !file.exists(out))
x <- read.csv("example/mini.csv", stringsAsFactors=FALSE)
stopifnot(identical(names(x),c("sample","value")),
          all(!is.na(x$sample) & nzchar(x$sample)),
          is.numeric(x$value), all(is.finite(x$value)))
result <- aggregate(value ~ sample, data=x, FUN=sum)
result <- result[order(result$sample),]
stopifnot(identical(result$sample,c("S1","S2")),
          all(result$value==c(3,7)))
stopifnot(dir.create(out, recursive=FALSE))
write.csv(result,file.path(out,"summary.csv"),row.names=FALSE)
writeLines(R.version.string,file.path(out,"R-version.txt"))
print(result)

把代码状态与数据状态分别保存

如果代码已经由Git管理,先核对工作区是否有未提交文件、子模块或大文件指针。git archive只归档指定提交的受跟踪内容,未提交修改与未跟踪数据不会自动加入,也不包含完整提交历史。先决定交接者要的是源码快照还是可维护仓库,再使用对应材料。

set -euo pipefail
git status --short
git rev-parse HEAD
git ls-files
# 确认列表与批准提交后,在仓库外创建新归档目录
mkdir ../handoff-package1
git rev-parse HEAD > ../handoff-package1/code-commit.txt
git archive --format=tar --output=../handoff-package1/code.tar HEAD
sha256sum ../handoff-package1/code.tar > ../handoff-package1/code.tar.sha256

由接手人记录缺口

接手人用自己的账号和新工作目录重建环境,先跑合成小例,再用获准的代表性真实输入验证正式流程。依赖缺失、路径错误、字段不明和结果差异分别记录;原作者补齐文档后重新验收,不能由原作者代跑完成就签字。

最小实例应覆盖关键入口和容易出错的字段,而非只打印hello。正式复杂方法还需相应质量指标与数值容差,不能用本例固定总和替代。结果表中保留哪些部分已复现、哪些需要大数据或专门资源后才能验证;未完成项留责任人和下一步,避免毕业后依赖无人维护的私人目录。

数据字典还应明确ID是否区分大小写、分隔符及一行代表样本还是读段。相同字段名可能含义不同,接手人应能从说明追到原始来源,不能靠猜测补全。

参考资料

需要额外算力时

适用前提:团队需要持续保留环境且租赁适合其管理安排。如需额外资源,可评估课题组多用户计算环境。咨询时说明软件版本、任务规模和使用期限,配置与支持范围另行确认。

咨询本任务的服务器配置

咨询本任务的服务器配置

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

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

把知识用于当前任务

下一步可以直接开始分析

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

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