肿瘤微环境可视化分析系统

肿瘤微环境可视化分析系统一、项目概述本系统是一个面向肿瘤微环境Tumor MicroEnvironment, TME研究的可视化分析平台整合单细胞转录组与空间转录组数据提供从数据导入、解卷积计算到交互式空间可视化的全链路分析能力。系统采用 Flask SQLite 后端、原生 JavaScript deck.gl (WebGL) 前端架构支持多项目隔离、角色权限管理与科研验证闭环。二、目录结构说明·flask/ ├── backend/ # Flask 应用层 │ ├── app.py # 应用工厂注册蓝图与路由 │ ├── http_util.py # 请求/响应工具函数 │ ├── scripts_init_db.py # 数据库初始化入口 │ └── blueprints/ # API 蓝图按领域拆分 │ ├── auth_bp.py # 认证与项目管理 │ ├── datasets_bp.py # 数据集管理 │ ├── tasks_bp.py # 解卷积任务 │ ├── visualization_bp.py # 可视化数据 │ ├── reports_bp.py # 报告生成 │ ├── validation_bp.py # 验证基准 │ └── ops_bp.py # 审计与导入日志 │ ├── core/ # 核心业务逻辑层 │ ├── config.py # 全局配置路径、开关、超时 │ ├── constants.py # 细胞类型色板、必填列、阈值常量 │ ├── db.py # SQLite 连接与初始化 │ ├── errors.py # 统一错误类型 │ ├── schemas.py # Pydantic 请求校验模型 │ ├── security.py # 鉴权、角色判断、项目权限 │ ├── path_utils.py # 存储路径安全解析 │ ├── processing.py # 解卷积计算主流程 │ ├── geo_import.py # GEO 原始数据自动转换 │ ├── public_import.py # 公开/远程数据导入 │ ├── quality.py # 数据质量评分 │ └── services/ # 各领域的服务函数 │ ├── datasets.py # 数据集增删查与导入 │ ├── tasks.py # 任务队列管理 │ ├── visualization.py # 可视化查询与导出 │ ├── reports.py # 报告生成PDF/JSON │ ├── validation.py # 验证基准评估 │ └── ops.py # 审计/导入日志查询 │ ├── frontend/ # 前端页面与静态资源 │ ├── login.html # 登录/注册页 │ ├── workspace.html # 工作台主页核心交互页 │ ├── index.html # 入口跳转页 │ └── static/ │ ├── css/ │ │ └── styles.css # 全局样式深色主题 │ └── js/ │ ├── api.js # 后端 API 封装 │ ├── auth.js # 登录/注册/鉴权逻辑 │ ├── workspace.js # 工作台主控逻辑 │ ├── workspace-helpers.js # 辅助工具颜色、区域计算 │ ├── workspace-charts.js # ECharts 图表构建 │ ├── echart-panel.js # ECharts 面板封装 │ ├── echarts-setup.js # ECharts 全局配置 │ ├── echarts.min.js # ECharts 库 │ ├── spatial-deck.js # deck.gl WebGL 空间渲染引擎 │ └── toast.js # 消息通知组件 │ ├── worker/ # 后台任务 Worker │ └── worker.py # 轮询 SQLite 队列执行解卷积 │ ├── scripts/ # 辅助脚本 │ ├── init_db.py # 数据库建表与默认用户 │ ├── prepare_geo_input.py # GEO 原始数据打包为可导入 ZIP │ └── verify_graduation.py # 计算机设计自动化验收脚本 │ ├── sql/ # 数据库 DDL │ └── schema_sqlite.sql # 全部表结构定义 │ ├── GEO/ # GEO 原始数据集5 套 │ ├── 01_lung_GSE268049_GSE131907/ │ ├── 02_breast_GSE240212_scRef_GSE131907/ │ ├── 03_hepatoblastoma_GSE249965_scRef_GSE131907/ │ ├── 04_PDAC_GSE274103_scRef_GSE131907/ │ ├── 05_CRC_GSE267401_scRef_GSE131907/ │ └── README.md # GEO 数据集说明 │ ├── data/ # 运行时数据 │ ├── app.db # SQLite 数据库文件 │ ├── output/ # 解卷积计算结果按数据集 ID 分目录 │ └── raw/ # 导入的原始数据 │ ├── imported/ # 用户上传/GEO 自动导入的数据 │ ├── public_demo/ # 内置演示数据基础样例 │ ├── public_tumor_core/ # 内置演示数据肿瘤核心 │ ├── public_immune_ring/ # 内置演示数据免疫环 │ ├── public_myeloid_bands/ # 内置演示数据髓系条带 │ ├── public_balanced_mix/ # 内置演示数据混合均衡 │ └── public_quadrants/ # 内置演示数据四象限 │ ├── input/ # 待导入 ZIP 包GEO 转换后的输出 │ ├── reports/ # 生成的报告文件 │ └── validation/ # 验证基准报告 │ ├── 运行步骤必看/ # 运行说明文档 ├── mac_run.sh # macOS 日常启动脚本 ├── mac_setup_run.sh # macOS 首次安装脚本 ├── window_run.bat # Windows 启动脚本 ├── requirements.txt # Python 依赖清单 └── 项目说明.md # 本文件三、功能清单3.1 用户与认证功能说明用户登录用户名 密码登录返回 Bearer Token有效期 24 小时用户注册注册新账号密码至少 6 位角色可选 editor / viewer修改密码验证原密码后修改支持向后兼容历史哈希Token 鉴权所有 API 请求携带 Bearer Token自动校验有效期与撤销状态角色权限editor 可执行写操作导入、删除、运行任务viewer 只读项目隔离每个用户绑定项目viewer 只能访问自己项目的数据3.2 项目管理功能说明创建项目editor 角色可创建项目名称 描述删除项目editor 角色可删除项目及其关联数据项目列表按角色过滤editor 查看全部viewer 仅看所属项目3.3 数据集管理功能说明ZIP 批量导入上传包含四份标准 CSV 的 ZIP系统自动解压入库多文件分项上传分别上传单细胞表达、单细胞元数据、空间表达、空间坐标、组织切片图GEO 自动导入从本地 GEO 目录自动解析 Visium/10x 数据转换为标准格式后入库公开数据导入通过 URL 下载公开数据支持 HTTP/本地 file://自动解析归档内置演示数据导入系统自带 6 套模拟数据肿瘤核心、免疫环、髓系条带等一键导入数据集列表按项目过滤显示名称、来源、版本、状态数据集详情查看数据集元信息、输入资产清单、质量报告删除数据集editor 角色可删除数据集及其输出文件版本管理同一数据集支持多版本可查看历史版本3.4 数据质量检查功能说明空间数据校验检查坐标有效性、丰度值合法性、细胞类型数量参考数据校验检查标记基因完整性、细胞类型标注完整性质量评分百分制评分按错误比例扣分坐标 30 分、丰度 20 分、空细胞类型 20 分等通过/警告判定可用点位 ≥ 20、细胞类型 ≥ 2 且错误率 10% 为通过3.5 解卷积任务功能说明提交任务对指定数据集提交解卷积任务integration_deconvolution任务队列SQLite 生产者-消费者模型Flask 入队Worker 出队执行任务轮询前端定时轮询任务状态支持进度显示30 分钟硬超时任务运行超过 30 分钟直接标记为 failed任务删除editor 可删除失败或已完成的任务任务指标汇总项目内任务成功率、平均耗时等指标3.6 解卷积计算Worker功能说明签名投影模型基于单细胞参考构建细胞类型签名矩阵投影到空间表达NNLS 空间平滑非负最小二乘拟合 空间邻居平滑优化丰度估计UMAP 降维对空间点位表达谱进行 UMAP 嵌入用于聚类可视化桥接模式当仅有 spatial_spots sc_reference 时自动生成合成单细胞参考与空间表达基因筛选按空间表达量与标记基因特异性排序选择高区分度基因置信度评估计算每个点位的解卷积置信度与不确定性比例拟合质量报告 R²、ΔR²、告警等级高/中/提示/无基准评估对比不同平滑参数组合选择最优 alpha 和 k3.7 可视化 — WebGL 空间图功能说明deck.gl 渲染基于 WebGL 的 ScatterplotLayer高性能渲染数万空间点位组织切片叠加在点位下方叠加组织切片图像BitmapLayer深色主题深色背景 高饱和度色板确保点位醒目丰度映射点位大小与亮度随丰度值动态变化细胞类型筛选按细胞类型显示/隐藏点位未选中类型半透明缩放平移支持 0.001x ~ 12x 缩放范围首次加载自动适配全量区域框选 ROI在空间图上框选感兴趣区域自动计算区域统计预设保存保存当前可视化参数点大小、透明度、丰度阈值等3.8 可视化 — ECharts 图表功能说明ROI 细胞比例堆叠图展示左半区/右半区各细胞类型比例的堆叠柱状图ROI 指标对比图对比两个区域的关键指标平均丰度、主导细胞类型等UMAP 聚类图基于空间表达 UMAP 嵌入的散点图按细胞类型着色四象限热力矩阵将空间图分为四象限展示各象限细胞组成数据集对比跨数据集的统计对比3.9 可视化 — 数据查询功能说明空间点位查询分页获取点位坐标、细胞类型、丰度支持区域/类型/丰度过滤细胞类型图例获取数据集的细胞类型列表及对应颜色统计概览点位总数、平均丰度、细胞类型分布解卷积结果获取完整解卷积输出模型名称、版本、各点位比例区域统计按空间范围聚合统计空间点位导出导出点位数据为 JSON 或 CSV组织切片图获取组织切片图像3.10 报告生成功能说明数据集报告生成包含空间分析、模型评估、数据质量的解读报告PDF/JSON空间形态解读自动计算四象限分布、主导细胞类型、空间拉伸方向模型评估解读置信度、R²、告警等级、平滑参数等建议动作根据结果质量给出后续分析建议3.11 科研验证闭环功能说明准确性评估解卷积预测 vs 地面真值的 MAE 与主导类型一致率稳定性评估平均置信度、不确定点位比例、变异系数稳定性重复性评估两次独立运行的一致性MAE、主导类型一致率综合评分准确性 45% 稳定性 35% 重复性 20% 加权综合分按癌种汇总按癌种分组汇总各指标按样本汇总按样本分组汇总各指标验证报告生成验证基准报告PDF/JSON告警机制根据综合分自动评定告警等级3.12 运维与审计功能说明审计日志记录所有 API 请求的用户、方法、路径、状态码导入日志记录每次数据导入的类型、来源、质量、错误信息健康检查/health端点快速检测服务可用性内联 Worker可配置 BACKEND_INLINE_WORKER 使 Flask 同步执行任务调试用演示数据禁用/api/demo-datasets/profiles返回 410防止虚假数据误用3.13 数据准备脚本功能说明GEO 数据转换prepare_geo_input.py将 GEO 原始归档Visium RAW.tar 单细胞矩阵转换为标准四 CSV 打包 ZIPVisium HDF5 支持自动检测并转换 10x HDF5 表达矩阵 spatial.tar.gz标记基因评分对单细胞矩阵进行细胞类型特异性评分优先选择高区分度基因细胞过滤排除 doublet/ambiguous/unknown 等低质量细胞类型基因过滤排除管家基因、核糖体蛋白、血红蛋白、免疫球蛋白等计算机设计验收verify_graduation.py自动化测试全链路登录→导入→解卷积→可视化→WebGL 检测数据库初始化init_db.py建表并创建默认 admin 账号四、细胞类型色板细胞类型颜色说明Tumor#ff3b4f红色肿瘤细胞T-cell#3b8bff蓝色T 细胞B-cell#22d3a7绿色B 细胞Myeloid#ffb020橙色髓系细胞系统同时支持 20 种扩展细胞类型如 Fibroblasts、Endothelial cells、Macrophages 等每种均有独立高饱和度配色并在超出预设范围时自动使用 20 色回退色板。五、技术栈层级选型后端框架Flask 3.0数据库SQLite本地单文件任务队列SQLite 轮询生产者-消费者模型数据校验Pydantic 2.9降维UMAP-learn 0.5机器学习scikit-learn 1.5NNLS 拟合HDF5 读取h5py 3.11PDF 生成ReportLab 4.2空间渲染deck.gl 9.2WebGL 2图表ECharts 5前端原生 HTML CSS JavaScriptES Module默认端口8100六、运行方式脚本用途mac_setup_run.shmacOS 首次安装创建虚拟环境、安装依赖、初始化数据库、启动服务mac_run.shmacOS 日常启动Flask 后端 Worker 后台运行window_run.batWindows 启动脚本python scripts/init_db.py单独初始化数据库python scripts/prepare_geo_input.py从 GEO 数据生成可导入 ZIPpython scripts/verify_graduation.py计算机设计自动化验收python worker/worker.py单独启动 Worker支持 --once 单次执行默认账号admin/admin123