R package user guide | TidyMass

Installation and versions

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

Prepare R

This guide checks tidymass 2.0.10 and the current source of its companion packages. Some packages declare R 4.1 as a minimum, but current masstools requires R ≥ 4.5. Use R 4.5 or a later compatible release satisfying the full dependency set, with a writable user library and your preferred IDE.

Source compilation on Windows needs a toolchain matching R; macOS may need command-line development tools and package-specific system libraries. Diagnose the first substantive installation error before adding dependencies. Docker/ProteoWizard is an additional requirement for relevant raw-format conversion, not for reading an existing peak table.

Install

The commands use official GitHub sources. Dependency metadata can also reference GitLab and Bioconductor, so those sources must be reachable. Installation accesses the network and may compile packages.

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()

Record versions and diagnose problems

Restart R, load tidymass, and inspect packageVersion(), .libPaths() and sessionInfo(). The umbrella version is not the version of every companion package. Use package::function() to resolve overlapping function names.

Run tidymass::check_tidymass_version(packages = "all") to inspect updates and update_tidymass() only when you intend to upgrade. Mirrors can differ and network failures can leave version information incomplete. Preserve a lockfile/environment record and analysis code before upgrading an active or published project, then validate the new environment.

Begin an analysis

Learn the data structure in massdataset or follow the complete workflow for raw files. Each package chapter gives its scope, an example and its exported API. Run data-dependent examples only after preparing the specified inputs. Example parameters are not a validated universal method.

tidymass — Install and manage the ecosystem

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

Version checked for this guide: 2.0.10 · 2026-09-23

tidymass installs and attaches a coordinated set of packages. It does not replace their individual functions. Start here to inspect the package set, detect namespace conflicts and record versions. Load extra packages such as massdatabase and massconverter explicitly when needed.

Use a fresh R session for installation or updates. Save the old project’s package versions before upgrading, restart R afterwards and rerun a representative analysis. A successful update check is not a guarantee that every remote repository was reachable.

Functional scope

Package discovery; conflict reporting; version checks; coordinated updates.

Example

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")

Find a function

The checked source exports the following APIs, including compatibility interfaces and utilities. Consult the installed version with help("function_name", package = "tidymass") for argument details.

Show exported functions

check_tidymass_version, tidymass_conflicts, tidymass_logo, tidymass_packages, update_tidymass

Package source and reference documentation · Complete workflow

massdataset — Create, inspect and exchange datasets

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

Version checked for this guide: 0.99.3 · 2026-09-23

The central mass_dataset combines an expression matrix, sample information, feature information, optional MS2, annotation tables and processing history. Rows of the matrix are features; columns are samples. Its identifiers and ordering must match the metadata.

For your data, read the three tables, preserve IDs as text, place numeric intensities in the expression matrix, and align its columns/rows to sample/feature IDs before calling create_mass_dataset(). The example below uses package data to demonstrate the contract. Use activate_mass_dataset() before a tidy transformation to state whether sample or feature metadata is being edited.

Import MS2 with mutate_ms2() after checking polarity, RT units and precursor/RT tolerances. Use extraction functions to obtain ordinary tables, export_mass_dataset() for interchange and RDS to retain the full R object. Converters support documented MS-DIAL/MZmine, mzTab and SummarizedExperiment routes; inspect their input-specific requirements rather than treating every CSV as interchangeable.

Functional scope

Dataset construction and validation; sample/feature editing, filtering, joins and merges; MS2 import and export; annotation and history access; missingness/RSD summaries; data-format conversion.

Example

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")

Find a function

The checked source exports the following APIs, including compatibility interfaces and utilities. Consult the installed version with help("function_name", package = "massdataset") for argument details.

Show exported functions

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

Package source and reference documentation · Complete workflow

massconverter — Convert vendor files

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

Version checked for this guide: 1.0.3 · 2026-09-23

Use massconverter to configure a ProteoWizard/msconvert conversion workflow and convert vendor files into open formats. It is separate from chromatographic peak detection. Successful conversion depends on the vendor reader, platform, container and access to the source directory.

Choose mzML/mzXML, centroiding method, polarity and MS levels deliberately. Preserve MS2 when later annotation needs it. Keep the original acquisition files. First convert one file, then inspect scan counts, RT range, polarity and TIC before batching. Vendor centroiding is only available where the reader supports it; a container does not make every vendor format universally compatible.

The example builds a parameter object; the commented call performs file conversion after you configure Docker/ProteoWizard and replace paths.

