Quick Start Guide

Submission Checklist

Tip

Before Submission:

• Create MetaboLights user account (If you do not have one).

• Make ready study supplementary, derived, and raw data. ie. spectral files produced by the analytical instrument and/or an open source version. Please see accepted file formats.

• MetaboLights accepts only file names containing letters (a–z, A–Z), numbers (0–9), hyphens (-), underscores (_), or dots (.). Please ensure that supplementary, derived, and raw data file names comply with this pattern. Otherwise, rename them accordingly. Space characters are not accepted.

• Since June 2025, MetaboLights accepts only raw/derived data files and compressed versions of raw/derived data folders (e.g., .d, .raw, or any NMR raw data folder). If your study includes raw data folders, please compress each folder individually using a ZIP utility before submission. A zip file containing multiple raw folders is not accepted.

• Organize your supplementary, raw and derived data files on your local storage. Create subfolders if needed. Subfolder names MUST comply with filename pattern. Ensure subfolder names contain only letters (a–z, A–Z), numbers (0–9), hyphens (-), underscores (_), or dots (.)

• If you want to use FTP to upload your data files, install an FTP client (e.g., FileZilla).

• If you are not principal investigator of the study, collect principal investigator contact information (e.g. email, affiliation, ORCID, address, phone number, etc.).

During Submission:

• If you are experiencing problems with Aspera, try to use FTP client to upload your data (e.g., Filezilla).

• Ensure your data file uploads are completed successfully.

• Do not forget to index your FTP folder after your new uploads.

• Complete all fields of the following sections metadata:

  • Summary: title, contacts, abstract/description
  • Publications (status can be 'in preparation', 'submitted', etc.)
  • Descriptors: Define at least 3 keywords.
  • Protocols
  • Samples
  • Assays
  • Metabolites

• Add principal investigator as a contact person.

• Define at least one study factor and complete its values (At least two rows MUST be filled with different factor values).
• Ensure sample names are unique and referenced in assay files.

• In your Samples and Assays we recommend including few samples using the online editor, to select the proper ontology terms. Then, an easy way to make changes to these files and the Metabolite files (MAF) is to follow these steps:

  • Download corresponding metadata file (e.g., s_REQxxxx.txt) from the ISA METADATA list (under the Files tab).

  • Open the metadata file with your favorite editor (Microsoft Excel, OpenOffice, etc) without changing the original format and encoding.

  • Update the metadata data file on your favorite editor (do not change file templates, e.g., do not change columns order, column headers, etc.)

  • Save it without changing the original file extension, format and encoding.

  • Ensure that the local metadata file name is exactly the same as in your study folder on MetaboLights Editor.

  • Upload the metadata file and 'synchronise metadata files' on Files tab on MetaboLights Editor.

  • Refresh your editor (if needed)

• Reference your raw data or derived files in the 'Raw Spectral Data File' or 'Derived Spectral Data File' column of your ASSAY files. Be sure all referenced data files start with FILES/ prefix. Example: FILES/RAW_FILES/myfiles.raw OR FILES/DERIVED_FILES/myfiles.mzML.

• Datasets with .wiff and .wiff.scan files require the upload of both types of files. Although we generally ask submitters not to modify metadata file templates, an additional 'Raw Spectral Data File' column is required for these submissions, so that both files can be properly referenced in the corresponding ASSAY.

• Run study validation and fix all errors.

• Define and update your study release date.

Overview

Create Study

Select Submit study in the MetaboLights homepage to create a new submission (or edit an existing one).

Alternative: Use ‘Create New Study’ from the editor console and select ‘Guided Submission’ to be guided through the upload of your data files and creation of your Assays.

Choose to upload your RAW files at this point or later.

Note: You will be issued a temporary identifier (REQxxx). Please refer to this identifier in any communication with the MetaboLights team.

Update Study Metadata

Use the Online Editor option to view and edit existing submissions. Access through My Studies page or with a study URL.

Note: You can give collaborators edit rights to the study following these steps.

Validate

Studies must pass validation to be private. Validation errors are evident in the information bar at the top of the study (if nothing is displayed the study has passed validation). Details of errors are available in the study validations tab.

Validation Framework v2 - With the aim of improving reporting and speeding up data release, the MetaboLights team has developed a more structured and stricter new study validation ruleset.

