GEARS

Full name SMRUCC.genomics.Analysis.GEARS.GEARS Assembly SMRUCC.genomics.Analysis.GEARS Members 48

GEARS：基于图神经网络的基因表达调控网络虚拟扰动实验

00 Remarks

本类是整个算法的门面（facade），把 readme 中的五个步骤串联为一条完整的实验流水线：

Step 1：由先验调控网络 GEARS.priorNetwork 构建基因-基因调控图（GeneRegulatoryGraph）；
Step 2：以 control 基线表达 + 基因身份嵌入 + 扰动标记 + 扰动集合向量构成初始节点特征；
Step 3：多层边类型感知消息传递，让扰动信号沿调控边向下游级联传播；
Step 4：解码器输出 Δ表达，预测 x̂^pert = x^input + Δx̂；
Step 5：用（仿真或实测的）Perturb-seq 样本做监督训练，之后即可泛化到未见过的扰动。

使用方式：

 Dim gears As New GEARS(exprData, priorNetwork)
 Dim ko = gears.KnockoutGene("codY")
 Dim combo = gears.PredictCombination({"codY", "luxR"}, InterventionMode.Knockout)

本类实现了 InsilicoPerturbationExperiment 接口，因此可以与 BNLearn 中已有的贝叶斯网络虚拟扰动实现互换使用。

01 Syntax

SMRUCC.genomics.Analysis.GEARS.GEARS

02 Methods

Name	Overloads	Summary
.ctor	2	创建 GEARS 虚拟扰动实验
SelectBaselineSamples	1	选取用于估计 control 基线的样本列索引
ComputeBaseline	2	用构造时选定的样本集合估计 control 基线
GenerateTrainingSamples	1	用内置仿真器生成伪 Perturb-seq 训练样本
BuildPerturbationCandidates	1	构建可作为扰动目标的候选基因列表（转录因子优先）
NewGeneSpec	1	构造一个干预定义
SetTrainingSamples	2	Set Perturb-seq training sample from a given gene expression matrix
BuildGeneRowMap	1	建立「基因名 → 表达矩阵行索引」的映射，并校验 GEARS 所需的基因全部存在
BuildSampleIndex	2	建立「样本列名 → 列索引」的映射
ResolveSampleColumns	1	把一组样本列名解析为矩阵列索引，任一列名不存在时抛出友好异常
ResolvePerturbedGenes	1	从样本信息对象中解析出被扰动基因集合与干预模式
ParseInterventionMode	1	把文本解析为 InterventionMode 枚举
SyncBaselineSamples	1	当 control 列名同时存在于主表达矩阵时，同步更新基线样本索引
Save	1	Save current model as zip file
Load	1	Load model from a zip file
ToExpressionMatrix	1	把内部的基因表达数据还原为 Matrix 对象
PackBaseline	1	把野生型均值与标准差打包为单个向量，便于写入一个 zip 条目
RestoreBaseline	1	从打包向量中还原野生型均值与标准差
Train	1	训练 GNN 模型
Predict	1	执行一次（组合）虚拟扰动预测
CreateUndefinedResult	1	构造「目标基因不存在、未执行虚拟扰动」的降级结果
KnockoutGene	1	虚拟基因敲除：把目标基因表达置为 0，预测全网络的级联响应
OverexpressGene	1	虚拟基因过表达：把目标基因表达提升到 control 均值 + 3 倍标准差
KnockDownGene	1	虚拟基因下调：把目标基因表达降低到 control 均值 − 2 倍标准差
PredictWithBaseline	1	单次预测的便捷入口（可临时指定用于估计基线的样本数量）
RecomputeBaseline	1	使用指定数量的样本重新估计 control 基线（原地修改 GEARS.WildtypeMeans 与 GEARS.WildtypeSDs）
PredictCombination	1	组合扰动预测：同时扰动多个基因，捕捉非加性的协同/拮抗效应
BatchPerturbation	1	批量执行虚拟扰动
ToString	1	输出实验配置与结果的摘要

03 Properties

Name	Overloads	Summary
GraphData	1	基因调控图
Model	1	GNN 模型
GeneNames	1	基因名称列表（顺序与表达矩阵行序一致）
WildtypeMeans	1	control（野生型）表达均值
WildtypeSDs	1	control（野生型）表达标准差，用于归一化、Z-score 与显著性判定
Options	1	当前实验使用的超参配置
TrainingSamples	1	训练样本集合（默认由内置仿真器生成，可用实测数据覆盖）
LossCurve	1	最近一次训练得到的损失曲线（每个 epoch 的平均 MSE）
Trainer	1	训练器实例；尚未训练时为 Nothing

04 Fields

