用 PLAN 一步步建实验设计

用 PLAN 一步步建实验设计 从选系统到检查通过,每一步填什么、会被什么拦住

PLAN 用五步向导建实验设计。每一步点 Next 时都会先检查,不通过就不能进入下一步。走到 Finish 的设计,就是这台 Stuntman 能运行的设计。

文中的截图大多来自原厂指南里的同一个例子:一份注射剂稳定性筛选设计。先在 4 × 6 母板上配 8 个处方,再分到振荡、热和冻融三块子板上加应力。五个程序各做什么,见 Stuntman 软件概览。内容依据原厂 Stuntman PLAN User Guide(Rev A)。

一个 .stunt 项目文件可以存多个设计

PLAN 启动后是 Dashboard,只有两个按钮。Create New Design 新建设计,Open Existing Design 打开已有设计。

新建设计时不会马上让你起名。第一次点 Save 时,才弹出 Design Management 窗口,选文件位置、填设计名。默认文件名是「Active Design」加日期时间,可以改成有意义的名字。

Design Management 窗口

打开和保存用的是同一个窗口,分四块。顶部是文件路径,左边是最近用过的文件,最多 30 个。中间是文件里的设计列表,右边是所选设计的详情。

  • 同一块样品库要在几个设计里用,建议把这些设计存进同一个 .stunt 文件。后面第 2 步可以直接从下拉列表选这块库。
  • 无关的设计分开存。一个 .stunt 文件上限 10 GB,RUN 的结果数据也写在里面。
  • 双击设计名可以重命名,最长 256 个字符。重命名时按 Esc 等于点 Cancel,整个窗口关闭,未保存的改动全部丢掉。
  • 同一文件里设计名不能重复,不分大小写。Design1 和 design1 算同名。
  • Description 和 Created By 建议随手填好,以后在文件里找设计靠这两栏。

Design Management 窗口。中间选中的是注射剂稳定性筛选设计,右边是它的描述,以及已经写好的加单抗、组氨酸缓冲液、辅料等步骤。System Name 一栏已涂去。图取自原厂用户指南。

复制和删除

  • Duplicate:复制选中的整个设计。Current File 复制到同一个文件,Another File 复制到另一个 .stunt 文件。副本自动改名为「原名_年月日_时分秒」。
  • 复制到另一个文件时,如果那个文件里已有同名样品库,行列数必须一致,否则报「Library Conflict in Target File」。
  • Delete:删除前会让你确认。只读设计不能删,选中时 Delete 按钮是灰的。
  • 窗口里的 Cancel 只放弃改名和描述这类改动,撤销不了已经做的复制和删除。

运行过的设计变成只读

RUN 往设计里写入第一条结果数据时,这份设计就永久锁定,列表里显示挂锁图标。只读设计能看,不能改名、编辑或删除,也没有办法解锁。要改就先 Duplicate,改副本。

如果你正在 PLAN 里编辑的设计被 RUN 运行了,界面不会变灰,照样能输入。点 Save 或 Next 时,PLAN 才发现它已锁定,丢掉刚才的输入,弹出 Design Locked 对话框。可能被运行的设计,先复制一份再继续改。

多人共用项目文件

打开 .stunt 文件时,PLAN 在同一文件夹里建一个 .lock 文件,防止另一个 PLAN 同时编辑。回到 Dashboard 或关闭 PLAN 时自动释放。

  • 文件放在共享网络盘上,用映射的盘符访问,不要直接输入 UNC 路径。
  • 每个要编辑的人都要有这个文件夹的写权限。只有读权限的人建不了 .lock 文件,PLAN 也不报错,两个人可能同时改同一个文件。
  • 不要放在 OneDrive、SharePoint、Dropbox、Google Drive 这类云同步文件夹里。.lock 文件不一定及时同步,两个人可能各改一份副本。
  • .lock 文件锁和挂锁图标是两回事。挂锁表示设计已运行过、不能再改;.lock 表示有人正开着这个文件。

PLAN 没有自动保存,也没有崩溃恢复。从第 2 步起每一步都有 Save 按钮,Save 不做完整检查,未完成的设计也能存下来,下次接着做。

第 1 步 Select System:选定这台 Stuntman 的硬件配置

