macOS user guide | TidyMass

Installation and quick start

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

Install on macOS

Open the TidyMass DMG, drag TidyMass to Applications, and open it there. Wait for the R environment check to finish. This guide targets the 0.1.65 Apple Silicon preview. A public installer link has not yet been verified; use the preview installer supplied by the project maintainers and check the version shown in the app. An Intel Mac build is not documented here.

The app includes R and its core packages. You do not need to install R separately for the core workflow. Optional third-party Shiny tools can require additional packages or system libraries.

The preview may be unsigned or unnotarized. If macOS blocks it, verify its source and use the system’s Privacy & Security prompt to allow that app. Do not disable system-wide security checks.

Create a project

Open Workflows and choose the untargeted metabolomics workflow.
Enter a project name. Click Choose location & create and choose a parent folder.
In Data import, select mzML/mzXML files and, preferably, sample information.
Check sample IDs and groups, then import the files.
Continue to Raw data processing.

Use a new project folder. Reopen an existing project with Projects or Open project, selecting the folder containing project.json.

Find your way around

Entry	Purpose
Workflows	Run a complete analysis in order
Analysis tools	Run an individual analysis or preparation tool
Shiny tools	Install and open third-party Shiny apps
R environment	Inspect R and manage additional packages
Code	Read execution code and records
Task center	Inspect the current R task, logs, memory and task history
Show settings / Hide settings	Expand or collapse parameters

A project holds analysis records; a run is one execution; a feature is a detected signal, not automatically an identified compound. Changing parameters affects a new run. Use Settings used for this result to inspect how a saved result was produced.

TidyMass used, Computer used and Computer total report different memory quantities. A high system total is not necessarily caused by this app. After your first run, verify sample counts, missingness, peak shapes and warnings. A completed task confirms execution, not scientific validity.

Input data and sample information

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

Tutorial contents · Applies to: 0.1.65

Raw files

The untargeted workflow and Raw chromatograms read mzML / mzXML. Convert proprietary vendor files with a suitable instrument-compatible converter first. Process positive and negative ion modes as separate projects. Keep each file’s basename unique, including across subfolders; do not distinguish samples only by letter case.

The project records the file locations. Keep raw files available and unchanged while analyzing: later EIC and spectrum inspection can need them.

Sample information

Raw import accepts CSV, TSV and Excel sample information. For example:

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

This example illustrates the format, not an adequate experimental design.

Column	Meaning
sample_id	Exact filename without extension: S001.mzXML becomes S001
group	Biological comparison group; select its actual name under Group column
class	Sample purpose, normally Subject, QC or Blank
batch	Analytical batch
injection.order	Actual acquisition order for drift assessment
subject_id	Subject identifier when a paired comparison is needed

Include every selected raw file exactly once. Preserve case and leading zeros as text. Do not use spreadsheet row numbers as identifiers. Fill in class explicitly; a pooled sample used only to collect MS2 is not automatically suitable as a quantitative QC.

Existing peak tables

Use Dataset builder & converter to construct a mass_dataset for individual analysis tools. A wide peak table can look like this:

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

Each feature ID must be unique; intensity columns must match the sample information. RT is in seconds in this example: match the import unit selector. NA is missing; zero remains a numeric observation. Preserve the source and evidence of any annotation columns.

MS2 and input checks

Attach MS2 using a supported import, builder or annotation entry. Association with a feature depends on precursor m/z and RT, and does not establish a unique structure. Use Sample & file checker to detect duplicates, missing files and unexpected files before a large run. RDS/RData imports must contain the supported object type, such as a single mass_dataset.

Complete untargeted workflow

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

Tutorial contents · Applies to: 0.1.65

1. Data import

Choose mzML/mzXML files and sample information, review the groups and click Import raw files. Import registers files; it does not detect chromatographic peaks. Folder grouping is a convenience, so check it against the biological design.

2. Raw data processing

