可复现生信项目目录：从 data 到 logs 的组织方法

2025 年 6 月，我在思源笔记中记录了一套“服务器操作习惯”。最初它只是文件命名和目录树，目的是减少自己在不同服务器、不同课题之间切换时的混乱。

后来我逐渐意识到，目录结构并不只是整洁问题。它决定了几个月后能否回答这些问题：

原始数据是否被改动过？
当前结果由哪段代码和哪组参数生成？
失败任务的日志在哪里？
图表能否从中间结果重新生成？
其他人能否在不询问作者的情况下理解项目？

data：把原始数据和派生数据分开

data/raw/ 保存收到时的原始文件，原则上只读。清洗、过滤、格式转换和合并后的文件进入 data/processed/。

我会同时保存：

原始文件清单；
文件大小和校验值；
样本名与分析编号的映射；
数据获取日期和来源；
生成 processed 数据的脚本或任务编号。

涉及临床或个人数据时，目录和日志中只使用去标识化的分析编号，不直接放置姓名、住院号或联系方式。

ref：参考数据也需要版本

参考基因组、注释文件和数据库快照并不是永远不变的。ref/ 中除了数据文件，还应记录：

物种与版本；
下载地址或来源；
下载日期；
文件校验值；
必要的索引构建命令。

“使用了 hg38”通常还不够，因为不同来源和注释版本可能产生不同结果。

src 与 scripts：区分逻辑和入口

我把可复用的分析逻辑放在 src/，把面向具体任务的执行入口放在 scripts/。

src/
├── qc/
├── alignment/
├── statistics/
└── visualization/

scripts/
├── 01_qc.sh
├── 02_align.sh
├── 03_quantify.sh
└── 04_report.R

数字前缀表达默认执行顺序，但真正的依赖关系仍应写进工作流、Makefile 或任务说明，而不是只依赖文件名。

config：参数不应散落在命令历史中

线程数、阈值、参考文件路径和样本分组应集中写入配置文件。这样做有三个直接收益：

修改参数时不需要改动分析逻辑。
不同批次可以保存各自配置。
结果目录能够反向追溯到具体参数。

配置文件中不要保存密码、API Key 和长期访问令牌。它们应通过环境变量或专门的凭据管理方式提供。

results：结果不是所有中间文件的垃圾桶

results/ 只保存需要检查、汇报或交付的内容：

tables/：统计结果和结构化数据表；
figures/：可重新生成的图；
reports/：面向阅读者的汇总报告。

体积大、可重新计算的中间文件应留在 processed 数据或临时工作目录，并明确清理规则。

logs：让失败也留下证据

每次运行至少记录：

开始和结束时间；
命令或任务名称；
软件版本；
输入与输出路径；
标准输出和错误输出；
退出状态。

日志的价值往往在任务失败后才显现。没有日志时，“为什么上次能跑、这次不能”通常只能依赖记忆。

env 与 docs：保存运行环境和决策

env/ 可以保存 Conda、容器或语言依赖的锁定文件；docs/ 则保存 README、方法说明、数据字典和重要决策。

一个最低限度的 README 应回答：

项目解决什么问题。
数据来自哪里。
如何准备环境。
从哪个命令开始运行。
主要结果在哪里。
哪些内容尚未完成。

我的命名习惯

项目和任务使用固定宽度编号，便于排序和引用：

p01__project_name/
├── t01__data_preparation/
├── t02__primary_analysis/
└── t03__validation/

编号只表达组织关系，不替代日期、版本控制和执行日志。文件名优先使用小写英文、数字、下划线或连字符，减少跨系统处理时的转义问题。

一次分析应形成怎样的证据链

理想状态下，一张最终图可以沿着下面的路径回查：

figure
→ plotting script
→ result table
→ analysis task
→ config
→ processed data
→ raw data + reference version

目录模板的真正目标不是让树形结构看起来专业，而是让这条链保持完整。只要证据链能够被重新执行、检查和解释，项目结构就完成了它最重要的任务。