Temporary submission requests (REQxxx) must pass validation to be promoted to ‘Private’ and get assigned a full MetaboLights study accession number (MTBLSxxx). Validation errors are evident in the information bar at the top of the study (if no validation box is displayed, next to ‘Release Date’, the study has passed validation). Details of errors are available in the ‘Study Validations’ tab.

Make Your Study 'Private'

To promote your temporary submission request (REQxxx) to ‘Private’ and obtain a full MetaboLights study accession number (MTBLSxxx), select Status and change from 'Provisional' to ‘Private’.

Update release date before making your study Private

If your study reaches 'Private' status, you can make it public at any time. Please note that once a study is Public, you won't be able to change it back to Private.

MetaboLights will automatically release your dataset to the public 1) when the selected release date is reached or 2) upon notification of the corresponding publication.

If the MetaboLights team selects your study for manual curation, the curation process may extend the selected release date and the study will become public once the curation is complete.

Update your 'Private' study

'Private’ studies cannot be edited. If amendments are required (e.g. update manuscript DOI number, update release), change your study status to 'Provisional' and update your study. After you complete amendments, validate your study and update study status to 'Private' again.

What to include in your Manuscript

Please add to your manuscript the following sentence (typically in the "Methods" section or just before/in the Acknowledgements):

"The metabolomics data have been deposited to MetaboLights[1] repository with the study identifier MTBLSxxx".

MetaboLights reference:

[1] Yurekten O, Payne T, Tejera N, Amaladoss FX, Martin C, Williams M, O'Donovan C. MetaboLights: open data repository for metabolomics. Nucleic Acids Res. 2024 Jan 5;52(D1):D640-D646. doi:10.1093/nar/gkad1045. PMID:37971328.

We would recommend you to also include this information in a much abridged form into the abstract itself, e.g. "Data are available via MetaboLights with identifier MTBLSxxx."

Obtain Your Reviewer Link

‘Private' studies offer a private read-only 'Reviewer Link' on the study page, which it will make easier to share your validated submissions with collaborators, reviewers, editors, etc.

Note: MetaboLights curation will be retained in certain cases.

Publish

Make your study public once your manuscript is accepted and no further updates are needed.

Note: It can take up to 24h for your study to be publicly available.

Please add to your manuscript the following sentence (typically in the "Methods" section or just before/in the Acknowledgements):

"The metabolomics data have been deposited to MetaboLights[1] repository with the study identifier MTBLSxxx".

MetaboLights reference:

[1] Yurekten O, Payne T, Tejera N, Amaladoss FX, Martin C, Williams M, O'Donovan C. MetaboLights: open data repository for metabolomics. Nucleic Acids Res. 2024 Jan 5;52(D1):D640-D646. doi:10.1093/nar/gkad1045. PMID:37971328.

We would recommend you to also include this information in a much abridged form into the abstract itself, e.g. "Data are available via MetaboLights with identifier MTBLSxxx."

Note: Please send manuscript DOI to MetaboLights help once available.

Submission Process

Overview of the 3 stages in the study submission process.

'In Curation' Studies

Studies with status In Curation in the previous workflow, will now have Private status under the new workflow.

For those submitters who wish to make their studies Public, please:

1) Change status to Provisional (drop down menu in the status bar at the top of your study).

3) Run new Study Validations and address errors, until validation is successful.

4) Change status to Private (i.e. keep private until publication is out) or Public (for immediate release).

Create Study

Select Submit study in MetaboLights website followed by 'Create New Study' to be guided through your submission. If you have an existing account you will first be taken to My Studies where you can choose to edit an existing study (MTBLSxxx) or create a new study (REQxxx).

Complete your Study

Once you click on 'Create New Study', you will be required to complete the following steps in order to progress with your submission:

1. Select type of techniques used

2. Complete Contacts details

3. Read and accept MetaboLights Dataset License and Data Policy agreements

4. Add Study title

5. Add Study Description/Abstract

6. Complete Publication Details

Once these are completed, a new temporary submission request (REQxxx) will be automatically generated with a unique study identifier.

You will be able to progress with your submission using the Study Overview editor or using the Guided Submission mode.

To enter the study in Guided Submission mode, simply go to My Studies and select the Guided Submission option below the study information.