Configure peak detection, RT correction and feature grouping. The software calls massprocesser/XCMS-related functions. Review m/z tolerance against instrument accuracy and the peak-width interval against observed chromatography. Signal/noise, noise and prefilter settings control low-quality signals; grouping bandwidth and minimum fraction control feature correspondence across samples.

Fill peaks integrates missing chromatographic signals where supported. It differs from later matrix imputation. Set Worker processes to match available memory as well as CPU capacity. In macOS 0.1.65, inspect representative samples with Parameter trial, then click Process raw data for the complete imported set.

Inspect the resulting feature table and mass_dataset. Project folder opens the saved outputs; use the run ID to find the correct execution.

3. Data exploration

Review m/z–RT distributions, sample and feature missingness, batches, peak shapes, spectra and intensities. Select a feature to inspect its evidence. Feature filters change the displayed subset. Manual Exclude is a review label; it does not remove rows from the downstream matrix.

4. Data cleaning

Choose missingness filtering, investigate potential outlier samples, impute remaining missing values, normalize, and apply batch integration only when appropriate. QC-based filtering and correction require suitable quantitative QCs. A PCA outlier alone does not justify exclusion.

Check the dataset size and metrics before and after each operation. Separately fitted before/after PCAs do not share a fixed coordinate system. Retain the unmodified input and document exclusion decisions.

5. Metabolite annotation

Choose a metid-compatible database, polarity, chromatography, adducts and matching tolerances. Use RT matching only when reference and experimental conditions are compatible. Select candidates to inspect experimental/reference MS2 mirrors, mass error and supporting evidence. An MS1-only match is a candidate, not MS2-supported identification.

Where available, Skip annotation for statistics lets you continue feature-level analysis. Annotation-dependent pathway analysis requires suitable annotations and updated downstream steps.

6. Statistical analysis

Inspect PCA and explicitly choose the comparison groups. Check which input dataset and intensity transformation are used. Paired analysis requires a correct subject column and one matching observation in each group per included subject; sample order cannot establish pairing. Record the test, fold-change direction and multiple-testing correction.

7. Pathway analysis

Check compound IDs, candidate ambiguity, input selection, organism, pathway database and background definition. Do not count multiple ion features as independent confirmations of one compound. Empty results can be valid: investigate coverage and mappings before changing thresholds.

8. Results & export

Export complete tables, objects, parameters, code, logs and session information for the desired run scope. A paginated preview is not the complete table. Keep external raw files and databases with the project backup.

Continue or rerun

Reopen a saved project to continue at the first unfinished step whose prerequisites are satisfied. A successful upstream rerun makes dependent downstream results stale; rerun the affected steps. Old results remain in Run history. A failed or canceled retry does not replace the previous successful result.

Recovery operates between saved steps, not at an arbitrary scan inside interrupted peak detection.

Parameter trials, tasks and templates

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

Tutorial contents · Applies to: 0.1.65

Try parameters on a small subset

Open Workflows → Raw data processing → Analysis settings → Parameter trial after importing files.

Select 1–5 samples. The initial selection is up to the first three files, not an automatically representative subset; include relevant QCs, groups and batches yourself.
Set peak-detection and other processing parameters in Analysis settings.
Click Run parameter trial.
Inspect sample/feature counts, missingness, warnings and saved settings.
Select a feature under Inspect trial peak and click Show peak shape.

The selector uses a saved preview of up to 150 features. Complete tables remain in the run directory. The EIC supports zoom, reset and download.

Change parameters and run again to create a separate record. Compare saved results compares two runs and their settings. Keep the sample subset consistent when assessing parameter effects.

To apply a successful trial, open its settings snapshot, click Restore this run’s settings, review the parameters and run Process raw data. Formal processing uses the full imported manifest. A trial does not complete the formal step, unlock downstream analysis or replace existing formal results. Retrying a canceled trial starts its computation again.

Monitor work

