R shiny user guide | TidyMass

Install or access R Shiny

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

Based on the current published tutorial and the public tidymassshiny 1.0.0 source; checked September 23, 2026.

Choose where to run

The hosted application runs on a remote server. The published guide describes a 512 MB upload limit and deletion of results after 24 hours; these are service settings and can change. Follow the notices shown by the running service, save the JOB ID, and download results with Download All Data before leaving.

A local installation runs R on your computer and provides access to your local files. Docker runs the app in a container; only mounted host folders are visible there. Choose a local or appropriately managed server installation for data that should not be uploaded to the public service.

Install the R package

Use an R version compatible with all dependencies. Although the app declares R ≥ 4.1, current companion packages can require R ≥ 4.5. Run the following in a writable R library. Repository dependencies can also require GitLab, CRAN and Bioconductor access.

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

Wait for the listening address and open the application in your browser. Keep the R process running. Check packageVersion("tidymassshiny") and retain sessionInfo() when reporting a problem. Install missing optional module dependencies from their correct source rather than assuming every toolkit ships with the core app.

On macOS, a Cairo/X11 error can require XQuartz and the appropriate Cairo setup. Follow the actual error; a failure compiling a system library is not repaired by repeatedly reinstalling unrelated R packages.

Docker

Install and start Docker. Replace the host directory below with your own existing data folder:

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

Open http://localhost:3838 after startup. Inside the app, select the mounted /home path. On Windows, use the actual drive path and Docker’s supported volume syntax. Verify Docker has access to the directory. Record the resolved image digest for reproducibility because the latest tag can move.

Managed server

For a shared server, use a supported R/Shiny Server environment, an application service account, persistent working directories and the required R/system dependencies. Configure authorized users’ file access, resource limits and the public endpoint with the administrator. A shinyFiles picker sees the filesystem of the R server, not arbitrary folders on a remote browser user’s computer. Upload controls are the route for transferring browser-side files.

The older tutorial includes Ubuntu-specific deployment examples. Check their suitability for your server instead of copying obsolete OS repository keys or version-pinned installer URLs blindly.

Original tutorial and screenshots

Create a project and import data

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

Based on the current published tutorial and the public tidymassshiny 1.0.0 source; checked September 23, 2026.

Initialize a project

Choose a working directory, upload sample_info.csv, map its columns when necessary, then click Initialize Project. Inspect the resulting sample information. IDs must match the intensity columns or raw filenames exactly; distinguish biological group, sample class, batch and acquisition order.

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

This is a format example, not sufficient replication for an experiment. Keep positive and negative measurements distinguishable and preserve leading zeros in IDs.

Start with MS files

Convert vendor files to suitable mzML/mzXML first. Vendor reader availability depends on the converter and platform. Organize MS1 files into the documented sample-type folders, such as QC and Subject.

Open Data import → Start with MS file, choose SELECT MS1 FOLDER, and click CHECK INPUT FILE. Review ppm, peakwidth, snthresh, noise and threads. A parameter optimization option is an aid; inspect resulting EICs and alignment to judge suitability. Start peak picking once inputs and parameters are correct, and wait for completion without launching the same operation repeatedly.

For the hosted version, use its upload workflow, package MS files as the required ZIP, then Process MS1 Files to unpack/process the upload. A local-directory picker is not a substitute for uploading to a remote server.

Start with a peak table

Open Start with table file and choose the CSV. The current source allows mapping the feature ID, m/z, RT and ion columns; the initial mapping uses the first four columns. A compatible template is:

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

Use pos/neg or the supported polarity labels. Set Retention time in correctly: minutes are converted to seconds. Map the four metadata columns explicitly if your names/order differ. Keep all remaining columns as numeric sample intensities and ensure they match the initialized sample sheet.

Click Input file summary and check matching, polarity, sample counts and feature counts before Generate massdataset object. Inspect the separate positive/negative outputs. An extra text annotation column can be mistaken for intensity input, so remove or import it through the appropriate annotation route.

Start with an existing object

Choose Start with mass_dataset file, load the positive and negative objects into their respective controls, and use Check input. A CSV is not an R object merely because its extension is changed. Keep the original object and its package-version record.

The screenshot is from the existing published Shiny tutorial; minor visual details can differ across deployments.

Original tutorial and screenshots

Assess quality and clean data

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

Based on the current published tutorial and the public tidymassshiny 1.0.0 source; checked September 23, 2026.

Generate an overview

Open Overview and click START. Review m/z–RT distribution, missingness by sample/feature, QC RSD, intensity distributions, PCA and sample correlations. Select the relevant group, batch or injection-order coloring and download plots with their settings.

