R package 使用说明 | TidyMass

安装与版本管理

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

准备环境

本教程核对了 tidymass 2.0.10 及各包的当前源码。虽然部分包声明最低 R 4.1，当前 masstools 要求 R ≥ 4.5；新环境应采用满足整套依赖的 R 4.5 或更高兼容版本。安装 R 和适合自己的 IDE，使用可写用户包库。

Windows 源码编译需要匹配 R 版本的工具链；macOS 可能需要命令行开发工具及特定系统库。先看安装日志的第一个实际错误，再补齐相关依赖。Docker/ProteoWizard 属于原始格式转换的额外需求，不是打开峰表的前提。

安装

以下从官方 GitHub 源安装；依赖元数据中也可能引用 GitLab 和 Bioconductor，因此需能访问相应来源。安装会访问网络并可能编译包。

if (!requireNamespace("remotes", quietly = TRUE)) install.packages("remotes")
if (!requireNamespace("BiocManager", quietly = TRUE)) install.packages("BiocManager")
remotes::install_github("tidymass/tidymass")
# Additional packages when your analysis needs them:
remotes::install_github("tidymass/massdatabase")
remotes::install_github("tidymass/massconverter")
# Standalone legacy normalization interface:
# remotes::install_github("jaspershen/MetNormalizer")
library(tidymass)
sessionInfo()

记录版本与排错

重启 R 后加载 tidymass，检查 packageVersion()、.libPaths() 和 sessionInfo()。主包的版本不代表每一个子包版本相同。遇到同名函数用 包名::函数名()，不要因为加载顺序变化而运行了另一个包的接口。

使用 tidymass::check_tidymass_version(packages = "all") 检查更新；明确需要升级时再运行 update_tidymass()。远程镜像可能不同步，网络失败也可能使更新信息不完整。对于已经发表或正在比较的项目，先保存环境锁定记录和分析代码，再升级并验证。

从哪里开始

从 massdataset 学习数据结构；已有原始数据按完整工作流处理。每个包的章节列出功能范围、使用示例和导出函数。数据依赖示例只有在准备了相应输入时才运行，示例参数不是经过验证的通用分析方法。

tidymass — 安装与管理包体系

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

文档核对版本: 2.0.10 · 2026-09-23

tidymass 用于安装和加载共享数据结构的一组包，实际分析由各功能包完成。先查看包列表、函数名冲突和版本；massdatabase、massconverter 等扩展包按需单独加载。

安装或更新使用新的 R 会话。升级前保存原项目环境，完成后重启 R 并检查代表性数据。更新检查成功不代表每个远程源都已正常访问。

功能范围

包发现、函数冲突提示、版本检查与整套更新。

使用示例

library(tidymass)
tidymass::tidymass_packages()
tidymass::tidymass_conflicts()
packageVersion("tidymass")
sessionInfo()
# Run deliberately when checking/updating the environment:
# tidymass::check_tidymass_version(packages = "all")
# tidymass::update_tidymass(packages = "all", from = "github")

函数查询

下面列出已核对源码中导出的 API，包括兼容接口与辅助函数。具体参数以安装版本的 R 帮助为准；例如运行 help("函数名", package = "tidymass")。

展开导出函数列表

check_tidymass_version, tidymass_conflicts, tidymass_logo, tidymass_packages, update_tidymass

包源码与参考文档 · 完整工作流

massdataset — 构建、查看与交换数据集

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

文档核对版本: 0.99.3 · 2026-09-23

核心 mass_dataset 同时保存强度矩阵、样品信息、feature 信息、可选 MS2、注释表和处理历史。矩阵的行是 feature，列是样品；ID 和顺序必须与元数据对应。

处理自己的数据时，分别读取三张表，保留文本 ID，构造数值强度矩阵，并按 sample/feature ID 对齐行列，再调用 create_mass_dataset()。下例使用包内数据展示结构。使用 tidy 操作前通过 activate_mass_dataset() 明确操作的是样品还是 feature 信息。

通过 mutate_ms2() 加入 MS2，先检查离子模式、RT 单位和前体/RT 匹配容差。extract 系列函数用于取出普通表格；export_mass_dataset() 用于交换文件；RDS 保留完整对象。MS-DIAL/MZmine、mzTab 和 SummarizedExperiment 转换器各有输入约定，不能把任意 CSV 当作同一种格式。

功能范围

数据构建与校验，样品/feature 编辑筛选、连接合并，MS2 读写，注释和历史提取，缺失值/RSD 汇总及格式转换。

使用示例

data("expression_data", package = "massdataset")
data("sample_info", package = "massdataset")
data("variable_info", package = "massdataset")
object <- massdataset::create_mass_dataset(
  expression_data = expression_data,
  sample_info = sample_info,
  variable_info = variable_info
)
head(massdataset::extract_sample_info(object))
head(massdataset::extract_variable_info(object))
saveRDS(object, "dataset.rds")

函数查询

下面列出已核对源码中导出的 API，包括兼容接口与辅助函数。具体参数以安装版本的 R 帮助为准；例如运行 help("函数名", package = "massdataset")。

展开导出函数列表

