Windows 使用说明 | TidyMass

安装与快速开始

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

安装 Windows 版本

本教程对应 0.1.63 Windows x64 预览版。向维护者获取预览 ZIP，完整解压后运行 TidyMass-0.1.63-windows-x64-setup.exe，按安装向导完成安装。当前尚未核实可供公众直接访问的下载链接；已有 CI 构建产物需要 GitHub 仓库访问权限。

启动后等待 R environment 检查结束。安装包内置 R 4.5.2 和核心依赖，主工作流无需单独安装系统 R。选择本机可写项目目录，保留原始文件供后续查看峰形。如果 Windows 提示未知发布者，先向维护者核实安装包来源和校验值，再按系统提示允许该应用。

0.1.63 已记录安装及安装后应用的自动化测试，仍需在用户实际 Windows 环境中确认。本页不声明 Windows ARM 兼容性。

创建第一个项目

点击左侧 Workflows。
打开非靶向代谢组学工作流，输入项目名。
点击 Choose location & create，选择存放项目的父目录。
在 Data import 中选择 mzML/mzXML 和可选的 sample information。
导入完成后进入 Raw data processing。

软件会创建新的项目目录；不要选择一个同名已有目录来覆盖旧项目。后续通过 Projects 或 Open project 打开项目目录。

正式处理大批样品前，建议在独立测试项目用少量有代表性的样品检查参数。

认识界面

入口	用途
Workflows	按步骤完成完整分析
Analysis tools	执行单个分析或准备任务
Shiny tools	安装、启动第三方 Shiny 应用
R environment	查看 R 环境与管理额外 R 包
Code	查看相关代码和执行记录
Run history	查看已保存运行及其参数
Show settings / Hide settings	展开或收起参数面板

左下角内存分别显示 TidyMass used、Computer used、Computer total。软件占用和系统总占用不是同一个指标；系统总占用较高不一定由 TidyMass 单独造成。

第一次运行后的检查

确认导入样品数、分组和文件匹配正确，再查看结果中的 feature 数、缺失值、峰形及警告。仅显示 completed 表示程序执行完成，不代表分析参数或生物学结论已经验证。

输入数据与样品信息

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

返回教程目录 · 适用版本：0.1.63

原始数据

非靶向工作流和 Raw chromatograms 使用 mzML / mzXML。本版本这些入口不直接处理厂商专有 RAW 文件；请先使用适合仪器和采集方式的转换工具。

正、负离子模式建议分别建立项目。文件名去掉扩展名后必须唯一，即使文件在不同子文件夹中也不能重名。不要只用大小写区分样品名。

导入会登记文件位置，后续需要检查 EIC 或质谱时仍可能使用原始文件。因此不要在分析过程中移动、替换或重命名它们。

sample information

原始数据导入支持 CSV、TSV、Excel 样品信息。示例：

sample_id,group,class,batch,injection.order,subject_id
S001,Control,Subject,B1,1,P01
S002,Treatment,Subject,B1,2,P02
QC001,QC,QC,B1,3,
Blank001,Blank,Blank,B1,4,

列	含义与要求
`sample_id`	与原始文件名去掉扩展名后完全一致。例如 `S001.mzXML` 对应 `S001`
`group`	生物学分组；如果列名不同，在 Group column 中指定实际列名
`class`	样品用途，例如 `Subject`、`QC`、`Blank`
`batch`	分析批次，用于检查批次效应等
`injection.order`	进样顺序，用于漂移检查及需要顺序信息的方法
`subject_id`	配对分析中的个体标识，不配对时可以不提供

导入原始文件时，样品信息必须覆盖所有选中的文件，每个 sample ID 只能出现一次。不要用表格行号代替样品名。前导零应保留为文本，例如 001 不能变成 1。

建议明确填写 class，不要依赖自动推断。用于收集 MS2 的 pooled QC 不是自动等同于用于定量质量评价的 QC；只有符合定量实验设计的 QC 才应进入相应 QC 计算。

