Stunner API 三段字符串:实验、样品、结果

系列指南 · 第 5 篇

Stunner API 三段字符串：实验、样品、结果

19 个 API 命令本身只是动作开关：打开托盘、关闭托盘、开始测量。仪器具体要测什么、测哪几个孔、结果里要给哪些列，都靠三段纯文本字符串传给 Stunner。三段分别是实验定义、样品定义、结果定义，彼此靠列号串起来。格式本身不复杂，但字段多，第一次写最容易漏字段或对错列号。

先认识几个名词

• INI 格式 / [Section] 段 — 一种纯文本配置文件格式。用 [方括号里的名字] 划分段落，段落内每行 key=value。实验定义和结果定义都是这种格式。
• CSV — Comma-Separated Values，逗号分隔的纯文本表格。样品定义就是一份没有表头的 CSV，每行一个孔。
• 列号映射 — 实验定义里告诉仪器"样品定义这张 CSV 表里第 N 列装的是什么数据"。列号从 0 开始数。
• BSRF — 简化写法里的孔类型标识，一个字母：B = Blank(空白),S = Sample(样品),R = Reference(参考),F = Fluorescent(荧光)。Reference 是已知浓度的参考样，可以排成浓度梯度。
• sample group(样品组) — 一组共用同一份空白和参考样的样品。一板上可以放多个 sample group，各自用各自的空白扣本底。
• blanking_information — 实验定义里的一个字段，值 0–4，告诉仪器这次实验整体怎么扣空白，从 0 的 autoblank 到 4 的本地空白库。各个值怎么选，见下文「空白的五种用法」。
• DAR — Drug-Antibody Ratio，药物抗体偶联比，ADC(抗体偶联药物)的关键质量参数。Stunner 的 ADC 应用从 UV/Vis 吸光度算出 DAR。
• API Tester — Unchained Labs 自带的桌面工具。它不接工作站也能直接对着 Stunner 把三段字符串和命令逐一调通。

三段字符串各管什么

脚本里要传字符串的地方有两处：调用 Define_Experiment 时，前两个参数是实验定义和样品定义；调用 Get_Results 时，第一个参数是结果定义。三段各管各的内容，衔接点在列号：实验定义里写明"样品定义的第几列是什么数据"，样品定义就按这个约定排列。

• 段 1 — 实验定义 — Experiment Definition — 告诉仪器这次"怎么测":实验名、用哪个应用、DLS 参数、扣空白方式。 — 同时声明样品定义那张表里每一列是什么(列号映射)。 — INI 格式，两个 [Section]
• 段 2 — 样品定义 — Sample Definition — 告诉仪器"测哪些孔":一行一个孔，板号、孔位、样品名、缓冲液等等。 — 可以一次写多块板，共用一段实验定义。 — 无表头 CSV
• 段 3 — 结果定义 — Results Definition — 告诉仪器"返回什么":要哪些列、怎么分隔、空格子填什么。 — 列名必须和 Stunner Analysis 软件 Report Settings 里的列名一字不差。 — INI 格式，一个 [Export results] 段

实验定义：仪器怎么测

实验定义文件分两个 INI 段：[Experiment definition] 写这次实验本身的设置(实验名、应用、DLS 参数等);[Import samples] 写样品定义那张 CSV 表的列号映射(每一列是什么数据)。

[Experiment definition] 段：实验设置

字段:含义

experiment_name:自定义实验名；含空格时整段套半角双引号

application_name:应用名，和 Stunner Client 的 Select app 页面里一模一样，例如 "Protein + Advanced Sizing"、"RNA-LNP EE"

dropplate_type:板型，Stunner Plate 填 "Stunner Plate";比色皿适配器是另一种板型，见手册第 6 节

dls_acquisition_time:DLS 单次采集时长，单位秒，正数

dls_number_of_acquisitions:DLS 采集次数，正数

dls_number_of_angles:DLS 角度数，最多 30，默认 7。不做 DLS 的应用可省略前三项

background_wavelength:单点应用(Single Point apps)的背景波长，单位 nm，例如 320

[Import samples] 段：列号映射

每一项 column_xxx=N 表示样品定义 CSV 里第 N 列(从 0 开始数)装的是什么数据。这些字段大多可选，哪些必填由所选的 application 决定。没用到的填 -1，仪器会跳过这一列；也可以整行省略，不会报错。常用的几类字段：