选的系统决定了后面能用哪些分液、处理和检测工具,以及台面上有哪些位置。

  • 在 Current System 下拉列表里选系统。没选之前,页面提示「Please select a system configuration to proceed」,Next 是灰的。
  • 选好后,左边出现 Dispense Tools、Process Tools、Analysis Tools 三类工具卡片,系统里没有的类别不显示。右边是台面布局图。
  • 核对工具和台面无误,点 Next。

在连着 Stuntman 的电脑上,或者配置文件夹里只有一个系统时,系统会自动选好,直接点 Next。列表里缺系统,要往 C:\Stuntman\Plan\Configurations 里加配置文件夹,做法见 电脑要求与软件安装。

第 1 步选定系统后的界面。左边是这台系统的工具,分液用 PDT。处理工具有 Time Controls、VPG、Capping Station、Vortexer 等。右边是台面布局。图取自原厂用户指南。

已保存的设计如果换系统,PLAN 会从项目文件里删除这份设计,化学品、样品库和流程全部清空。换之前会弹出警告,点 Cancel 可以退回。拿不准以后会不会换系统,先 Duplicate 一份再换。

第 2 步 Add Chemicals & Libraries:登记试剂,定义板子

这一步有两张表。上面登记化学品,下面定义样品库。样品库就是一块板或一个样品瓶架,用行数 × 列数定义,每个设计至少要有一个。

注射剂稳定性的例子里有六种化学品。单抗原液 50 mg/mL,组氨酸缓冲液 pH 6.0,蔗糖 40% w/v。另外三种是 1% w/v 聚山梨酯 80、150 mM 氯化钠和注射用水。样品库是 4 × 6 的母板、三块 4 × 6 的应力子板,以及一块 8 × 12 的 Lunatic 读板。

化学品

  • 表头有名称、类别、分子量、密度、浓度、浓度单位、SMILES 和条码。只有 Name 必填。
  • Category 决定第 3 步里化学品按什么分组,例如 Buffer、Excipient、Protein、Solvent、Surfactant。
  • 分子量、密度和浓度只能填数字、小数点或科学计数法,填了就必须大于 0。
  • Conc Unit 从下拉列表选,有 mol/L、mmol/L、mg/mL、Mass %、Volume %、mol % 等。
  • 化学品名和条码在设计内不能重复,不分大小写。

常用试剂不必每次手敲。Import 从 .tsv 文件批量导入,表头必须和 PLAN 的列一致。Add To Favorites 把选中的行存进个人常用清单,下次用 Add From Favorites 调出来。名称、分子量和密度都相同的行会跳过。

样品库

  • 表头是 Name、Rows、Columns、Description、Barcode。
  • 行列数要对应这台系统上配置过的板或样品瓶架。尺寸放不进任何台面位置时,报「No accommodating substrate found」。
  • Name 下拉列表列出同一 .stunt 文件里其他设计用过的库,显示为「库名 (设计名)」。选一个,行列数、描述和条码自动填好,上一个设计跑完后的剩余体积带过来作为起始体积。
  • 库一旦被流程步骤用到,行列数就不能再改,也不能删。要改,先删掉用到它的步骤。
  • Duplicate 复制选中的库,名字后加「 - Copy」。同一块库复制两次会得到两个同名的库,保存前要改掉一个。

库在另一个 .stunt 文件里时,点 Libraries 下面的 Import。浏览到那个文件,选设计,勾选要的库加入导入清单,再点 Import。当前文件里已有同名的库,整次导入会被拒绝。

从另一个 .stunt 文件导入样品库。选中注射剂稳定性设计后,右上列出它的四块库。母板和冻融板都是 4 × 6,已加入导入清单。系统名已涂去。图取自原厂用户指南。

Save 和 Next 检查的内容不同

选整行要点最左边的行号。只点单元格不算选中行,Delete Rows、Add To Favorites、Duplicate 这些按钮会一直是灰的。PLAN 里所有表格都是这样。

  • Save:只查两件事。有数据的行必须有名字,化学品和库的名字不能重复。
  • Next:做全部检查,所有问题一起列出来。包括必填项、名称和条码不重复、数值大于 0、库的尺寸与系统配置相符。
  • 一个设计最多 1024 种化学品、1024 个样品库。

第 2 步的两张表。下面两块 8 × 12 库是复制出来的,条码都是 1,底部状态栏报条码重复,改好才能继续。图取自原厂用户指南。

第 3 步 Create a Recipe:按顺序加分液、处理和检测步骤

