comMS documentation: Commands · Configuration · Configuration reference · Output structure · README

comMS

comparative Mass Spectrometry analysis pipeline

Contents

• Overview
• Requirements
  • Python
  • External tools
  • comms report dependencies
• Installation
  • Installing external tools
• Quick start
• How comMS works
• Documentation
• Getting help & contributing
• License

Overview

comMS is a command-line tool for automated proteomic analysis and quantification, wrapping the Crux toolkit and ThermoRawFileParser into a single reproducible pipeline. comMS was designed to enable rapid and accurate proteomic analysis and quantification, particularly from multi-species experiments where samples may originate from more than one organism.

comMS was originally written to allow comparative analysis of samples derived from experiments investigating arbuscular mycorrhizal symbiosis (a plant-fungal mutualism) in Medicago truncatula, but the pipeline is applicable to any shotgun proteomics experiment that uses tryptic digestion.

Requirements

Python

comMS requires Python 3.14 or later. The recommended way to manage comMS and its Python dependencies is using the package manager uv. If uv is not already installed, follow the installation instructions.

External tools

comMS wraps two external binaries that must be available within a bin/ directory. Both tools must be downloaded manually and placed there, as described in Installing external tools.

Tool	Minimum version	Purpose	Platform notes
Crux toolkit	4.0.0 (5.0.0 for lfq)	Peptide index, spectrum search, PSM rescoring, quantification	Uses platform-specific binaries
ThermoRawFileParser	1.4.5	.RAW → .mzML conversion	Versions < 2.0.0 require Mono on Linux/macOS

comms report dependencies

The report command requires R (≥ 4.3.0) and a set of R packages (listed in the report command documentation). Required R packages can be installed by running:

Rscript src/comms/r/install_deps.R

Installation

The recommended installation method is uv tool install, which installs comMS as an isolated command available on your PATH:

uv tool install git+https://github.com/holsam/comMS

Once installed, verify the installation:

comms version

Installing external tools

Download Crux and ThermoRawFileParser and place them in a single bin/ directory (this directory can be anywhere, it does not have to be with your data or the comMS installation). The expected layout is:

bin/
  crux-v.v.platform.arch/
    bin/
      crux
  ThermoRawFileParser-v.v.v/  # versions ≥2.0.0 ship a platform subdirectory which is supported
    ThermoRawFileParser.exe

comMS locates binaries by patterns, so version subdirectories are supported and exact names are flexible. If multiple versions of either tool are installed under bin/, comMS will automatically select the recent version.

Once downloaded, point comMS at the bin/ directory by either:

• Setting it for an experiment via bin_dir in experiment.toml (see Configuration).
• Exporting an environment variable: export COMMS_BIN_DIR=/absolute/path/to/bin

External tool version considerations

On Linux and macOS, ThermoRawFileParser versions <2.0.0 require Mono. Install it via your system package manager (e.g. brew install mono on macOS or apt install mono-complete on Debian/Ubuntu). ThermoRawFileParser versions ≥2.0.0 and later are native binaries and do not require Mono.

The lfq command requires Crux >= 5.0.0, which introduced the crux lfq subcommand wrapping FlashLFQ. All other comMS commands are compatible with Crux >= 4.0.0. comMS will raise an error at startup if the installed Crux version does not meet the requirement for the command being run.

Quick start

Using an experiment

# 1. Create a comMS experiment
comms experiment                    # via GUI
comms experiment --headless         # via terminal

# 2. Run comMS analysis pipeline
comms pipeline -e /path/to/experiment/dir

Use --skip-convert if .mzML files are already available, and --skip-report to omit the report step.

You need two inputs to run the pipeline: a sample sheet (TSV or CSV) and a combined FASTA database containing your proteome(s) and contaminants. Both are described in Input files. The --experiment-dir option sets where comMS reads its configuration and writes its results, explained in Configuration.

Using command line options

Alternatively, each file that a comMS experiment resolves can be passed directly:

comms pipeline \
    --sample-sheet sample_sheet.tsv \
    --fasta combined_proteome.fasta \
    --data /path/to/sample1.RAW \
    --data /path/to/sample2.RAW \
    --experiment-dir /path/to/experiment/directory/ \
    --organism-tags "<Org1>,<Pattern1>,<Org2>,<Pattern2>"

The -d/--data flag is repeatable and, as above, --skip-convert should be used if .mzML files are already available and --skip-report can be used to omit the report step.

How comMS works

Running comms pipeline carries out the following stages:

1. .RAW to .mzML conversion (ThermoRawFileParser)
2. Peptide index construction (Crux tide-index)
3. Peptide-spectrum matching (Crux tide-search)
4. PSM rescoring (Crux percolator with picked-protein FDR)
5. Quantification by MS1 label-free quantification (lfq) and dNSAF spectral counting (quantify)

An optional report stage then generates figures and spreadsheets from the quantification output.

single- and multi-species analysis modes

comMS supports two analysis modes for single- and multi-species experiments, which are selected via the analysis field in experiment.toml:

Mode | [analysis] value | Pipeline runs | Suitable for -- | -- | -- Single-species | single | Percolator on the combined protein database, resulting in one set of PSMs per sample | Analysing proteins from one organism or where cross-organism FDR control is not a priority Multi-species | multi | Percolator is called on the combined protein database, with results split by organism before a second round of Percolator runs on individual organisms to apply per-organism picked-protein FDR | Analysing proteins from two (or more) organisms where target/decoy ratios differ substantially

Analysis mode is resolved when rescore runs: if analysis is not set, the pipeline infers multi if organism tags are supplied or configured, otherwise defaults to single. N.B. contaminants should not be counted as an organism.

Documentation

Page	Contents
Configuration	Experiment context, experiment directories, global vs local configuration and resolution order, the config and experiment commands
Configuration reference	Protocol flags and the default index, search and Percolator parameters
Commands	Input file formats, the full command list, and the report command in detail
Output structure	The results directory layout and logging behaviour

Developer guidance is in CONTRIBUTING.md.

Getting help & contributing

If you come across any bugs/issues while using comMS, or if you have a feature request, please open an issue via GitHub.

Any contributions to this project are also very welcome! Specific guidance for developers is provided in CONTRIBUTING.md, please read this beforehand.

License

This repository is distributed under the GPL-3.0 license. See LICENSE for more information.

comMS documentation: Commands · Configuration · Configuration reference · Output structure · README