已有峰表

通过 Dataset builder & converter 将峰表构建为 mass_dataset，再用于独立分析模块。宽表格式示例：

variable_id,mz,rt,S001,S002
F001,100.1234,60,1000,1200
F002,200.2345,120,500,NA

variable_id 唯一。
mz 为离子质荷比，rt 的单位与所选导入选项一致；上例为秒。
强度列名与样品信息的 sample_id 对应。
NA 表示缺失。零是实际数值，不会自动当作缺失值。
元数据中的注释名称不应被当作已确认鉴定，需保留其证据来源。

MS2 数据

MS2 可在支持的导入、数据构建或注释入口附加。MS2 与 feature 的关联依赖前体 m/z 和 RT 等条件；有匹配的 MS2 不代表已确认化合物身份。

开始前用 Sample & file checker 排查重复、缺失和未预期的文件，尤其适合多批次项目。

完整非靶向代谢组学工作流

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

返回教程目录 · 适用版本：0.1.63

1. Data import

选择 mzML/mzXML 文件和样品信息，检查分组，点击 Import raw files。这一步登记原始文件，不执行色谱峰检测。

使用目录导入时，子目录可以参与分组；使用单独文件选择时应通过样品信息确认真实分组。检查导入表，不要将文件存放方式误当作生物学设计。

2. Raw data processing

软件使用 massprocesser/XCMS 相关处理功能，进行峰检测、保留时间校正和跨样品特征分组；是否补峰由设置决定。

重点检查：

参数类别	检查目的
m/z tolerance	与仪器质量精度相符
Peak width range	与实际色谱峰宽相符
Signal / noise、noise、prefilter	控制噪声和低质量信号进入峰表
Grouping bandwidth、minimum fraction	控制跨样品分组条件
Fill peaks	决定是否执行补峰，不等同于后面的矩阵缺失值填补
Worker processes	控制并行规模，同时考虑内存和数据量

先在独立测试项目用少量样品检查参数，确认后在正式项目点击 Process raw data 处理完整数据。

结果包括 mass_dataset、峰表和处理输出。需要查看生成文件时点击 Project folder，结合该次运行 ID 定位文件。

3. Data exploration

检查 m/z–RT 分布、样品及 feature 缺失值、分组和批次信息。在联动工作台选择 feature，查看峰形、MS1/MS2、样品强度及可用的注释证据。

Feature filters 改变当前显示范围，不删除下游数据；人工 Exclude 标记也不是自动从分析矩阵移除。详见结果审查。

4. Data cleaning

按研究设计选择：

缺失值过滤，包括 QC 或生物学组内条件。
异常样品检查及明确的移除选择。
缺失值填补。
归一化。
可选的批次整合。

没有定量 QC 时，不要启用依赖 QC 的过滤或校正。异常点需要结合实验记录判断，不能仅凭 PCA 位置决定删除。

检查每一步的设置与前后结果。前后 PCA 可能是分别拟合的模型，坐标轴不能被理解为同一个固定坐标系。

5. Metabolite annotation

选择 metid 支持的参考数据库，配置离子模式、色谱类型、加合物、MS1/MS2 容差和匹配阈值。只有数据库 RT 与实验条件相容时才使用 RT 匹配。

在注释表中选择候选项，检查实验与参考 MS2 镜像谱，以及质量误差、RT 和其他证据。没有 MS2 的候选不能被解释为 MS2 已验证鉴定。

若暂不做注释，可在界面允许时选择 Skip annotation for statistics。跳过后仍可继续统计，但基于注释的 pathway analysis 需要先补做注释并更新其后步骤。

6. Statistical analysis

检查 PCA 和所需的差异分析设置。明确选择 Control 与 Treatment 等实际比较组。

配对分析需要正确的个体列，并保证两组中每个参与比较的个体各有一个样品且标识匹配。不能靠样品顺序自动推断配对。