这是 PLAN 里内容最多的一屏。上半部分编辑当前这一步,下半部分是 Recipe 列表,存放已经加好的所有步骤。左上角选步骤类型:Dispense Step、Process Step 或 Analytics Step。

这一屏的选项、参数和操作名都有鼠标悬停说明。不确定某个选项做什么,先把鼠标停在上面看。

分液步骤的选项

右边的 Options 面板从上到下这样填:

  • Dispense Operation:Liquid Dispense(液体)或 Powder Dispense(粉末),只列出系统支持的。
  • Dispense Tool:第 1 步系统里的分液工具,例如 6Tip 或 PDT。工具有多种吸头规格时,会多出一个 Tip Type。
  • Dispense Category:选好工具后出现,进一步细分操作,例如 BackSolvent。
  • 可选勾选项(Tag):如 Source Tracking、Destination Tracking、Look Ahead。列表随上面选的操作和类别变化。RUN 按这些 Tag 决定用哪个硬件、怎么执行。

有些 Tag 在同一系统上互斥,勾选时 PLAN 会自动处理。分液类别和液面跟踪的原理,见 Stuntman 分液指南。

分液步骤的编辑区:左边选来源,中间选目标库和孔,右边是 Options。这里选的是 Liquid Dispense、H6Tip 和 BackSolvent 类别,下面是可勾选的 Tag。图取自原厂用户指南。

从化学品加到孔里

  • Select Source 选 Chemicals,从按 Category 分组的树里点一种化学品,例如单抗原液。
  • Select Destination Library 选目标库,在下面的板图上选孔。选中的每个孔都会加这种化学品。
  • 切到 Value 标签,填加入量,选单位。
  • 在右边 Options 里选操作、工具和类别。
  • 点 Add To Recipe,这一步出现在下方列表里。

Value 标签容易忘,它和 Options 不在一处。没填加入量就点 Add To Recipe,会弹框说明缺了什么。

选孔有几种方式:单击选一个孔,Ctrl+单击增减单个孔,拖动框选一块,点行号或列号选整行整列,勾 Select All 选全板。

所有孔加同样的量,用 Uniform。每个孔加的量不同,用 Discrete,逐孔填写,也可以用 Import 从 CSV 文件批量导入。例子里的糖、聚山梨酯 80、氯化钠和注射用水都用 Discrete 逐孔加,8 个孔配成 8 个处方。体积单位有 µL 和 mL,质量单位有 µg、mg、g、kg。

从一块板转移到另一块板

板间转移,例如梯度稀释、复制子板,来源要选 Libraries。

  • Select Source 选 Libraries,选来源库,在弹出的小板图上选要吸的孔。
  • 选目标库和目标孔。
  • 两边都选好后,切到 Map 标签,查看来源孔和目标孔的对应关系,需要时调整。
  • 切到 Value 标签填转移量,点 Add To Recipe。

来源和目标是同一块库时,同一个孔不能两边都选。两边选了同一个孔,Add To Recipe 会报错,并列出重叠的孔。

Auto-Mapping:多孔对多孔时选 Daughter 或 Transpose

  • 一个来源孔:自动对应到所有选中的目标孔,不弹框。
  • 多个来源孔对一个目标孔:只能 Pool,把所有来源孔合到这一个孔里,弹框确认。
  • 多个来源孔对多个目标孔:两边都必须是连续的矩形区域。弹框让你选 Daughter(默认)或 Transpose,Pool 不可选。

Daughter 把来源区域的排布原样印到目标区域,能整除时重复铺满。例如 4 × 6 的排布按 2 × 2 印满 8 × 12 板。不能整除时,按顺序把来源孔依次排到目标区域。Transpose 做同样的事,但行列互换。目标板的方向相对来源板旋转时用它,例如来源的 8 行要排到目标板的列上。

从 4 × 6 母板选了 A1–B3 共 6 个孔,转移到同为 4 × 6 的冻融板。多孔对多孔,PLAN 弹框选映射方式,默认 Daughter,Pool 不可选。图取自原厂用户指南。