activate_mass_dataset, adjust_confounder, aes, arrange, case_when, cbind_mass_dataset, check_annotation_table, check_column_name, check_mass_dataset, check_mass_dataset_class, check_object_class, convert_mass_dataset2mztab, convert_mass_dataset2summarizedexperiment, convert_msdial2mass_dataset, convert_mztab2mass_dataset, convet_mzmine2mass_dataset, count, create_mass_dataset, desc, drop_na, export_mass_dataset, export_mass_dataset4metdna, export_ms2_data, extract_annotation_table, extract_expression_data, extract_ms2_data, extract_process_info, extract_sample_info, extract_sample_info_note, extract_variable_info, extract_variable_info_note, fill, filter, filter_samples, filter_variables, get_massdataset_version, get_mv_number, get_sample_id, get_sample_number, get_variable_id, get_variable_number, ggplot, ggplot_mass_dataset, glimpse, group_by, hello_world, intensity_plot, left_join, left_join_mass_dataset, massdataset_conflicts, massdataset_logo, massdataset_packages, match_mz_rt, merge_mass_dataset, ms2_plot, mutate, mutate_all, mutate_annotation_table, mutate_at, mutate_mean_intensity, mutate_median_intensity, mutate_ms2, mutate_rsd, mutate_sample_na_freq, mutate_sample_na_number, mutate_sample_zero_freq, mutate_sample_zero_number, mutate_variable_na_freq, mutate_variable_na_number, mutate_variable_zero_freq, mutate_variable_zero_number, n, parse_tidymass_parameter, pivot_longer, plot_ms2, pull, rbind_mass_dataset, read_mgf, read_mztab, read_mzxml, relocate, rename, rename_with, report_parameters, select, show_missing_values, show_mz_rt_plot, show_sample_missing_values, show_variable_missing_values, slice, slice_head, slice_max, slice_min, slice_sample, slice_tail, split_mass_dataset, summarise, summarise_samples, summarize, summarize_samples, translate_tidymass_parameter, transmute, update_mass_dataset, update_sample_info, update_variable_info, write_ms2_data

包源码与参考文档 · 完整工作流

massconverter — 转换厂商原始文件

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

文档核对版本: 1.0.3 · 2026-09-23

massconverter 用于配置 ProteoWizard/msconvert，将厂商文件转换为开放格式；这一步不做色谱峰检测。是否能转换取决于厂商读取器、操作系统、容器环境和目录访问权限。

明确选择 mzML/mzXML、质心化方法、离子模式和 MS level。后续鉴定需要 MS2 时保留相关扫描。保留原始采集文件，先转换一个文件并检查扫描数、RT 范围、模式和 TIC，再批量处理。vendor 质心化需要读取器支持，容器不代表兼容所有厂商格式。

下例构建参数对象；配置 Docker/ProteoWizard 并替换路径后，才能执行注释掉的转换调用。

功能范围

转换参数构建与校验、命令生成、容器准备和批量文件转换。

使用示例

parameter <- massconverter::create_msconvert_parameter(
  output_format = "mzML",
  peak_picking_algorithm = "vendor",
  subset_polarity = "positive",
  subset_mslevels = c(1, NA)
)
parameter
# massconverter::convert_raw_data(
#   input_path = "vendor_raw", output_path = "converted",
#   msconvert_parameter = parameter
# )

函数查询

下面列出已核对源码中导出的 API，包括兼容接口与辅助函数。具体参数以安装版本的 R 帮助为准；例如运行 help("函数名", package = "massconverter")。

展开导出函数列表

check_msconvert_parameter, convert_raw_data, create_msconvert_parameter, docker_pull_pwiz, from_msconvert_parameter_to_code, get_massconverter_version, get_run_code, massconverter_logo, massconverter_packages

包源码与参考文档 · 完整工作流

massprocesser — 峰检测与样品对齐

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

文档核对版本: 1.0.11 · 2026-09-23

输入转换后的 mzML/mzXML，使用独立处理目录，通常按 QC、Subject 等样品类型建立子目录。正负离子模式分别处理。process_data() 完成原始数据处理并在 Result 中写入结果。

ppm 依据仪器表现设置，peakwidth 以秒表示并参考实际色谱；使用代表性文件调整信噪比、prefilter 和 noise。bw、min_fraction 影响跨样品分组；fill_peaks 控制色谱补峰，不是统计填补。内存不足时降低 threads。

检查 TIC/BPC、RT 校正、峰表和 EIC。需要后续审查时保留中间文件。下例参数仅展示调用形式，并非适用于所有仪器的方法。运行后检查输出文件，不要把函数返回值直接当作最终数据集。

功能范围

原始数据处理、EIC 提取、色谱可视化、校正 RT 可视化及靶向表格校验。

使用示例

# Requires your converted files under analysis/MS1/.
# massprocesser::process_data(
#   path = "analysis/MS1", polarity = "positive",
#   ppm = 15, peakwidth = c(5, 30), snthresh = 10,
#   threads = 2, min_fraction = 0.5, fill_peaks = FALSE,
#   output_tic = TRUE, output_bpc = TRUE
# )
help("process_data", package = "massprocesser")

函数查询

下面列出已核对源码中导出的 API，包括兼容接口与辅助函数。具体参数以安装版本的 R 帮助为准；例如运行 help("函数名", package = "massprocesser")。

展开导出函数列表

