R shiny 使用说明 | TidyMass

安装与访问 R Shiny

Wed, 23 Sep 2026 00:00:00 +0800

依据现有公开教程和 tidymassshiny 1.0.0 公开源码整理，核对日期：2026-09-23。

选择运行位置

在线应用在服务器上运行。现有公开教程说明上传限制为 512 MB、结果在 24 小时后删除；这些属于可变的服务配置，应以实际服务提示为准。记下 JOB ID，离开前使用 Download All Data 下载结果。

本地 R 版本使用本机计算和文件；Docker 版本只能访问挂载到容器中的目录。不适合上传到公共服务的数据，应在本地或经过管理的服务器环境分析。

安装 R 包

使用满足整套依赖的 R。虽然应用声明 R ≥ 4.1，当前依赖包可能要求 R ≥ 4.5。以下命令在可写 R 包库中执行，依赖安装还可能需要访问 GitLab、CRAN 和 Bioconductor。

if (!requireNamespace("remotes", quietly = TRUE)) install.packages("remotes")
if (!requireNamespace("BiocManager", quietly = TRUE)) install.packages("BiocManager")
install.packages(c("tidyverse", "writexl", "hexbin", "ComplexUpset",
                   "shinyalert", "colourpicker"))
remotes::install_github("tidymass/tidymass")
remotes::install_github("tidymass/massdatabase")
remotes::install_github("tidymass/massdbbuildin")
remotes::install_github("tidymass/tidymass_shiny")
library(tidyverse)
library(tidymass)
library(tidymassshiny)
run_tidymass_shiny()

等待控制台出现监听地址后，在浏览器打开应用；分析期间保持 R 进程运行。使用 packageVersion("tidymassshiny") 核对版本，排错时保存 sessionInfo()。部分可选工具有额外依赖，按实际报错从正确来源安装。

macOS 遇到 Cairo/X11 错误时，可能需要 XQuartz 和相应 Cairo 配置。依据具体错误处理；系统库编译失败不能靠反复安装无关 R 包解决。

Docker

安装并启动 Docker。将下面的主机目录替换为自己已有的数据目录：

docker pull tidymass/tidymassshiny:latest
docker run --rm -p 127.0.0.1:3838:3838   -v "/absolute/path/to/data:/home" tidymass/tidymassshiny:latest

启动完成后打开 http://localhost:3838，应用内选择挂载后的 /home。Windows 使用自己的盘符路径和 Docker 支持的卷挂载语法，并确认 Docker 有访问权限。记录实际镜像 digest，因为 latest 标签会更新。

共享服务器

管理员应准备受支持的 R/Shiny Server 环境、服务账号、持久工作目录和所需 R/系统依赖，并配置用户文件访问、资源限制和外部入口。shinyFiles 选择器看到的是 R 所在服务器的文件系统，不会直接读取远程浏览器所在电脑的任意文件夹；浏览器本地文件应通过上传入口传输。

旧教程包含 Ubuntu 部署示例，使用前先核对系统适用性，不要直接复制已过时的仓库密钥命令或固定版本安装器。

原教程及操作截图

创建项目与导入数据

Wed, 23 Sep 2026 00:00:00 +0800

依据现有公开教程和 tidymassshiny 1.0.0 公开源码整理，核对日期：2026-09-23。

初始化项目

设置工作目录，上传 sample_info.csv，必要时映射列名，再点击 Initialize Project 并检查样品信息。样品 ID 必须与强度列或原始文件名准确匹配；区分生物学 group、用途 class、批次和进样顺序。

sample_id,group,class,injection.order,batch
S001,Control,Subject,1,B1
S002,Treatment,Subject,2,B1
QC001,QC,QC,3,B1

该表仅展示格式，不代表实验具有足够重复。区分正负模式测量并保留 ID 前导零。

从 MS 文件开始

先将厂商文件转为适用的 mzML/mzXML；厂商读取能力取决于转换器和平台。按文档要求将 MS1 文件放入 QC、Subject 等样品类型目录。

进入 Data import → Start with MS file，选择 SELECT MS1 FOLDER，点击 CHECK INPUT FILE。检查 ppm、peakwidth、snthresh、noise、threads。参数优化只能辅助选择，仍需结合 EIC 和对齐结果判断适用性。确认后开始峰检测并等待完成，不要反复启动同一任务。

在线版需要使用上传流程，将 MS 文件打包成要求的 ZIP，再通过 Process MS1 Files 解压/处理。服务器的目录选择器不能代替上传本机文件。

从峰表开始

选择 Start with table file 并上传 CSV。当前源码允许映射 feature ID、m/z、RT 和 ion 列，初始映射取前四列。可使用如下格式：

variable_id,mz,rt,ion,S001,S002,QC001
F001,100.1234,60,pos,1000,1200,1100
F002,200.2345,120,neg,500,600,550

使用 pos/neg 等支持的模式标识，正确选择 Retention time in；分钟会转为秒。自己的列名或顺序不同时显式映射四个元数据字段，剩余列只保留数值样品强度，并与项目样品表一致。