QC RSD describes technical repeatability where suitable quantitative QCs exist. Matrix intensity totals are not automatically raw TIC. Investigate suspicious samples against acquisition records before excluding them.

Remove noisy features

Choose QC and biological-group missingness cutoffs, run the filtering step and inspect its retained feature count and missingness plots. The existing tutorial’s 20% QC / 50% group examples are adjustable choices, not universal cutoffs. Do not activate a QC-dependent condition when quantitative QCs are absent. Confirm how group criteria are combined in the installed module.

Review outlier samples

Generate missingness/PCA displays. By tidymass offers the documented missingness, PC SD, PC MAD and distance-based strategies; By myself permits explicit selections. Review candidate IDs and experimental reasons, then run the exclusion operation. Preserve both the original object and your exclusion decisions.

Impute missing values

Choose a method and inspect its parameter panel. kNN uses neighbors and row/column missingness controls; random forest uses iteration/tree controls; PPCA uses component and convergence settings. maxp in kNN concerns the maximum block size used by the underlying algorithm, not a percentage. Record the seed when provided.

Click START, wait for completion and verify that the intended sample subset was processed. Avoid imputing a wholly unobserved feature as if it were supported quantitative evidence.

Normalize and integrate

Select a method appropriate to the experiment. SVR and LOESS require suitable QCs and acquisition information; PQN, median, mean and total are sample-wise approaches. Review keep_scale, optimization, reference and thread controls. Click Start analysis, then Show plot to inspect before/after results.

Record batch handling separately from normalization. No normalization method can rescue a completely confounded biological-group/batch design. Separately fitted PCAs should not be compared as a single unchanged coordinate system.

Save cleaned objects and diagnostic outputs before proceeding to annotation or statistics.

Original tutorial and screenshots

Annotation, statistics and enrichment

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

Based on the current published tutorial and the public tidymassshiny 1.0.0 source; checked September 23, 2026.

Attach experimental MS2

Choose Select MS2 folder and the prepared MGF files, separated by polarity. Set chromatography and precursor m/z/RT association tolerances, then click Start. Association tolerance links a spectrum to a feature; it is distinct from matching to a reference library.

Annotate metabolites

Place compatible reference databases in a dedicated directory and select Choose folder. Set MS1/MS2 tolerances, RT tolerance, candidate count, column and threads, then click Start annotation once. Watch the logs and wait for the task to finish.

MoNA, MassBank and HMDB are public resources, not automatically in-house standards. Use reference RT only for comparable chromatography. Inspect candidates and available spectral evidence before accepting a name. Software confidence labels require interpretation in light of the actual measurements; an MS1-only candidate does not become a confirmed structure by receiving a level label.

Filter annotations and inspect origins

Choose how to retain multiple candidates, handle redundant adducts and filter supported evidence levels. Use Adduct for level 3 annotation where appropriate and run START. Preserve the unfiltered candidates and the rule used to reduce them.

In Metabolites origin, use Check database, then Start. An UpSet view summarizes origin associations and intersections. Select a compound and Show network plot for its database relationships. These are reference associations, not demonstrated biosynthetic origins in your sample.

Differential analysis

Use Wake up object, choose the sample attribute and explicitly select the control/reference group. Run the comparison, then inspect PCA and volcano plots. Confirm fold-change direction and distinguish a raw P-value cutoff from FDR/adjusted P-value. Retain the full table, including nonsignificant features.

Use only the biological samples intended for the test. Do not infer pairing from row order. If the module cannot represent the study’s repeated measures or covariates, export the object and use the appropriate R model.

Pathway enrichment

Choose KEGG/HMDB or Upload custom database, verify the organism and ID system, and set the adjustment method, cutoff and threads. Inspect the bar/scatter plots and mapping coverage. Review candidate ambiguity, collapse redundant compound IDs and record the background used by the method. Enrichment is a statistical association with a reference set, not direct proof of pathway activation.

Screenshot from the existing published tutorial.

Original tutorial and screenshots

fMSEA, FPA and database toolkits

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

Based on the current published tutorial and the public tidymassshiny 1.0.0 source; checked September 23, 2026.

fMSEA

Open Tidymass shiny toolkits → fMSEA Analysis. Load the required R data files: a processed Feature Table, an MS1 Database (KEGG/HMDB as supported) and a Pathway Database. The published module lists KEGG, HMDB, IMETPD, Reactome and WikiPathways resources. Use the module’s demo/file schema, not an arbitrary renamed CSV.

