Documentation
Quick start

Quick Start

Let’s dive into the untargeted metabolomics workflow, designed to simplify and streamline untargeted metabolomics analysis. This powerful workflow delivers comprehensive results with just a single command.

If you haven’t installed MassCube yet, be sure to follow the installation guide before proceeding.

The MassCube untargeted metabolomics workflow

One command to process untargeted metabolomics data (Fig. 1).

Fig. 1. The MassCube untargeted metabolomics workflow

Input (4 items)

You will need data, sample table, parameters, and MS/MS database to run the workflow.

In your project folder (e.g. my_project), you need to prepare the following components:

my_project
├── data
│   ├── sample1.mzML
│   ├── sample2.mzML
|   └── ...
|── sample_table.csv
└── parameters.csv

  1. data folder: a file folder containing all raw LC-MS data in .mzML or .mzXML format. It’s mandatory. I don’t know how to convert my files.

  2. sample_table.csv file: a csv file to claim quality control samples, blank samples and biological groups. Use MassCube to generate a sample table and then edit. Set yes in the ‘is_blank’ column for blank samples, and yes in the ‘is_qc’ column for quality control (QC) samples. If not provided, normalization and statistical analysis will not be applied.

  3. parameters.csv file: Set and download a parameter file. If not provided, the default parameters will be applied, but annotation will not be performed since the file location of the MS/MS database is not provided.

  4. MS/MS database: Download a MS/MS database for MS/MS spectral annotation. You may also prepare your own MS/MS database.

Using MassCube 1.0 or 1.1
For MassCube 1.1 or earlier, please use the old MS/MS databases

Extra component for annotation:

  1. mzrt_list.csv file: a csv file to provide the m/z and retention time for feature annotation. It was designed to annotate features using retention time (e.g. internal standards). A template can be downloaded from here. It’s optional.
Data Preparation Demo data

Processing

In the project folder, open a terminal and run the following command:

untargeted-metabolomics
How to open a terminal
Make sure the terminal directory is set to the project folder. For Windows user and MacOS user

Output

After the processing, you will find the following files and folders in the project folder:

project/
├── data
├── sample_table.csv
├── parameters.csv
├── mzrt_list.csv (optional)
├── project_files
│   ├── data_processing_metadata_[DATE].pkl
│   ├── features.msp
│   └── ...
├── aligned_feature_table.txt
|── normalized_feature_table.txt (if signal normalization applied)
├── single_files
│   ├── sample1.txt
│   ├── sample2.txt
│   └── ...
├── chromatograms
│   ├── sample1.png
│   ├── sample2.png
│   └── ...
├── ms2_matching
│   ├── compound1.png
│   ├── compound2.png
│   └── ...
├── statistical_analysis
├── normalization results
|   ├──feature_0_normalization.png
|   ├──feature_1_normalization.png
|   └── ...
├── ...
  1. project_files folder: a folder containing the metadata file for data processing.
  2. aligned_feature_table.txt file: feature table after alignment (if applied).
  3. single_files folder: a folder containing the feature table for each sample.
  4. chromatograms folder: a folder containing the chromatogram for each sample.
  5. ms2_matching folder: a folder containing the MS/MS matching for each annotated compound.
  6. statistical_analysis folder: a folder containing the statistical analysis results.
  7. normalization results folder: a folder containing the normalization results (if applied).
Installation