先点击 Input file summary 核对匹配、模式、样品数和 feature 数，再点击 Generate massdataset object，查看正负模式输出。额外文本注释列可能被当作强度，因此应先移除或通过合适的注释入口导入。

从已有对象开始

选择 Start with mass_dataset file，分别在正负模式入口加载对应对象，再点击 Check input。修改扩展名不能把 CSV 变成 R 对象；保留原对象和包版本记录。

截图沿用现有公开 Shiny 教程，不同部署的界面细节可能不同。

原教程及操作截图

质量评估与数据清洗

Wed, 23 Sep 2026 00:00:00 +0800

依据现有公开教程和 tidymassshiny 1.0.0 公开源码整理，核对日期：2026-09-23。

生成概览

进入 Overview，点击 START。检查 m/z–RT 分布、按样品/feature 的缺失值、QC RSD、强度分布、PCA 和样品相关性，按分组、批次或进样顺序着色，并保存图与设置。

QC RSD 描述合适定量 QC 中的技术重复性；矩阵总强度不自动等于原始 TIC。发现可疑样品后，结合采集记录调查再决定是否删除。

过滤噪声 feature

设置 QC 和生物学组的缺失阈值，运行后检查保留的 feature 数和缺失分布。旧教程中的 QC 20%、组内 50% 是可调整示例，不是通用阈值。没有定量 QC 时不要启用相应过滤条件，并确认当前模块如何组合各组条件。

审查异常样品

先生成缺失值与 PCA 图。By tidymass 提供缺失率、PC SD、PC MAD、距离等策略；By myself 可明确选择。核对样品 ID 和实验原因后执行删除，保存原对象和排除记录。

缺失值填补

选择方法并查看参数。kNN 使用邻居数和行列缺失控制；随机森林使用迭代与树数；PPCA 使用主成分数和收敛设置。kNN 的 maxp 对应底层算法的最大分块大小，并非比例。界面提供随机种子时应记录。

点击 START 并等待结束，检查处理范围是否正确。完全没有有效观测的 feature 不应通过填补伪装成可靠定量结果。

归一化与整合

按实验选择方法。SVR、LOESS 依赖合适 QC 与采集信息；PQN、median、mean、total 为样品级方法。检查 keep_scale、optimization、参考值和线程等选项，点击 Start analysis，随后 Show plot 比较前后表现。

批次处理与归一化分别记录。任何归一化都不能挽救生物学组与批次完全混杂的设计。分别拟合的 PCA 也不能当成同一个固定坐标系比较。

保存清洗对象和诊断图，再进入注释或统计。

原教程及操作截图

注释、统计与富集

Wed, 23 Sep 2026 00:00:00 +0800

依据现有公开教程和 tidymassshiny 1.0.0 公开源码整理，核对日期：2026-09-23。

关联实验 MS2

通过 Select MS2 folder 选择准备好的 MGF，正负模式分开存放。设置色谱类型、前体 m/z 和 RT 关联容差，再点击 Start。将谱图关联到 feature 的容差，与参考库匹配容差是不同参数。

代谢物注释

将相容参考数据库放在专用目录，用 Choose folder 选择。设置 MS1/MS2 容差、RT 容差、候选数、色谱及线程，只点击一次 Start annotation，观察日志并等待结束。

MoNA、MassBank、HMDB 是公共资源，不自动等于自建标准品库。参考 RT 只在色谱可比时使用。接受名称前审查候选与谱图证据；软件的置信度标签必须结合实际测量解释，MS1 候选不会因为获得某个 level 标签就成为结构确认。

注释筛选与来源查看

选择多候选保留方式、加合物冗余处理和支持的证据等级；适用时设置 Adduct for level 3 annotation，再点击 START。保留筛选前候选表及筛选规则。

在 Metabolites origin 点击 Check database、Start。UpSet 图汇总来源关联及交集，选择化合物后用 Show network plot 查看数据库关系。这些是参考关联，不是样品中实际生物合成来源的证明。

差异分析

点击 Wake up object，选择样品属性并明确对照/参考组。运行后查看 PCA 和火山图，核对 fold change 方向，并区分原始 P 值与 FDR/校正 P 值阈值。保存包含不显著 feature 的完整结果表。

只让目标生物学样品进入检验，不按表格顺序推断配对。如果界面不能表示研究所需的重复测量或协变量，导出对象后使用适当 R 模型。

通路富集

选择 KEGG/HMDB，或用 Upload custom database 加载自己的通路库；检查物种、ID 类型、校正方法、阈值和线程。查看柱状/散点图和 ID 映射覆盖，审查候选歧义、去重化合物 ID 并记录方法使用的背景。富集表示相对参考集合的统计关联，不直接证明通路激活。

截图来自现有公开教程。

原教程及操作截图

fMSEA、FPA 与数据库工具

Wed, 23 Sep 2026 00:00:00 +0800