Name	Overloads	Summary
exprData	1	基因表达数据（行=基因，列=样本）
priorNetwork	1	先验调控网络
config	1	超参配置
baselineSamples	1	用于估计 control 基线所选取的样本列索引
metadata_perturbed_genes	1	SampleInfo.metadata 中记录「本样本被扰动了哪些基因」的键名
metadata_intervention_mode	1	SampleInfo.metadata 中记录「本样本使用哪种干预模式」的键名

05 Members

method .ctor #

#ctor(GeneExpressionData, PriorNetwork, GEARSConfig, Int32)

创建 GEARS 虚拟扰动实验

Parameters

Name	Type	Description
`expression`	`GeneExpressionData`	基因表达数据（行=基因，列=样本）
`prior`	`PriorNetwork`	先验调控网络
`gearsConfig`	GEARSConfig	超参配置；为 Nothing 时使用默认配置
`nSamples`	`Int32`	用于估计 control 基线（均值/标准差）的样本数量；小于等于 0 或大于总样本数时使用全部样本

method .ctor overload 2 #

#ctor(Matrix, PriorNetwork, GEARSConfig, Int32)

创建 GEARS 虚拟扰动实验（直接由表达矩阵构造）

Parameters

Name	Type	Description
`matrix`	`Matrix`	表达矩阵（行=基因，列=样本）
`prior`	`PriorNetwork`	先验调控网络
`gearsConfig`	GEARSConfig	超参配置；为 Nothing 时使用默认配置
`nSamples`	`Int32`	用于估计 control 基线的样本数量；0 表示使用全部样本

method SelectBaselineSamples #

SelectBaselineSamples(Int32)

选取用于估计 control 基线的样本列索引

Parameters

Name	Type	Description
`nSamples`	`Int32`	请求的样本数量

Returns

样本列索引数组

method ComputeBaseline #

ComputeBaseline

用构造时选定的样本集合估计 control 基线

method ComputeBaseline overload 2 #

ComputeBaseline(Int32())

用指定的样本集合估计 control 条件下每个基因的表达均值与标准差

Parameters

Name	Type	Description
`sampleIdx`	`Int32()`	参与统计的样本列索引

method GenerateTrainingSamples #

GenerateTrainingSamples

用内置仿真器生成伪 Perturb-seq 训练样本

Remarks

优先挑选在先验网络中作为转录因子出现的基因（它们拥有下游靶基因，扰动效应更容易在网络中传播），数量不足时再用其余基因补齐。

Returns

生成的样本数量

method BuildPerturbationCandidates #

BuildPerturbationCandidates

构建可作为扰动目标的候选基因列表（转录因子优先）

Returns

基因名列表

method NewGeneSpec #

NewGeneSpec(String, InterventionMode)

构造一个干预定义

Parameters

Name	Type	Description
`geneName`	`String`	目标基因名
`mode`	`InterventionMode`	干预模式

Returns

干预定义对象

method SetTrainingSamples overload 2 #

SetTrainingSamples(IEnumerable(Of PerturbSeqSample))

注入外部的真实 Perturb-seq 训练样本（覆盖内置仿真样本）

Parameters

Name	Type	Description
`samples`	`IEnumerable(Of PerturbSeqSample)`	实测扰动样本集合

method SetTrainingSamples #

SetTrainingSamples(Matrix, String(), SampleInfo())

Set Perturb-seq training sample from a given gene expression matrix

Parameters

Name	Type	Description
`samples`	`Matrix`	基因表达矩阵对象
`control`	`String()`	基线样本名称列表，计算出mean/sd作为共享野生型基线
`perturbed`	`SampleInfo()`	扰动后的样本名称列表，每一个`SampleInfo.ID`为samples矩阵中的样本ID，为扰动样本，每一个扰动样本中被扰动的基因id集合以字符串json数组的形式记录在`SampleInfo.metadata`元数据字典中，通过键名GEARS.metadata_perturbed_genes来获取

method BuildGeneRowMap #

BuildGeneRowMap(Matrix)

建立「基因名 → 表达矩阵行索引」的映射，并校验 GEARS 所需的基因全部存在

Parameters

Name	Type	Description
`samples`	`Matrix`	表达矩阵

Returns

基因名到行索引的映射（大小写不敏感）

method BuildSampleIndex #

BuildSampleIndex(Matrix)

建立「样本列名 → 列索引」的映射

Parameters

Name	Type	Description
`samples`	`Matrix`	表达矩阵

Returns

列名到列索引的映射（大小写不敏感）

method BuildSampleIndex overload 2 #

BuildSampleIndex(String())

建立「样本列名 → 列索引」的映射

Parameters

Name	Type	Description
`sampleNames`	`String()`	样本名数组

Returns

列名到列索引的映射（大小写不敏感）

method ResolveSampleColumns #

ResolveSampleColumns(Matrix, String(), String)