Open Task center at the top of the window for the current R operation, elapsed time, logs, memory, cancellation and project task history. Stage-specific progress is not necessarily an overall workflow percentage.

You can close the panel and browse saved summaries, history, annotation tables and already-cached exploration results in the same project. New EIC/MS2 extraction or uncached computations must wait for the current R task. Parameter editing and project switching remain locked. Closing the panel does not cancel the task; use Cancel task and wait for its status to update. This interface does not imply multiple simultaneous R analyses.

Save a workflow template

Above the analysis panels, expand Workflow templates, enter New workflow template name, then click Save workflow template. A template collects parameters for seven analysis stages. It uses current drafts, saved settings or defaults, and records which stages had current successful results. Defaults saved in a template are not a validated method.

In another project, select the Workflow template, inspect Preview settings and its source version, and click Apply workflow template. Configure this project’s files, databases, sample choices and comparison groups before running each step.

Templates retain reusable parameters, software version and source-stage records. They omit raw/database paths, sample choices, trial subsets and comparison-group IDs. Export choices are separate. Applying a template changes parameter drafts; it does not execute the workflow, change historical results or bypass prerequisites. Templates are local to this computer’s TidyMass user-data directory.

Feature review and interactive plots

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

Tutorial contents · Applies to: 0.1.65

Browse features

In Data exploration, open m/z–RT distribution. On macOS 0.1.65, the plot and feature table share a resizable workspace; narrow windows stack them. Selecting a point or row synchronizes the selection and reveals feature details. Use Find feature by ID for an exact lookup.

Previous feature / Next feature follow the filtered, sorted feature list. Left/right arrow keys work when the detail area is focused, without intercepting normal text editing.

Table columns

The macOS 0.1.65 Column view selector provides Basic (m/z, RT, mean intensity, missingness), Quality (QC RSD, Sample / Blank, MS2, review state) and Annotation (available candidate fields). Sort with column headers; add up to eight sample-intensity columns. These views display existing data and do not create annotations. Missing metrics are NA, not zero or a pass.

Filter and review

Feature filters subset the plot and table using MS2, annotations, m/z, RT, intensity, missingness and available QC/Blank metrics. QC RSD requires at least three valid QC observations. Filters do not change the saved matrix.

Assign Keep, Exclude, Needs confirmation, Favorite and notes as appropriate. Click Save review and use Export reviews CSV to save your decisions. Exclude is a label: use Data cleaning for an actual downstream exclusion and create a new result.

Inspect evidence

Depending on the saved input, inspect Peak evidence, Sample intensities, Injection drift, RT alignment, MS2 spectra, Annotation candidates and MS1 spectrum. An MS1 scan includes other ions recorded in that scan; it is not a purified spectrum of the selected compound. A high MS2 score does not by itself resolve all structural ambiguity.

Click Show peak shape, then expand Samples and extraction settings to change samples, m/z tolerance and RT window. The plot is an MS1 EIC in raw RT. Available dashed boundaries come from saved integration evidence. Initial extraction can read raw files and build a local scan cache; subsequent requests can reuse it. Missing or replaced raw files can prevent extraction.

Plot and table downloads

Drag to zoom; use Reset view or double-click to reset. Download plot offers the supported formats, dimensions and PNG DPI. Download CSV, where present, exports plot data. Read the adjacent information icon: some downloads regenerate the full plot instead of preserving the current zoom.

Use Download complete CSV or Results & export for complete tables. Pagination and limited previews do not define the full export scope.

Individual analysis tools

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

Tutorial contents · Applies to: 0.1.65

Open Analysis tools, then Open tool on the relevant card. Some tools create their own projects; others save outputs from their dedicated page.