7. Pathway analysis

确认注释 ID、候选歧义处理、输入筛选和背景集。根据研究目的选择合适的方法和多重检验设置。

没有符合要求的化合物时，空结果可能是合理结果；先检查输入筛选、注释与数据库覆盖，不要为了得到通路而随意放宽条件。

8. Results & export

选择运行范围和导出内容，保存完整表格、R 对象、代码和日志。详见导出与恢复。

中断、继续与重跑

完成步骤保存在项目中。重开项目后可以从第一个尚未完成且前置条件满足的步骤继续，不必重跑已完成步骤。

重跑上游步骤成功后，依赖旧结果的下游步骤会变为过期，需要重新运行。旧结果仍在 Run history 中。失败或取消的重试不会把之前成功的结果当作新结果覆盖掉。

这里的恢复是从已保存的步骤继续，不代表可以从某一次峰检测内部的任意扫描点恢复。

任务、重跑与版本差异

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

返回教程目录 · 适用版本：0.1.63

监控与取消

运行时查看当前任务的状态和日志。需要中止时使用界面的取消按钮，并等待状态更新。不要通过删除项目文件来中止计算。减少 worker 数可以降低并行计算的内存需求。

小规模检查与正式处理

在独立测试项目中选择少量有代表性的 QC 和研究样品，检查峰宽、质量容差与峰形。参数合适后，在正式项目导入完整样品并运行。保留两次分析的参数和输出；测试项目结果不是完整数据的正式结果。

从保存步骤继续

重新打开项目后，从第一个未完成且前置条件满足的步骤继续。成功重跑上游会使相关下游结果过期；重新执行相关步骤即可。Run history 保留旧记录。取消后的峰检测需重新执行，不支持扫描级续算。

与 macOS 0.1.65 的差异

Windows 0.1.63 不包含 macOS 0.1.65 新增的 Parameter trial、Task center、Workflow templates，也不包含新的可调宽度图表工作台及 Basic / Quality / Annotation 列视图。不要在本版本中查找这些新入口。核心分析步骤请按 Windows 本教程操作；升级后以实际版本及对应文档为准。

Feature 审查与交互图

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

返回教程目录 · 适用版本：0.1.63

查找与查看 feature

在 Data exploration 打开 m/z–RT distribution，点击散点或表格中的 feature 查看详情。使用 Find feature by ID 精确查找；Previous feature / Next feature 按当前过滤和排序后的列表切换。表格可以按列排序，并添加少量样品强度列。

Windows 0.1.63 使用原有图表布局，不包含 macOS 0.1.65 新增的可调宽度工作台和列视图切换。

筛选与人工审查

Feature filters 可按 MS2、注释状态、m/z、RT、强度、缺失率、QC RSD、Sample / Blank 等条件筛选。质量指标需要数据中有相应 QC/Blank 和有效观测；QC RSD 至少需要三个有效 QC 观测。

筛选同时影响图和表，但不改变保存的矩阵。需要实际删除或过滤数据时，应使用 Data cleaning 并生成新的结果。

人工审查可设置 Keep、Exclude、Needs confirmation、Favorite 和备注。点击 Save review 保存，使用 Export reviews CSV 导出。Exclude 是审查标记，不自动删除下游数据。

检查证据

选中 feature 后可按需加载：

Peak evidence：可用的检测、补峰及积分边界记录。
Sample intensities：各样品中的强度。
Injection drift：按进样顺序检查变化。
RT alignment：可用的保留时间对齐信息。
MS2 spectra：已关联的 MS2。
Annotation candidates：保存结果中的候选项。
MS1 spectrum：所选样品中接近该 feature RT 的扫描谱。

MS1 扫描谱包含该扫描的其他离子，不是分离后的“该化合物纯谱”。有 MS2 和高匹配分数也不能单独证明唯一结构。

峰形

