🏗️ HelixInsight 代码架构

架构概览

                    ┌─────────────────────────────┐
                    │   AnalysisEngine (纯逻辑)    │  ← 零依赖，可 CLI 调用
                    │   - clean()                  │
                    │   - compute_all_pvalues()    │
                    │   - compute_group_means()    │
                    │   - build_results()          │
                    │   - run_pipeline()           │
                    └──────────────┬──────────────┘
                                   │ 读/写
                    ┌──────────────▼──────────────┐
                    │   AnalysisState (数据容器)    │  ← 逐步富化，不重复计算
                    │   raw_df → cleaned_df        │
                    │   → detection_rates          │
                    │   → mean_matrix              │
                    │   → pvalue_matrix (缓存)     │
                    │   → fc_matrix                │
                    │   → results                  │
                    └──────────────┬──────────────┘
                                   │
          ┌────────────────────────┼────────────────────────┐
          │                        │                        │
  ┌───────▼──────┐   ┌────────────▼────────┐   ┌───────────▼────────┐
  │ DataManager  │   │ DifferentialAnalyzer │   │    Visualization   │
  │  (UI only)   │   │     (UI only)        │   │    (Plotly)        │
  └──────────────┘   └─────────────────────┘   └────────────────────┘

数据流转

每一步都会在 AnalysisState 上写入新的中间结果，后续步骤直接读取缓存，绝不重复计算：

Raw Data (.csv/.xlsx)
  │
  ├─[clean()]─► cleaned_df          ← 清洗后的表达矩阵
  │             detection_rates     ← 每基因每组的检出率（基于原始数据）
  │
  ├─[compute_group_means()]─► mean_matrix   ← 每基因每组的均值
  │
  ├─[compute_all_pvalues()]─► pvalue_matrix ← 所有对比组的 P 值（一次性计算，缓存）
  │                           fc_matrix      ← 所有对比组的 FC 值
  │
  └─[build_results()]─► results            ← 完整结果表（ID对齐，含检出率百分比）

模块说明

文件	职责	UI 依赖
`analysis_engine.py`	核心计算引擎：清洗、P值、FC、结果构建	无
`data_manager.py`	文件上传、列配置、分组配置、数据浏览	Streamlit
`differential_analysis.py`	对比组配置、阈值设置、结果展示	Streamlit
`visualization.py`	火山图、散点图、热图、PCA、韦恩图	Plotly
`report_generator.py`	Excel/CSV 导出、汇总报告生成	Streamlit
`utils.py`	文件检测、格式转换、下载链接	部分 Streamlit
`config/settings.py`	全局默认参数	无

核心类

AnalysisConfig

不可变的配置快照，描述如何解析原始数据：

id_col, name_col, class_col — 元数据列
sample_cols — 样本列
group_mapping — {sample_name: group_name} 映射

AnalysisState

管线状态容器，随分析流程逐步富化：

阶段	字段	说明
初始化	`raw_df`	原始数据
`clean()`	`cleaned_df`	清洗后数据（缺失值已填充）
	`detection_rates`	每基因每组检出率（0~1）
`compute_group_means()`	`mean_matrix`	每基因每组均值
`compute_all_pvalues()`	`pvalue_matrix`	所有对比组 P 值
	`fc_matrix`	所有对比组 FC
`build_results()`	`results`	`{comp_key: DataFrame}`

AnalysisEngine

无状态的计算引擎，所有方法接收并返回 AnalysisState：

engine = AnalysisEngine()
state = engine.clean(state)                          # 清洗
state = engine.compute_all_pvalues(state, "ttest")   # 算P值
state = engine.build_results(state, fc=1.5, p=0.05)  # 构建结果
# 或一键运行：
state = engine.run_pipeline(state, "ttest")

清洗策略

组内均值填充：某化合物在某组内缺失时，用该化合物在同组其他样本的均值填充
极小值兜底：该化合物在该组内全部缺失时，填充 1e-6
检出率：基于原始数据（填充前）计算，= 组内有值样本数 ÷ 组内总样本数

扩展指南

新增统计方法

在 AnalysisEngine 中添加新方法，例如：

def compute_fdr_correction(self, state: AnalysisState, method="bh"):
    """添加多重检验校正"""
    for comp_key in state.pvalue_matrix.columns:
        # 计算 FDR...
    return state

新增图表

在 visualization.py 中添加函数，接收 AnalysisState 或 DataFrame，返回 go.Figure：

def plot_ma(state, comp_key: str) -> go.Figure:
    """MA-plot"""
    ...

CLI 脚本示例

参见 README.md 中的 CLI 使用说明。

技术栈

UI框架: Streamlit
数据处理: Pandas, NumPy, SciPy
统计检验: SciPy (T检验, Mann-Whitney U)
可视化: Plotly (交互式), Matplotlib (韦恩图)
机器学习: Scikit-learn (PCA)

FilesExpand file tree

ARCHITECTURE.md

Latest commit

History