Functional scope

Conversion parameter creation and validation; command generation; container preparation; batch file conversion.

Example

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
# )

Find a function

Show exported functions

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

Package source and reference documentation · Complete workflow

massprocesser — Detect peaks and align samples

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

Version checked for this guide: 1.0.11 · 2026-09-23

Start with converted mzML/mzXML files in a dedicated processing directory, normally grouped into sample-type subdirectories such as QC and Subject. Run positive and negative modes separately. process_data() performs raw-data processing and writes outputs under Result.

Set ppm from instrument performance, peakwidth in seconds from chromatography, and signal/noise, prefilter and noise using representative files. bw and min_fraction affect across-sample grouping. fill_peaks controls chromatographic gap filling, not statistical imputation. Reduce threads when memory is limiting.

Review TIC/BPC, RT correction, the peak table and extracted EICs. Preserve intermediate files if later inspection requires them. The parameter values below are an example, not a validated method for your instrument. Inspect output files after the call; do not assume its return value is the final dataset.

Functional scope

Raw processing; EIC extraction; chromatogram visualization; adjusted-RT visualization; targeted-table validation.

Example

# 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")

Find a function

Show exported functions

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

Package source and reference documentation · Complete workflow

masscleaner — Filter, impute and normalize

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

Version checked for this guide: 1.0.12 · 2026-09-23

Begin with a validated mass_dataset and sample classes, batches and injection order. Filter excessive missingness before imputation. Review outlier candidates with experimental records, rather than automatically deleting every unusual PCA sample.

impute_mv() offers kNN, random forest, simple-value and model-based methods. Choose the method and sample subset based on the missingness mechanism and data size. normalize_data() provides sample-wise total, mean, median and PQN methods and QC-based SVR/LOESS. QC correction needs suitable QC coverage and acquisition metadata. integrate_data() and align_batch() address supported cross-batch tasks; they do not resolve a design in which batch and biological group are completely confounded.

Preserve the input object, inspect missingness and QC metrics afterwards and compare before/after plots. For predictive modeling, fit preprocessing within each training fold to avoid leakage. The example uses median imputation and median normalization only to illustrate the API.

Functional scope

Outlier detection and reporting; missing-value imputation; sample-wise/QC-based normalization; LOESS optimization; batch alignment and integration.

Example

# 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")

Find a function

Show exported functions

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

Package source and reference documentation · Complete workflow

massqc — Assess and report quality

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

Version checked for this guide: 1.0.8 · 2026-09-23

Quality assessment is useful before and after cleaning. Give massqc a mass_dataset with correct sample classes, batches and injection order. Generate a report into a new output directory and retain the object used to create it.

Review missingness by sample and feature, intensity distributions, QC RSD, correlations and PCA. A QC RSD needs actual quantitative QC replicates. A low RSD does not establish metabolite identity, and an unusual PCA point may represent biology. Report which input state was assessed: imputation and normalization affect the metrics.

HTML reporting requires the report-rendering dependencies available in your R environment; PDF adds its document toolchain. If rendering fails, inspect the log and produce individual diagnostic plots while resolving the missing renderer.

Functional scope

HTML/PDF reports; sample and feature missingness; m/z–RT distributions; RSD curves; intensity boxplots; PCA and sample correlations.

Example

# 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)

Find a function

The checked source exports the following APIs, including compatibility interfaces and utilities. Consult the installed version with help("function_name", package = "massqc") for argument details.

Show exported functions

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

Package source and reference documentation · Complete workflow

massdatabase — Retrieve and build reference resources

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

Version checked for this guide: 1.0.14 · 2026-09-23

massdatabase retrieves, parses and converts compound, spectrum and pathway resources. It is not itself one universal metabolite database. Choose the source and the identifier system needed by your next analysis.

A typical spectral route downloads a source library, reads its documented MSP/XML/SDF format and converts it into a metid database. A pathway route downloads organism-specific KEGG or another supported resource, reads it and converts it into a metpath object. Preserve the original resource, retrieval date, organism, conversion parameters and source version.

The exported API includes KEGG, HMDB, MassBank, MoNA, GNPS, PubChem, ChEBI, LipidMaps, FooDB, BiGG, SMPDB, Reactome and WikiPathways-related tasks; different sources provide different combinations of download/read/request/convert functions. Network services and file schemas can change. A failed request is not evidence that a metabolite is absent. Inspect source terms and database coverage before redistributing a derived database.

Functional scope

