探索型生信分析项目管理规范手册

返回

探索型生信分析项目管理规范手册

发布于: 更新于:
统计加载中...

1 总原则

一个项目目录应该回答 6 个问题：

问题对应目录
项目是什么？怎么运行？README.md
分析步骤在哪里？code/
可复用工具在哪里？utils/
原始和处理后数据在哪里？data/
样本信息在哪里？metadata/
图表结果在哪里？results/
分析说明和记录在哪里？docs/

推荐顶层结构：

ProjectName/
├── README.md
├── code/
├── utils/
├── data/
├── metadata/
├── results/
└── docs/

2 顶层目录职责

2.1 README.md

项目入口说明文件。建议包括：

# Project title

## Background
## Data sources
## Directory structure
## Analysis workflow
## How to run
## Key outputs
## Notes

不要写太长，但要能让三个月后的自己看懂。

2.2 code/

放主分析流程脚本。特点：

  • 一步一个脚本
  • 按执行顺序编号
  • 不放大段可复用函数
  • 不放临时测试脚本

推荐：

code/
├── 00_parse_metadata.R
├── 01_read_qc.R
├── 02_filter_qc.R
├── 03_clustering.R
├── 04_major_annotation.R
├── 05_celltype_fraction.R
├── 06_deg.R
└── 07_subcluster_analysis.R

命名规则：

步骤编号_动作_对象.R

例如：

01_read_qc.R
02_filter_qc.R
03_run_clustering.R
04_annotate_major_celltypes.R
05_compare_cell_fractions.R
06_run_deg_by_celltype.R

2.3 utils/

放可复用工具和资源。包括：

  • 函数
  • marker 表
  • 调色板
  • 主题函数
  • 通用绘图函数
  • 批处理模板
  • 公共参数

推荐：

utils/
├── functions/
│   ├── io_utils.R
│   ├── qc_utils.R
│   ├── seurat_utils.R
│   └── plot_utils.R
├── markers/
│   ├── major_celltype_markers.csv
│   └── microglia_markers.csv
├── palettes/
│   └── plot_colors.R
└── workflows/
    ├── run_rscript_template.sh
    └── submit_job_template.sh

原则：

code/ 管流程，utils/ 管能力。

2.4 data/

放数据对象。推荐：

data/
├── raw/
└── processed/

2.4.1 data/raw/

放原始数据。

原则：

  • 不手动修改
  • 不覆盖
  • 不直接用于保存分析结果
  • 下载什么样就尽量保持什么样

例如：

data/raw/
├── GSE237718_RAW/
├── GSE237718_RAW.tar
└── checksums.txt

2.4.2 data/processed/

放处理后的中间对象。例如：

data/processed/
├── 01_read_qc/
│   └── seurat_raw_qc.rds
├── 02_filter_qc/
│   └── seurat_filtered.rds
├── 03_clustering/
│   └── seurat_clustered.rds
└── 04_major_annotation/
    └── seurat_annotated.rds

原则：

RDS、h5ad、rda、loom、处理后的矩阵都放 data/processed/，不要放 results/。

2.5 metadata/

放正式输入样本信息。例如：

metadata/
├── Metadata.Ind.csv
├── GSE237718_series_matrix.txt.gz
└── metadata_dictionary.md

适合放：

  • 样本分组表
  • donor 信息表
  • GEO series matrix
  • 样本字段说明
  • 手工整理后的正式 metadata

不适合放：

  • metadata 检查结果
  • 样本数统计表
  • 缺失样本检查表
  • 临时预览文件

这些应该放到：

results/tables/00_metadata_check/

2.6 results/

放结果。

推荐第一层按文件类型拆：

results/
├── figs/
└── tables/

第二层按分析步骤拆：

results/
├── figs/
│   ├── 00_metadata_check/
│   ├── 01_read_qc/
│   ├── 02_filter_qc/
│   ├── 03_clustering/
│   ├── 04_major_annotation/
│   ├── 05_celltype_fraction/
│   ├── 06_deg/
│   └── 07_subcluster_analysis/
└── tables/
    ├── 00_metadata_check/
    ├── 01_read_qc/
    ├── 02_filter_qc/
    ├── 03_clustering/
    ├── 04_major_annotation/
    ├── 05_celltype_fraction/
    ├── 06_deg/
    └── 07_subcluster_analysis/

原因：

  • 找图时只进 figs/
  • 找表时只进 tables/
  • 每一步结果又不会混在一起

不建议：

results/
├── 01_read_qc/
│   ├── figs/
│   └── tables/

这种也能用，但后面写论文时找图表不如第一种顺手。

2.7 docs/

放人类阅读材料。 推荐：

docs/
├── data_sources.md
├── sample_metadata_notes.md
├── analysis_plan.md
├── run_log.md
├── methods_draft.md
└── questions_and_decisions.md

用途：

文件内容
data_sources.md数据来源、GEO 编号、DOI、下载链接
sample_metadata_notes.md样本分组、字段含义、特殊说明
analysis_plan.md分析路线
run_log.md每次运行记录
methods_draft.md后续论文/开题的方法草稿
questions_and_decisions.md关键问题和决策记录

3 可选目录

3.1 logs/

如果项目运行脚本很多，可以加：

logs/
├── 00_parse_metadata.log
├── 01_read_qc.log
└── 02_filter_qc.log

如果你不想顶层多目录，也可以放：

results/logs/

但我个人建议单独 logs/，更清楚。

3.2 envs/

如果需要记录环境：

envs/
├── environment.yml
├── renv.lock
├── sessionInfo_renv.txt
└── package_versions.csv

如果环境简单，也可以把这些放进 docs/。

