跳到主要内容

10 数据与代码归档：可复现交付清单

分析做完、文章投出去了，项目还没有结束。最后一步是把数据和代码归档成一个"别人（包括半年后的你自己）能复现的完整包"。这不是可选项——越来越多的期刊把代码和数据可用性作为接收条件，审稿人也会检查你的代码是否和 Methods 描述一致。这一章给出一份实操清单：数据放哪里、代码怎么组织、环境怎么锁定、README 怎么写。

为什么可复现性很重要​

三个现实原因让你必须认真对待归档：

第一，审稿人会检查。越来越多的审稿人会 clone 你的代码仓库，试着跑一遍看能不能重现核心结果。如果跑不通或者结果对不上，基本就是 major revision 或 reject。

第二，半年后你自己需要。Revision 来了之后审稿人要求"用不同阈值重新跑一遍"或者"加一个新的分析"。如果你的代码一团糟、环境已经更新了、中间文件找不到，重新跑通可能要花一周——而如果归档做得好，两小时就搞定。

第三，影响力和信用。有代码仓库的文章被引用率更高，因为别人可以直接用你的方法和数据做后续研究。一个干净的 GitHub 仓库也是你的专业名片。

GEO/SRA 数据提交​

如果你有自己产出的原始测序数据，投稿前需要提交到公共数据库。本专栏的 TCGA-LIHC 项目用的是已公开数据，不需要提交，但你需要知道这个流程：

GEO 提交流程（适用于处理后的表达矩阵）：

  1. 准备 metadata spreadsheet（从 GEO 官网下载模板）
  2. 填写实验信息：organism、experiment type、platform
  3. 准备数据文件：raw counts matrix + normalized matrix
  4. 通过 GEO 的 FTP 上传
  5. 获得 GSE accession number（投稿时用 "will be made available upon acceptance"）

SRA 提交流程（适用于原始 FASTQ）：

  1. 注册 NCBI 账号，获取 submission portal 权限
  2. 创建 BioProject → BioSample → SRA Experiment
  3. 上传 FASTQ 文件（支持 Aspera 加速）
  4. 获得 SRP/SRR accession number
# 使用 Aspera 上传 FASTQ 到 SRA（比 FTP 快 10 倍）
ascp -i ~/.aspera/connect/etc/asperaweb_id_dsa.openssh \
     -QT -l 500m -k 1 \
     ./fastq_files/ \
     subasp@upload.ncbi.nlm.nih.gov:uploads/your_folder/

对于 TCGA-LIHC 项目，数据引用格式：

# 在 Methods 中这样引用 TCGA 数据
"RNA-seq gene expression data (HTSeq-Counts) for TCGA-LIHC were 
downloaded from the GDC Data Portal (https://portal.gdc.cancer.gov/, 
Data Release 37.0, accessed January 15, 2024)."

GitHub 仓库组织​

一个好的分析仓库应该让别人 git clone 下来，按照 README 的步骤就能复现核心结果。推荐的目录结构：

TCGA-LIHC-lipid-signature/
├── README.md                   # 项目说明（最重要！）
├── LICENSE                     # 开源协议（推荐 MIT）
├── renv.lock                   # R 包版本锁定
├── .Rprofile                   # renv 自动激活
├── renv/                       # renv 库文件
├── data/
│   ├── README.md               # 数据说明：来源、版本、下载方式
│   ├── download_data.sh        # 自动下载脚本
│   └── processed/              # 处理后的中间文件（可选 .gitignore）
├── scripts/
│   ├── 00_download_data.R      # 数据获取
│   ├── 01_preprocessing.R      # 预处理和过滤
│   ├── 02_differential_expr.R  # DESeq2 差异分析
│   ├── 03_enrichment.R         # GO/KEGG 富集
│   ├── 04_survival_lasso.R     # LASSO Cox + KM
│   ├── 05_mutation_analysis.R  # maftools 突变景观
│   ├── 06_external_validation.R # ICGC-LIRI 验证
│   └── 07_figures.R            # 论文图表生成
├── results/
│   ├── DEG_list.csv            # 差异基因列表
│   ├── signature_genes.csv     # Signature 基因和系数
│   └── survival_results.csv    # 生存分析结果
├── figures/
│   ├── Figure1.pdf             # 论文主图
│   ├── Figure2.pdf
│   └── Supplementary/
│       ├── FigS1.pdf
│       └── FigS2.pdf
└── docs/
    ├── sessionInfo.txt         # 完整的 R session info
    ├── methods_full.md         # 详细版 Methods
    └── CHANGELOG.md            # 版本变更记录

几个关键原则：

脚本按顺序编号。 用数字前缀（00_, 01_, 02_...）保证执行顺序清晰。每个脚本只做一件事，输入和输出明确。

数据不直接放仓库。 原始数据通常太大（几个 GB），不适合 push 到 GitHub（免费版限制 100MB 单文件）。改用下载脚本：

#!/bin/bash
# data/download_data.sh — 自动下载 TCGA-LIHC 数据

