🧬 HelixInsight - 差异倍数分析系统

Fold Change Analysis System for Medical Researchers

HelixInsight 是一个差异倍数（Fold Change, FC）分析系统，支持 Web 界面和命令行两种使用方式。

代码架构和扩展指南请参阅 ARCHITECTURE.md。

🚀 快速开始

环境要求

Python >= 3.9
pip

安装

cd helix-insight
pip install -r requirements.txt

🖥️ Web 界面使用

启动

streamlit run app.py

浏览器打开 http://localhost:8501。

操作流程

1. 数据管理 → 上传表达矩阵（CSV/Excel），配置列角色和分组，执行清洗。

2. 差异分析 → 选择对比组、统计方法和阈值，一键运行。

3. 数据可视化 → 查看火山图、散点图、热图、PCA、韦恩图（均支持悬停/缩放/下载）。

4. 结果导出 → 导出差异基因列表（CSV/Excel），生成汇总报告。

数据格式

上传的 CSV/Excel 文件每一行为一个基因/蛋白/代谢物，列包含：

列角色	说明	默认列名
ID 列	唯一标识符	`COMP_ID`
名称列	图表展示名	`COMPOUND_Name`
分类列	分类/通路	`SUPER_META_PATHWAY`
样本列	表达量数据，多列	用户指定

示例：

COMP_ID	COMPOUND_Name	SUPER_META_PATHWAY	Control_1	Control_2	Drug_1	Drug_2
CMP_001	Compound_1	Amino Acid	10.5	11.2	15.3	14.8
CMP_002	Compound_2	Lipid	8.3	7.9	5.1	4.8

分组文件（可选）

除了手动配置分组外，也可上传包含 sample 和 group 两列的 CSV/Excel 文件自动映射：

sample	group
Control_1	Control
Control_2	Control
Drug_1	Drug

⌨️ 命令行使用

核心分析引擎（AnalysisEngine）零 UI 依赖，可直接在 Python 脚本或 Jupyter 中调用。

完整分析示例

import pandas as pd
from modules.analysis_engine import (
    AnalysisEngine, AnalysisConfig, AnalysisState
)

# 1. 加载数据
raw_df = pd.read_csv("my_expression_data.csv")

# 2. 配置
config = AnalysisConfig(
    id_col="COMP_ID",
    name_col="COMPOUND_Name",
    class_col="SUPER_META_PATHWAY",
    sample_cols=["Control_1", "Control_2", "Control_3",
                  "Drug_1", "Drug_2", "Drug_3"],
    group_mapping={
        "Control_1": "Control", "Control_2": "Control", "Control_3": "Control",
        "Drug_1": "Drug", "Drug_2": "Drug", "Drug_3": "Drug",
    },
)

# 3. 运行分析
engine = AnalysisEngine()
state = AnalysisState(raw_df, config)
state = engine.run_pipeline(state, test_method="ttest")

# 4. 导出结果
for comp_key, df in state.results.items():
    n_up = (df["Significance"] == "up").sum()
    n_down = (df["Significance"] == "down").sum()
    print(f"{comp_key}: ↑{n_up} ↓{n_down}")
    df.to_csv(f"result_{comp_key}.csv", index=False)

分步执行（按需控制）

engine = AnalysisEngine()
state = AnalysisState(raw_df, config)

# 仅清洗，看检出率
state = engine.clean(state)
print(state.detection_rates)   # 每基因每组的检出率
state.cleaned_df.to_csv("cleaned.csv", index=False)

# 计算 P 值（一次性计算所有对比组，缓存到 state.pvalue_matrix）
state = engine.compute_all_pvalues(state, "ttest")
state = engine.compute_group_means(state)

# 自定义阈值构建结果
state = engine.build_results(state, fc_threshold=2.0, pvalue_threshold=0.01)

# 查看结果
for comp_key, df in state.results.items():
    sig = df[df["Significance"] != "ns"]
    print(f"{comp_key}: {len(sig)} 个显著差异")

可配置项

参数	默认值	说明
`test_method`	`"ttest"`	统计方法：`"ttest"` 或 `"wilcoxon"`
`fc_threshold`	`1.5`	FC 阈值
`pvalue_threshold`	`0.05`	P 值阈值
`comparisons`	全部两两组合	如 `[("Control", "Drug")]`

结果表字段

字段	说明
`ID`	唯一标识
`Name`	展示名称
`Class`	分类
`Mean_<组名>`	组均值
`FC`	Fold Change
`Log2FC`	Log2 Fold Change
`P_value`	P 值
`Significance`	`up` / `down` / `ns`
`DetectRate_<组名>`	检出率（如 `"83.3%"`）

🎨 Logo

将 PNG 格式的 Logo 放在 assets/logo.png，Web 界面侧边栏自动展示。

📄 License

MIT License

FilesExpand file tree

README.md

Latest commit

History