处理步骤:振荡、控温、加盖、等待

  • Select Step Type to Create 选 Process Step。
  • 在 Select Hardware & Operation 树里选操作。树按工具分组,例如 Vortexer、Time Controls、Capping Station。鼠标停在操作名上,会列出它涉及的所有参数。按 Ctrl+F 可以在树里搜索。
  • 选目标库和孔。处理步骤没有 Map 标签,操作施加在选中的孔上。
  • 在 Options 里填参数。参数的单位由系统配置定义,例如温度用 °C、振荡用 rpm。
  • 点 Add To Recipe。

一个处理步骤可以同时设几个参数。例如 Set Heated Cooled Vortex with Delay 一步里设起始振荡速度、振荡时间和结束速度。这时板图上的 Value 标签会拆成几个,每个参数一个,各自可选 Uniform 或 Discrete。

有些处理步骤只是设置,在流程里的那个位置不执行,到需要时才生效。OSR 相关的步骤多是这种。

处理步骤:左边的操作树按工具分组,可见加盖、振荡、压盖等工具下的操作。中间选的是 4 × 6 母板。图取自原厂用户指南。

检测步骤

Analytics Step 的界面和处理步骤一样:选检测工具和方法、选库和孔、填参数。树按检测工具分组,列出各自的检测方法。例子里母板配完后,加了一步 pH 测量。

双击一个孔,查看里面加了什么

在 Recipe 列表里选一步,切到板图的 Volume % 或 Mass % 标签,双击一个孔,打开 Well Details。左边是这个孔到这一步为止的组成,按体积和质量列出绝对量和百分比。右边是动过这个孔的每一步。

母板 A4 孔共 2,400 µL。单抗原液和组氨酸缓冲液各 480 µL,蔗糖 600 µL,聚山梨酯 80 为 120 µL,注射用水 720 µL。这个处方不加氯化钠。右边是对应的六步分液。图取自原厂用户指南。

管理 Recipe 列表

  • 点列表里的一步,它回到上面的编辑区,按钮变成 Update Recipe。改完点 Update Recipe。再点一次或点 Clear Selection 取消选择。
  • 有问题的步骤,行首显示红色警示图标,鼠标停上去看原因。
  • Move Up、Move Down 调顺序,Duplicate 在原步骤后插入副本,Delete 删除。这几个按钮都支持多选:Shift+单击选连续几步,Ctrl+单击挑选。
  • 角上的展开图标把列表弹成独立窗口,可以拖到第二台显示器上。
  • Validate 打开模拟日志,逐步模拟整个流程。和点 Next 时自动做的检查相同。

流程长的时候,每加几步就点一次 Validate。加完一步就查出问题,比最后一起排查容易。几步只差目标孔时,先 Duplicate 一步,再改孔,点 Update Recipe。

同一种化学品分几步加入时,单位类别和 Backing Solvent、Inventory 这两个 Tag 要每步一致。一步用 mL、另一步用 mg,Next 时会报「inconsistent unit categories」。

例子的流程弹成独立窗口后的样子。母板配好、混匀、测 pH 后,各取 700 µL 转到三块子板。振荡板 400 rpm 振荡 120 min。热应力板以 2 °C/min 升到 40 °C,保持 240 min。冻融板每个循环先暂停,由人放进 −20 °C 冰箱 12 h,再放回台面。图取自原厂用户指南。

Recipe 列表为空时 Next 不可用,提示「At least one recipe step is required」。第 1 步换过系统后,原来的步骤可能指向已经不存在的工具或类别,要删掉重建。

第 4 步 Configure Deck:给每块库和每种化学品指定台面位置

上半部分是台面图,下半部分分 Libraries 和 Chemicals 两个标签。

Libraries 标签

  • Library Substrate Type:先选载具类型。只列出和第 2 步行列数相符的类型。
  • Library Substrate Position:再选台面位置。可选的位置由载具类型决定。
  • Initial State:起始状态,None、Covered、Capped 或 Uncapped。
  • Cap Rack Substrate Position:起始状态是 Capped 或 Uncapped 时,指定盖子放在哪个瓶盖架位置。这个位置不能和库本身的位置相同。

第 4 步。4 × 6 反应板用 4 mL 样品瓶架,放在 Deck 1-2 Position 1。8 × 12 分析板用 1 mL 样品瓶架,放在 Deck 5-6 Position 1。台面图上对应的两个位置标为 Library。图取自原厂用户指南。

Chemicals 标签

