project_name/                 # 项目根目录（用有意义的名字，如 t2d_metagenome）
├── README.md                # 项目说明书（最重要的文件！）
├── CHANGELOG.md             # 版本变更记录
├── LICENSE                  # 开源许可证（如果要公开）
│
├── data/                    # 数据目录
│   ├── raw/                 # 原始数据（只读！绝对不能修改原始数据）
│   │   ├── sample1_R1.fastq.gz
│   │   └── sample_metadata.tsv
│   ├── processed/           # 中间处理结果
│   │   ├── clean_reads/
│   │   └── assemblies/
│   ├── reference/           # 参考数据库（或用软链接指向公共数据库）
│   │   └── silva_138/ -> /db/silva_138/
│   └── external/            # 外部数据（文献中下载的、合作方提供的）
│
├── scripts/                 # 分析脚本
│   ├── 01_qc.sh            # 按步骤编号，一看就知道顺序
│   ├── 02_assembly.sh
│   ├── 03_binning.sh
│   ├── 04_taxonomy.sh
│   ├── 05_statistics.R
│   └── utils/               # 工具函数、辅助脚本
│       └── common.sh
│
├── results/                 # 最终结果（图表、表格、报告）
│   ├── figures/             # 发表级图片
│   │   ├── fig1_diversity.pdf
│   │   └── fig2_heatmap.pdf
│   ├── tables/              # 结果表格
│   │   └── diff_abundance.tsv
│   └── reports/             # 分析报告
│       └── analysis_report.html
│
├── docs/                    # 文档
│   ├── methods.md           # 方法描述（论文 Methods 节草稿）
│   ├── notebook.md          # 分析日志/实验记录
│   └── references/          # 参考文献
│
├── envs/                    # 环境配置
│   ├── environment.yml      # conda 环境文件
│   ├── requirements.txt     # Python 依赖（如果用 pip）
│   └── Dockerfile           # 容器化配置（可选）
│
├── config/                  # 配置文件
│   ├── params.yaml          # 分析参数（集中管理）
│   └── sample_list.tsv      # 样本信息表
│
├── logs/                    # 运行日志
│   ├── 01_qc.log
│   └── 02_assembly.log
│
├── Makefile                 # 流程管理（或 Snakefile/nextflow.config）
└── .gitignore               # Git 忽略规则

# 大文件不入库
data/raw/
data/processed/
*.fastq.gz
*.bam
*.sam
*.fasta

# 日志
logs/

# 系统文件
.DS_Store
__pycache__/
*.pyc

# 编辑器临时文件
*.swp
*~
.vscode/

# T2D 肠道菌群宏基因组分析

## 项目简介
基于 2 型糖尿病（T2D）患者与健康对照的肠道宏基因组数据，
分析菌群组成差异、功能通路富集和潜在生物标志物。

## 数据来源
- 原始数据：NCBI SRA PRJNA123456（30 例 T2D + 30 例对照）
- 参考数据库：SILVA 138.1, KEGG 2025-01

## 环境配置
```bash
conda env create -f envs/environment.yml
conda activate t2d_meta

### 每段的作用

| 段落 | 作用 | 白话 |
|---|---|---|
| 项目简介 | 30 秒内让读者知道这是干啥的 | 电梯演讲 |
| 数据来源 | 数据可追溯 | 原始数据在哪下载的 |
| 环境配置 | 一条命令复现环境 | 换台电脑也能装好 |
| 分析流程 | 怎么跑、跑哪些步骤 | 操作手册 |
| 目录结构 | 文件在哪找 | 地图 |
| 结果概要 | 关键发现 | 不想看代码的人直接看结论 |

---

## 四、分析报告规范

### R Markdown 报告模板

```r
---
title: "T2D 肠道菌群多样性分析报告"
author: "[用户]"
date: "`r Sys.Date()`"           # 自动插入日期
output:
  html_document:
    toc: true                    # 自动生成目录
    toc_float: true              # 目录悬浮在侧边
    code_folding: hide           # 代码默认折叠（点击展开）
    theme: flatly                # 主题样式
params:
  data_path: "results/tables/"   # 参数化路径（可复用）
---

# 1. 分析概述
本报告分析 30 例 T2D 患者和 30 例健康对照的 16S rRNA 测序数据...

# 2. 数据概况
```{r load-data}
# 加载必要的包
library(phyloseq)   # 微生物组分析
library(ggplot2)    # 绑图

# 读取数据
ps <- readRDS(file.path(params$data_path, "phyloseq_object.rds"))
cat("样本数:", nsamples(ps), "\n")
cat("物种数:", ntaxa(ps), "\n")

plot_richness(ps, x = "Group", measures = c("Shannon", "Simpson"))

sessionInfo()   # 记录所有 R 包版本

### Jupyter Notebook 报告模板

```python
# 第一个 cell：环境信息
import sys
import pandas as pd
import matplotlib.pyplot as plt

print(f"Python: {sys.version}")       # 记录 Python 版本
print(f"pandas: {pd.__version__}")    # 记录包版本