Source-specific web requests and downloads; spectrum/compound/pathway parsers; conversion to metid and metpath; identifier and source utilities.

Example

# 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")

Find a function

Show exported functions

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

Package source and reference documentation · Complete workflow

metid — Annotate features and inspect spectra

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

Version checked for this guide: 1.3.2 · 2026-09-23

metid matches precursor masses, compatible RT and available MS2 against a databaseClass. Import or construct the reference database and attach experimental MS2 to your mass_dataset first. Check ion polarity, chromatography and adduct settings.

The current API includes annotate_metabolites_mass_dataset() alongside established metIdentify* and mzIdentify* interfaces. Do not mix argument names from different interfaces. The example explicitly disables RT evidence for a reference whose chromatography is not comparable. Review tolerances against your instrument; these values are illustrative.

Inspect all candidate evidence, not just a top score. An MS1 candidate is not a confirmed structure. An in-house database can support stronger identification when standards and measurements meet the actual evidence criteria; the database’s name alone does not establish confidence. Retain ambiguous candidates and record any filtering or adduct de-duplication. Origin annotations report database associations, not direct evidence of synthesis in your sample.

Functional scope

Database construction and validation; MS1/MS2 annotation; single-peak queries; matching scores and mirror spectra; confidence/candidate/adduct filtering; origin summaries.

Example

# 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")

Find a function

The checked source exports the following APIs, including compatibility interfaces and utilities. Consult the installed version with help("function_name", package = "metid") for argument details.

Show exported functions

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

Package source and reference documentation · Complete workflow

massstat — Explore variation and compare groups

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

Version checked for this guide: 1.0.6 · 2026-09-23

Use an appropriately cleaned dataset and a prespecified comparison. Keep QC/Blank samples out of biological hypothesis tests. Use transformations and scaling for the purpose at hand: PCA scaling does not mean fold changes should be calculated from scaled values.

run_pca() returns a PCA model; pca_score_plot() visualizes scores. mutate_fc() calculates case/control fold change using a mean or median summary. mutate_p_value() supports t and Wilcoxon tests and adds multiple-testing adjusted results. Match paired samples explicitly before a paired test. The example is an independent-group comparison and takes its group labels from sample metadata. These massstat interfaces require at least three samples per comparison group.

Additional functions cover heatmaps, correlations, distances, graph conversion, PLS and PLS-DA. Supervised separation on training data is not predictive validation: use appropriate held-out or nested validation and avoid selecting features before splitting the data.

Functional scope

PCA and scaling; fold change and hypothesis tests; volcano plots and heatmaps; correlations, distances and graphs; PLS/PLS-DA.

Example

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)
}

Find a function

The checked source exports the following APIs, including compatibility interfaces and utilities. Consult the installed version with help("function_name", package = "massstat") for argument details.

Show exported functions

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

Package source and reference documentation · Complete workflow

metpath — Analyze pathways and feature modules

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

Version checked for this guide: 1.0.10 · 2026-09-23

For compound-level enrichment, prepare de-duplicated compound IDs, a pathway database for the organism and an explicit selection rule. Match KEGG IDs to KEGG resources and HMDB IDs to compatible resources; human-readable names are not a substitute for these identifiers.

enrich_kegg(), enrich_hmdb() and enrich_pathways() support the documented pathway enrichment interfaces. Specify the adjustment method instead of silently accepting a default. In enrich_kegg(), the background derives from the supplied pathway database; the interface does not expose a separate background argument. If your experiment requires a measured-compound universe, construct and verify an appropriately restricted database or use a method with an explicit universe. Do not silently report the full database as the measured background.

Feature-based functionality includes isotope annotation, RT grouping, candidate assignment, activity scoring, null distributions and perform_fpa(). It extends analysis beyond confidently annotated compounds while retaining annotation uncertainty. Such modules are hypotheses, not confirmation of every compound or pathway activity. Bar, scatter and network displays summarize supported results.

Functional scope

Pathway data access/filtering; over-representation tests; enrichment plots/networks; isotope/feature grouping and functional module analysis.

Example

# 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")

Find a function

The checked source exports the following APIs, including compatibility interfaces and utilities. Consult the installed version with help("function_name", package = "metpath") for argument details.

Show exported functions

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

Package source and reference documentation · Complete workflow

masstools — Work with formulas, spectra and IDs

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

Version checked for this guide: 0.99.1 · 2026-09-23

masstools supplies utilities shared by other packages: formula checks and masses, adduct handling, m/z–RT matching, spectrum input/conversion, noise removal and matching scores. Call with the package namespace when names overlap.

