GEARSModel

Full name SMRUCC.genomics.Analysis.GEARS.Model.GEARSModel Assembly SMRUCC.genomics.Analysis.GEARS Members 21

GEARS 模型：面向基因表达调控网络虚拟扰动的图神经网络

00 Remarks

本类型把 readme 的 Step 2 ~ Step 4 编排为一个可端到端训练的模型：

Step 2 节点特征与扰动编码：

h_i^(0) = [ x̄_i ‖ p_i ‖ e_i ‖ z_pert ]，其中 x̄ 为 control 基线表达（建议先做 Z-score 标准化）、p 为扰动 multi-hot 标记、 e 为可学习的基因身份嵌入、z_pert 为被扰动基因集合经 Deep Sets 均值池化得到的全局扰动向量。

Step 3 多层消息传递：堆叠若干 GEARSConvLayer，

每层沿调控图入边做边类型感知聚合，L 层对应 L-hop 的间接调控效应。

Step 4 解码预测：解码器把最终节点嵌入映射为 Δ表达，

最终预测表达为 x̂^pert = x̄^control + Δx̂。

扰动标记 p 的取值由调用方给出（GEARS 门面类会按 InterventionMode 把被扰动基因的表达值改写后一并编码进 x̄ 通道），因此同一个模型可以同时支持单基因与多基因组合扰动。

01 Syntax

SMRUCC.genomics.Analysis.GEARS.Model.GEARSModel

02 Methods

Name	Overloads	Summary
.ctor	1	创建 GEARS 模型
BuildNodeFeatures	1	构建初始节点特征 h^(0) = [ x̄ ‖ p ‖ e ‖ z_pert ]
Forward	2	实现基类接口：使用内部缓存的调控图做前向传播
ForwardFeatures	1	前向传播：直接给定初始节点特征
BackwardFrom	1	反向传播：累积所有层参数梯度，并把 z_pert 的梯度回传至基因身份嵌入表
PredictDelta	1	推理：返回预测的表达变化量向量
Backward	1	实现基类接口：反向传播

03 Properties

Name	Overloads	Summary
NumGenes	1	基因数量（图中节点数量）
EmbeddingDim	1	基因身份嵌入维度
HiddenDim	1	隐藏层维度
NumLayers	1	图卷积层数（对应可捕捉的间接效应跳数）
FeatureDim	1	初始节点特征的维度：1(表达) + 1(扰动标记) + d(身份嵌入) + d(扰动集合向量)
LastNodeFeatures	1	获取最近一次前向传播构建的初始节点特征 [numGenes, FeatureDim]

04 Fields

Name	Overloads	Summary
graphData	1	基因调控图（提供稀疏入边缓存）
embeddingLayer	1	基因身份嵌入层
poolingLayer	1	扰动集合的 Deep Sets 池化层
convLayers	1	多层边类型感知图卷积
decoder	1	Δ表达解码器
zPertGrad	1	反向传播时用于回传 z_pert 梯度的缓冲区
lastFeatures	1	最近一次前向传播构建的初始节点特征（调试用）

05 Members

method .ctor #

#ctor(GeneRegulatoryGraph, Int32, Int32, Int32, ActivationType, Boolean, Boolean, Nullable(Of Int32), String)

创建 GEARS 模型

Parameters

Name	Type	Description
`graph`	GeneRegulatoryGraph	基因调控图
`embeddingDim`	`Int32`	基因身份嵌入维度，建议取 16~64
`hiddenDim`	`Int32`	图卷积隐藏层维度，建议取 32~64
`numLayers`	`Int32`	图卷积层数，等于可捕捉的间接调控跳数；readme 建议取 2~4，过深会导致过平滑
`activation`	`ActivationType`	图卷积层的激活函数
`usePerRelationTransform`	`Boolean`	是否为每种边关系类型分配独立的变换矩阵
`useDense`	`Boolean`	是否使用稠密邻接矩阵聚合（默认稀疏，稠密仅用于小图对照）
`seed`	`Nullable(Of Int32)`	随机初始化种子；给定后实验可复现
`name`	`String`	模型名称

method BuildNodeFeatures #

BuildNodeFeatures(Double(), Double())

构建初始节点特征 h^(0) = [ x̄ ‖ p ‖ e ‖ z_pert ]

Remarks