check_targeted_table, extract_eic, get_massprocesser_version, massprocesser_conflicts, massprocesser_logo, massprocesser_packages, plot_adjusted_rt, plot_chromatogram, process_data

包源码与参考文档 · 完整工作流

masscleaner — 过滤、填补与归一化

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

文档核对版本: 1.0.12 · 2026-09-23

从校验后的 mass_dataset 开始，准备样品用途、批次和进样顺序。先过滤缺失过多的 feature，再填补。异常样品应结合实验记录判断，不能自动删除所有 PCA 离群样品。

impute_mv() 提供 kNN、随机森林、简单值和模型填补等方法，按缺失机制和数据规模选择样品范围与方法。normalize_data() 提供 total、mean、median、PQN 样品级方法和依赖 QC 的 SVR/LOESS；后两者需要合适的 QC 覆盖和采集信息。integrate_data()、align_batch() 处理支持的跨批次任务，但不能消除批次与生物学分组完全混杂的设计问题。

保留输入对象，检查处理后的缺失情况、QC 指标及前后图。预测建模时在训练折内部拟合预处理，避免信息泄漏。下例的中位数填补和归一化仅用于展示 API。

功能范围

异常样品检测与报告、缺失值填补、样品级/QC 归一化、LOESS 参数优化、批次对齐与整合。

使用示例

# object is the mass_dataset created/imported in the previous chapter.
expr <- massdataset::extract_expression_data(object)
keep <- which(rowSums(!is.na(expr)) > 0)
stopifnot(length(keep) > 0)
object <- object[keep, ]
cleaned <- masscleaner::impute_mv(object, method = "median")
normalized <- masscleaner::normalize_data(cleaned, method = "median")
saveRDS(normalized, "normalized.rds")

函数查询

下面列出已核对源码中导出的 API，包括兼容接口与辅助函数。具体参数以安装版本的 R 帮助为准；例如运行 help("函数名", package = "masscleaner")。

展开导出函数列表

align_batch, check_for_data_integration, check_for_qc_normalization, detect_outlier, extract_outlier_table, get_masscleaner_version, impute_mv, integrate_data, masscleaner_conflicts, masscleaner_logo, masscleaner_packages, normalize_data, normalize_data_pqn, optimize_loess_span

包源码与参考文档 · 完整工作流

massqc — 质量评估与报告

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

文档核对版本: 1.0.8 · 2026-09-23

清洗前后都应评估质量。为 massqc 提供样品用途、批次和进样顺序正确的 mass_dataset，将报告写入新的输出目录，并保留生成报告的输入对象。

检查按样品/feature 汇总的缺失值、强度分布、QC RSD、相关性和 PCA。QC RSD 需要真实定量 QC 重复。低 RSD 不代表身份已确认，PCA 异常点也可能反映生物学差异。报告中写清输入是否已填补或归一化，因为这些处理影响指标。

HTML 报告需要可用的渲染依赖；PDF 还需要相应文档工具链。渲染失败时先检查日志，可以先输出单独诊断图，再修复缺少的渲染环境。

功能范围

HTML/PDF 报告、样品与 feature 缺失值、m/z–RT 分布、RSD 曲线、强度箱线图、PCA 和样品相关性。

使用示例

# Requires object and the report-rendering dependencies.
# massqc::massqc_report(object, path = "qc_before", type = "html")
massqc::show_sample_missing_values(object)
massqc::show_variable_missing_values(object)

函数查询

下面列出已核对源码中导出的 API，包括兼容接口与辅助函数。具体参数以安装版本的 R 帮助为准；例如运行 help("函数名", package = "massqc")。

展开导出函数列表

extract_expression_data, extract_process_info, extract_sample_info, extract_variable_info, get_mv_number, massqc_conflicts, massqc_cumulative_rsd_plot, massqc_logo, massqc_packages, massqc_pca, massqc_pca_pc1, massqc_report, massqc_rsd_plot, massqc_sample_boxplot, massqc_sample_correlation, show_missing_values, show_mz_rt_plot, show_sample_missing_values, show_variable_missing_values

包源码与参考文档 · 完整工作流

massdatabase — 获取与构建参考数据库

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

文档核对版本: 1.0.14 · 2026-09-23

massdatabase 用于获取、解析和转换化合物、谱图及通路资源，本身不是一个包罗所有化合物的数据库。先确定后续分析需要的数据来源和 ID 系统。

典型谱库流程为：下载来源文件 → 按 MSP/XML/SDF 等格式读取 → 转为 metid 数据库。通路流程为：获取物种对应的 KEGG 或其他支持资源 → 读取 → 转为 metpath 对象。保存原始资源、获取日期、物种、转换参数和来源版本。

导出 API 覆盖 KEGG、HMDB、MassBank、MoNA、GNPS、PubChem、ChEBI、LipidMaps、FooDB、BiGG、SMPDB、Reactome、WikiPathways 等相关操作，各来源支持的下载/读取/查询/转换组合不同。在线服务和文件结构可能变化；请求失败不代表化合物不存在。共享衍生数据库前检查来源使用条件和覆盖范围。

功能范围

来源特定的在线查询下载、谱图/化合物/通路解析、metid/metpath 格式转换及 ID/来源辅助工具。

使用示例