Tool	Purpose
Sample & file checker	Compare sample records and raw filenames
Injection sequence designer	Randomize samples, allocate batches and insert QC/Blank injections
Raw chromatograms	Inspect TIC, BPC, EIC and scan spectra
Raw data processing	Run peak detection and alignment separately
Dataset builder & converter	Construct or convert a dataset from tables
Data exploration	Inspect an existing dataset
Data cleaning	Filter, impute, normalize and handle batches
Metabolite annotation	Annotate features or individual queries
Pathway analysis	Analyze eligible compound IDs
QC report	Report sample and feature quality
Targeted peak extractor	Integrate predefined m/z–RT targets

Sample & file checker

Supply a sample CSV and raw folder; select the matching column. Use sample_id for a typical sample sheet, or unique file_name for an injection list with repeated QCs. Matching strips extensions and is case-sensitive. The checker recognizes mzML, mzXML and Thermo RAW filenames; recognition does not mean it can read or convert Thermo spectra. Resolve missing, duplicate and unexpected entries before analysis.

Injection sequence designer

Import a CSV with at least sample_id; optional columns include group, position or vial_position. Set batch count, randomization and seed. Configure Conditioning QC, Pooled QC, Blank, RTQC and MS2 QC as needed, inspect batch counts, then export a running list/metadata or save the plan as JSON.

Randomization shuffles all study samples before splitting batches; it is not a stratified group-balancing design. Repeated injections need unique filenames. Exported metadata uses injection filenames as sample_id while retaining original identifiers. The export is a generic plan: compare its columns, methods, vial positions and volumes with the actual instrument sequence template before instrument use.

Raw chromatograms

Select mzML/mzXML files and MS level; click Read TIC / BPC. Choose a trace, hover for RT, or click a chromatographic position to inspect its scan and sample. After reading files, enter a target ion m/z, tolerance and unit to extract an EIC.

Enter ion m/z, not neutral molecular mass. An MS2-level EIC tracks fragment intensity in the selected MS2 scans and is not automatically a precursor-specific transition.

QC report

Import a mass_dataset RDS/RData and set QC RSD, missingness and Sample / Blank thresholds. The report evaluates and flags features; it does not delete them. Intensity across injection order is a sum of the input matrix intensities, not raw-scan TIC. Prior normalization and imputation change its interpretation.

Targeted peak extractor

Prepare a target CSV such as:

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

RT is in seconds. Choose raw files, m/z tolerance and a fixed RT integration window, then run and inspect peak shapes. The current method sums MS1 signal within the tolerance and integrates by the trapezoidal rule. It does not identify compounds or automatically separate coeluting peaks. Check the preview and export scope before interpreting areas.

Shiny tools and the R environment

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

Tutorial contents · Applies to: 0.1.65

Shiny tools installs and starts complete third-party Shiny apps. R environment inspects R and manages additional packages. Installing a missing dependency does not require registering it as a separate app. The dedicated TidyMass R Shiny tutorial is a separate guide under TUTORIALS → R shiny.

Install and start a tool

Open Shiny tools → Install a Shiny tool.
Select GitHub, CRAN or Bioconductor and enter the repository or package.
If known, enter R package name and Startup function; otherwise try automatic detection.
Review the source, use the interface’s trust checkbox and click Install tool.
Inspect View log, then use Open tool under Installed tools.

A repository name is not always its R package name. Do not enter a complete URL as the package name. These tools execute local R code and can have their own dependencies.

Back to installed tools returns to the list without necessarily stopping the process. Use Stop tool to release its resources.

Configure startup

Under Manage tool, select Auto-detect, Exported function, Package app_ui / app_server, or Shiny application folder as appropriate. Folder mode starts an app directory using shiny::runApp().

For an exported startup function, enter the function name alone, such as run_featuremap, not a call with parentheses or a namespace. runApp belongs to shiny; do not assume a third-party package exports it.

Install missing packages

Open R environment, identify the exact missing package, select the correct source and review the installation log. For example, org.Mm.eg.db is a Bioconductor package. Stop and restart the affected tool after installation.