z_pert 的计算遵循 GEARS 的「扰动基因集合编码器」设计：先取被扰动基因的身份嵌入，再经 Deep Sets 均值池化聚合为全局扰动向量，最后广播拼接回每一个节点，使得所有节点都能感知到「本次扰动了哪些基因」。均值池化保证结果与扰动基因的列举顺序无关。

Parameters

Name	Type	Description
`controlExpr`	`Double()`	control 基线表达向量 [numGenes]（建议已做 Z-score 标准化）
`pertFlag`	`Double()`	扰动标记向量 [numGenes]；被扰动基因位置为 1（或干预强度），其余为 0

Returns

初始节点特征 numGenes, [GEARSModel.FeatureDim]

method Forward overload 2 #

Forward(Double(), Double())

前向传播：由 control 表达与扰动标记预测每个基因的 Δ表达

Parameters

Name	Type	Description
`controlExpr`	`Double()`	control 基线表达向量 [numGenes]
`pertFlag`	`Double()`	扰动标记向量 [numGenes]

Returns

预测的表达变化量 Δ，形状为 [numGenes, 1]

method Forward #

Forward(Tensor, Graph)

实现基类接口：使用内部缓存的调控图做前向传播

Parameters

Name	Type	Description
`nodeFeatures`	`Tensor`	初始节点特征 numGenes, [GEARSModel.FeatureDim]
`graph`	`Graph`	图结构参数；本模型已持有 GeneRegulatoryGraph，该参数仅用于满足基类签名，可传入 Nothing

Returns

预测的表达变化量 [numGenes, 1]

method ForwardFeatures #

ForwardFeatures(Tensor)

前向传播：直接给定初始节点特征

Parameters

Name	Type	Description
`features`	`Tensor`	节点特征 numGenes, [GEARSModel.FeatureDim]

Returns

预测的表达变化量 Δ，形状为 [numGenes, 1]

method BackwardFrom #

BackwardFrom(Tensor)

反向传播：累积所有层参数梯度，并把 z_pert 的梯度回传至基因身份嵌入表

Remarks

梯度链路：解码器 → 各图卷积层（逆序） → 拆分 h0 梯度 → z_pert 通道按行求和 → GlobalPoolingLayer 反池化 → GeneEmbeddingLayer 累积嵌入梯度。

Parameters

Name	Type	Description
`gradient`	`Tensor`	损失函数对 Δ 预测的梯度 [numGenes, 1]

Returns

相对于初始节点特征的梯度 numGenes, [GEARSModel.FeatureDim]

method PredictDelta #

PredictDelta(Double(), Double())

推理：返回预测的表达变化量向量

Parameters

Name	Type	Description
`controlExpr`	`Double()`	control 基线表达向量 [numGenes]
`pertFlag`	`Double()`	扰动标记向量 [numGenes]

Returns

每个基因的 Δ表达预测值

method Backward #

Backward(Tensor, Graph)

实现基类接口：反向传播

Parameters

Name	Type	Description
`gradient`	`Tensor`	损失函数对 Δ 预测的梯度 [numGenes, 1]
`graph`	`Graph`	图结构参数；本模型已持有调控图，该参数可传入 Nothing

Returns

相对于初始节点特征的梯度

property NumGenes #

NumGenes

基因数量（图中节点数量）

Returns

节点数量

property EmbeddingDim #

EmbeddingDim

基因身份嵌入维度

Returns

嵌入向量长度

property HiddenDim #

HiddenDim

隐藏层维度

Returns

图卷积层的输出维度

property NumLayers #

NumLayers

图卷积层数（对应可捕捉的间接效应跳数）

Returns

层数

property FeatureDim #

FeatureDim

初始节点特征的维度：1(表达) + 1(扰动标记) + d(身份嵌入) + d(扰动集合向量)

Returns

特征维度大小

property LastNodeFeatures #

LastNodeFeatures

获取最近一次前向传播构建的初始节点特征 [numGenes, FeatureDim]

Returns

节点特征张量；尚未执行前向传播时为 Nothing

field graphData #

graphData

基因调控图（提供稀疏入边缓存）

field embeddingLayer #

embeddingLayer

基因身份嵌入层

field poolingLayer #

poolingLayer

扰动集合的 Deep Sets 池化层

field convLayers #

convLayers

多层边类型感知图卷积

field decoder #

decoder

Δ表达解码器

field zPertGrad #

zPertGrad

反向传播时用于回传 z_pert 梯度的缓冲区

field lastFeatures #

lastFeatures

最近一次前向传播构建的初始节点特征（调试用）