# Use the source-specific reader matching your downloaded data.
help("read_msp_data", package = "massdatabase")
help("convert_mona2metid", package = "massdatabase")
help("download_kegg_pathway", package = "massdatabase")
help("convert_kegg2metpath", package = "massdatabase")

函数查询

下面列出已核对源码中导出的 API，包括兼容接口与辅助函数。具体参数以安装版本的 R 帮助为准；例如运行 help("函数名", package = "massdatabase")。

展开导出函数列表

convert2metid, convert_bigg_universal2metid, convert_chebi2metid, convert_foodb2metid, convert_gnps2metid, convert_hmdb2metid, convert_kegg2metid, convert_kegg2metpath, convert_lipidbank2metid, convert_lipidmaps2metid, convert_massbank2metid, convert_massbank2metid_nist, convert_massbank2metid_riken, convert_mona2metid, convert_nist2metid, convert_smpdb2metpath, convert_species2source, download_bigg_model, download_bigg_universal_metabolite, download_chebi_compound, download_foodb_compound, download_gnps_spectral_library, download_kegg_compound, download_kegg_drug, download_kegg_pathway, download_kegg_rclass, download_kegg_reaction, download_lipidbank_lipid_class, download_lipidmaps_lipid, download_massbank_compound, download_pubchem_compound, download_smpdb_pathway, get_words_similarity, massdatabase_logo, massdatabase_packages, parse_pubchem_compound, parse_reactome_pathway, parse_reactome_reaction, read_bigg_model, read_bigg_universal_metabolite, read_chebi_compound, read_foodb_compound, read_gpml, read_kegg_compound, read_kegg_drug, read_kegg_pathway, read_msp_data, read_msp_data_gnps, read_msp_data_massbank, read_msp_data_mona, read_msp_data_nist, read_sdf_data_lipidmaps, read_smpdb_pathway, read_xml_data, read_xml_data_hmdb, request_bigg_model_info, request_bigg_reaction_info, request_bigg_universal_metabolite, request_bigg_universal_metabolite_info, request_bigg_universal_reaction, request_bigg_universal_reaction_info, request_bigg_version, request_chebi_compound, request_foodb_compound, request_foodb_compound_info, request_foodb_compound_info_crawler, request_foodb_compound_ms2, request_hmdb_metabolite, request_hmdb_reaction, request_kegg_compound, request_kegg_compound_info, request_kegg_drug, request_kegg_drug_info, request_kegg_pathway, request_kegg_pathway_info, request_kegg_rclass, request_kegg_rclass_info, request_kegg_reaction, request_kegg_reaction_info, request_lipidbank_lipid_class, request_lipidmaps_lipid, request_pubchem_compound, request_reactome_organisms_info, request_reactome_pathway, request_reactome_pathway_info, request_reactome_reaction, request_reactome_reaction_info, request_wikidata_metabolite, request_wikipathway, request_wikipathway_info, request_wikipathway_organisms_info, request_wikipedia_compound, request_wikipedia_scientific_classification, search_hmdb_database, show_progresser

包源码与参考文档 · 完整工作流

metid — Feature 注释与谱图审查

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

文档核对版本: 1.3.2 · 2026-09-23

metid 将前体质量、条件相容的 RT 及可用 MS2 与 databaseClass 匹配。先导入或构建参考数据库，再给 mass_dataset 关联实验 MS2，核对离子模式、色谱和加合物。

当前 API 包含 annotate_metabolites_mass_dataset()，也保留 metIdentify*、mzIdentify* 等接口，不能混用参数名。下例针对色谱不可比的参考库明确关闭 RT 证据；质量容差需依据自己的仪器设置，示例值只用于说明。

审查完整候选证据，不只看最高分。MS1 候选不是结构确认；自建库也需要标准品和实际测量满足证据要求，不能仅按库名判断置信度。保留歧义，记录候选筛选和加合物去重规则。来源注释是数据库关联，不是样品中实际合成来源的直接证明。

功能范围

数据库构建校验、MS1/MS2 注释、单峰查询、匹配分数和镜像谱、置信度/候选/加合物筛选及来源汇总。

使用示例

# Requires an MS2-associated object and a compatible databaseClass.
# database <- readRDS("reference_database.rds")
# annotated <- metid::annotate_metabolites_mass_dataset(
#   object = object, database = database,
#   polarity = "positive", column = "rp",
#   ms1.match.ppm = 15, ms2.match.ppm = 30,
#   rt.match.tol = NA, rt.match.weight = 0,
#   candidate.num = 3, threads = 2
# )
help("annotate_metabolites_mass_dataset", package = "metid")

函数查询

下面列出已核对源码中导出的 API，包括兼容接口与辅助函数。具体参数以安装版本的 R 帮助为准；例如运行 help("函数名", package = "metid")。

展开导出函数列表

