Windows user guide | TidyMass

Installation and quick start

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

Install on Windows

This guide targets the 0.1.63 Windows x64 preview. Obtain the preview ZIP from the maintainers, extract it fully, and run TidyMass-0.1.63-windows-x64-setup.exe. A public download has not yet been verified; the existing CI artifact requires GitHub repository access. Do not use a macOS DMG or rename an installer to change platforms.

Follow the installer, launch TidyMass and wait for R environment to finish checking the bundled R 4.5.2 and core packages. You do not need a separate system R for the main workflow. Prefer a local writable project folder; keep the raw data available for later peak inspection. If Windows blocks an unknown publisher, verify the supplied installer and its checksum with the maintainers before allowing this app.

Installer and installed-app automated tests were recorded for 0.1.63. They do not establish compatibility with every Windows installation. This guide does not claim Windows ARM support.

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
Run history	Inspect saved runs and their settings
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.63

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

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. Inspect representative samples in a separate test project, then click Process raw data in the formal project 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.

Tasks, reruns and version differences

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

Tutorial contents · Applies to: 0.1.63

Monitor and cancel

Inspect the running operation and its logs. To stop it, use the interface’s cancellation button and wait for the status update. Do not delete project files to stop computation. Reducing worker count can reduce parallel memory requirements.

Check parameters on a small dataset

Create a separate test project with representative QCs and study samples. Inspect tolerances, peak width and peak shapes there. Then import all samples into the formal project and run with the reviewed settings. Preserve both parameter records; test-project results are not the complete dataset.

Continue from saved steps

Reopen a project and continue from the first unfinished step with satisfied prerequisites. A successful upstream rerun makes affected downstream results stale. Rerun those stages; Run history retains previous records. Canceled peak detection must be started again, without scan-level resume.

Differences from macOS 0.1.65

Windows 0.1.63 does not include the newer Parameter trial, Task center, Workflow templates, resizable plot/table workspace or Basic / Quality / Annotation column views. Follow this Windows guide for the shared analysis steps. After upgrading, use the documentation matching the actual installed version.

Feature review and interactive plots

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

Tutorial contents · Applies to: 0.1.63

Browse features

Open m/z–RT distribution in Data exploration and select a point or table row to inspect a feature. Use Find feature by ID for exact lookup and Previous feature / Next feature to move through the filtered, sorted list. Sort table columns and add a few sample-intensity columns as needed.

Windows 0.1.63 uses the earlier plot/table layout. The resizable workspace and column-view selector belong to macOS 0.1.65.

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

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

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

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

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

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.