• 基本定位 — column_plate_ID · column_plate_position · column_sample_name · column_sample_group — 孔的板号、孔位(A1–H12 写法)、样品名、样品组名(sample group)。一板上只有一组样品时，sample group 一列可以填 -1 省掉。
• 样品来源追溯 — column_source_plate · column_source_position — 样品在源板(比如 biobank 板、储样板)上的板名和孔位。用于追溯 Stunner Plate 上每个孔对应到上游哪个原始样品，典型用于 LIMS 集成。
• 应用相关 — column_analyte · column_buffer · column_payload — 可测物质、缓冲液、负载物。具体哪些字段必填、填什么值，由 application_name 决定，可以在 Stunner Client 的 Select app 页面查。
• 蛋白浓度 — column_E1% — 蛋白 1% 消光系数(E1%),Stunner 用这个值把 280 nm 吸光度换算成浓度。
• ADC 双波长 — column_E_mAb_at_280nm · column_E_mAb_at_drug_wvl · column_drug_wvl · column_E_drug_at_drug_wvl · column_E_drug_at_280nm — ADC 双波长应用算 DAR 要用的几项，即抗体和药物在 280 nm 和药物特征波长上的消光系数，以及药物特征波长本身。
• 参考样 — column_reference_value — 参考样(reference)的已知浓度。只对 R 类型的孔有意义。
• 空白指定 — column_blank_plate_ID · column_blank_plate_position · column_stored_blanks_sample_group_name — 逐行指定每个样品配哪个空白。需要 blanking_information = 3 或 4 才用得到。

样品定义：一行一个孔

样品定义就是一份没有表头的 CSV，每行写一个孔的全部信息。列的顺序你可以自己定，只要和实验定义里的列号映射对得上即可。下面是手册里的经典示例，对应 12 个样品 + 4 个空白：

对应的实验定义里，列号映射就是：column_plate_ID=0、column_plate_position=1、column_sample_name=2、column_analyte=3、column_buffer=4、column_E1%=5。空白行最后一列空着，因为空白不需要消光系数。

写样品定义有三条要点：

• 分隔符是英文逗号。
• 某一列没数据，要保留空位(两个逗号之间空着 ,,)，不要省略，否则后面的列会错位。
• 字段里如果含逗号或空格，用半角双引号包起来。

上面这个例子整板只有一个 sample group。一板上也可以放两组或两组以上(比如各自用不同缓冲液、各自需要自己的空白)。这时在样品定义里多加一列，写 sample group 的名字。同时在实验定义里加 column_sample_group=N，告诉仪器 sample group 名在样品定义的第几列。

手册里的双组示例：A1 是 SG1 的空白，B1/C1/D1 是 SG1 的样品；E1 是 SG2 的空白，F1/G1/H1 是 SG2 的样品。每组各扣各的空白，结果按组返回。

结果定义：输出什么列

结果定义控制 Get_Results 返回的文本格式：要哪些列、怎么分隔、缺失值怎么显示。一个典型例子：

• column_names — 返回的列名清单，用 ; 分隔。列名必须和 Stunner Analysis 软件 Report Settings 标签页里看到的完全一致，大小写、空格、单位都不能差。常用的有：Plate ID、Plate Position、Sample name、Concentration (mg/ml)、Z-Avg Dia. (0deg) (nm)、PdI、A280、Temperature (degC)。
• separator — 列之间的分隔字符。只能填 ;(分号)、,(英文逗号)或 tab 三个值之一。
• undefined_column_name — 当 column_names 里的某个列名 Analysis 不认识时怎么办。"remove" 从结果里去掉、"include" 保留但留空、"Return_error" 直接报错让脚本知道。生产环境建议用 "Return_error"，避免列名写错却没察觉，等数据进了 LIMS 才发现。
• no_result_value — 没结果的格子里填什么(比如空白孔的浓度、未加液孔的粒径)。默认 "-"，也可以写成 ""、"N/A"、"0"。要进数据库的，推荐 "" 或 "N/A"，别用 "0"，容易被误算进平均值。