3.3 archive/

放废弃但暂时不想删的东西：

archive/
├── old_scripts/
└── deprecated_results/

原则：

不确定要不要删的，先进 archive/，不要混在主流程里。

4 推荐完整模板

ProjectName/
├── README.md
│
├── code/
│   ├── 00_parse_metadata.R
│   ├── 01_read_qc.R
│   ├── 02_filter_qc.R
│   ├── 03_clustering.R
│   ├── 04_major_annotation.R
│   ├── 05_celltype_fraction.R
│   ├── 06_deg.R
│   └── 07_subcluster_analysis.R
│
├── utils/
│   ├── functions/
│   │   ├── io_utils.R
│   │   ├── qc_utils.R
│   │   ├── seurat_utils.R
│   │   └── plot_utils.R
│   ├── markers/
│   │   ├── major_celltype_markers.csv
│   │   └── microglia_markers.csv
│   ├── palettes/
│   │   └── plot_colors.R
│   └── workflows/
│       └── run_rscript_template.sh
│
├── data/
│   ├── raw/
│   └── processed/
│       ├── 01_read_qc/
│       ├── 02_filter_qc/
│       ├── 03_clustering/
│       └── 04_major_annotation/
│
├── metadata/
│   ├── Metadata.Ind.csv
│   ├── series_matrix.txt.gz
│   └── metadata_dictionary.md
│
├── results/
│   ├── figs/
│   │   ├── 00_metadata_check/
│   │   ├── 01_read_qc/
│   │   ├── 02_filter_qc/
│   │   ├── 03_clustering/
│   │   └── 04_major_annotation/
│   └── tables/
│       ├── 00_metadata_check/
│       ├── 01_read_qc/
│       ├── 02_filter_qc/
│       ├── 03_clustering/
│       └── 04_major_annotation/
│
└── docs/
    ├── data_sources.md
    ├── sample_metadata_notes.md
    ├── analysis_plan.md
    ├── run_log.md
    └── methods_draft.md

5 文件命名规范

5.1 脚本命名

编号_动作_对象.R

例如：

01_read_qc.R
02_filter_qc.R
03_run_clustering.R
04_annotate_major_celltypes.R
05_compare_cell_fractions.R
06_run_deg_by_celltype.R

5.2 结果表命名

步骤编号_内容.csv

例如：

01_sample_qc_summary.csv
01_matrix_metadata_match.csv
02_filter_cell_counts.csv
03_cluster_markers.csv
04_celltype_annotation_summary.csv

5.3 图命名

步骤编号_图内容.pdf

例如：

01_qc_violin_by_sample.pdf
01_qc_scatter_counts_features.pdf
03_umap_by_cluster.pdf
04_umap_by_major_celltype.pdf
05_cell_fraction_by_group.pdf

6 路径写法规范

推荐：

project <- path.expand("~/Projects/APOE_TGP_scRNA_GSE237718")

raw_dir <- file.path(project, "data/raw/GSE237718_RAW")
meta_file <- file.path(project, "metadata/Metadata.Ind.csv")

result_dir <- file.path(project, "results")
fig_dir <- file.path(result_dir, "figs")
table_dir <- file.path(result_dir, "tables")

不推荐在分析脚本里大量写：

"./data/raw"

也不推荐写死：

"/home/nizhu/Projects/APOE_TGP_scRNA_GSE237718/data/raw"

最佳实践：

project <- path.expand("~/Projects/项目名")

然后所有路径用：

file.path(project, "子目录", "文件名")

7 code/、utils/、data/、metadata/ 的边界

7.1 code/

放主流程：

source(file.path(project, "utils/functions/qc_utils.R"))

然后执行分析。

7.2 utils/

放函数和资源，不直接跑完整分析。

7.3 data/

放数据对象。

7.4 metadata/

放正式样本信息。

7.5 results/

放图表和统计结果。

7.6 docs/

放解释和记录。

8 不同文件应该放哪里

文件位置
GEO 原始压缩包data/raw/
10x 原始矩阵data/raw/
Seurat RDSdata/processed/步骤名/
样本分组表metadata/
字段说明metadata/metadata_dictionary.md
metadata 检查结果results/tables/00_metadata_check/
QC 图results/figs/01_read_qc/
QC 表results/tables/01_read_qc/
UMAP 图results/figs/03_clustering/
DEG 表results/tables/06_deg/
marker gene 列表utils/markers/
调色板utils/palettes/
通用函数utils/functions/
分析计划docs/analysis_plan.md
运行记录docs/run_log.md

9 生信项目特别建议

9.1 原始数据永远不改

data/raw/

只读，不改，不覆盖。

9.2 每个关键节点保存 RDS

例如：

data/processed/01_read_qc/seurat_raw_qc.rds
data/processed/02_filter_qc/seurat_filtered.rds
data/processed/03_clustering/seurat_clustered.rds
data/processed/04_major_annotation/seurat_annotated.rds

这样中间出错不用从头跑。

9.3 每步都输出一个 summary 表

例如：

01_sample_qc_summary.csv
02_filter_summary.csv
03_cluster_cell_counts.csv
04_annotation_summary.csv

9.4 每步都保存 session 信息

可以在每个脚本结尾加：

sink(file.path(log_dir, "01_sessionInfo.txt"))
sessionInfo()
sink()

或者统一放：

docs/session_info/

10 最简可执行版本

如果不想太复杂，最小版本就是：

ProjectName/
├── README.md
├── code/
├── utils/
├── data/
│   ├── raw/
│   └── processed/
├── metadata/
├── results/
│   ├── figs/
│   └── tables/
└── docs/

这套已经足够支撑大多数生信分析项目。

评论