单细胞项目为什么要在测序前确定文件命名规则

命名错误为何会成为分析错误

单细胞项目常同时包含供体、组织、处理条件、建库批次和测序批次。文件名如果只写一个简短样本号，含义就被留在个人记忆或聊天记录里。几周后，分析者可能知道文件来自哪个项目，却无法判断它是否是重新拆分、重新比对或经过过滤的版本。真正危险的不是文件看起来凌乱，而是不同对象被误当成同一对象。

命名规则的作用，是让机器可读的标识与人工可理解的实验设计保持稳定关系。它不能代替样本表，却应当让文件与样本表能够互相校验。

命名方案还要考虑自动化工具的排序方式。若样本号使用不等长数字，文件列表可能把S10排在S2之前；补零、固定字段和明确分隔符能减少脚本读取差异。

文件名里的日期容易被误解为采样、建库、测序或上传日期。若日期确有用途，应在字段字典中定义其含义，并将其他时间点保存在清单。

跨语言团队应统一字段值而不是只翻译说明文档。字段名可以提供双语解释，实际数据值保持受控，才能避免自动汇总失效。

若“跨语言团队应统一字段值而不是只翻译说”相关条件发生变化，应在派生文件映射中新增版本，而不是覆盖旧结论。“跨语言团队应统一字段值而不是只翻译说”的新旧记录并列，才能判断变化来自样本、工具、参考数据还是人员决策。

先把生物学身份与技术批次分开

供体、组织和处理条件描述生物学问题；建库板、芯片通道和测序批次描述技术过程。两类字段混在一个自由文本名称里，会让后续统计模型难以判断哪些差异需要保留，哪些差异需要控制。较稳妥的做法是为每类字段设定固定位置，并为缺失值准备明确代码。

编号不宜直接包含姓名、手机号或病历号。研究团队应使用去标识化样本编号，把可识别信息留在权限更严格的映射表中。

同一供体的重复建库不应覆盖旧编号。重复实验既可能用于技术验证，也可能对应新的处理条件，保留独立运行标识才能在质量比较时知道差异来自哪里。

字段字典应同时保留“同一供体的重复建库不应覆盖旧编号”对应的正常结果与例外说明。与“同一供体的重复建库不应覆盖旧编号”相关的失败原因、重试次数和最终决定，往往比一组只有成功样本的记录更有参考价值。

多个分析团队并行工作时，派生结果需要运行标识而不是分析者姓名。人员会变化，运行标识可以稳定关联代码提交、环境和参数。

围绕“多个分析团队并行工作时”形成的派生文件映射最好采用结构化字段，并限制自由文本承担核心含义。“多个分析团队并行工作时”的结构化记录便于自动检查，自由文本则保留无法预先编码的现场情况。

版本冻结后若发现规则缺陷，应发布修订说明和迁移脚本。直接批量改名而不保存映射，会让旧报告、校验清单和共享链接全部失去对应关系。

批次记录还需要写明“版本冻结后若发现规则缺陷”的适用范围。一个批次、平台或组织得到的经验，不应直接推广到所有项目；明确边界能减少不可比较的操作。

原始数据和派生数据不能共用一种语气

FASTQ、比对结果、表达矩阵、质控报告和细胞注释表处于不同处理阶段。若它们都只沿用样本名，文件夹里很快会出现 final、new、latest 之类无法追溯的后缀。更好的方法是把处理阶段、软件或流程版本、关键参数版本写进元数据，并让目录结构承担一部分层级关系。

文件名应当短而稳定，复杂信息进入结构化清单。这样既避免路径过长，也能让批量脚本、对象存储和协作平台可靠处理。

组织名称应使用项目认可的词表。自由输入容易同时出现中文、英文、缩写和旧称，分析合并时会把同一组织拆成多个类别，或把不同区域错误合并。

复核“组织名称应使用项目认可的词表”时，不只检查文件是否存在，还要让另一位成员根据派生文件映射完成一次读取或重建。能够独立复现关键步骤，才说明文字已经转化为可用接口。

命名规则应兼容对象存储、Linux服务器和桌面系统。斜线、冒号、尾随空格和大小写差异都可能导致跨平台同步后出现不同路径。

若“命名规则应兼容对象存储、Linux服”相关条件发生变化，应在批次记录中新增版本，而不是覆盖旧结论。“命名规则应兼容对象存储、Linux服”的新旧记录并列，才能判断变化来自样本、工具、参考数据还是人员决策。

目录权限也要跟随数据阶段。原始数据、临床映射和公开结果不应因为使用相同样本号就自动拥有相同访问范围。

针对“目录权限也要跟随数据阶段”，可以把判断写进权限清单，并指定核对人、完成时间和异常处理方式。“目录权限也要跟随数据阶段”出现差异时，团队便能回到同一份记录，而不是依赖聊天截图或个人记忆。