做 RADLS 多角度散射实验时，还可以把每个角度的分布数据(DLS XY data)加进 column_names。可用字段名：Intensity distribution、Mass distribution、Numbers distribution、Correlation function。多角度时如果只要某一个角度的相关函数，写成 Correlation function_143deg(143 换成实际角度数值)。

这几个字段写进 column_names 之后，在 return text 里会按粒径或时间展开成一大批列，不单独占一列。例如分布数据的列名是 Int. Distr. (15nm)、Int. Distr. (30nm)，一直到 Stunner 这次测出来的所有粒径值；相关函数则是 Delay_30deg (1.5s)、Delay_30deg (3.0s)，一直到所有时间点。括号里的数字是具体的粒径或时间。

所以 column_names 里多加一个 Intensity distribution,return 拿回来的列数就会多一大批。脚本里读这些数据时，建议按列名前缀(Int. Distr.、Mass Distr.、Numb. Distr.、Delay_)去匹配，不要写死成"第几列到第几列"。这是因为粒径和时间点的数量会随仪器配置变化，列数不固定。

经典写法 vs BSRF 简化写法

前面的例子用的是经典写法，孔的类型(空白/样品/参考/荧光)靠样品名约定或者列号映射来区分。Stunner AF 上线之后，Unchained Labs 加了一种简化写法。它在样品定义最左边多一列 BSRF，把孔类型直接标在第一位。对普通样品，两种写法在仪器侧效果一样，差别只在样品表从哪来。LNP EE、ADC 这类一个样品要占几种孔型的应用，则要用 BSRF。

传统

经典写法

样品定义里没有 BSRF 列。孔类型靠样品名或 blank_name_used 等字段约定。

• · 适合 LIMS / 调度系统直接出的 CSV(孔类型已经按列分开存)
• · 改造成本低，把现成表拿过来，填好列号映射就行
• · 不适合一个样品同时占多种孔型的应用

BSRF

简化写法

实验定义里加 column_BSRF=0，样品定义第一列填 B / S / R / F，孔类型直接写在第一列。

• · 适合从 Client 板布局可视化导出的样品表
• · 适合 LNP EE、ADC 等一个样品占多种孔型(S + F 配对)的应用
• · 一眼能看出每个孔是什么类型，人工 review 更直观

下面摘自手册里 RNA-LNP EE(包封率)实验的 BSRF 样品定义，只截了几行。手册原表里参考样(R)有 4 个浓度梯度，空白(B)有 4 个。同一个 sample_1 占两种孔：S 孔测 UV/Vis+DLS,F 孔测荧光。

中间的 ,, 表示这一列没值，占位用。所有孔放在同一个 sample group 里，共用一份空白和参考样。

从 Client 软件的板布局编辑器导出的样品表，默认就是这种 BSRF 排列。这套字符串和 Client 板布局之间是双向的。可以先在 Client 的板布局编辑器里设计好布局，再导出成 BSRF 字符串给 API 用。也可以把脚本里跑过的字符串导回 Client，用界面再编辑或人工 review。

Stunner Client 软件的板布局编辑器。左侧四种颜色对应 BSRF 四种孔型：黄是 Reference、蓝是 Blank、绿是 Sample、紫是 Fluorescent。这种可视化布局可以一键导出成 API 用的样品定义字符串。

对应的 Edit samples 表格视图。每行一个样品，左边的色块即是 BSRF 类型。后面是样品名、参考浓度、UV/VIS+DLS 孔位、Fluo 孔位、Source Plate ID、Source Position、Payload、Buffer。这张表的内容和 API 样品定义字符串一一对应。

空白的五种用法

实验定义里有一个字段 blanking_information，值 0–4，决定这次实验整体怎么扣空白。值选错的话，整板的浓度结果会整体偏掉，而且不容易立刻看出来。

怎么选:日常筛选最常用 1 或 3。1 简单，每板放几个空白做平均，适合大多数场景；3 严谨，每个样品配对自己的缓冲液空白，适合多种缓冲液混测的实验。自动化整夜跑、空白长期固定的项目，4 最省事。前一天做一板空白存进库里，后面几板都直接引用。0 仅在高浓度且精度要求不高时使用。

多板实验的两条约束

