Contents

• Overview
• Documentation
• System Requirements
• Installation Guide
• Quick Start
• Demo
• Attribution
• For Developers

Overview

FERMO is a dashboard for metabolomics data analysis. FERMO integrates metabolomics data with orthogonal data such as phenotype information for rapid, hypothesis-driven prioritization. To perform data anlysis, FERMO utilizes the fermo_core package.

FERMO can be freely accessed online at FERMO Online. For a local installation, see the description below.

For general information on FERMO, see the FERMO Metabolomics GitHub Organization page.

Documentation

The official documentation can be found HERE.

System Requirements

Hardware requirements

FERMO can be run on a standard computer and does not have any special requirements.

Software requirements

OS Requirements

Local installation of the Docker container was tested on:

• Windows 10 (Docker Desktop)
• Ubuntu Linux 20.04 and 22.04 (command line)

Python dependencies

Dependencies including exact versions are specified in the pyproject.toml file.

Installation Guide

Building the Docker-container should take no more than a few minutes.

Note: the Docker-container automatically runs the script cleanup_jobs.py, which automatically deletes jobs older than 30 days. If you plan to run the container for a long time, you need to disable this in entrypoint_docker.sh.

With Docker Desktop

Assumes that Docker Desktop is installed

• Open Docker Desktop
• Open the terminal and pull image: docker pull ghcr.io/fermo-metabolomics/fermo:main
• The newly downloaded image should appear under Images
• Click Run, expose port 8001
• Access in any browser at the URL http://0.0.0.0:8001/

With docker from GitHub

Assumes that you have docker and git installed on your machine

commandline docker run -it --rm -p 8001:8001 ghcr.io/fermo-metabolomics/fermo:main

Once started, FERMO can be accessed in any browser at the URL http://0.0.0.0:8001/.

Quick Start

Running FERMO on your data

For an installation-free version, please see FERMO Online

As minimal requirement, FERMO takes LC-MS(/MS) metabolomics data, which it can integrate with a range of optional orthogonal data formats. Compatible formats are described in the Documentation.

For a step-by-step guide, please refer to our Tutorial.

Demo

Overview

To demonstrate the functionality of FERMO, we provide an example dataset sourced from this publication. It describes a set of extracts from strains belonging to the bacterial genus Planomonospora grown in the same condition, showing differential antibiotic activity against Staphylococcus aureus. FERMO can be used to investigate and prioritize the phenotype-associated and differentially abundant molecular features. Application of the Phenotype Score filter setting on the dashboard results in the selection of a group of molecular features annotated as siomycins, thiopeptides with known anti-Gram positive antibiotic activity.

Details on the experimental conditions can be found in the Wiki.

Setup and start analysis

The analysis can be started on the Start of Load Analysis page. We recommend using FERMO Online, but the app can be also started locally.

First, load the example files in the corresponding fields.

• Peak table file parameters : casestudypeaktablequant_full.csv
• MS/MS file parameters: casestudyMSMS.mgf
• Phenotype data file parameters: casestudybioactivity_qualitative.csv
• Sample metadata file parameters: casestudygroup_metadata.csv
• Feature identity annotation parameters/MS2Query Annotation Module: casestudy.ms2queryresults.csv

All settings can be left default except in Phenotype data file parameters. Here, the format of the phenotype data file must be specified as Qualitative.

Once all files and parameters are specified, the analysis is initiated by clicking on the Start new analysis button.

Execution time is hardware-dependent but usually takes only a few minutes. On a machine running Ubuntu 22.04 with Intel® Core™ i5-7200U CPU @ 2.50GHz x 4 with 8 GiB Memory, execution time was 104 seconds.

Results and Interpretation

After successful completion of the run, the GUI will guide you to the dashboard page showing the results.

By using the Search and filter options panel and selecting Show additional filters, the Phenotype score filter can be applied.

Antibiotic activity is attributable to the thiopeptide siomycin and congeners (e.g. feature ID 83).

Attribution

License

FERMO is an open source tool licensed under the MIT license (see LICENSE).

Publications

See CITATION.cff or FERMO online for information on citing FERMO.

For Developers

Nota bene: for details on how to contribute to the FERMO project, please refer to CONTRIBUTING.

Package Installation

Please note that the development installation is only tested and supported on (Ubuntu) Linux.

With uv from GitHub

Note: assumes that uv and redis-server are installed locally

commandline git clone git@github.com:fermo-metabolomics/FERMO.git && cd FERMO uv sync uv run flask --app fermo_gui run --debug

In a separate terminal, run celery commandline uv run celery -A make_celery worker --loglevel ERROR

With docker-compose from GitHub

Note: assumes that docker-compose is installed locally and can be accessed without sudo

commandline git clone git@github.com:fermo-metabolomics/FERMO.git && cd FERMO docker-compose build --no-cache docker-compose up -d

Config file

The FERMO Flask application runs by default in "offline" mode, which does not set restrictions in files sizes used. To run FERMO in "online" (production-ready) mode, the default settings need to be overridden by a config.py file in an instance directory in the fermo_gui source directory.

WARNING: DO NOT USE DEFAULT SETTINGS IN PRODUCTION!

python config.py SECRET_KEY: str # Security ONLINE: bool = True # Flag for online/offline functionality CELERY: dict = { "broker_url": "redis://localhost", "result_backend": "redis://localhost", "task_soft_time_limit": 3600 } # settings for async job handling ROOTURL = "fermo" # subdomain, only used for email MAIL_DEFAULT_SENDER: str # settings for postgres mail MAIL_SERVER: str MAIL_PORT: int MAIL_USE_TLS: bool MAIL_USE_SSL: bool

The number of workers can be adjusted in the entrypoint_docker.sh script.

FERMO Online update procedure

commandline docker cp fermo-fermo_gui-1:/fermo_gui/fermo_gui/upload . && docker cp fermo-fermo_gui-1:/fermo_gui/fermo_gui/job_counter.txt . docker-compose stop git pull docker-compose build --no-cache docker-compose up -d docker cp ./upload fermo-fermo_gui-1:/fermo_gui/fermo_gui/ && docker cp ./job_counter.txt fermo-fermo_gui-1:/fermo_gui/fermo_gui/ docker exec fermo-fermo_gui-1 ls fermo_gui/upload | wc -l