analyze_metabolite_origins, annotate_metabolites, annotate_metabolites_mass_dataset, annotate_peaks_mz_rt_ms2, annotate_single_peak_mass_dataset, calculate_confidence_level, calculate_dotproduct, calculate_ms2_matching_score, calculate_mz_match_score, calculate_rt_match_score, calculate_total_score, check_adduct_table, check_database, check_mass_dataset, check_ms1_ms2_info, check_object4metablite_origin, check_parameters4annotate_metabolites, check_parameters4calculate_total_score, construct_database, construct_massbank_database, construct_mona_database, correct_database_rt, extract_database_name, extract_ms1_database, extract_ms1_info, extract_ms2_database, extract_ms2_info, filter, filter_adducts, filter_identification, getIdentificationTable2, getMS2spectrum, get_iden_info, get_identification_table, get_identification_table_all, get_ms2_spectrum, get_ms2_spectrum_from_object, get_parameters, get_parameters_metid, identify_metabolite_all, identify_metabolites, identify_metabolites_params, identify_ms2_only, identify_peak, identify_single_peak, load_adduct_table, match_ms2_fragments, match_ms2_temp, metIdentification, metIdentify, metIdentify_mass_dataset, metabolite_origin_network, metabolite_origin_upsetplot, metid, metid_conflicts, metid_logo, metid_packages, ms2_plot_mass_dataset, ms2plot, mzIdentify, mzIdentifyParam, mzIdentify_mass_dataset, plot_ms2_matching, readMGF, readMSP, readMSP_MoNA, readMZXML, read_mgf_experiment, read_mgf_gnps, read_mgf_mona, read_msp, read_msp_database, read_msp_gnps, read_msp_mona, remove_impossible_annotations, remove_impossible_annotations_fix, remove_noise, source_metabolite_network, source_network, specific_source_network, summary_annotation_table, trans_to_new_style, which_has_identification, write_mgf_gnps, write_mgf_massbank, write_mgf_mona, write_msp, write_msp_gnps, write_msp_massbank, write_msp_mona

包源码与参考文档 · 完整工作流

massstat — 探索变异与组间比较

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

文档核对版本: 1.0.6 · 2026-09-23

使用适当清洗的数据和预先定义的比较方案。QC/Blank 不参与生物学假设检验。按用途选择变换与缩放：PCA 使用缩放不意味着 fold change 也要从缩放值计算。

run_pca() 返回 PCA 模型，pca_score_plot() 绘制得分；mutate_fc() 按均值或中位数计算 case/control；mutate_p_value() 支持 t 检验和 Wilcoxon 检验，并添加多重校正结果。配对检验前明确对齐同一个体。下例为独立分组比较，组名来自样品信息；这些 massstat 接口要求每个比较组至少三个样品。

其他功能包括热图、相关性、距离、图结构转换、PLS 和 PLS-DA。训练数据上的监督分离不是预测验证，需使用合适的留出或嵌套验证，不能先在全部数据上筛选特征再切分。

功能范围

PCA 与缩放、倍数变化和假设检验、火山图与热图、相关性/距离/图结构，以及 PLS/PLS-DA。

使用示例

si <- massdataset::extract_sample_info(normalized)
control <- si$sample_id[si$group == "Control"]
case <- si$sample_id[si$group == "Treatment"]
# Replace labels to match your experimental design.
if (length(control) >= 3 && length(case) >= 3) {
  stats_object <- massstat::mutate_fc(normalized, control, case,
                                     mean_median = "mean")
  stats_object <- massstat::mutate_p_value(stats_object, control, case,
    method = "t.test", p_adjust_methods = "BH")
  write.csv(massdataset::extract_variable_info(stats_object),
            "feature_statistics.csv", row.names = FALSE)
}

函数查询

下面列出已核对源码中导出的 API，包括兼容接口与辅助函数。具体参数以安装版本的 R 帮助为准；例如运行 help("函数名", package = "massstat")。

展开导出函数列表

Heatmap, convert_dummy_variable, convert_mass_dataset2graph, cor_mass_dataset, dist_mass_dataset, massstat_conflicts, massstat_logo, massstat_packages, mutate_fc, mutate_p_value, pca_score_plot, pls, plsda, run_pca, scale_data, scale_data1, scale_data2, volcano_plot

包源码与参考文档 · 完整工作流

metpath — 通路与 feature 模块分析

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

文档核对版本: 1.0.10 · 2026-09-23

化合物层面的富集需要去重后的化合物 ID、对应物种的通路库和明确的筛选规则。KEGG ID 与 KEGG 资源对应，HMDB ID 与相容资源对应，不能直接用名称替代 ID。

enrich_kegg()、enrich_hmdb()、enrich_pathways() 提供相应富集接口，显式设置多重校正方法。enrich_kegg() 的背景来自传入的通路数据库，没有独立的 background 参数。如果实验需要以实际测到的化合物为背景，应构造并核验受限数据库，或采用可显式指定背景的方法，不能把完整数据库暗称为实测背景。

Feature 方法包括同位素注释、RT 分组、候选分配、活性评分、零分布和 perform_fpa()。它拓展对未充分鉴定 feature 的解释，但保留注释不确定性。模块结果是待验证假设，不能确认其中每个化合物或实际通路活性。柱状图、散点图和网络图用于展示相应结果。

功能范围

通路数据提取筛选、过度表达富集检验、富集图和网络、同位素/feature 分组及功能模块分析。

使用示例

# Requires your deduplicated IDs and a pathway_database object.
# enrichment <- metpath::enrich_kegg(
#   query_id = unique(selected_kegg_ids), query_type = "compound",
#   id_type = "KEGG", pathway_database = pathway_database,
#   method = "hypergeometric", p_adjust_method = "BH",
#   p_cutoff = 0.05, threads = 2
# )
help("perform_fpa", package = "metpath")