一次 Define_Experiment 可以包含任意多块板。所有孔都写进同一个样品定义字符串里，通过 Plate 1、Plate 2 这样的板号区分。Define_Experiment 返回的 plate_IDs 数组按定义顺序列出每块板的 ID，后续 Measure(plate_ID) 依次调用即可。

设计上有两条硬约束，违反会被仪器直接报错。

板数要对得上

实际放进仪器测量的板数，要和样品定义里声明的板数一致。多放或少放都会被拒。

Get_Results 要等全部测完

Get_Results 要等所有声明的板都测完之后才能调用。提前调，Stunner 会返回错误，不会返回半截结果。全部测完之后，plate_ID 留空一次取回所有板，填某块板的 ID 则只取那一块。

所以中途要放弃，需要显式发 Abort_Measurement，不能默默跳过剩下的板。

在 API Tester 上先验一遍

上面这些字段，任何一个写错都要到测量时才暴露。直接接上工作站再调试，代价不小，一块样品板装错就要重做。Unchained Labs 自带的 API Tester 工具不接工作站，也能直接对着 Stunner 把字符串和命令逐一调通。这样，字符串和命令顺序上的错误在接工作站之前就能排除。界面如下：

Lunatic & Stunner API Tester 工具。顶部一排按钮一对一对应 19 个 API 命令；中间 Experiment / Sample / Results 三块文本框就是这一篇讲的三段字符串；底部 return code / return text 显示每条命令的执行结果。

左侧填 Stunner 的 IP 和端口(6300)，中间三个文本框粘进三段字符串。然后挨个点上方的命令按钮(Define_Experiment、Measure、Get_Results 等等)。底部会显示这次调用的返回码和返回文本。等到 Define_Experiment 返回 0、Get_Results 能拿到预期的列之后，再去接真实工作站。

Tester 自带一些默认脚本作为模板。第一次写字符串，可以从默认模板里拷一份过来在它上面改，不必从零开始。手册里给的几个示例(table 2、3、7、9 等)也在这套模板里能找到对应的起点。

除了字符串语法和命令顺序，Tester 还会把 .bin 原始数据真正写到实验定义里指定的网络共享目录。也就是说，不接工作站，"配置 → 命令 → 数据落盘"整条链路就能先跑通一遍。

Tester 里写好的脚本，可以保存到下面这个目录，以后直接从下拉菜单里选用：

.txt 脚本文件里，实验定义、样品定义、结果定义这三段之间要用两个连续换行分隔，Tester 才能识别出三段。