Run Step 1: configure column, database type, MS1 ppm, RT clustering tolerance and isotope count. Inspect candidate assignment before enrichment. The tutorial examples use 15 ppm, 10 s and three isotopes; adapt them to your data.
Run Step 2: set threads, minimum/maximum pathway size, permutations, iterations and FDR threshold. The published defaults include 1,000 permutations and pathway sizes of 15–300; these are computational choices, not guaranteed optimal settings.
Select a row in Significant Modules Table to display its enrichment-score profile. Save full results and settings, not only a significant plot.

An existing compatible results object can be loaded for visualization without rerunning Steps 1–2. Feature-based enrichment preserves uncertainty from candidate assignment; it does not identify every contributing compound.

Optional LLM evaluation

The module offers matrix-relevance and literature-relevance evaluation. Configure the sample source or research topic and the selected provider’s API settings, then run the requested evaluation. This step is optional: a missing endpoint/key means it has not run. Do not substitute generated scores for statistical validation or verified literature evidence. Check what information is sent to the selected service before using private study details. Download evaluation results separately from the enrichment tables/PNG/PDF plots.

Feature-based pathway analysis (FPA)

Use the toolkit’s FPA entry with the required feature data, ion mode and compatible pathway/candidate resources. Review feature grouping, isotope/adduct assumptions, mass tolerance and the null/permutation settings offered by the installed module. Run, inspect contributing features and export the resulting modules with parameters. Consult the metpath guide for the R interfaces and interpretation. FPA and fMSEA are distinct analyses; their output scores are not interchangeable.

Construct an in-house metabolite database

Acquire standard compounds under conditions comparable to the study. Prepare metabolite metadata and MS2 according to metid’s database schema. In the toolkit, select the CSV with File Path, inspect Construction Parameters, then Build Database. Verify m/z, RT, names and spectra, assign a descriptive database identifier and use Download Database.

Put the resulting .rda in a dedicated annotation-database folder and select it during annotation. Saving an object with an in-house label does not replace verification of standards and acquisition conditions.

Build a species-specific KEGG database

Find the intended organism code, for example hsa or mmu, from KEGG’s organism list. Open KEGG Pathway Database Construction, use Set working directory, enter the code and a request interval (the tutorial uses at least one second), then Download pathway. Monitor network errors and resulting file paths. Verify that pathway IDs carry the intended species prefix before enrichment; preserve retrieval date and organism code.

Convert metabolite IDs

Select the provider under Convert Parameters, choose Source ID Type and Target ID Type, enter queries in Conversion Input and click Convert ID. Inspect failed and one-to-many mappings instead of silently dropping them. API-based services require their credentials. The experimental LLM conversion route may produce incorrect identifiers; verify structures/identifiers independently before using them in a database or pathway analysis.

Screenshot from the existing published tutorial.

Original tutorial and screenshots

Save results and solve problems

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

Based on the current published tutorial and the public tidymassshiny 1.0.0 source; checked September 23, 2026.

Save a complete analysis

Keep the initialized sample sheet, raw-file references, intermediate mass_dataset objects, cleaned and annotated objects, complete statistical/enrichment tables, figures and parameters. For local use, inspect the output directories reported by the app. For hosted use, record the JOB ID and Download All Data before the service retention window expires. Confirm the archive opens and contains the results you intended to keep.

When reopening compatible objects or fMSEA results, confirm which steps they represent. Changing a parameter does not retroactively regenerate a saved result. Preserve software/package versions and database provenance alongside the outputs.

Troubleshooting

Problem	Action
Folder picker cannot see my computer	A remote R process sees its server filesystem; use upload or run locally
Docker cannot find data	Check host-folder permissions and container mount; select the container path
Table sample mismatch	Compare exact IDs against the initialized sample sheet; remove non-intensity columns
Incorrect polarity or RT	Map the ion column and set minutes/seconds explicitly
Missing R package	Install from the correct source, inspect the first error and restart the app
Raw processing takes a long time	Inspect progress/logs, reduce threads if memory is limiting; avoid repeated Start clicks
No MS2 candidates	Check polarity, precursor/RT association, database type and matching tolerances
No enrichment results	Check ID mapping, organism, selection and background; an empty result can be valid
LLM evaluation fails	Verify the optional provider configuration; preserve the statistical results independently
A plot looks different after reloading	Confirm the saved object, selected sample groups and plotting settings

For a report, include app/package versions, local/Docker/hosted deployment, module, steps to reproduce, logs and a de-identified input example. Do not share API keys or private sample identifiers.

Original tutorial and screenshots