点击 Show peak shape，默认只展示少量样品。展开 Samples and extraction settings 可修改样品、m/z 容差和 RT 窗口。

峰形是原始 RT 下的 MS1 EIC；图中可用的虚线边界来自保存的峰积分证据。首次提取可能需要读取原始数据并建立本地扫描缓存，后续复用缓存。更换或丢失原始文件仍可能导致提取失败。

图表操作与下载

图表工具栏位于各图附近：

鼠标拖动框选区域进行放大。
Reset view 或双击恢复初始视图。
Download plot 选择可用格式、宽高及 PNG DPI。
提供 Download CSV 时可导出该图对应的数据。
点击 information icon 查看该图的说明。

保存图可能使用完整范围，而不是当前缩放区域；以图旁的说明为准。表格分页和图形预览不代表完整导出被截断，应使用 Download complete CSV 或 Results & export 获取完整数据。

Analysis tools：独立分析工具

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

返回教程目录 · 适用版本：0.1.63

点击 Analysis tools，再点击对应卡片的 Open tool。部分工具创建独立项目，部分工具在自己的页面保存结果。

工具	主要用途
Sample & file checker	检查样品清单与原始文件是否匹配
Injection sequence designer	随机化、分批和安排 QC/Blank 进样
Raw chromatograms	TIC、BPC、EIC 和原始扫描谱
Raw data processing	独立执行峰检测与对齐
Dataset builder & converter	从表格构建或转换数据集
Data exploration	探索已有数据集
Data cleaning	清洗、填补、归一化和批次处理
Metabolite annotation	对 feature 或查询进行注释
Pathway analysis	对符合条件的化合物做通路分析
QC report	输出样品与 feature 质量报告
Targeted peak extractor	提取预定义 m/z–RT 目标的峰面积与峰形

Sample & file checker

提供样品 CSV 和原始文件目录，选择匹配列。普通样品清单通常用 sample_id；进样计划有重复 QC 时通常用唯一的 file_name。

工具检查 mzML、mzXML 和 Thermo RAW 的文件名，不代表能够读取或转换 Thermo RAW 的谱图。匹配去掉扩展名后进行，并区分大小写。检查缺失、重复和未预期文件后，再进行大规模分析。

Injection sequence designer

最少输入：

sample_id
S001
S002
S003

也可包含 group、position 或 vial_position。

点击 Import sample CSV。
设定 batch 数、随机化和随机种子。
设置 Conditioning QC、Pooled QC、Blank、RTQC、MS2 QC 的启用与插入规则。
检查每批的样品数和总进样次数。
导出 running list、metadata 或保存计划 JSON。

随机化是全体研究样品打乱后分批，不是生物学组别的分层平衡设计。加入 QC 后，总进样次数会超过研究样品数。

重复进样必须有唯一文件名。导出的 metadata 使用进样文件名作为 sample_id，并保留原样品标识，有助于随后与实际原始文件匹配。

当前导出是通用进样计划，不保证可直接导入某一版本的 Xcalibur。 仪器软件要求的列名、方法路径、瓶位和进样量，需要依据该仪器的实际模板确认。

Raw chromatograms

选择一个或多个 mzML/mzXML，设定 MS level。
点击 Read TIC / BPC。
在结果中选择 TIC 或 BPC，默认 TIC。
hover 查看 RT；点击色谱位置检查该处的扫描谱，并选择对应样品。
读取后再输入目标离子 m/z、容差和单位，提取 EIC。

输入的是离子 m/z，不是中性分子质量。MS2 模式下的 EIC 表示相应 MS2 扫描中碎片离子的强度随时间变化，不能自动解释为某个特定前体的靶向碎片曲线。

QC report

输入 mass_dataset 的 RDS/RData，设置 QC RSD、缺失率和 Sample / Blank 阈值。报告只评估和标记，不自动删除 feature。