• three-strings · 三段字符串各管什么
• experiment · 实验定义：仪器怎么测
• results · 结果定义：输出什么列
• classic-vs-simplified · 经典写法 vs BSRF 简化写法
• multi-plate · 多板实验的两条约束
• api-tester · 在 API Tester 上先验一遍
• INI 格式 / [Section] 段 · 一种纯文本配置文件格式。用 [方括号里的名字] 划分段落，段落内每行 key=value。实验定义和结果定义都是这种格式。
• CSV · Comma-Separated Values，逗号分隔的纯文本表格。样品定义就是一份没有表头的 CSV，每行一个孔。
• 列号映射 · 实验定义里告诉仪器"样品定义这张 CSV 表里第 N 列装的是什么数据"。列号从 0 开始数。
• BSRF · 简化写法里的孔类型标识，一个字母：B = Blank(空白),S = Sample(样品),R = Reference(参考),F = Fluorescent(荧光)。Reference 是已知浓度的参考样，可以排成浓度梯度。
• sample group(样品组) · 一组共用同一份空白和参考样的样品。一板上可以放多个 sample group，各自用各自的空白扣本底。
• blanking_information · 实验定义里的一个字段，值 0–4，告诉仪器这次实验整体怎么扣空白，从 0 的 autoblank 到 4 的本地空白库。各个值怎么选，见下文「空白的五种用法」。
• DAR · Drug-Antibody Ratio，药物抗体偶联比，ADC(抗体偶联药物)的关键质量参数。Stunner 的 ADC 应用从 UV/Vis 吸光度算出 DAR。
• API Tester · Unchained Labs 自带的桌面工具。它不接工作站也能直接对着 Stunner 把三段字符串和命令逐一调通。
• 段 1 · 实验定义 · Experiment Definition · 告诉仪器这次"怎么测":实验名、用哪个应用、DLS 参数、扣空白方式。 · 同时声明样品定义那张表里每一列是什么(列号映射)。 · INI 格式，两个 [Section]
• 段 2 · 样品定义 · Sample Definition · 告诉仪器"测哪些孔":一行一个孔，板号、孔位、样品名、缓冲液等等。 · 可以一次写多块板，共用一段实验定义。 · 无表头 CSV
• 段 3 · 结果定义 · Results Definition · 告诉仪器"返回什么":要哪些列、怎么分隔、空格子填什么。 · 列名必须和 Stunner Analysis 软件 Report Settings 里的列名一字不差。 · INI 格式，一个 [Export results] 段
• 基本定位 · column_plate_ID · column_plate_position · column_sample_name · column_sample_group · 孔的板号、孔位(A1–H12 写法)、样品名、样品组名(sample group)。一板上只有一组样品时，sample group 一列可以填 -1 省掉。
• 样品来源追溯 · column_source_plate · column_source_position · 样品在源板(比如 biobank 板、储样板)上的板名和孔位。用于追溯 Stunner Plate 上每个孔对应到上游哪个原始样品，典型用于 LIMS 集成。
• 应用相关 · column_analyte · column_buffer · column_payload · 可测物质、缓冲液、负载物。具体哪些字段必填、填什么值，由 application_name 决定，可以在 Stunner Client 的 Select app 页面查。
• 蛋白浓度 · column_E1% · 蛋白 1% 消光系数(E1%),Stunner 用这个值把 280 nm 吸光度换算成浓度。
• ADC 双波长 · column_E_mAb_at_280nm · column_E_mAb_at_drug_wvl · column_drug_wvl · column_E_drug_at_drug_wvl · column_E_drug_at_280nm · ADC 双波长应用算 DAR 要用的几项，即抗体和药物在 280 nm 和药物特征波长上的消光系数，以及药物特征波长本身。
• 参考样 · column_reference_value · 参考样(reference)的已知浓度。只对 R 类型的孔有意义。
• 空白指定 · column_blank_plate_ID · column_blank_plate_position · column_stored_blanks_sample_group_name · 逐行指定每个样品配哪个空白。需要 blanking_information = 3 或 4 才用得到。
• column_names · 返回的列名清单，用 ; 分隔。列名必须和 Stunner Analysis 软件 Report Settings 标签页里看到的完全一致，大小写、空格、单位都不能差。常用的有：Plate ID、Plate Position、Sample name、Concentration (mg/ml)、Z-Avg Dia. (0deg) (nm)、PdI、A280、Temperature (degC)。
• separator · 列之间的分隔字符。只能填 ;(分号)、,(英文逗号)或 tab 三个值之一。
• undefined_column_name · 当 column_names 里的某个列名 Analysis 不认识时怎么办。"remove" 从结果里去掉、"include" 保留但留空、"Return_error" 直接报错让脚本知道。生产环境建议用 "Return_error"，避免列名写错却没察觉，等数据进了 LIMS 才发现。
• no_result_value · 没结果的格子里填什么(比如空白孔的浓度、未加液孔的粒径)。默认 "-"，也可以写成 ""、"N/A"、"0"。要进数据库的，推荐 "" 或 "N/A"，别用 "0"，容易被误算进平均值。
• 0 · autoblank · 仪器内部估算，不专门测空白。适合浓度较高、对精度要求不严格的样品；低浓度场景准确度不足。
• 1 · averaging of blanks · 多个空白取平均。在 blank_name_used 里写空白的名字(例 "blank1")。样品定义里把这个名字写到几个孔上，仪器取这些孔的平均值作为空白。
• 2 · single blank · 整板共用一个空白。可以用 blank_name_used 指定名字，也可以用 blank_plate_ID + blank_plate_position 直接指定一个具体的孔。
• 3 · multiple blanks · 每个样品配自己的空白。在样品定义里用 column_blank_plate_ID 和 column_blank_plate_position 两列，逐行指定。
• 4 · stored blanks · 用仪器本地存好的空白库(空白库通过 Stunner Client 的 Transfer Blanks 或 API 的 Store_Blanks 命令存入)。多个 sample group 时，用 stored_blanks_sample_group_name(整体指定)或 column_stored_blanks_sample_group_name(逐行指定)告诉仪器从空白库里取哪个 group。