建立一份可执行的样本清单

样本清单至少应包含唯一编号、实验条件、批次、数据文件、校验值和当前状态。上传前由产生数据的人填写，分析前由接收者复核。若文件数量与清单不一致，应先停止合并，而不是用猜测补齐。

清单最好使用受控词汇和数据验证，避免同一组织出现多个拼写。日期采用统一格式，版本号使用递增规则，状态字段区分待上传、已校验、分析中和已归档。

若研究跨越多个机构，可以在项目清单中保留机构字段，但不必把机构名称写进每个文件。合作关系可能变化，稳定样本身份不应依赖组织简称。

围绕“若研究跨越多个机构”形成的批次记录最好采用结构化字段，并限制自由文本承担核心含义。“若研究跨越多个机构”的结构化记录便于自动检查，自由文本则保留无法预先编码的现场情况。

不要在文件名里保存会频繁变化的结论，例如最终细胞类型。注释属于版本化分析结果，样本与原始数据身份则应保持稳定。

权限清单还需要写明“不要在文件名里保存会频繁变化的结论”的适用范围。一个批次、平台或组织得到的经验，不应直接推广到所有项目；明确边界能减少不可比较的操作。

验收时随机抽取几个文件，从名称回查样本表、实验记录和派生流程，再从样本表反向找到所有文件。双向都能完成，规则才真正可用。

公开提交表应同时保留“验收时随机抽取几个文件”对应的正常结果与例外说明。与“验收时随机抽取几个文件”相关的失败原因、重试次数和最终决定，往往比一组只有成功样本的记录更有参考价值。

把校验值放进交接过程

大文件传输完成不代表内容完整。传输前后计算校验值，可以发现中断、静默损坏或错误覆盖。校验清单应与数据包分开保存，同时记录算法和生成时间。若文件经过解压、拆分或格式转换，应重新生成派生文件的校验记录。

校验值只能证明两份字节相同，不能证明样本标签正确。因此它必须与样本清单、实验记录和交接确认共同使用。

条形码白名单、拆分规则和样本多重化方法也要进入版本记录。相同FASTQ经过不同拆分参数，可能得到不同细胞集合，派生目录必须能说明处理来源。

若“条形码白名单、拆分规则和样本多重化方”相关条件发生变化，应在权限清单中新增版本，而不是覆盖旧结论。“条形码白名单、拆分规则和样本多重化方”的新旧记录并列，才能判断变化来自样本、工具、参考数据还是人员决策。

合并样本产生的新对象需要新的编号，并记录来源样本列表。仅把多个编号用加号拼接，容易超过路径限制，也不利于机器查询。

针对“合并样本产生的新对象需要新的编号”，可以把判断写进公开提交表，并指定核对人、完成时间和异常处理方式。“合并样本产生的新对象需要新的编号”出现差异时，团队便能回到同一份记录，而不是依赖聊天截图或个人记忆。

规则需要经过一次小规模演练

在正式测序前，用几个模拟样本跑一遍命名、上传、校验、读取和归档流程。演练能暴露大小写、空格、特殊字符、路径长度和自动化脚本兼容问题。修改规则后再冻结版本，并把示例放在团队容易找到的位置。

一个可执行的规则通常比一份很长却无人验证的说明更可靠。团队成员应能根据示例独立完成命名，也能从任一派生文件追溯到原始样本。

样本撤回或伦理范围变化时，不宜直接从目录中无痕删除。应在权限允许的记录里标明状态、处理日期和影响输出，防止旧派生结果继续被使用。

公开提交表还需要写明“样本撤回或伦理范围变化时”的适用范围。一个批次、平台或组织得到的经验，不应直接推广到所有项目；明确边界能减少不可比较的操作。

项目可设置保留字段，禁止临时含义占用。规则扩展时优先新增可选字段，避免重新解释已经用于历史数据的代码。

样本主表应同时保留“项目可设置保留字段”对应的正常结果与例外说明。与“项目可设置保留字段”相关的失败原因、重试次数和最终决定，往往比一组只有成功样本的记录更有参考价值。

项目结束时仍要保留解释能力

项目交付后，人员和工具都会变化。只有把字段定义、版本历史、样本清单和校验记录一起归档，未来的复分析才不会依赖某个人的记忆。对于准备公开的数据，还要检查公开编号与内部编号的映射是否泄露身份。

好的命名规则并不追求把所有信息塞进文件名，而是让每个文件都能进入一条可核对的数据链。

公开数据库通常要求特定元数据字段。项目内部规则若能提前映射到公开提交格式，结项时就不必从聊天记录反向重建样本背景。

质量控制失败的文件不应改名成bad后丢在角落。清单中的状态、失败原因和复测关系更适合表达质量决定，也方便统计失败模式。