Additional package libraries are managed separately from the app’s bundled library, and some tools have private dependency libraries. Check the actual loaded version when a package appears installed but the error persists. Installing from source can require system libraries or compilers; find the first substantive error rather than repeatedly reinstalling unrelated R packages.

Export, save and recover

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

Tutorial contents · Applies to: 0.1.65

Save a figure

Click Download plot near the figure and choose an available format. Dimensions are in inches; PNG supports DPI. Some figures also provide Download CSV. Inspect the exported file: an R-generated export may use the full range rather than the current interactive zoom.

Export an analysis

In Results & export, select Selected run or All completed datasets / queries. For a single run, verify the run ID. Select R objects, complete tables, code/parameters/logs/session information and available figures, then click Export selected content.

A full project copy includes its saved artifacts independently of other individual-content checkboxes. External raw files and databases are not automatically part of that copy. Check and back them up separately. Trials also have run IDs; do not export a small trial as if it were the full analysis.

What the project preserves

Runs save parameters, input relationships, logs, results and execution/reproduction records. Code exposes these records, but a displayed record is not necessarily a self-contained script. Reproduction needs the referenced files, databases and a compatible R/package environment. Preserve sessionInfo.txt, request/settings files and reproduce.R where present.

Reopen a project

Choose Open project and the folder containing project.json. Saved steps remain accessible. Unfinished executions can appear as interrupted, and results depending on changed upstream inputs as stale. Restore missing run files or rerun the affected stage. Editing project status fields cannot create missing outputs.

Move or clean up

Copy the entire project directory and separately account for external raw files and databases. Internal result paths can be relocated with a project; external references may need repair. Use Storage for supported cache management and read its scope first. Removing scan caches can make the next EIC extraction slower.

Do not delete run folders during computation or open the same project for modification in multiple app instances. If a project lock is reported, close the other instance first.

Troubleshooting

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

Tutorial contents · Applies to: 0.1.65

Symptom	What to check
A step is unavailable	Confirm its preceding formal step has a current successful result
Downstream results are stale	Rerun stages affected by the changed upstream input
A trial completed but processing remains unfinished	Run Process raw data for the formal dataset
A table and export have different row counts	Check filters, pagination, preview limits and selected run
An excluded feature remains downstream	Manual Exclude is a review label; run an actual cleaning operation
A plot stays unchanged after editing settings	Run again; the current plot belongs to saved results
MS2 or annotation fields show No/NA	Check spectrum association and whether annotation was run
Sample IDs do not match	Check basenames, case, leading zeros, duplicates and missing records
Group column not found	Select the actual column name in the sample sheet
QC filtering has no QCs	Verify quantitative QC classes or disable an inapplicable QC-dependent operation
Missing values remain before statistics	Review the input version, filtering and imputation
Paired analysis fails	Check unique subject IDs and matching observations in both groups
No pathway results	Inspect identifiers, input selection, database coverage and background; empty output may be valid
Peak extraction cannot find files	Check for moved, renamed or replaced raw files

R busy means the requested operation needs the occupied R worker. Saved summaries and cached results can be viewed where supported, but a second analysis must wait. Closing a task panel does not cancel computation. Use the cancellation control and wait for confirmation. Recovery resumes between saved steps, not within interrupted peak detection.

When memory is high, compare Computer used with TidyMass used, reduce worker count or trial size, and inspect other system processes. More threads do not always make analysis faster.

For Missing package, install the package from its correct source and restart the tool. For Invalid R package name, check whether a URL or repository name was entered instead. For not an exported object, inspect the startup function and mode. Missing images or styles in a Shiny app can reflect static-asset paths rather than text encoding. Read the first substantive error and final installation state; a warning alone is not necessarily a failure.

When reporting an issue, include the app and OS versions, tool/stage, run ID, reproduction steps and relevant logs. A few de-identified sample-information rows can clarify input problems. Preserve the failing project and logs before clearing data, and check shared logs for private sample names and paths.