linear


        require(GCModeller);
                               

#' The linear (elastic net) gene regulatory network builder and the in silico perturbation toolkit that runs on top of the fitted linear models.
imports "linear" from "TRNtoolkit";

The linear (elastic net) gene regulatory network builder and the in silico perturbation toolkit that runs on top of the fitted linear models.

.NET clr type export
elastic_net.options: ElasticNetPerturbationOptions	基于弹性网络线性调控网络的虚拟扰动参数。
linear_grn: GeneRegulatoryNetwork	基于线性拟合的基因表达调控网络推断对于表达矩阵之中的每一个基因 `g`，都会建立如下的线性模型： `expr(g) = const + beta_1 * expr(r1) + beta_2 * expr(r2) + ...` 其中 `r1, r2, ...` 为候选调控因子(默认从与 `g` 相关性最高的若干个基因之中选出，并且总是排除 `g` 自身)。把所有基因的模型汇总之后，就得到了一个 `调控因子 -> 目标基因` 的有向加权网络：边的权重即为回归系数。

.NET clr function exports
log2cpm	把原始 counts 矩阵变换成 `log2(CPM + 1)`。逐样本按总计数归一化到 scale（默认 1e6，即 CPM），再取 `log2(x + pseudo)`。这个变换消除了样本之间测序深度的差异：未取对数的 counts 矩阵上，任意两个基因的相关系数都会被共同的深度因子拉到 0.6 以上且彼此接近，弹性网络的 L1 路径因此不存在稀疏的中间解，拟合出来的模型会退化成 r2 ~ 0 的常数模型。
top_variable_genes	按 MAD(中位数绝对偏差)降序挑选变异最大的若干个基因。用于扩充候选调控因子池：`TF ∪ 扰动靶基因` 之外，再补上一批"在样本之间波动最大"的基因，让每个目标基因的模型有机会用上真正与它共变的调控因子，而不是被迫只能用 TF 和 300 个扰动靶基因去解释。使用 MAD 而不是标准差，是因为 MAD 对离群样本(双细胞、线粒体爆表)不敏感，不会像 SD 那样把少数极端样本的基因顶到榜首。
normalize_log_matrix	去掉样本级的全局表达程序(每个样本减去跨基因均值)。对样本 s: `x'(g, s) = x(g, s) - mean_g(x(g, s))`。横截面共表达数据里，所有基因都被同一个"全局程序"绑定(细胞状态、线粒体含量、测序质量等)，导致任意两个基因的相关系数都被抬高、且几乎全为正。把这个样本级常数移除之后，剩下的相关更接近"特异性共表达"，负相关才会出现：这一步直接改善敲降之后"全部基因一起下调、极少上调"的现象。把一个已经在对数空间的表达矩阵重新标定到指定的文库规模(默认 CPM，1e6)。输入矩阵假定是 `x = log2(y + pseudo)` 的形式，其中 y 是"归一化之后的计数" (不必是整数)。先把 y 反解出来，整体乘以 `target / median(Σy)`，再取对数： `S = median_s( Σ_g (2^x - pseudo) ) x' = log2( (2^x - pseudo) * target / S + pseudo )` 这一步不改变基因之间的相对丰度，只改变数值尺度。它解决的问题是：低深度数据(例如每细胞只有几千个 UMI)上 `log2(1 + y)` 落在近似线性的区间里，全矩阵被压到 0~2 之间，于是 80% 敲降只产生 0.05 量级的变化，下游传播几乎为 0；重标到 CPM 之后，同一个基因的对数值落回对数区间，敲降幅度回到 2 左右、下游响应回到可观测的量级，模型空间的语义也与 `scale = "log2cpm"` 一致。
remove_global_factor
remove_principal_components	去掉表达矩阵的前若干个主成分(比"减去跨基因均值"更强的去全局因子)。做法：在基因抽样的子矩阵上用块幂迭代求出前 components 个右奇异向量(样本空间的全局方向)，然后把每个基因的表达向量投影到这些方向上并减掉。等于把"细胞组成 / 测序质量 / 全局调控程序"这类共同因子从数据里移除。与只减跨基因均值相比，这一步能真正削弱残留的全局共表达，从而让网络里出现更多负相关(抑制型)的边。
elastic_net	Fit a linear (elastic net) gene regulatory network from the expression matrix.
coef	Export the coefficient matrix of the fitted network.
elastic_formulas
elastic_model	Build the in silico perturbation engine from a fitted linear GRN model.
gene_names	Get the gene ids of the fitted network, in the row order of the expression matrix.
wildtype_means	Get the currently effective wildtype (baseline) expression vector of the model.
set_log_offset	设置模型空间的整体对数偏移量(去全局因子之后的 context 需要)。拟合矩阵做过"逐样本减去跨基因均值"之后，模型空间是 `x' = log2(CPM + 1) - offset`；扰动幅度必须先在 `x' + offset` 上计算，再换算回来，否则负基线会被压成 0，敲降变成"敲到底"甚至反号。
library_sizes	Get the implied library size of every training sample of the fitted network.
set_baseline	Set the wildtype baseline (the cell context) of the perturbation engine.
intervene	Run one in silico perturbation experiment and return the raw result object.
profiles_matrix	Run the perturbation experiment for a set of genes and collect the profiles into a matrix.
export_profiles	Run the perturbation experiment for a set of genes and save the profiles as a csv file.