echo "Downloading TCGA-LIHC data from GDC..."

# 使用 gdc-client 下载（需要先安装）
# gdc-client download -m gdc_manifest.txt

# 或者用 TCGAbiolinks 在 R 中下载
Rscript -e '
library(TCGAbiolinks)
query <- GDCquery(
  project = "TCGA-LIHC",
  data.category = "Transcriptome Profiling",
  data.type = "Gene Expression Quantification",
  workflow.type = "STAR - Counts"
)
GDCdownload(query, method = "api")
'

echo "Download complete. Run scripts/01_preprocessing.R next."

用 .gitignore 排除大文件和临时文件：

# .gitignore
data/raw/
data/processed/*.rds
*.Rhistory
*.RData
.Rproj.user/
renv/library/
renv/staging/

Docker/renv 环境锁定​

"在我电脑上能跑"是可复现性的最大敌人。两种环境锁定方案按难度和覆盖范围从低到高：

方案一：renv（推荐起步方案）

renv 锁定 R 包的版本，保证别人安装的包和你的一模一样：

# 项目初始化（只需做一次）
renv::init()

# 每次安装/更新包后，锁定当前状态
renv::snapshot()

# 别人 clone 你的仓库后，一键恢复环境
renv::restore()

renv.lock 文件长这样（截取片段）：

{
  "R": {
    "Version": "4.3.1",
    "Repositories": [
      {
        "Name": "BioCsoft",
        "URL": "https://bioconductor.org/packages/3.18/bioc"
      },
      {
        "Name": "CRAN",
        "URL": "https://cloud.r-project.org"
      }
    ]
  },
  "Packages": {
    "DESeq2": {
      "Package": "DESeq2",
      "Version": "1.42.0",
      "Source": "Bioconductor"
    },
    "glmnet": {
      "Package": "glmnet",
      "Version": "4.1-8",
      "Source": "Repository",
      "Repository": "CRAN"
    }
  }
}

renv 的局限性：它只锁定 R 包，不锁定系统依赖（如 libcurl、Java）。如果你的分析依赖系统库，需要用 Docker。

方案二：Docker（完整环境锁定）

Docker 把整个运行环境（操作系统 + 系统库 + R + 所有包）打包成一个镜像：

# Dockerfile
FROM rocker/r-ver:4.3.1

# 安装系统依赖
RUN apt-get update && apt-get install -y \
    libcurl4-openssl-dev \
    libxml2-dev \
    libssl-dev \
    && rm -rf /var/lib/apt/lists/*

# 安装 BiocManager
RUN R -e "install.packages('BiocManager'); BiocManager::install(version = '3.18')"

# 安装关键包（指定版本）
RUN R -e "BiocManager::install(c('DESeq2', 'clusterProfiler', 'org.Hs.eg.db', 'maftools'))"
RUN R -e "install.packages(c('survival', 'glmnet', 'survminer', 'tidyverse', 'renv'))"

# 复制项目文件
COPY . /project
WORKDIR /project

# 用 renv 恢复精确版本
RUN R -e "renv::restore()"

# 默认入口
CMD ["Rscript", "scripts/02_differential_expr.R"]

使用方式：

# 构建镜像
docker build -t tcga-lihc-analysis .

# 运行分析
docker run -v $(pwd)/results:/project/results tcga-lihc-analysis

# 交互式 R 环境
docker run -it tcga-lihc-analysis R

推荐策略：日常开发用 renv，正式发布时加 Docker。 renv 够用于大部分审稿人的复现需求，Docker 适合追求极致可复现性或需要部署到服务器的场景。

README 模板​

README 是别人接触你的项目的第一个文件。以下是 TCGA-LIHC 项目的 README 模板：

# Lipid Metabolism-Related Prognostic Signature in Hepatocellular Carcinoma

## Overview

This repository contains the analysis code for the manuscript:
"A lipid metabolism-related gene signature predicts prognosis in 
hepatocellular carcinoma" (Journal Name, 2024).

We identified a [N]-gene prognostic signature from lipid metabolism 
pathway genes using TCGA-LIHC data and validated it in ICGC-LIRI.

## Requirements

- R >= 4.3.1
- Bioconductor >= 3.18
- ~8 GB RAM for DESeq2 analysis
- ~2 GB disk space for data

## Quick Start

​```bash
# 1. Clone this repository
git clone https://github.com/username/TCGA-LIHC-lipid-signature.git
cd TCGA-LIHC-lipid-signature

# 2. Restore R environment
Rscript -e "renv::restore()"

# 3. Download data
bash data/download_data.sh

# 4. Run the full pipeline (takes ~30 minutes)
Rscript scripts/00_run_all.R

# Or run step by step:
Rscript scripts/01_preprocessing.R
Rscript scripts/02_differential_expr.R
Rscript scripts/03_enrichment.R
Rscript scripts/04_survival_lasso.R
Rscript scripts/05_mutation_analysis.R
Rscript scripts/06_external_validation.R
Rscript scripts/07_figures.R
​```

## Data Sources

| Dataset | Source | Samples | Access |
|---------|--------|---------|--------|
| TCGA-LIHC | GDC Portal (Release 37.0) | 371T + 50N | Open |
| ICGC-LIRI | ICGC Portal (Release 28) | 232 HCC | Open |

## Output

After running the pipeline, you will find:
- `results/DEG_list.csv` — Differentially expressed genes
- `results/signature_genes.csv` — Signature genes with coefficients
- `figures/Figure*.pdf` — Publication-ready figures

## Citation

If you use this code, please cite:
> Author et al. (2024). Title. Journal. DOI: xxx

## License

This project is licensed under the MIT License.

可复现交付清单​

在投稿之前，逐一检查以下清单：

## 投稿前可复现性检查清单

### 数据
- [ ] 原始数据有公开访问途径（GEO/SRA/GDC accession）
- [ ] 数据下载脚本经过测试，能在新环境运行
- [ ] data/README.md 说明了数据来源和格式
- [ ] 受控访问数据有说明访问申请方式

### 代码
- [ ] 所有分析步骤都有对应脚本
- [ ] 脚本按顺序编号，可顺序执行
- [ ] 脚本内有注释说明关键步骤
- [ ] 没有硬编码的本地绝对路径
- [ ] 使用相对路径或配置文件管理路径
- [ ] 随机种子已设置且在代码中可见

### 环境
- [ ] renv.lock 存在且是最新的
- [ ] sessionInfo.txt 已保存
- [ ] 所有关键包的版本号已记录
- [ ] （可选）Dockerfile 存在且经过测试

### 文档
- [ ] README.md 包含 Quick Start 说明
- [ ] README.md 包含系统要求和预估运行时间
- [ ] Methods 描述与实际代码一致
- [ ] CHANGELOG.md 记录了重要修改

### 测试
- [ ] 在一台"干净"的机器上 clone + restore + run 成功
- [ ] 核心结果（差异基因数、signature 基因）与文章一致
- [ ] 所有 figure 可以重新生成且与投稿版一致

常见坑​

  • 代码依赖本地绝对路径：用了 /Users/zhangsan/Desktop/TCGA/ 这样的路径，别人的电脑上根本不存在这个目录。解决方法：使用 here::here() 包管理项目内的相对路径，或者在脚本开头用 setwd() 指向项目根目录，并在 README 中说明。

  • 没有锁定包版本：半年后 DESeq2 更新了，默认行为变了，同样的代码跑出不同结果。审稿人 revision 时你无法重现自己的结果。解决方法：项目开始时就 renv::init()，每次安装新包后 renv::snapshot()。

  • 大文件直接 push 到 GitHub：把 2GB 的 count matrix 直接 push，导致仓库 clone 极慢甚至失败。解决方法：用 .gitignore 排除大文件，提供下载脚本。如果非要版本管理大文件，用 Git LFS。

  • README 太简略：只写了"run analysis.R"，没说需要什么环境、什么输入文件、预期输出是什么。别人（包括审稿人）根本跑不起来。解决方法：用上面的模板写一个完整的 README，至少包含 Requirements、Quick Start、Data Sources 三个部分。

  • "能跑"不等于"可复现"：代码能跑但结果和文章不一致——因为中间改过参数没更新代码，或者数据版本不对。解决方法：投稿前在一台干净的环境（或 Docker）中从头跑一遍，确认输出和文章一致。

下一步​

接着深入： 恭喜！走完这 10 章，你已经完成了一个从选题到归档的完整组学项目流程。回到 专栏概览 复习整体框架，然后用同样的方法论开始你自己的项目。

横向延伸： 如果你想了解数据管理和环境配置的更多基础知识，可以看 数据获取与环境配置。如果你想把思维方式提升到更高层次，可以进入 组学分析笔记 系列。

参考资源​

  • Wilkinson MD et al. (2016) "The FAIR Guiding Principles for scientific data management and stewardship." Scientific Data 3:160018. FAIR 数据原则的奠基论文。
  • Sandve GK et al. (2013) "Ten Simple Rules for Reproducible Computational Research." PLoS Computational Biology 9:e1003285. 可复现计算研究的 10 条原则。
  • Grüning B et al. (2018) "Practical Computational Reproducibility in the Life Sciences." Cell Systems 6:631-636. 生命科学中的计算可复现性实践。
  • renv 文档：https://rstudio.github.io/renv/ R 项目环境管理的官方文档。
  • Rocker Project：https://rocker-project.org/ 生物信息学 Docker 镜像的最佳来源。
AI 陪学

让 AI 陪我学这一篇

AI 会读这篇文章后给你 3-5 步学习计划， 逐步陪你学完，最后出 1-3 道题验证你掌握得怎么样。 登录后 AI 才能记住你的进度。

静态文件

离线资料下载

手册 HTML / PDF 已在后台预生成，点击后直接下载网站静态资源。

本篇 HTML本篇 PDF说明