# 导出为 HTML：jupyter nbconvert --to html report.ipynb

# ========== 1. 文件级注释（docstring） ==========
"""
模块名: diversity_analysis.py
功  能: 计算 alpha/beta 多样性指标
作  者: [用户]
日  期: 2026-05-01
依  赖: scikit-bio>=0.5.8, pandas>=1.5
"""

# ========== 2. 函数级注释 ==========
def calculate_shannon(abundance_table):
    """
    计算 Shannon 多样性指数。

    Parameters
    ----------
    abundance_table : pd.DataFrame
        物种丰度表，行=样本，列=物种，值=reads数

    Returns
    -------
    pd.Series
        每个样本的 Shannon 指数

    Examples
    --------
    >>> shannon = calculate_shannon(otu_table)
    >>> print(shannon.mean())
    """
    # 3. 行内注释（解释"为什么"，而非"做了什么"）
    # 加伪计数避免 log(0)（零丰度物种会导致数学错误）
    table = abundance_table + 1e-10
    proportions = table.div(table.sum(axis=1), axis=0)
    return -(proportions * np.log(proportions)).sum(axis=1)

# ========== 函数说明 ==========
# 功能：检查 FASTQ 文件是否完整（行数应为 4 的倍数）
# 参数：$1 = fastq 文件路径
# 返回：0=完整，1=不完整
check_fastq_integrity() {
    local fastq_file="$1"
    local line_count
    line_count=$(zcat "$fastq_file" | wc -l)   # 统计行数（解压后）
    # FASTQ 每条 read 占 4 行，所以总行数必须能被 4 整除
    if (( line_count % 4 != 0 )); then
        return 1    # 不完整
    fi
    return 0
}

# TODO: 后续版本添加 Beta 多样性的 PERMANOVA 检验
# FIXME: 当样本数 < 10 时 bootstrap 会报错，需要加判断
# HACK: 临时绕过 phyloseq 的 bug，等上游修复后删除
# NOTE: 这里用 Bray-Curtis 而非 UniFrac 是因为没有进化树
# DEPRECATED: 这个函数在 v2.0 中将被 calculate_diversity() 替代

v1.2.3
 │ │ └── Patch：修 bug（不影响接口）
 │ └──── Minor：加功能（向后兼容）
 └────── Major：重大变更（可能不兼容）

# 生信项目示例：
# v0.1.0 - 初始版本，完成质控流程
# v0.2.0 - 新增组装和分箱步骤
# v0.2.1 - 修复 MEGAHIT 内存参数错误
# v1.0.0 - 完整流程，论文投稿版本
# v1.1.0 - 审稿人建议新增功能注释分析

# Changelog

## [v1.1.0] - 2026-05-03
### Added
- 新增 KEGG 功能注释分析步骤（scripts/05_kegg.sh）
- 新增差异丰度分析的 Volcano Plot

### Changed
- MEGAHIT 最小 contig 长度从 500bp 改为 1000bp

### Fixed
- 修复 MetaBAT2 在单样本模式下崩溃的问题

## [v1.0.0] - 2026-04-20
### Added
- 完整的宏基因组分析流程（QC → Assembly → Binning → Taxonomy）
- R Markdown 分析报告
- conda 环境配置文件

# 给当前提交打标签
git tag -a v1.0.0 -m "论文投稿版本"   # -a 创建带注释的标签
git push origin v1.0.0                 # 推送标签到远程

# 查看所有标签
git tag -l                             # 列出所有标签

# 查看某个标签的详情
git show v1.0.0

# 分析日志

## 2026-05-03

### 目的
探索 T2D 组和对照组在 Shannon 多样性上是否有显著差异

### 操作
1. 用 phyloseq 计算 Shannon 指数
2. Wilcoxon 秩和检验比较两组差异
3. 绘制箱线图

### 参数
- 稀释深度：10000 reads/样本
- 检验方法：Wilcoxon rank-sum test（非正态分布）

### 结果
- T2D 组 Shannon 指数均值 2.31 ± 0.45
- 对照组 Shannon 指数均值 3.12 ± 0.38
- p = 0.003（显著）

### 决策
多样性确实降低，继续做 Beta 多样性（PCoA）看组间分离情况

### 相关文件
- 脚本：scripts/05_statistics.R（第 42-78 行）
- 图：results/figures/fig1_alpha_diversity.pdf

# conda 环境导出
conda env export --no-builds > envs/environment.yml
# --no-builds 去掉编译哈希，跨平台兼容性更好

# pip 环境导出
pip freeze > envs/requirements.txt

# R 环境记录
Rscript -e 'sessionInfo()' > envs/R_session_info.txt
# 或者用 renv
Rscript -e 'renv::snapshot()'

# 一键创建项目目录结构
mkdir -p myproject/{data/{raw,processed,reference,external},scripts/utils,results/{figures,tables,reports},docs,envs,config,logs}
touch myproject/{README.md,CHANGELOG.md,Makefile,.gitignore}
chmod -R 444 myproject/data/raw/   # 原始数据只读（有文件后设）