The Guided Submission will look like this:

You can choose to continue in this mode or you can exit the guided submission at any time and the information you have added will be automatically saved.

You can also switch between guided submission and online editor at any point by clicking on the icon on the bottom right of the screen.

Submitters and authors

Submitters are the study creators and editors, they have access and edit rights to the private study during the submission process and correspondence will be directed to the submitter. They will also be the main contact for once the study is public.

Study Contacts are named contributors (as for a manuscript) but will not automatically have edit rights or private access to the study.

The submitter can provide access & edit rights to collaborators provided they have a MetaboLights account by adding first as an author and then choosing Make submitter.

A Submitter can only create or currently have a maximum of 2 studies in the Submission stage. If you need to create more studies then contact the MetaboLights team through the support email: metabolights-help@ebi.ac.uk.

Edit Study

All studies can be edited directly online. To access, choose from the options below.

• Navigate to MetaboLights EditorHome page and click on Study overview.

• Use the temporary URL assigned when your study was created. This will be something like (https://www.ebi.ac.uk/metabolights/editor/study/REQxxx).

As mentioned before, when editing a study there is always the option to switch between the Study Overview editor and the Guided Submission mode. Look for the pop-out option in the bottom right corner of the screen or choose either option on your My studies page.

Metadata files in your study can be edited online or downloaded and edited in e.g., MS Excel.

It is important not to remove existing columns, change column order or alter column headers when editing, as the format is a fixed requirement linked to validation. Additional columns can be added, e.g., in the Samples Section by choosing +factor, to better describe samples. This should be done online before downloading files.

Some sections of metadata require ontology fields. When adding information using the online options, ontology options will appear as you type. If uploading a file without ontologies added, the Online Editor will prompt you to select ontologies in the fields above the tables.

Shortcuts & Functions

Text fields

In text fields such as abstract and protocols, formatting options are available as below. To accept a change select Save and OK to exit.

Tables

Action	Description
Auto complete column	Click on column header & enter text to add information to the entire column.
Copy paste multiple	Select an entire column (click on header) or highlight several cells to paste the same information into each.
Paste list	Select an entire column (click on header) to paste a list (starting in first cell) from e.g., Excel
Add sample	Select cell and paste / type sample name
Add multiple samples	Use +samples to add a list of sample name or import names using the names of raw data files
Add row	+row
Delete row	Select end of row to highlight, then delete option.
Add columns	Use +factor option to add more columns to sample sheet
Expand table	To view underlying ontology information
Upload / download	Up / download files underlying a specific table to edit offline in e.g., text editor or Excel etc (ensure to retain study name & extension)
Filter

Ontologies

Where possible terms are supported by controlled vocabularies / ontologies. Simply start to type and if available, options will appear below and you can select the appropriate term. If the term you are looking for does not appear, simply press enter and the text to add it as free text.

Where ontologies have not been added within tables a section will appear above the table to highlight terms. Simply click edit option to add on.

For detailed information on which ontologies are prioritised for each section of your study, please refer to our GitHub Prioritised-control-lists.

We also encourage users to explore leading ontology repositories such as the Ontology Lookup Service OLS and BioPortal. In addition, ZOOMA is a valuable tool for identifying optimal ontology mappings and converting free-text annotations into consistent ontology terms.

Study Overview

When you create a study the Guided submission process will take you through the setup step-by-step. It will guide you through raw data upload, creating assays and provide you with controlled vocabulary/ontology options in relevant fields. If you don’t have all the information to hand, don’t worry! You can access and edit your entire study at any time when in submission from your My Studies page.

Each MetaboLights study has 5 main sections, Overview, Samples, Assays, Protocols and Metabolites information. The basic outlines for each are given below. Each section also corresponds to a specific file as indicated in which the information is stored.

Overview (i_Investigation.txt)

This section provides a description of the study, an overview that will inform the reader the type of data they will find.

Note: (a) Title (b) Contacts (c) Study Description (Abstract) (d) Publication link (e) Design Descriptors (Keywords) (f) Protocol text () Funding (*) Links to related datasets

There are several parts to this section:

• (a) Title: Descriptive title which should match manuscript title.
• (b) Author information: A list of all contributing authors.
• (c) Abstract: High level description of the study.
• (d) Manuscript publication information: Manuscript title, authors and public link. A tentative title should be provided if the manuscript is in preparation. This can be updated at any stage by contacting MetaboLights Help directly and a DOI / PMID Identifier can be used to update title/author/abstract directly from the manuscript.
• (e) Keywords / Descriptors: e.g., targeted metabolite profiling, ultra-performance liquid chromatography-mass spectrometry, microbiome, etc.
• (f) Descriptive protocols: When an assay is selected a set of corresponding protocol boxes will automatically be generated in the protocol section to guide the required information.
• (*) Funding: Details of the Funding that supported the study, including Funding Organization and Grant Identifier.
• (**): Links to related datasets in MetaboLights and other repositories.

Sample information (s_MTBLSxxx.txt)

The sample information should provide all relevant facts about each sample and any controls / standards included in the study. There is ONE sample sheet per study. Sample metadata should include a unique sample name, organism, organism part (for controls use e.g., experimental blank and solvent) and sample type (ie. control, QC, experimental sample). Further sample descriptors should be included where available by selecting +Factor to add new columns (e.g., Gender, Age, Treatment).

Assay information (a_MTBLSxxx.txt)

The assay information will describe the assay process for each control and sample in the assay and connect the sample name to both its corresponding raw data file and metabolite identification table.

MULTIPLE assays can be added per study.

The assay is divided into sections each starting with a Protocol Ref column, e.g., Chromatography, which describes the specifics of that part of the assay using controlled vocabulary, so every study using the same system is easily findable.

Protocols (i_Investigation.txt)

This section is linked to the Assays, so different sections protocol sections will be generated according to the specific analytical technique used to analyze the samples and selected when creating the Assays.

Metabolites information (m_MTBLSxxx.tsv)

Each assay has a corresponding metabolite table. If results are cumulative of multiple assays, use the metabolite assignment file column in the assay table to point all assays to the same m_MTBLSxxx.tsv file name.

The metabolite information should include all metabolites / unknowns / features identified within the study, their measurements (e.g., mass-to-charge ratio, chemical shift, etc.) and retention time (where supported by the technique).

Please include information such as chemical identifiers, confidence and intensities / abundances (column V+). This information often can be simply copied and pasted, for example, from software outputs.

Validate Study

A study must successfully pass validation before it can progress to the Private stage. If validations need to be re-run due to recent updates, the Validations tab title will show in red, accompanied by a notification indicating that the study has been modified. Further details can be found in the Study Validations tab.

To run validations you need to click on Initiate Validation Task button. You will need to re-run Validations after making any updates in your study (e.g. metadata updates and/or data files uploads).

The validations report can be downloaded by clicking on the Download Report button. The resulting reports generated each time the validations are triggered are available by selecting the Select a Report drop-down menu.

Further information is available in the Study Validations tab. There are 7 validation tabs, which include the reported ERRORS and WARNINGS found in all sections of the study. You must address all errors and should also address warnings where applicable to progress your study.

If you have any problems or queries, please contact MetaboLights help.

Referencing a study

What to include in a manuscript

• Permanent unique identifier; MTBLSxxxx.
• Public url for your metabolomics study https://www.ebi.ac.uk/metabolights/MTBLSxxxx.
• You may also wish to cite the MetaboLights reference Yurekten et al.

Study accession number

When you first create a new study you will be provided with information about the temporary submission request (e.g., REQxxx) as shown below. You will also receive this information by email. This REQxxx is a temporary identifier and should NOT be included in your manuscript.

Once the study passes the required validation and status is promoted to ‘Private’, an accession number (e.g., MTBLSxxx) will be issued. This MTBLSxxx permanent unique identifier should be used to reference the study in manuscripts and other communications.

As part of MetaboLights new workflow, submitters can change the status of their studies from ‘Private’ to ‘Public’. You can also use your MetaboLights study URL https://www.ebi.ac.uk/metabolights/MTBLSxxxx to reference your study in any type of publication.

You can see a list of all your submission requests (REQxxx), studies (MTBLSxxx) & their unique identifiers on your My Studies page.

Reviewer link

Once a study has been completed and the status updated to ‘Private’, a private read-only link will be available at the top of your study page to share with the journal.