📚 课程目录第3章 FASTQ文件命名规范

3. 文件命名规范：让文件名替你说话

在FASTQ的世界里，文件名不是随便起的。我见过太多项目，样本数据拿到了，结果文件名乱七八糟，根本分不清哪个是哪个。说白了，文件名就是第一道元数据防线。一个好名字，能让你半年后回看时，一秒就知道这是哪批样本、什么条件、第几次测序。

这一章，我们就来聊聊命名规范。我会从最实用的原则讲起，再拆开每个字段的含义，最后给你一套可以直接用的模板。嗯，避坑指南自然少不了——我以前踩过的坑，你就不用再踩了。

3.1 命名原则：三个必须一个不要

先定规矩。不管项目有多大，命名规范必须满足这四个基本点：

唯一性：同一项目中，任何两个文件不能有完全一样的名字。
可排序：按文件名排序后，相同样本的文件应该自然聚在一起。
自解释：脱离说明文档，单看文件名也能猜出七八分内容。
平台兼容：不要用空格、括号、冒号、中文。Linux 命令行下这些字符会让你欲哭无泪。

我个人习惯用下划线 _ 作为字段分隔符，连字符 - 只在值内部使用。比如 Tumor_WES 表示肿瘤样本的全外显子捕获，清晰明了。以前有个项目用了空格+中文括号，结果写循环批量处理时脚本炸了一地——嗯，从此我再也不敢在文件名里用特殊字符。

3.2 必要组件：文件名里放什么

一个规范的 FASTQ 文件名，至少要包含以下 6 个核心组件。我用表格列出来，方便你对照检查。

字段	含义	示例	备注
平台缩写	测序平台	NovaSeq, HiSeq, MGI	便于区分不同产线
运行日期	测序开始日期	20250314	YYYYMMDD 格式，方便排序
样本ID	送检样本唯一编号	S001, S002	与 LIMS 系统一致
组织/细胞类型	样本来源	PBMC, Tumor, FFPE	方便后续分组分析
文库编号	同一样本可能有多文库	L001, L002	区分同一份样本的不同建库批次
读段方向	双端还是单端	R1, R2, I1	R1 为正向读段，R2 为反向

当然，你还可以视项目需求加入更多字段，比如捕获面板、分析版本、批次号等等。但有一点请记住：字段不宜过多，控制在 7 个左右最佳。我以前试过塞了 12 个字段，结果文件名比序列本身还长，根本没法读。

3.3 项目命名约定：统一团队标准

单个文件命名是一回事，整个项目怎么定标准又是另一回事。我建议在项目启动前，先开个 5 分钟的会，把下面这张表填好：

约定项	选择原则	团队常用方案
组织缩写	统一用 3-6 个字母	PBMC, Tumor, Normal, CellLine
捕获面板	面板名称标准化	WES, WGS, RNAseq, Panel_v2
批次号	全局递增或日期编码	B001, B002 或 20250314_01
分析版本	语义化版本号	v1.0, v2.1_beta

🛠 我的经验： 不要等到测序数据下机了才去改文件名。我个人习惯在实验前就生成好样本-文件名映射表，建库时直接用。这样能避免很多低级错误，比如文件名打错字、大小写不一致、字段顺序错乱……

3.4 实战：写一个合规的文件名

好，理论讲完了，我们来动手拼一个。假设今天有一个实际场景：

平台：NovaSeq 6000
运行日期：2025年3月14日
样本ID：TS001
组织类型：FFPE
捕获面板：全外显子 (WES)
文库编号：第1个文库 (L01)
读段方向：R1

对应的文件名就是：

NovaSeq_20250314_TS001_FFPE_WES_L01_R1.fastq.gz

用下划线分割，所有字段大写开头，数一下刚好 7 个字段。再写个双端 R2：

NovaSeq_20250314_TS001_FFPE_WES_L01_R2.fastq.gz

你想想看，如果项目里有 100 个样本，每个样本 2 个读段文件，文件名只要按字母排序，所有同一样本的文件自然就聚在一起了。这就是可排序性的价值。

3.5 避坑指南：我踩过的几个雷

⚠️ 注意： 以下问题都是我在真实项目中遇到过的，你千万要避开。

不要用大小写混搭：比如 tumor_WES 和 Tumor_WES 在 Linux 下会被视为两个不同样本。我建议全大写或全小写，统一就好。
不要用句号做分隔：有些人喜欢用 TS001.Tumor.WES.R1.fastq.gz，但句号在生物信息软件中容易引起解析歧义。推荐只用下划线。
不要包含空格：任何空格、制表符、换行符都不要出现。有个合作团队在文件名里加了空格，结果我的 for 循环直接爆炸。
不要用过长的样本ID：有些 LIMS 系统会生成 TS20250314_FFPE_001_A_2 这类超长 ID。建议重新映射成简短编号，比如 TS001 到 TS999。

我曾经有一次因为文件名里混了大写和小写的 "R1"/"r1"，导致下游分析脚本只认 _R1 而不认 _r1，不得不挨个重命名。那滋味，不想再体验第二次。

3.6 我的推荐模板：拿来即用

如果你不想从头设计，可以用我一直在用的这套模板。它经过十几个项目的检验，兼容主流分析流程（cellranger、bwa、STAR 等）：

{平台}_{运行日期}_{样本ID}_{组织}_{捕获面板}_{文库编号}_{读段方向}.fastq.gz

例如：

NovaSeq_20250314_TS001_FFPE_WES_L01_R1.fastq.gz
NovaSeq_20250314_TS001_FFPE_WES_L01_R2.fastq.gz
NovaSeq_20250314_TS001_FFPE_WES_L02_R1.fastq.gz
NovaSeq_20250314_TS001_FFPE_WES_L02_R2.fastq.gz

注意文库编号的变化：L01 和 L02 表示同一份样本做了两次建库。这在 FFPE 样本中很常见，因为 DNA 质量差可能需要重做。

    📌 关键总结：
    命名规范要早定，最好在实验前就定好映射表。
6-7 个结构化字段足够覆盖 95% 的场景。
字段间用下划线，字段内用连字符，全大写或全小写统一。
绝对不要使用空格、特殊字符、中文。
按文件名排序后，同一样本的文件自然相邻。

好了，命名规范这部分我先讲这么多。下一节我们要进入实操环节——怎么用命令行批量重命名、校验格式、以及把这些命名规则固化到自动化脚本里。