函数查询

下面列出已核对源码中导出的 API，包括兼容接口与辅助函数。具体参数以安装版本的 R 帮助为准；例如运行 help("函数名", package = "metpath")。

展开导出函数列表

annotate_isotope, annotate_metabolites_fpa, arrange, calculate_activity_score, calculate_activity_socre, calculate_centrality, calculate_redundance, compound_list, database_info, describtion, enrich_bar_plot, enrich_hmdb, enrich_kegg, enrich_metabolic_pathway, enrich_network, enrich_pathways, enrich_scatter_plot, filter, filter_pathway, gene_list, generate_null_activity_score_distribution, get_hidden_metabolites, get_pathway_class, group_peaks_rt, identify_metabolic_modules, metpath_conflicts, metpath_logo, metpath_packages, pathway_class, pathway_id, pathway_name, perform_fpa, plot_metabolic_module_fpa, plot_metabolic_network_fpa, reference_list, related_disease, related_module, remove_redundancy, score_peak_group

包源码与参考文档 · 完整工作流

masstools — 分子式、谱图与 ID 工具

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

文档核对版本: 0.99.1 · 2026-09-23

masstools 提供其他包共用的辅助工具：分子式校验与质量计算、加合物处理、m/z–RT 匹配、谱图读取转换、去噪及匹配分数。存在同名函数时使用包命名空间。

中性精确质量不是实测前体 m/z，应按离子/加合物和电荷正确转换。谱图相似度受容差、强度处理和碎片覆盖影响，分数本身不等于鉴定。

ID 转换依赖上游服务，保留输入、输出、服务及失败记录，使用结构标识核验一对多映射。LLM 或其他远程服务接口为可选功能，需要配置；生成的 ID 必须独立核验后才能用于注释或富集。

功能范围

分子式与加合物操作、质量转换、谱图解析转换与相似度、m/z–RT 匹配、ID 服务及化合物分类查询。

使用示例

masstools::calculate_mass("C6H12O6", which = "exact_mass")
help("convert_precursor_mz2accurate_mass", package = "masstools")
help("read_mgf", package = "masstools")
help("calculate_spectra_match_score", package = "masstools")

函数查询

下面列出已核对源码中导出的 API，包括兼容接口与辅助函数。具体参数以安装版本的 R 帮助为准；例如运行 help("函数名", package = "masstools")。

展开导出函数列表

build_progress_table, calculate_dot_product, calculate_mass, calculate_spectra_match_score, check_adduct_formula, check_chemical_element, check_chemical_formula, combine_formula_adduct, convert_metabolite_id, convert_metabolite_id_chemspider, convert_metabolite_id_oliver, convert_metabolite_id_openai, convert_precursor_mz2accurate_mass, deduplicate_names, detect_os, df_to_spectra, getDP, getSpectraMatchScore, get_compound_class, get_dp, get_os, get_spectra_match_score, keep_best_match, keep_one, list_masstools_packages, list_metabolite_id_systems, masstools_logo, masstools_packages, match_mz_rt, ms2Match, ms2_match, ms2_plot, mz_rt_match, name_duplicated, parse_chemical_formula, plot_ms2, read_mgf, read_mgf4database, read_mgf_database, read_mzxml, removeNoise, remove_noise, report_conflicts, request_chemspider_metabolite, request_metabolite_id_systems, retrieve_chemspider_metabolite, retrieve_compound_class, show_progresser, spectra_to_df, split_formula, sum_formula, trans_ID

包源码与参考文档 · 完整工作流

MetNormalizer — 使用独立归一化流程

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

文档核对版本: 1.3.02 · 2026-09-23

MetNormalizer 是官网包目录列出的独立 QC 归一化工具，其文件式 metNor() 接口不同于 masscleaner::normalize_data()。必须准备对应格式，不能直接把它替换进 mass_dataset 流程。

按包示例准备 MS1 表和样品信息 CSV，包含所需 QC 与采集信息。在独立目录中检查过滤比例和优化参数，运行后查看归一化数据与诊断结果，保留原始输入和设置。

当前接口中 multiple = 1 使用基于进样顺序的 SVR，更大的值使用相关峰，应根据采集与研究设计选择。新的对象式 TidyMass 流程通常可以直接采用 masscleaner 的归一化入口。

功能范围

输入校验与独立的 QC/SVR 归一化流程。

使用示例

# Requires MetNormalizer-format CSV files in normalization_input/.
# MetNormalizer::metNor(
#   ms1.data.name = "data.csv",
#   sample.info.name = "sample.info.csv",
#   path = "normalization_input", optimization = TRUE,
#   multiple = 1, threads = 2
# )
help("metNor", package = "MetNormalizer")

函数查询

下面列出已核对源码中导出的 API，包括兼容接口与辅助函数。具体参数以安装版本的 R 帮助为准；例如运行 help("函数名", package = "MetNormalizer")。

展开导出函数列表

MetNormalizer_logo, checkData, metNor

包源码与参考文档 · 完整工作流

完整 LC-MS 分析工作流

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

这份模板连接原始处理、探索、清洗、统计、注释和通路分析。每个环节都保留输出，不把程序执行成功当作科学结论得到验证。所有数据路径、组名和示例阈值都需要按研究修改。