Intensity across injection order 是输入强度矩阵的总强度趋势，不是从原始扫描提取的 TIC。已经归一化或填补的矩阵会影响指标含义。

Targeted peak extractor

输入目标 CSV：

target_id,mz,rt
Target_A,195.0877,180
Target_B,300.1234,240

RT 单位为秒。选择原始文件、m/z 容差和 RT 积分窗口后运行。

当前方法累加容差内的 MS1 信号，并在固定 RT 窗口用梯形法积分。它不是化合物鉴定，也不会自动拆分共洗脱峰。检查峰形后再解释面积结果。预览可限制样品数，导出范围以工具说明为准。

Shiny tools 与 R environment

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

返回教程目录 · 适用版本：0.1.63

两个入口的区别

Shiny tools 安装和启动一个完整的 Shiny 应用。
R environment 查看当前 R 环境，并安装额外 R 包，例如工具缺失的依赖。

给 Shiny 安装一个依赖包，不需要把它再注册为一个 Shiny 工具。

安装 Shiny 应用

打开 Shiny tools → Install a Shiny tool。
选择 GitHub、CRAN 或 Bioconductor。
输入仓库地址或包名。
如已知，可填写 R package name 和 Startup function；否则先留空尝试自动识别。
确认来源可信后勾选界面的信任选项，点击 Install tool。
用 View log 检查安装过程。

GitHub 仓库名不一定等于 R 包名。例如仓库名可能含下划线，而实际包名不同。不要把整个 GitHub URL 填到 R package name 中。

工具执行的是本机 R 代码，不只是一个静态网页。第三方应用的功能和依赖由其开发者决定。

启动与管理

在 Installed tools 点击 Open tool。应用占据左侧导航栏之外的主要空间，顶部保留返回、停止和日志按钮。

Back to installed tools 返回列表，不等同于停止进程；需要释放该工具资源时点击 Stop tool。

Manage tool 中可配置启动模式：

模式	使用场景
Auto-detect	优先尝试自动识别
Exported function	包导出了明确的启动函数
Package app_ui / app_server	包提供相应 UI 和 server 接口
Shiny application folder	选择含 Shiny 应用文件的目录，以 `shiny::runApp()` 启动

启动函数只填函数名，例如 run_featuremap，不要填 featuremapshiny::run_featuremap()。

runApp 是 shiny 包中的函数，并不是每个第三方包都导出了自己的 runApp。若报 “not an exported object”，检查启动模式和实际函数名。

安装缺失的 R 包

打开左下角 R environment。
查看已安装包，确认报错中缺少的准确包名。
在包安装区域选择正确来源并输入包名或仓库地址。
检查安装日志。
安装成功后停止并重新启动相关 Shiny 工具。

例如 org.Mm.eg.db 属于 Bioconductor，应按其来源安装，而不是将它当作 CRAN 包。

额外包库与应用内置库分开管理。Shiny 工具还可能具有自己的私有依赖库；核心分析与第三方工具的库搜索优先级可能不同。因此“某处安装成功”不代表每个进程已经加载同一版本，重启工具后仍报错时应查看日志和实际包版本。

从源码安装的包可能需要编译器或系统依赖。遇到此类失败，安装更多 R 包不一定能解决问题，应先找到日志中的首个实际错误。

导出、项目保存与恢复

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

返回教程目录 · 适用版本：0.1.63

下载单张图片

在图片附近点击 Download plot，选择提供的格式。宽高以英寸为单位，PNG 可设置 DPI。部分图还提供 Download CSV。

交互图当前缩放范围不一定等于导出范围，尤其是 R 重新生成的图。需要保存特定范围时先检查图旁说明和导出结果。

导出完整分析结果

在 Results & export：

选择 Selected run 或 All completed datasets / queries。
如果只导出某次运行，选择对应运行 ID。
勾选 R 对象、完整表格、Code/参数/日志/会话信息，以及所需图形。
点击 Export selected content，选择目标位置。

