Harvey's Garden

标准的项目结构

7 min read

核心原则

  1. 可复现性是第一要务： 目标是让任何人（包括未来的你）都能用完全相同的软件，重新运行你的分析，并得到完全相同的结果。
  2. 各司其职，互不干扰： 代码、配置、数据和结果应存放在独立的、功能明确的目录中。
  3. 自动化是关键： 整个分析流程都应通过根目录的 Snakefile 文件实现自动化。
  4. 环境即项目： 项目所需的所有软件都应在 pixi.toml 文件中明确定义。
  5. （几乎）一切皆需版本控制： 所有的代码、配置文件和环境定义都必须用 Git 进行追踪。但原始数据和结果文件则不必。

推荐的目录结构

这是一个黄金标准的项目布局，通过数字编号让所有内容井井有条。

你的项目名/
├── .gitignore          # 告诉 Git 应该忽略哪些文件和目录。
├── pixi.toml           # 项目环境的“唯一信源”，由 Pixi 管理。
├── README.md           # 项目的简介、目标和如何开始的说明文档。
├── Snakefile           # 项目的“总指挥”，位于根目录的核心工作流文件。
│
├── 1_code/
│   └── normalize_counts.py # 被 Snakefile 调用的独立脚本（例如 Python 脚本）。
│
├── 2_config/
│   ├── config.yaml     # 存放所有的工作流参数、样本信息和文件路径。
│   └── samples.csv     # 样本信息表，用于关联样本名和对应的原始数据文件。
│
├── 3_data/
│   ├── 3_1_raw/        # “神圣不可侵犯”的原始数据（例如 FASTQ 文件）。
│   ├── 3_2_processed/  # 工作流生成的中间文件（例如 BAM 比对文件、计数矩阵）。
│   └── 3_3_reference/  # 参考基因组、注释文件等。
│
├── 4_results/
│   ├── 4_1_plots/      # 最终生成的图表和图片。
│   ├── 4_2_tables/     # 最终生成的表格、基因列表等。
│   └── 4_3_reports/    # 汇总报告（例如 MultiQC 的报告）。
│
└── 5_notebooks/
    └── exploratory_analysis.ipynb  # 用于交互式分析和探索的 Jupyter Notebook。

第一步：初始化项目环境

  1. 创建并进入项目目录：

    mkdir 你的项目名
cd 你的项目名

  2. 初始化 Git 仓库和 Pixi 环境：

    git init      # 初始化 Git
pixi init     # 初始化 Pixi，会自动创建 pixi.toml 文件

  3. 创建目录结构：

    mkdir -p 1_code 2_config 3_data/3_1_raw 3_data/3_2_processed 3_data/3_3_reference 4_results/4_1_plots 4_results/4_2_tables 4_results/4_3_reports 5_notebooks
touch Snakefile 2_config/config.yaml

  4. 用 Pixi 添加核心软件：

    # 添加工作流引擎和编程语言
pixi add snakemake python
 
# 添加常用的生物信息学工具
pixi add fastqc multiqc star samtools

第二步：配置你的工作流 (2_config/)

切记：永远不要在代码里写死路径或参数。 所有可变的东西都应在这里定义。

2_config/config.yaml 示例：

# 路径信息（相对于项目根目录）
samples_csv: "2_config/samples.csv"
ref_genome_dir: "3_data/3_3_reference/"
 
# 分析参数
read_ending: "_R{read}.fastq.gz" # 例如：sample1_R1.fastq.gz
star_threads: 8

第三步：编写你的工作流 (Snakefile 和 1_code/)

  1. 根目录的 Snakefile： 这是你分析流程的大脑，它定义了从输入到输出的每一步“规则”。 Snakefile 代码片段示例：

    # 从配置目录加载参数
configfile: "2_config/config.yaml"
 
rule all:
    input:
        "4_results/4_3_reports/multiqc_report.html"
 
rule align_with_star:
    input:
        fq1="3_data/3_1_raw/{sample}_R1.fastq.gz",
        ref=config["ref_genome_dir"]
    output:
        bam="3_data/3_2_processed/{sample}/Aligned.sortedByCoord.out.bam"
    threads: config["star_threads"]
    shell:
        "STAR --runThreadN {threads} --genomeDir {input.ref} --readFilesIn {input.fq1} ... "
 
rule process_counts:
    input:
        "3_data/3_2_processed/all_counts.txt"
    output:
        "4_results/4_2_tables/normalized_counts.tsv"
    script:
        "1_code/normalize_counts.py" # 脚本路径指向 1_code 目录

  2. 独立的脚本 (1_code/)： 任何超过一两行的复杂命令，都应该写成一个独立的脚本放在这里。这能让你的 Snakefile 保持整洁，代码也更容易测试和复用。

第四步：管理数据和结果 (3_data/, 4_results/)

  • 3_1_raw/ 是只读的： 永远不要修改你的原始数据。
  • 3_2_processed/ 存放中间文件： 比如比对文件、原始计数矩阵等。
  • 4_results/ 存放最终成果： 这里是你项目最终要产出的图、表和报告。
  • 3_data 和 4_results 目录都是“可再生”的，因为 Snakemake 可以随时重新生成它们，所以不需要纳入 Git 版本控制。

第五步：配置版本控制 (.gitignore)

一个好的 .gitignore 文件能让你的 Git 仓库保持干净整洁。

.gitignore 示例：

# 忽略所有数据、结果和日志文件
/3_data/
/4_results/
/logs/

# 忽略 Notebook 的缓存文件
.ipynb_checkpoints/

# 忽略 Pixi 的环境缓存
/.pixi/

整合所有步骤：开始你的分析

  1. 准备工作： 将原始数据放入 3_data/3_1_raw/，参考数据放入 3_data/3_3_reference/，并填写好 2_config/ 目录下的配置文件。

  2. 激活环境： 在项目根目录下运行 pixi shell，即可进入配置好的工作环境。

  3. 运行流程： 同样在项目根目录下执行。

    # “演习”一下，看看要执行哪些任务
snakemake -n
 
# 用 8 个核心正式运行
snakemake --cores 8

  4. 探索结果： 在 5_notebooks/ 目录下打开 Jupyter Notebook，对 4_results/ 中的最终成果进行交互式的探索和可视化。

遵循这套结构，你的生物信息学项目将会从一开始就清晰、高效，并且科学严谨。

Graph View