A calculated neutral exact mass is not the measured precursor m/z. Choose the correct ion/adduct conversion and check charge. Spectrum similarity depends on tolerance, intensity treatment and the available fragments; a score alone is not identification.

ID-conversion helpers depend on their upstream providers. Preserve input, output, service and failures, and verify one-to-many mappings against structure identifiers. Functions that use an LLM or another remote service are optional and require configuration; generated IDs need independent verification before annotation or enrichment.

Functional scope

Formula and adduct operations; mass conversion; spectrum parsing, conversion and similarity; m/z–RT matching; ID services and compound-class lookup.

Example

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")

Find a function

Show exported functions

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

Package source and reference documentation · Complete workflow

MetNormalizer — Use the standalone normalization workflow

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

Version checked for this guide: 1.3.02 · 2026-09-23

MetNormalizer is the standalone QC-based normalization package linked from the TidyMass package catalogue. Its file-based metNor() interface is different from masscleaner::normalize_data() and should not be substituted into a mass_dataset pipeline without preparing its input format.

Prepare the MS1 table and sample-information CSV according to the package example, including the required QC and acquisition metadata. Work in a dedicated directory, review filtering fractions and optimization settings, then inspect the saved normalized data and diagnostics. Preserve the input and method settings.

multiple = 1 uses injection-order-based SVR in the documented interface; larger values use correlated peaks. Choose according to acquisition and study design, not simply because a larger value looks more powerful. For a new object-based TidyMass workflow, masscleaner usually provides the direct integration point.

Functional scope

Input checks and a standalone QC/SVR normalization workflow.

Example

# 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")

Find a function

The checked source exports the following APIs, including compatibility interfaces and utilities. Consult the installed version with help("function_name", package = "MetNormalizer") for argument details.

Show exported functions

MetNormalizer_logo, checkData, metNor

Package source and reference documentation · Complete workflow

Complete LC-MS analysis workflow

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

This template connects raw processing, exploration, cleaning, statistics, annotation and pathway analysis while saving intermediate outputs. Successful execution is not scientific validation. Replace all paths and group labels and review the example thresholds for your study.

Download the complete R script. It is designed for your real inputs and contains no fabricated study results; raw processing and database stages require the indicated files.

# 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. Prepare inputs and process raw files

The example starts with positive-mode mzML/mzXML; analyze negative mode separately. The sample sheet needs sample_id, group and class; use Subject for biological samples and QC only for quantitative QCs. Basenames in the QC/Subject directories must be unique. Validate example processing parameters on representative files first.

# 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. Match metadata and explore

Align metadata by exact sample ID, not row position. This example reconstructs the object after extracting the raw-processing matrix; retain the original processing directory and object to preserve the original provenance. Inspect sample/feature counts, missingness, RT and QCs.

# 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. Filter, impute and normalize

The explicit example retains a feature if missingness is at most 50% in either comparison group and, when QCs exist, at most 20% in QCs. These are example criteria, not a universal standard. It removes blanks before median imputation and normalization. Decide QC drift correction, outlier exclusions and cross-batch integration from your actual design.

# 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 and independent-group statistics

PCA uses biological samples, removes nonfinite or zero-variance features, and uses mean centering/unit-variance scaling. Fold changes and tests use unscaled normalized intensities. The code uses an independent-group t test with BH correction; it is not an unadjusted repeated-measures analysis. Align subjects and choose the appropriate paired test or model for paired observations.

# 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. Attach MS2 and annotate

Provide experimental MS2 and a metid databaseClass. The example disables incompatible reference RT matching and scoring. Preserve candidates and inspect mirror spectra, mass errors and ambiguity. Missing resources cause an explicit skip, not invented annotations. Statistics and annotation can be performed separately, then combined when preparing pathway inputs.

# 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. Analyze pathways after candidate review

Prepare a de-duplicated kegg_id list using your prespecified statistical selection and reviewed annotations. Multiple adducts are not independent compounds. The example enrichment background is the supplied database coverage, not automatically the compounds measured by your experiment. Construct and verify a suitable restricted database when a measured universe is required. Missing resources cause an explicit skip.

# 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. Archive for reproduction

Archive the script, parameters, sample sheet, raw files, reference provenance/versions, objects, statistical/candidate tables and sessionInfo. An RDS does not include every external input. Report sample selection, filters, missingness handling, comparison direction, correction, identification evidence and pathway background.

# 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.