把一组样本列名解析为矩阵列索引，任一列名不存在时抛出友好异常

Parameters

Name	Type	Description
`samples`	`Matrix`	表达矩阵
`names`	`String()`	样本列名
`paramName`	`String`	抛异常时使用的参数名

Returns

列索引数组

method ResolvePerturbedGenes #

ResolvePerturbedGenes(SampleInfo, InterventionMode)

从样本信息对象中解析出被扰动基因集合与干预模式

Remarks

解析优先级：

基因集合：metadata[metadata_perturbed_genes] 的 JSON 数组 → 回退到从样本 ID 解析；
干预模式：metadata[metadata_intervention_mode] → 回退到样本 ID 的模式后缀 → 默认 InterventionMode.Knockout。

Parameters

Name	Type	Description
`info`	`SampleInfo`	样本信息对象
`mode`	`InterventionMode`	解析得到的干预模式；无法识别时保持调用方传入的默认值

Returns

被扰动基因名数组；解析失败返回 Nothing

method ParseInterventionMode #

ParseInterventionMode(String, InterventionMode)

把文本解析为 InterventionMode 枚举

Parameters

Name	Type	Description
`text`	`String`	原始文本，大小写不敏感，支持 ko / kd / oe 等简写
`mode`	`InterventionMode`	解析得到的枚举值

Returns

解析成功返回 True，否则返回 False

method SyncBaselineSamples #

SyncBaselineSamples(String())

当 control 列名同时存在于主表达矩阵时，同步更新基线样本索引

Remarks

保持 GEARS.baselineSamples 与新的野生型基线同一口径，使 GEARS.RecomputeBaseline() 与接口方法的 nSamples 分支行为一致。

Parameters

Name	Type	Description
`control`	`String()`	control 样本列名

method Save #

Save(Stream)

Save current model as zip file

Remarks

zip 包内包含 manifest.json、prior.csv、expression.bin、 baseline.bin、model.bin 五个条目，完整保存配置、先验网络、表达矩阵、图结构（按同样入参重建）、模型参数、基线与损失曲线，加载后可继续训练。

Parameters

Name	Type	Description
`file`	`Stream`	目标可写流；调用方负责其生命周期，本方法不会关闭它

method Load #

Load(Stream)

Load model from a zip file

Parameters

Name	Type	Description
`file`	`Stream`	zip 包的可读流；调用方负责其生命周期，本方法不会关闭它

Returns

还原出来的 GEARS 实例，其推理结果与保存前一致，且可继续训练

method ToExpressionMatrix #

ToExpressionMatrix

把内部的基因表达数据还原为 Matrix 对象

Returns

表达矩阵（行=基因，列=样本）

method PackBaseline #

PackBaseline

把野生型均值与标准差打包为单个向量，便于写入一个 zip 条目

Returns

长度为 2×基因数的向量，前一半为均值，后一半为标准差

method RestoreBaseline #

RestoreBaseline(Double())

从打包向量中还原野生型均值与标准差

Parameters

Name	Type	Description
`packed`	`Double()`	长度为 2×基因数的向量

method Train #

Train

训练 GNN 模型

Remarks

训练样本；为 Nothing 时使用 GEARS.TrainingSamples若为空则先调用 GEARS.GenerateTrainingSamples() 生成）

Returns

损失曲线

method Predict #

Predict(IEnumerable(Of InterventionSpec))

执行一次（组合）虚拟扰动预测

Remarks

预测流程：先按 InterventionSpec.GetInterventionValue() 把被扰动基因的表达改写为干预值（这一步是扰动信号进入网络的"入口"），再交给 GNN 预测全网络的 Δ 响应。

Parameters

Name	Type	Description
`specs`	`IEnumerable(Of InterventionSpec)`	干预定义集合；单个元素为单基因扰动，多个元素为组合扰动

Returns

干预分析结果

method CreateUndefinedResult #

CreateUndefinedResult(InterventionSpec)

构造「目标基因不存在、未执行虚拟扰动」的降级结果

Parameters

Name	Type	Description
`spec`	`InterventionSpec`	干预定义

Returns

所有变化量均为 0 的结果对象，其 InterventionResult.Undefined 为 True

method KnockoutGene #

KnockoutGene(String, Int32)

虚拟基因敲除：把目标基因表达置为 0，预测全网络的级联响应

Parameters

Name	Type	Description
`geneName`	`String`	目标基因名
`nSamples`	`Int32`	用于估计 control 基线的样本数量；0 表示使用全部样本

Returns

干预分析结果

method OverexpressGene #

OverexpressGene(String, Int32)

虚拟基因过表达：把目标基因表达提升到 control 均值 + 3 倍标准差

Parameters