依据现有公开教程和 tidymassshiny 1.0.0 公开源码整理，核对日期：2026-09-23。

fMSEA

进入 Tidymass shiny toolkits → fMSEA Analysis。加载要求的 R 数据文件：处理后的 Feature Table、支持的 KEGG/HMDB MS1 Database 和 Pathway Database。公开模块列出 KEGG、HMDB、IMETPD、Reactome、WikiPathways 资源。按模块 demo 的对象结构准备，不能给任意 CSV 改扩展名后上传。

Run Step 1：设置色谱、数据库类型、MS1 ppm、RT 聚类容差和同位素数。进入富集前查看候选分配。教程示例为 15 ppm、10 s、三个同位素，自己的数据需调整。
Run Step 2：设置线程、通路最小/最大规模、置换次数、迭代次数和 FDR。公开默认值包括 1,000 次置换、通路规模 15–300；这些是计算选项，不保证最优。
在 Significant Modules Table 选择一行查看富集得分曲线。保存完整结果与设置，不只保存显著图。

已有相容结果对象可以直接导入查看，跳过步骤 1–2。Feature 富集仍包含候选分配不确定性，不能据此确认所有参与化合物。

可选 LLM 评估

模块提供基质相关性和文献相关性评估。填写样品来源或研究主题，配置所选服务的 API，再运行需要的评估。该步骤可选；没有 endpoint/key 就是没有运行。生成的分数不能替代统计验证或核实后的文献证据。使用非公开研究信息前，先确认向服务发送的内容。评估结果与富集表、PNG/PDF 图分别下载保存。

Feature-based Pathway Analysis（FPA）

进入 FPA 工具，准备要求的 feature 数据、离子模式和相容的通路/候选资源。检查当前模块的 feature 分组、同位素/加合物假设、质量容差和零分布/置换选项，运行后审查贡献 feature，并导出模块和参数。metpath 教程说明相关 R 接口及解释边界。FPA 与 fMSEA 是不同方法，分数不能直接混用。

构建自建代谢物数据库

在与研究可比的条件下采集标准品，按 metid 数据库结构准备化合物信息与 MS2。在工具中用 File Path 选择 CSV，检查 Construction Parameters，点击 Build Database。核对 m/z、RT、名称和谱图，使用描述性数据库标识，再 Download Database。

将生成的 .rda 放到专用注释数据库目录，注释时选择它。对象被标成 in-house 不能代替标准品和采集条件核验。

构建物种特异 KEGG 通路库

从 KEGG 物种列表确认代码，例如 hsa、mmu。进入 KEGG Pathway Database Construction，通过 Set working directory 指定工作目录，填写代码和请求间隔（现有教程使用至少一秒），再点击 Download pathway。观察网络错误和输出路径；富集前检查通路 ID 的物种前缀，保存获取日期与物种代码。

代谢物 ID 转换

在 Convert Parameters 选择服务，配置 Source ID Type、Target ID Type，在 Conversion Input 输入查询，再点击 Convert ID。检查失败与一对多映射，不要悄悄删除失败条目。API 服务需要配置凭据。实验性 LLM 转换可能产生错误 ID，进入数据库或通路分析前应独立核对结构和标识。

截图来自现有公开教程。

原教程及操作截图

保存结果与常见问题

Wed, 23 Sep 2026 00:00:00 +0800

依据现有公开教程和 tidymassshiny 1.0.0 公开源码整理，核对日期：2026-09-23。

保存完整分析

保留初始化样品表、原始文件引用、中间 mass_dataset、清洗和注释对象、完整统计/富集表、图片及参数。本地版查看界面报告的输出目录；在线版记下 JOB ID，在服务保留时间内 Download All Data，并确认压缩包能打开且包含需要的结果。

重新载入相容对象或 fMSEA 结果时，确认它对应哪个分析步骤。修改参数不会自动重建已经保存的结果，软件/包版本与数据库来源也应一起保存。

常见问题

问题	处理方法
目录选择器看不到本机	远程 R 看到的是服务器目录，改用上传或本地运行
Docker 找不到文件	检查主机目录权限和挂载，应用中选择容器路径
峰表样品不匹配	精确比较初始化样品 ID，去掉非强度列
离子模式或 RT 不正确	映射 ion 列，明确分钟/秒
缺少 R 包	从正确来源安装，检查首个实际错误，重启应用
峰检测很慢	检查进度日志，内存不足时减少线程，不反复点 Start
没有 MS2 候选	检查模式、前体/RT 关联、数据库及匹配容差
没有富集结果	核对 ID、物种、筛选和背景，空结果可能合理
LLM 评估失败	检查可选服务配置，独立保存已经得到的统计结果
重开后图不一样	确认对象版本、样品范围和作图设置

反馈问题时提供应用/包版本、本地/Docker/在线运行方式、模块、复现步骤、日志与脱敏输入示例，不分享 API key 或私人样品标识。

原教程及操作截图