FCS文本段关键Key含义与解析说明
FCS 文件 TEXT（文本）段关键 Key 含义与解析说明
以 FCS 3.2（2020，现行版） 为主，旧版本差异集中列在第 10、12 节。
用途：写 FCS 读文件 / 导入模块时的中文速查。描述已做简化，细节以原标准为准。
文中♦代表分隔符（delimiter），实际是 TEXT 段的第一个字节。
1. 一句话理解
DATA 段里只有一串数字，没有列名、没有类型、没有长度信息。
"怎么读这串数字、每个通道是什么、样本和仪器信息"全部放在 TEXT 段的 关键字♦值♦ 键值对里。
一个数据集包含 HEADER（必选、固定在最前）、TEXT（主段必选，补充段可选）、DATA（必选）、ANALYSIS（3.0 起可选）。
2. TEXT 段怎么定位（HEADER 偏移）
HEADER 前 58 字节是固定格式，每个偏移量占 8 字节、ASCII 数字右对齐、左侧补空格：
| 字节位置 | 内容 |
|---|---|
| 00–05 | 版本标识：FCS2.0 / FCS3.0 / FCS3.1 / FCS3.2（无空格） |
| 06–09 | 4 个空格 |
| 10–17 | 主 TEXT 段首字节偏移 |
| 18–25 | 主 TEXT 段末字节偏移 |
| 26–33 / 34–41 | DATA 首 / 末偏移 |
| 42–49 / 50–57 | ANALYSIS 首 / 末偏移（无该段时填 0 或留空格） |
| 58– | 用户自定义段偏移对（可选，可多组） |
解析要点：
- 偏移是含端点的首/末字节，段长 =
末 - 首 + 1。例：TEXT 256~1545 → 1290 字节。 - 偏移相对当前数据集首字节，不是文件绝对位置；多数据集用
$NEXTDATA串联（3.1 起不推荐多数据集）。 - 超过 99,999,999 字节的段：HEADER 里对应偏移写
0，真实值只放在 TEXT 的$BEGINDATA/$ENDDATA/$BEGINANALYSIS/$ENDANALYSIS里。 - 主 TEXT 必须整体落在前 99,999,999 字节内，但不要求紧跟 HEADER，也不要求在 DATA 之前。
- HEADER 结束到下一段之间用空格（ASCII 32）填充；HEADER 内不能有回车换行。
- 补充 TEXT 段可放在 HEADER 之后任意位置，由
$BEGINSTEXT/$ENDSTEXT定位，且只能放可选和自定义 key，不能与主 TEXT 重复。 - 2.0 的 ANALYSIS 段是必选段；3.0 起改为可选。
HEADER 实例（* 表示空格）：
FCS3.2*********256****1545****1792**202455*******0*******0
3. TEXT 段通用解析规则（实现必读）
| # | 规则 | 简化说明 |
|---|---|---|
| 1 | 分隔符 | TEXT 段第一个字节就是分隔符，取值 ASCII 1~126 的单字节（3.2 推荐换行 LF=10）。同一数据集的 ANALYSIS 段、补充 TEXT 段必须用同一个分隔符。 |
| 2 | 结构 | 字节流形如 ♦KEY1♦V1♦KEY2♦V2♦…。跳过首字节后，按分隔符交替读出 key、value。 |
| 3 | 转义 | key 或 value 里出现分隔符时，必须写成两个连续分隔符，解析时还原成一个。因 key/value 不允许为空，两个连续分隔符不会出现在「值与下一个 key 之间」，所以没有歧义。 |
| 4 | 编码 | key 用 ASCII 32~126 单字节；value 用 UTF-8（3.1/3.2）。3.0 默认 ASCII，靠 $UNICODE 指定哪些 key 用双字节码页。 |
| 5 | 数值 | ASCII 英文数字，不带空格、不带千分位逗号，可以有前导 0；整数为十进制；浮点可带 + -、小数点或 E/e 科学计数法。字符串型 value 里可以出现中文。 |
| 6 | 大小写 | key 不敏感（$tot = $TOT，读时统一转大写）；value 敏感。特例：判断时间通道的 $PnN 值建议大小写不敏感匹配 Time。 |
| 7 | 唯一/非空 | 同一数据集内 key 不得重复；key 和 value 都不能为空；任何 key 都没有默认值，缺失就是未知，不要自行猜测。 |
| 8 | 命名 | 标准 key 以 $ 开头且不得重新定义；厂商自定义 key 不得以 $ 开头，读取时忽略不认识的非 $ key。 |
| 9 | 禁用字符 | TEXT 段内不得有 CR/LF 等不可打印字符（ASCII 0~31、127），除非它是分隔符本身或位于 value 内部。 |
| 10 | 带 n 的 key | $PnX 的 n 从 1 连续编到 $PAR，与 DATA 段中列的顺序一一对应，不加前导零。$P 是历史命名（旧称 parameter，3.2 改称 measurement/通道）。$RnI / $RnW 的 n 是门区域号。 |
转义示例：
$SYS♦RSX-11♦♦M♦ → key=$SYS, value=RSX-11♦M
Key♦♦M1♦56♦ → key=Key♦M1, value=56
解析伪代码（不要直接 split(分隔符)，会破坏转义）：
delim = text[0] # 按字节取
i = 1
while i < len(text):
key = read_token() # 遇单个 delim 结束；遇 delim+delim 视为一个普通 delim 继续
value = read_token()
pairs[key.upper()] = utf8_decode(value)
补充提醒：按字节做状态机，UTF-8 解码放在取出 value 之后；不要把多字节字符当分隔符；复合值里逗号 , 常作字段分隔、分号 ; 用于 $RnW 顶点，而 $PnS 值内允许逗号、$PnN 值内禁止逗号。
4. 值格式记号与常用格式
| 记号 | 含义 |
|---|---|
n / n1,n2… |
ASCII 编码整数 |
f / f1,f2… |
ASCII 编码浮点数（支持 1.23 与 1.23E-2） |
string |
非空 UTF-8 字符串 |
c |
单个字符 |
[…] |
可选项 |
[REQUIRED] / [DEPRECATED] |
3.2 原文标注的必选 / 弃用 |
时间日期：$BEGINDATETIME 等用 ISO 8601 yyyy-mm-ddThh:mm:ss[Z 或 ±hh:mm]；旧 $DATE 用 dd-mmm-yyyy（月为 JAN…DEC）；旧 $BTIM/$ETIM 用 hh:mm:ss[.cc]（3.1 起 .cc 是 1/100 秒，3.0 是 1/60 秒）；$LAST_MODIFIED 用 dd-mmm-yyyy hh:mm:ss[.cc]。
5. 必选 Key（FCS 3.2 共 12 个，缺一不可）
| Key | 中文含义（简化） | 值 / 示例 | 解析方式 |
|---|---|---|---|
$BEGINDATA |
DATA 段首字节偏移 | n，如 123456789 |
与 HEADER 重复；HEADER 为 0 时以此为准。$TOT=0 时该值无意义，忽略 |
$ENDDATA |
DATA 段末字节偏移 | n |
长度 = END - BEGIN + 1；同上 |
$NEXTDATA |
下一数据集 HEADER 偏移 | n，0 = 最后一个 |
相对当前数据集首字节；用于多数据集文件 |
$PAR |
每个事件的通道（测量）数 | n，如 12 |
决定 $P1…$Pn 组数，也决定每个事件有几列 |
$TOT |
事件总数 | n，如 1000000 |
可为 0（空数据集）；校验 事件数 × 每事件字节数 = DATA 段长度 |
$DATATYPE |
默认数据类型 | I / F / D / A |
I=无符号二进制整数；F=IEEE754 单精度 32 位；D=双精度 64 位；A=ASCII 整数（3.2 弃用）。F/D 时所有 $PnB 必须为 32/64、所有 $PnE 必须为 0,0 |
$BYTEORD |
字节序 | 1,2,3,4 或 4,3,2,1 |
小端 / 大端。3.1 起只允许这两种（3.0 还允许 3,4,1,2 等混合序）。即使位宽不是 32 位也要写 |
$CYT |
仪器型号 | string，如 FACScan |
3.2 新升为必选；3.1 及以前是可选 |
$PnB |
第 n 通道分配的位数 | n，如 $P3B♦16♦ |
决定读取位宽；F/D 时固定 32/64；配合 $PnR 做位掩码。3.2 起非 8 的倍数已弃用（老文件仍有位打包） |
$PnR |
第 n 通道数值范围 | n，如 $P2R♦1024♦ |
I 型：通道值 0~R-1，并决定掩码（R 非 2 的幂时取下一个更高的 2 的幂算掩码）。F/D 型：只是期望范围，实际值可负、可超界，不加掩码 |
$PnE |
放大类型（线性/对数） | f1,f2，如 4,0.01 |
0,0=线性；f1>0=对数，f1=十进制跨度、f2=0 通道对应的线性值。二者必须同为 0 或同为正；f1,0 非法，建议按 f1,1 处理。浮点数据、时间通道强制 0,0 |
$PnN |
第 n 通道短名 | string，如 $P4N♦PE-A♦ |
必须唯一、不含逗号；值为 Time 表示时间通道（读时大小写不敏感比对） |
6. $Pn* 通道描述类 Key（可选，但读数据/显示时很常用）
| Key | 中文含义 | 值 / 示例 | 解析要点 |
|---|---|---|---|
$PnS |
通道长名（常含染料/标记） | string，如 CD161-PE |
可含逗号、可不唯一，常用作坐标轴标签；染料建议取 ISAC Probe Tag Dictionary 的简称 |
$PnD |
建议显示刻度 | Linear,f1,f2 / Logarithmic,f1,f2 |
Linear：f1/f2 = 显示左右边界（刻度单位，非通道单位）；Logarithmic：f1=显示十进制跨度数，f2=左边界刻度值。仅作显示默认值，软件可不采纳 |
$PnDATATYPE |
逐通道覆盖 $DATATYPE |
I / F / D |
3.2 新增。让 Time/Index 等整数通道在整体为浮点时仍用整数；不支持 A |
$PnG |
放大增益 | f，如 10.0 |
仅整数数据可用；线性时刻度值 = 通道值 / g；不能与对数 $PnE 同用，时间/补偿通道不要给 |
$PnCALIBRATION |
刻度值→标准单位 | f1[,f2],string，如 1.234,100,MESF |
f1=斜率，f2=截距（3.2 新增，缺省 0），string=单位名；标定值 = 刻度值 × f1 + f2，在 $PnE/$PnG 换算之后做。3.1 只有 f,string 无截距 |
$PnF |
滤光片 | string，推荐 n1,n2 |
n1/n2 = 通过波长下限/上限（nm），如 515,545 即 530/30；老文件常见 530/30、520LP。补偿后通道不应给 |
$PnL |
激发波长 | n1[,n2,…]，如 560,625 |
单位 nm；3.1 起支持多激光共用一通道。补偿后通道不应给 |
$PnO |
激发功率 | n1，如 200 |
单位 mW；补偿后通道不应给 |
$PnT |
探测器型号 | string，如 PMT9524 |
补偿后通道不应给 |
$PnV |
探测器电压/控制量 | f，如 445.5 |
非 PMT（如 APD）时表示其控制设定值；补偿后通道不应给 |
$PnDET |
探测器名 | string，如 FSC、FL1 |
3.2 新增，用于结构化区分"探测器" |
$PnTAG |
染料/同位素标签 | string，如 AF633 |
3.2 新增；建议用 ISAC 词典简称；可沿用到补偿后通道 |
$PnANALYTE |
靶标分子/过程 | string，如 CD4 |
3.2 新增；与 $PnTAG 配套 |
$PnTYPE |
测量类型 | string |
3.2 新增。推荐取值：Forward Scatter、Side Scatter、Raw Fluorescence、Unmixed Fluorescence、Mass、Time、Electronic Volume、Classification、Index |
$PnFEATURE |
信号特征 | string |
3.2 新增；适用时取 Area / Height / Width |
$PnP |
收集光比例（%） | n1，如 50 |
3.2 已弃用，老文件可能仍有 |
3.2 引入
$PnDET/$PnTAG/$PnANALYTE/$PnTYPE/$PnFEATURE，就是为了不再靠猜$PnN/$PnS里混在一起的探测器、染料、靶标、信号特征。新写文件建议优先用这 5 个。
7. 段偏移 / 结构类可选 Key
| Key | 中文含义 | 解析要点 |
|---|---|---|
$BEGINANALYSIS / $ENDANALYSIS |
ANALYSIS 段首/末偏移 | 无该段时省略或写 0；HEADER 对应值为 0 时要靠这两个判断是否存在。3.2 起由必选降为可选 |
$BEGINSTEXT / $ENDSTEXT |
补充 TEXT 段首/末偏移 | 必须写在主 TEXT 段里；无补充段时省略或写 0。3.2 起由必选降为可选 |
$MODE |
数据模式 | 3.2 只允许 L（list mode），直方图模式已移除；3.2 已弃用（表 4 仍列在可选里、正文标注弃用，属于标准内部不一致，读时按"存在即 L"处理） |
8. 时间 / 实验 / 样本 / 载体 / 统计类可选 Key
| Key | 中文含义 | 值 / 解析要点 |
|---|---|---|
$BEGINDATETIME / $ENDDATETIME |
采集开始 / 结束时间 | 3.2 新增，ISO 8601；时区可省（本地时间）、Z（UTC）或 ±hh:mm |
$DATE / $BTIM / $ETIM |
旧版日期 / 开始 / 结束时刻 | 3.2 弃用，改用上面两个；若与新版同时存在，值应一致 |
$EXP |
实验发起人 | 字符串 |
$OP |
仪器操作员 | 字符串 |
$INST |
采集机构 / 实验室 | 字符串 |
$PROJ |
实验（项目）名称 | 字符串；3.2 明确为"实验名" |
$FIL |
原始文件名 | 字符串，可含路径 |
$SYS |
采集用计算机与操作系统 | 字符串；标准里演示分隔符转义的例子就是它 |
$CYTSN |
仪器序列号 | 字符串 |
$CELLS |
被测对象（细胞/微球） | 字符串，也可用于校准微球 |
$SRC |
样本来源 | 字符串，可能含患者信息，读取时注意隐私合规 |
$SMNO |
样本 / 管 / 孔编号 | 字符串 |
$COM |
备注 | 字符串，不要拿它替代标准 key |
$CARRIERID / $CARRIERTYPE / $LOCATIONID |
载具 ID / 载具类型 / 样本在载具上的位置 | 3.2 新增，替代 $PLATEID/$PLATENAME/$WELLID；后者 3.2 弃用 |
$FLOWRATE |
进样流速档位名 | 3.2 新增，字符串（如 high），不是体积/时间的实际流速 |
$VOL |
采集消耗样本体积 | 浮点，单位 nL |
$ORIGINALITY |
数据集是否被改过 | 取值 Original / NonDataModified / Appended / DataModified |
$LAST_MODIFIED / $LAST_MODIFIER |
最后修改时间 / 修改人 | 注意实际 key 用下划线（标准表格里写成 $LAST MODIFIED 是排版问题）；仅当 $ORIGINALITY 非 Original 时可出现 |
$ABRT |
电子学限制丢失的事件数 | 整数，含义随仪器而定，需查厂商文档 |
$LOST |
计算机忙丢失的事件数 | 整数，与 $ABRT 区分 |
9. 数据语义 / 补偿 / 触发类可选 Key
| Key | 中文含义 | 值 / 解析要点 |
|---|---|---|
$TR |
触发通道与阈值 | string,f，如 FSC-H,54.5；string 必须等于某个 $PnN 值；信号超过阈值才记录事件。3.0 用 string,n |
$TIMESTEP |
时间通道每单位对应秒数 | 浮点，如 0.01；时间通道 = $PnN 值为 Time 的通道，必须 $PnE=0,0 且不给 $PnG；实际秒数 = 通道值 × $TIMESTEP。3.2 要求有时间通道就必须给此 key |
$SPILLOVER |
荧光溢出（补偿）矩阵 | n,名称1,…,名称n,S11,…,Snn，逗号分隔，元素总数 = 1+n+n×n；名称必须与 $PnN 完全一致；矩阵按行存放，补偿 = 原始行向量 × S⁻¹（列向量则先转置）。3.2 明确规定：含光谱数据的数据集不得使用此 key |
$UNSTAINEDCENTERS |
未染色对照群体的中心值向量 | 3.2 新增。m,名称1,…,名称m,f1,…,fm；可作为背景/自发荧光偏移，但注意它定义在原始测量空间，不能直接加到补偿结果上 |
$UNSTAINEDINFO |
上述向量的来源与统计方式 | 3.2 新增，字符串说明 |
$GATING / $RnI / $RnW |
门区域组合 / 区域对应通道 / 区域窗口 | 3.2 弃用。$RnI = Pi[,Pj]；$RnW 一维为 下界,上界，二维为 x1,y1;x2,y2;… 多边形顶点；$GATING 用 AND/OR/NOT 与括号组合区域 |
10. 已弃用 / 旧版本专有 Key（读老文件时会遇到）
10.1 FCS 3.2 弃用清单
$BTIM、$DATE、$ETIM、$MODE、$GATING、$RnI、$RnW、$PnP、$PLATEID、$PLATENAME、$WELLID，以及 $DATATYPE=A、$PnB 非 8 倍数的位宽。
替代关系：日期时刻 → $BEGINDATETIME/$ENDDATETIME；板/孔 → $CARRIERID/$CARRIERTYPE/$LOCATIONID。
10.2 3.2 已删除（3.0/3.1 老文件里可能有）
$COMP、$UNICODE、$CSMODE、$CSVBITS、$CSVnFLAG、$GATE、$GnE/$GnF/$GnN/$GnP/$GnR/$GnS/$GnT/$GnV、$PKn、$PKNn，以及直方图模式相关 key。
| 旧 Key | 出自 | 含义与解析 |
|---|---|---|
$COMP |
2.0/3.0 | 旧补偿矩阵 n,f1,f2,…，n×n 个浮点数按行存；负值表示减法补偿，元素是"从 FLi 中减去的 FLj 百分比"。3.1 起被 $SPILLOVER 取代 |
$UNICODE |
3.0 | n,key1,key2,…，n=UNICODE 码页号，其后列出哪些 key 的 value 用双字节编码；不出现时全按 ASCII。3.1 起取消，统一 UTF-8 |
$DFCiTOj |
2.0 | 电子补偿百分比，如 $DFC1TO3♦5♦ 表示从参数 1 向参数 3 补偿 5% |
$GATE / $Gm* |
2.0/3.0 | 门参数个数 / 门参数描述（类比 $PAR / $Pn*）；3.2 删除 |
$PKn / $PKNn |
2.0/3.0 | 一维直方图峰位通道号 / 峰位计数；随直方图模式一起删除 |
$RjI / $RjW |
2.0 | 门区域定义，2.0 中值是参数号（如 $R1I♦2,3♦），3.1 起改为 Pi,Pj 形式（如 $R3I♦P2,P4♦），解析老文件时注意区分 |
10.3 各版本必选 Key 数量变化
| 版本 | 必选 Key | 与上一版的变化 |
|---|---|---|
| 2.0 | $DATATYPE、$PAR、$MODE、$PnB、$PnR、$BYTEORD、$NEXTDATA（7） |
TEXT/ANALYSIS 均为必选段；支持直方图；$PnN 是可选 |
| 3.0 | 15 个 | 新增 $BEGINDATA/$ENDDATA/$BEGINANALYSIS/$ENDANALYSIS/$BEGINSTEXT/$ENDSTEXT 等偏移类；$TOT、$PnE 升为必选；$CYT 仍可选；引入 >99,999,999 字节文件与补充 TEXT 段 |
| 3.1 | 16 个 | $PnN 升为必选；$BEGINSTEXT/$ENDSTEXT、$BEGINANALYSIS/$ENDANALYSIS 必选；$MODE 必选 |
| 3.2 | 12 个 | $CYT 升为必选；4 个 ST/ANALYSIS 偏移 key 与 $MODE 降为可选/弃用 |
11. 组合解析：从 TEXT 到 DATA 里的数值
按下面顺序处理，几乎所有读取错误都出在这几步：
- 每事件字节数
$DATATYPE=I：sum($PnB) / 8字节（按位连续打包，老文件可能不是 8 的倍数）；若某通道有$PnDATATYPE，按该通道自己的类型算宽度。$DATATYPE=F：4 × $PAR；D：8 × $PAR；A：各通道$PnB字节（字符数），*表示变长并用空白/逗号分隔。- 校验：
DATA 段字节数 == $TOT × 每事件字节数。
- 字节序：按
$BYTEORD选小端/大端，再按各通道$PnB位宽读取。 - 整数通道掩码：
I型只保留能表示0 ~ $PnR-1的位；$PnR不是 2 的幂时按下一个更高的 2 的幂取掩码。F/D型不做掩码。 - 通道值 → 刻度值
- 线性 + 增益（
PnE=0,0、$PnG=g）：刻度值 = 通道值 / g - 对数（
$PnR=r、$PnE=f1,f2）：刻度值 = f2 × 10^(f1 × 通道值 / r)，取值范围f2 ~ f2×10^f1 - 浮点数据：
$PnE全为0,0、不用$PnG，通道值即刻度值
- 线性 + 增益（
- 标定：有
$PnCALIBRATION时，结果 = 刻度值 × f1 + f2（单位取该 key 的 string 部分）。 - 时间：时间通道（
PnN=Time）的值 ×$TIMESTEP= 秒。 - 补偿：按
$SPILLOVER构造矩阵 S，行向量 e × S⁻¹得补偿后值；仅适用于非光谱的传统荧光数据。 - 显示：按
$PnD设置初始坐标范围（Linear 用上下界，Logarithmic 用跨度数与左边界），不要把它当数据变换。
12. 版本差异速查
| 项目 | 2.0 | 3.0 | 3.1 | 3.2 |
|---|---|---|---|---|
| 版本标识 | FCS2.0 |
FCS3.0 |
FCS3.1 |
FCS3.2 |
| 分隔符 | 任意 ASCII | 任意 ASCII | 限 ASCII 1~126 | 同 3.1，推荐 LF |
| value 编码 | ASCII | ASCII + $UNICODE 码页 |
UTF-8 | UTF-8 |
| 大文件（>99,999,999 B） | 不支持 | 支持（HEADER 填 0，偏移进 TEXT） | 支持 | 支持 |
| 补充 TEXT 段 | 无 | 有 | 有 | 有 |
$BYTEORD |
多种组合 | 多种组合 | 仅 1,2,3,4 / 4,3,2,1 |
同 3.1 |
| 数据模式 | L / U / C 直方图 | 同 2.0（直方图弃用） | 直方图弃用 | 仅 L，$MODE 弃用 |
| 补偿 key | $DFCiTOj |
$COMP |
$SPILLOVER |
$SPILLOVER（光谱数据禁用） |
| 时间小数单位 | 无 | 1/60 秒 | 1/100 秒 | ISO 8601 时间戳 |
| 通道命名 | $PnN 可选 |
$PnN 可选 |
$PnN 必选；时间通道写作 TIME |
$PnN 必选；时间通道写作 Time（读时不区分大小写）；另加 $PnDET/TAG/ANALYTE/TYPE/FEATURE 5 个描述 key |
| 逐通道类型 | 无 | 无 | 无 | $PnDATATYPE |
13. 光谱流式项目落地提示
- 不要用
$SPILLOVER表达光谱解析矩阵。3.2 明确写了「含光谱数据的数据集不得使用$SPILLOVER」。FCS 3.2 目前没有标准的"参比光谱矩阵 / 光谱拆解矩阵"字段，工程上有两条路：① 用非$开头的自定义 key（如SIBET_SPECTRA）存矩阵或矩阵文件引用；② 光谱矩阵随文件外的光谱库单独管理，FCS 内只存结果数据。写文件时务必保留$ORIGINALITY说明数据是否经过解析。 - 原始与解析后数据用
$PnTYPE区分：Raw Fluorescence（探测器原始光谱通道）与Unmixed Fluorescence（解析后的染料通道）是 3.2 正式推荐的取值，比在$PnN/$PnS里拼字符串可靠。 - 通道多、常为浮点：优先
$DATATYPE=F（或D），对应$PnB=32/64、$PnE=0,0、不给$PnG、$PnR只作期望范围且不加掩码；Time/Index通道用$PnDATATYPE=I单独保留整数精度。 - 探测器维度描述：
$PnDET（探测器名）+$PnL（激发波长，多激光可写多个）+$PnF（滤光片通过波段）+$PnTAG（染料）+$PnFEATURE（Area/Height/Width）组合，比$PnS更适合光谱阵列通道。 - 3.2 只支持 list mode，若下游需要传统补偿视图，应做数据转换生成派生文件，而不是往原文件里塞
$SPILLOVER。
浙公网安备 33010602011771号