下载完整 R 脚本。代码为自己的真实输入准备，不包含虚构实验结果；原始数据处理和数据库步骤需有相应文件。

# TidyMass LC-MS workflow template. Reviewed 2026-09-23.
# Replace paths/groups and review every analysis choice before execution.
# This script does not contain study data or claim validated instrument parameters.
library(tidymass)
library(dplyr)

1. 准备数据与原始处理

示例从正离子 mzML/mzXML 开始，负离子模式另建分析。样品表至少有 sample_id、group、class；QC 使用定量 QC，研究样品用 Subject。路径中 QC/Subject 子目录的文件名去扩展名后必须唯一。参数只是起点，先在代表性文件上验证。

# 1. Inputs and raw processing -------------------------------------------------
raw_dir <- "analysis/MS1"                 # mzML/mzXML in QC/Subject subdirectories
sample_csv <- "analysis/sample_info.csv"
output_dir <- "analysis/results"
control_group <- "Control"
case_group <- "Treatment"
dir.create(output_dir, recursive = TRUE, showWarnings = FALSE)
stopifnot(dir.exists(raw_dir), file.exists(sample_csv))
writeLines(capture.output(sessionInfo()), file.path(output_dir, "sessionInfo.txt"))
set.seed(20260923)
massprocesser::process_data(
  path = raw_dir, polarity = "positive",
  ppm = 15, peakwidth = c(5, 30), snthresh = 10,
  threads = 2, min_fraction = 0.5, fill_peaks = FALSE,
  output_tic = TRUE, output_bpc = TRUE
)
result_file <- file.path(raw_dir, "Result", "object")
stopifnot(file.exists(result_file))
saved <- new.env()
load(result_file, envir = saved)
objects <- mget(ls(saved), envir = saved)
keep <- vapply(objects, function(x) inherits(x, "mass_dataset"), logical(1))
stopifnot(sum(keep) == 1L)
object <- objects[[which(keep)]]

2. 匹配样品信息与探索

按精确 ID 对齐样品信息，不按原表行号。示例从原始结果提取矩阵后重新构建带元数据的对象，因此务必保留原处理目录及原对象以保存原始处理记录。检查样品/feature 数、缺失值、RT 和 QC。

# 2. Match metadata and inspect ------------------------------------------------
si <- read.csv(sample_csv, check.names = FALSE, stringsAsFactors = FALSE,
               colClasses = "character")
stopifnot(all(c("sample_id", "group", "class") %in% names(si)),
          !anyNA(si$sample_id), !anyDuplicated(si$sample_id))
ids <- colnames(massdataset::extract_expression_data(object))
stopifnot(setequal(ids, si$sample_id))
si <- si[match(ids, si$sample_id), , drop = FALSE]
if ("injection.order" %in% names(si)) {
  si$injection.order <- as.numeric(si$injection.order)
  stopifnot(!anyNA(si$injection.order))
}
# Reconstruct with the matched metadata before attaching MS2/annotations.
object <- massdataset::create_mass_dataset(
  expression_data = massdataset::extract_expression_data(object),
  sample_info = si,
  variable_info = massdataset::extract_variable_info(object)
)
saveRDS(object, file.path(output_dir, "01-imported.rds"))
massdataset::show_sample_missing_values(object)
massdataset::show_variable_missing_values(object)
# Optional report, with a working report-rendering environment:
# massqc::massqc_report(object, path = file.path(output_dir, "qc_before"), type = "html")

3. 过滤、填补与归一化

示例保留至少一个比较组中缺失不超过 50% 的 feature；有 QC 时再加 QC 缺失不超过 20% 的条件。这是明确写出的示例规则，不是默认科学标准。它移除 Blank 后做中位数填补与归一化。QC 漂移校正、异常样品删除和跨批次整合需要按设计另行决定。

# 3. Filter, impute and normalize ---------------------------------------------
# Illustrative criteria; revise and document for your study.
expr <- massdataset::extract_expression_data(object)
ctrl <- si$sample_id[si$class == "Subject" & si$group == control_group]
case <- si$sample_id[si$class == "Subject" & si$group == case_group]
qc <- si$sample_id[si$class == "QC"]
stopifnot(length(ctrl) >= 3L, length(case) >= 3L)
keep_feature <- rowMeans(is.na(expr[, ctrl, drop = FALSE])) <= 0.5 |
                rowMeans(is.na(expr[, case, drop = FALSE])) <= 0.5
if (length(qc) > 0L) {
  keep_feature <- keep_feature & rowMeans(is.na(expr[, qc, drop = FALSE])) <= 0.2
}
write.csv(data.frame(variable_id = rownames(expr), keep = keep_feature),
          file.path(output_dir, "filter_decisions.csv"), row.names = FALSE)
# Exclude blanks from the illustrative normalized matrix.
stopifnot(any(keep_feature))
object <- object[which(keep_feature), si$sample_id[si$class %in% c("Subject", "QC")]]
stopifnot(nrow(object) > 1L)
cleaned <- masscleaner::impute_mv(object, method = "median")
normalized <- masscleaner::normalize_data(cleaned, method = "median")
saveRDS(normalized, file.path(output_dir, "02-normalized.rds"))
# For QC-based SVR/LOESS, first verify quantitative QC coverage and metadata.
# Review outliers/batches with acquisition records; do not remove PCA outliers blindly.