Name	Type	Description
`geneName`	`String`	目标基因名
`nSamples`	`Int32`	用于估计 control 基线的样本数量；0 表示使用全部样本

Returns

干预分析结果

method KnockDownGene #

KnockDownGene(String, Int32)

虚拟基因下调：把目标基因表达降低到 control 均值 − 2 倍标准差

Parameters

Name	Type	Description
`geneName`	`String`	目标基因名
`nSamples`	`Int32`	用于估计 control 基线的样本数量；0 表示使用全部样本

Returns

干预分析结果

method PredictWithBaseline #

PredictWithBaseline(String, InterventionMode, Int32)

单次预测的便捷入口（可临时指定用于估计基线的样本数量）

Parameters

Name	Type	Description
`geneName`	`String`	目标基因名
`mode`	`InterventionMode`	干预模式
`nSamples`	`Int32`	基线样本数量；小于等于 0 时沿用构造时确定的基线

Returns

干预分析结果

method RecomputeBaseline #

RecomputeBaseline(Int32)

使用指定数量的样本重新估计 control 基线（原地修改 GEARS.WildtypeMeans 与 GEARS.WildtypeSDs）

Parameters

Name	Type	Description
`nSamples`	`Int32`	样本数量

method PredictCombination #

PredictCombination(IEnumerable(Of String), InterventionMode)

组合扰动预测：同时扰动多个基因，捕捉非加性的协同/拮抗效应

Parameters

Name	Type	Description
`geneNames`	`IEnumerable(Of String)`	同时扰动的基因名集合
`mode`	`InterventionMode`	干预模式，默认敲除

Returns

干预分析结果

method BatchPerturbation #

BatchPerturbation(IEnumerable(Of String), InterventionMode)

批量执行虚拟扰动

Parameters

Name	Type	Description
`geneNames`	`IEnumerable(Of String)`	待扰动的基因名集合
`mode`	`InterventionMode`	干预模式，默认敲除

Returns

每个基因对应的干预分析结果

method ToString #

ToString

输出实验配置与结果的摘要

Returns

多行摘要文本

property GraphData #

GraphData

基因调控图

Returns

GeneRegulatoryGraph 实例

property Model #

Model

GNN 模型

Returns

GEARSModel 实例

property GeneNames #

GeneNames

基因名称列表（顺序与表达矩阵行序一致）

Returns

基因名数组

property WildtypeMeans #

WildtypeMeans

control（野生型）表达均值

Remarks

可写：GEARS.SetTrainingSamples() 会用显式指定的 control 列重算并覆盖它；GEARS.Load() 则从 zip 包中还原保存时的取值。

Returns

每个基因的表达均值

property WildtypeSDs #

WildtypeSDs

control（野生型）表达标准差，用于归一化、Z-score 与显著性判定

Remarks

可写，语义同 GEARS.WildtypeMeans。

Returns

每个基因的表达标准差

property Options #

Options

当前实验使用的超参配置

Remarks

返回的是实际生效的配置对象引用，读取其中的字段是安全的；一般不建议在训练中途修改，但允许在重新训练前调整轮数、学习率等参数。（VB 标识符不区分大小写，故不能与私有字段 config 同名，这里取名为 Options。）

Returns

GEARSConfig 实例

property TrainingSamples #

TrainingSamples

训练样本集合（默认由内置仿真器生成，可用实测数据覆盖）

Returns

训练样本列表

property LossCurve #

LossCurve

最近一次训练得到的损失曲线（每个 epoch 的平均 MSE）

Returns

损失数组；尚未训练时为空数组

property Trainer #

Trainer

训练器实例；尚未训练时为 Nothing

Returns

GEARSTrainer 实例

field exprData #

exprData

基因表达数据（行=基因，列=样本）

field priorNetwork #

priorNetwork

先验调控网络

field config #

config

超参配置

field baselineSamples #

baselineSamples

用于估计 control 基线所选取的样本列索引

Remarks

该字段不是只读的：GEARS.SetTrainingSamples() 指定了显式的 control 列名后会更新它，从而让 GEARS.RecomputeBaseline() 与接口方法的 nSamples 分支与新的野生型基线保持同一口径。

field metadata_perturbed_genes #

metadata_perturbed_genes

SampleInfo.metadata 中记录「本样本被扰动了哪些基因」的键名

Remarks

对应值是一个 JSON 字符串数组，例如 ["codY","luxR"]。

field metadata_intervention_mode #

metadata_intervention_mode

SampleInfo.metadata 中记录「本样本使用哪种干预模式」的键名

Remarks

对应值为 InterventionMode 的枚举名（大小写不敏感），例如 Knockout、Knockdown、 Overexpression、Custom。缺失时回退到从样本 ID 的后缀解析，仍解析不出则取 InterventionMode.Knockout。