如果选择完整项目副本，它会包含该项目保存的完整产物，不受其他单项内容勾选的限制。但项目之外的原始文件、数据库等不应被默认认为已经归档；仍需单独核对与备份。

表格页面可能分页或仅显示预览，完整导出应通过完整表格下载或 Results & export 完成。

试跑也是独立的保存记录。导出时检查运行 ID 与用途，避免把小规模试跑当作正式全样品结果。

保存的内容

项目保存运行状态、参数、输入关系和结果。每次运行目录通常包含请求参数、日志、执行与复现代码、R 对象及相应输出。

Code 用于查看代码记录。执行记录不一定是可直接复制执行的独立脚本；完整复现还需要正确的数据路径、数据库及兼容的软件环境。

重开项目

通过 Open project 选择含 project.json 的项目目录。软件根据保存结果重建工作流状态。

已完成步骤可以继续使用。
上次未完成的执行可能标为 interrupted。
上游更新后的下游结果可能标为 stale。
丢失结果文件时需恢复对应运行目录或重新执行。

不要手工修改 project.json 中的状态来解锁步骤，这不会生成缺失的数据。

迁移和清理

迁移前复制整个项目目录，另外核对外部原始数据和数据库。项目内部结果路径可以随项目位置恢复，但外部文件引用不保证随迁移自动修复。

通过软件的 Storage 查看可管理的缓存，清理前阅读其说明。扫描缓存可减少重复读取；清除后再次提取峰形可能需要重新读取原始数据。

不要在分析运行中手工删除 run 文件夹。多个软件实例也不应同时修改同一个项目；遇到项目锁提示，先关闭另一个实例。

常见问题

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

返回教程目录 · 适用版本：0.1.63

处理步骤或结果

现象	检查与处理
重跑上游后下游显示 stale	下游仍依赖旧输入，需要从受影响步骤重新运行；历史结果保留
取消或重开后不能从内部进度继续	当前恢复以保存步骤为单位，不支持峰检测内部续算
页面显示的 feature 数与导出不同	检查当前筛选、分页和预览限制
Exclude 后下游仍有该 feature	人工 Exclude 是审查标记；实际清洗需另行运行
MS2 / 注释字段为 No 或 NA	可能未关联谱图或未做注释，不应直接判断“该物质不存在”
修改参数后图没有改变	参数影响下一次运行；当前图属于保存的结果

输入与统计

报错或现象	检查与处理
Sample IDs do not match	检查文件名去扩展名后的 ID、大小写、前导零、重复与漏行
Group column not found	将 Group column 设置为样品信息中的真实列名
QC filtering enabled but no QC samples	核对定量 QC 的 class；没有合适 QC 时关闭依赖 QC 的设置
统计前仍存在缺失值	检查 cleaning 设置、填补方法和当前输入版本
配对分析报错	检查 subject ID，两组应一一对应，不能按行号推断
Pathway analysis 没有结果	核对注释 ID、背景和输入筛选；空结果可能合理
峰形提取找不到文件	检查原始文件是否移动、改名或被替换

运行期间

Shiny 与 R 包

Missing package：在 R environment 安装正确来源的包，之后重启工具。
Invalid R package name：检查是否把仓库名或 URL 当作包名；包名应以实际包元数据为准。
not an exported object：检查 Manage tool 中的启动模式和函数名。
页面文字可读但图片丢失、样式异常：可能是静态资源路径问题，不一定是字符编码错误；保存日志和截图。
安装日志出现 warning：区分警告与导致失败的 error，查看最后状态及首个关键失败原因。

提交问题时提供什么

请提供软件版本、macOS/Windows 版本、具体工具或 workflow 步骤、运行 ID、复现操作和相关日志。数据问题可附脱敏的样品信息表头与几行示例。

保留出现问题的项目和运行记录，先不要删除缓存或历史结果。日志可能包含本地路径和样品标识，分享前检查其中的敏感信息。