4. PCA 与独立组间统计

PCA 仅用研究样品，并去除非有限值或零方差 feature，使用均值中心化与单位方差缩放；fold change 和检验使用未缩放的归一化值。该代码是独立组 t 检验及 BH 校正，不适用于未调整的重复测量设计。配对数据应先对齐个体，并选择相应检验或模型。

# 4. PCA and independent-group statistics ------------------------------------
# Keep scaled values out of fold-change calculation.
expr <- massdataset::extract_expression_data(normalized)
biological <- c(ctrl, case)
expr <- expr[, biological, drop = FALSE]
valid <- apply(expr, 1, function(x) all(is.finite(x)) && stats::sd(x) > 0)
stopifnot(sum(valid) >= 2L)
pca <- stats::prcomp(t(expr[valid, , drop = FALSE]), center = TRUE, scale. = TRUE)
write.csv(pca$x, file.path(output_dir, "pca_scores.csv"))
stats_object <- massstat::mutate_fc(normalized, ctrl, case, mean_median = "mean")
stats_object <- massstat::mutate_p_value(stats_object, ctrl, case,
  method = "t.test", p_adjust_methods = "BH")
feature_stats <- massdataset::extract_variable_info(stats_object)
write.csv(feature_stats, file.path(output_dir, "feature_statistics.csv"), row.names = FALSE)
saveRDS(stats_object, file.path(output_dir, "03-statistics.rds"))

5. 关联 MS2 与注释

提供实验 MS2 目录和 metid databaseClass。关闭不相容参考 RT 的匹配和分数权重。保留候选表，检查镜像谱、质量误差与歧义。没有所需输入时明确跳过，不生成假注释。统计与注释可分别完成，但进入通路前应综合其证据。

# 5. Attach MS2 and annotate ---------------------------------------------------
# Replace these paths and run this block when these resources are available.
ms2_dir <- "analysis/MS2"
reference_rds <- "analysis/reference_database.rds"
if (dir.exists(ms2_dir) && file.exists(reference_rds)) {
  with_ms2 <- massdataset::mutate_ms2(stats_object, path = ms2_dir,
    column = "rp", polarity = "positive",
    ms1.ms2.match.mz.tol = 15, ms1.ms2.match.rt.tol = 30)
  database <- readRDS(reference_rds)
  stopifnot(inherits(database, "databaseClass"))
  annotated <- metid::annotate_metabolites_mass_dataset(
    object = with_ms2, database = database, polarity = "positive", column = "rp",
    ms1.match.ppm = 15, ms2.match.ppm = 30,
    rt.match.tol = NA, rt.match.weight = 0, candidate.num = 3, threads = 2)
  saveRDS(annotated, file.path(output_dir, "04-annotated.rds"))
  write.csv(massdataset::extract_annotation_table(annotated),
    file.path(output_dir, "annotation_candidates.csv"), row.names = FALSE)
} else {
  message("Annotation not run: provide experimental MS2 and a compatible reference database.")
}

6. 候选审查后的通路分析

依据预先确定的统计筛选与注释审查，准备去重的 kegg_id 列表。多个加合物不能当作多个化合物。示例的富集背景是传入数据库覆盖的化合物，不自动等于本实验测到的化合物；如需实测背景，先明确构造并验证相应数据库。没有 ID/数据库时明确跳过。

# 6. Pathway analysis after candidate review ----------------------------------
# Prepare reviewed_kegg_ids.csv with one KEGG ID per row in a kegg_id column.
# Select using the prespecified statistical rule and reviewed annotation evidence.
# Do not count multiple features/adducts as independent compounds.
query_csv <- "analysis/reviewed_kegg_ids.csv"
pathway_rds <- "analysis/pathway_database.rds"
if (file.exists(query_csv) && file.exists(pathway_rds)) {
  query <- read.csv(query_csv, colClasses = "character")
  stopifnot("kegg_id" %in% names(query))
  query_ids <- unique(query$kegg_id[!is.na(query$kegg_id) & nzchar(query$kegg_id)])
  stopifnot(length(query_ids) > 0L, all(grepl("^C[0-9]{5}$", query_ids)))
  pathway_database <- readRDS(pathway_rds)
  enrichment <- metpath::enrich_kegg(query_id = query_ids, query_type = "compound",
    id_type = "KEGG", pathway_database = pathway_database,
    p_adjust_method = "BH", method = "hypergeometric", p_cutoff = 0.05, threads = 2)
  saveRDS(enrichment, file.path(output_dir, "05-pathway-enrichment.rds"))
  # Background is defined by the supplied pathway database, not automatically by measured compounds.
} else {
  message("Pathway analysis not run: provide reviewed compound IDs and a pathway database.")
}

7. 导出与复现

保存脚本、参数、样品表、原始文件、数据库来源/版本、R 对象、统计表、候选表和 sessionInfo。RDS 结果不会自动携带所有外部输入。公开结果时说明分析方法、样品范围、过滤阈值、缺失处理、比较方向、校正方法、鉴定证据及通路背景。

# 7. Archive -----------------------------------------------------------------
writeLines(capture.output(sessionInfo()), file.path(output_dir, "sessionInfo.txt"))
# Back up this script, parameter choices, all inputs/reference versions and all results.