化学品分 On-Deck 和 Off-Deck 两张表。Backing solvent 自动归入 Off-Deck,只填阀位。其他化学品都在台面上,和库一样要指定载具类型和位置,还要填它在架子上的行和列。

  • 一种化学品要装几个容器时,可以复制成几行,每行单独指定位置。
  • 粉末分液的化学品必须用 Hopper 类载具,起始状态固定为 None。
  • 填了 Amount 就要选 Unit。

位置不能重复

同一个台面位置只能放一块库或一种化学品。几种化学品共用一个架子时,行列位置必须不同。瓶盖架位置在不同时使用的情况下可以共用。

几块库放同一种载具时,先把一行设好,选中它点 Lock Info,再选其他行点 Apply Info,设置就复制过去。载具类型不适用的行会跳过,并在警告里列出。Reset 清空选中行的设置,释放位置。

编辑时状态栏实时显示第一个未满足的要求,例如「Library Substrate Type must be selected」。点 Next 时再全部检查一遍。

第 5 步 Validate Design:整体检查通过后点 Finish

点 Validate Design,PLAN 把前面各步的检查全部重做一遍,再做几项整体检查:

  • 跨步骤检查:几个步骤之间的依赖关系,单看一步查不出来。
  • 化学品和样品库:同第 2 步。
  • 化学品和样品库的台面分配:同第 4 步。
  • 流程:同第 3 步。
  • 分液体积:按起始体积模拟整个流程,标出会不够吸的孔。

只有硬错误会拦住你,例如配置缺失或无效。体积不足以 ⚠ 警告显示,不拦,带警告的设计也能继续。从未保存过的新设计会提示「Save Required」,先保存一次再检查。

检查通过:化学品和样品库、台面分配、流程、整体设计四项都打勾,Generate Script 和 Finish 可用。图取自原厂用户指南。

  • Generate Python Script(可选):把这份设计转成 Python 设计脚本,存成 .py 文件。可以交给编程的同事扩展,或作为起点交给 Stuntman AI 修改。这是设计脚本,不是 RUN 执行用的脚本。跳过不影响完成。
  • Finish:检查通过后可用。保存设计并回到 Dashboard。

检查不过时,看界面底部的信息,它会指出出错的步骤。常见原因是步骤放在了硬件不支持的位置,例如在不能加热的位置加热,或者数值超出允许范围。

用 AI 写设计的方法见 怎么给 Stuntman AI 写提示词。设计完成后在 RUN 里运行、在 SHOW 里看结果,见 用 RUN 运行、用 SHOW 看结果。

常见提示和处理办法

提示:原因和处理

There are multiple designs with the same name.:文件里有同名设计,不分大小写。改掉一个再保存。

This design is locked for editing.:设计已运行过,是只读的。Duplicate 一份再改。

This design has been run and is now read-only, so your changes were not saved.:打开后被 RUN 运行了,刚才的修改没有存下。Duplicate 后在副本里重做。

File In Use:.stunt 文件被另一个 PLAN、RUN 或其他程序占用。在那边关掉再试。

System configuration … cannot be found.:C:\Stuntman\Plan\Configurations 里没有这份设计用的系统配置。把对应的配置文件夹加回去。

Changing the system will delete the loaded design and all completed work.:第 1 步要换系统。点 Cancel 退回,什么都不会丢。

At least one library must be provided:第 2 步还没有定义样品库。

Duplicate Names Detected:两种化学品或两块库同名。按提示改名。

No accommodating substrate found for library …:库的行列数放不进台面上任何载具。按系统支持的板或架子改尺寸。

… cannot be deleted because they are used in recipe maps:化学品或库已被流程步骤用到。先删掉那些步骤。

Library with same name already available. Rename the library before import.:导入的库在当前文件里已有同名。先改名再导入。

At least one recipe step is required:第 3 步的 Recipe 列表为空。

One or more Dispense steps have invalid operation selections:分液步骤的工具、吸头、类别或 Tag 与系统配置对不上。按列出的步骤逐个改。

Chemical … has multiple dispense maps with inconsistent …:同一种化学品在几步里的单位类别或 Tag 不一致。统一后再继续。

分液步骤报吸头超出板边界:多吸头工具放不进选中的孔,例如 6 吸头头对板边的单列孔加液。换吸头数合适的工具,或改选孔。

Save Required: Please save the design before running validation.:新设计还没保存过。在任一步点 Save 后再检查。

  • chemicals · 第 2 步 化学品与样品库
  • validate · 第 5 步 检查与完成