Skip to content

Convert Commands

Convert various mass spectrometry data formats to the QPX standard format.

Overview

The convert command group provides converters for multiple proteomics software outputs, enabling standardization of data formats for downstream analysis. All commands generate parquet-format output files following the QPX specification.

Shared metadata options. The commands diann, maxquant, fragpipe, mzidentml, openms-consensus, quantms-msstats, spectronaut and cdap accept five options: --software-name, --software-version, --software-config, --enrich-pride and --compute-integrity. --software-version and --software-config require --software-name. --enrich-pride needs --project-accession. Without it, or when PRIDE cannot be reached, the command prints a warning and continues. --compute-integrity covers the Parquet and h5ad files, not the .h5mu file. The steps run in this order: conversion, --fasta, --software-name, --enrich-pride, MuData, --compute-integrity. The --fasta option and MuData exist only on diann and openms-consensus.

Modifications. The converters write peptidoform in ProForma with Unimod accessions (PEPTM[UNIMOD:35]K). Modification names (maxquant, spectronaut) and delta masses (fragpipe, cdap) are resolved with the Unimod release that ships with pyopenms (ModificationsDB). A name is looked up among Unimod names and synonyms, with or without the vendor site suffix (Phospho (STY), Deamidation (NQ), Pyro-glu from E), plus a few vendor names Unimod lacks (GlyGly, TMT10plex, TMT16plex); a name Unimod does not know stays a name in the peptidoform, with square brackets replaced by parentheses, and is logged. A name for a terminus (Acetyl (Protein N-term), Amidated (Protein C-term)) is placed on that terminus. A mass gets the closest Unimod entry within 0.01 Da that Unimod defines at that residue or terminus. Entries of equal mass at the same site resolve only to the modification search engines are configured with (iTRAQ4plex UNIMOD:214, not mTRAQ:13C(3)15N(1) UNIMOD:889; Butyryl UNIMOD:1289, not Crotonaldehyde UNIMOD:253). Any other tie (Isovaleryl, 2-methylbutyryl and Pentanoyl on K) and a mass without an entry at that site, such as TMT6plex on Y, are kept as the signed mass ([+999.1234]; cdap writes [CHEMMOD:+999.123] and leaves calculated_mz null). OpenMS' own ModificationsDB entries (record ids from 99900) are not used. calculated_mz uses the same Unimod masses.

Available Commands

  • openms - Enrich native OpenMS -out_qpx output into a full QPX dataset
  • openms-consensus - Convert an OpenMS consensusXML (+ SDRF) to QPX (interim; pg intensity = unnormalized unique-peptide sum)
  • diann - Convert DIA-NN report to QPX format
  • diann-xic - Merge DIA-NN XIC exports into one QPX xic view
  • spectronaut - Convert Spectronaut report to QPX format
  • maxquant - Convert MaxQuant output to QPX format
  • fragpipe - Convert FragPipe output to QPX format
  • mzidentml - Convert mzIdentML file to PSM format
  • cdap - Convert CPTAC CDAP .psm files to QPX format
  • mz - Convert an mzML spectra directory to QPX mz.parquet (full spectra)
  • sdrf - Convert SDRF to sample and run parquet files
  • quantms-msstats - Convert QuantMS *_msstats_in.csv plus SDRF to QPX

diann

Convert DIA-NN report files to QPX format.

Description

Reads a DIA-NN report.tsv file and converts feature-level quantification data into QPX Parquet format. When --pg-matrix-path is provided, also produces protein group output. 

Parameters

ParameterTypeRequiredDefaultDescription
--report-path FILE Yes - DIA-NN report file path
--sdrf-file FILE Yes - SDRF metadata file path
--mzml-info-folder DIRECTORY No - Folder containing mzML info files (optional; scan/mz fields left empty if omitted). Its *_ms2_info.parquet files, when present, also produce the mz view of the feature-matched MS2 spectra.
--qvalue-threshold FLOAT No - Optional q-value threshold. Unset (the default) converts the DIA-NN report as reported — no filtering — since DIA-NN already FDR-filters its main report and every per-row q-value column is carried through for downstream filtering. When given, the feature and pg views keep only precursors with Q.Value below it; protein-group q-values are carried, not filtered.
--output-folder DIRECTORY Yes - Output directory for generated QPX files
--output-prefix TEXT No - Prefix for output file names
--pg-matrix-path FILE No - DIA-NN protein quantities matrix file (enables PG conversion)
--xic-folder DIRECTORY No - Optional folder containing DIA-NN *.xic.parquet exports (one per run). When given, merges them into a single {PREFIX}.xic.parquet view.
--xic-selection TEXT No targets What the XIC export contains: targets, targets_and_decoys or all.
--xic-window TEXT No apex Whether the XIC traces cover only the apex region or the full extraction window.
--xic-extraction-window-seconds FLOAT No - XIC extraction-window width in seconds, stored in the file footer when known.
--xic-qvalue-threshold FLOAT No - Q-value threshold used to select the exported XIC precursors, stored in the footer.
--max-memory TEXT No - Maximum memory limit (e.g. '16GB')
--max-cpus INTEGER No - Maximum number of threads
--project-accession TEXT No - PRIDE / ProteomeXchange accession (e.g. PXD020192)
--compression TEXT No zstd Parquet compression codec.
--diann-log FILE No - DIA-NN summary log file (version auto-detected from first line)
--fasta FILE No - Optional protein FASTA used for the search. When given, fills null pg.sequence_coverage, pg.molecular_weight and feature.pg_positions for target rows after conversion; proteins absent from it (e.g. DIA-NN internal decoys) stay null. See 'qpxc transform protein-properties'.
--mudata FLAG No - Write the dataset's MuData (.h5mu) view after conversion. Best-effort: a view that cannot be built is reported and the conversion still succeeds. Use --no-mudata to skip the build on very large datasets.
--verbose FLAG No - Enable verbose logging
--software-name TEXT No - Workflow that produced the input (e.g. nf-core/mhcquant). Sets dataset.software_name/software_version and adds a 'workflow' provenance step.
--software-version TEXT No - Version of --software-name.
--software-config FILE No - JSON file with the workflow parameters (e.g. Nextflow params.json), stored in the workflow provenance step's config.
--enrich-pride FLAG No - Fetch project title, description and PubMed ID from the PRIDE API after conversion (needs --project-accession; best-effort).
--compute-integrity FLAG No - Write file checksums, row counts and sizes for the output folder into dataset.parquet, as the last step.

Usage Examples

Basic Example - Feature Data

Convert a DIA-NN report with default settings:

# Feature conversion
qpxc convert diann \
    --report-path report.tsv \
    --sdrf-file data.sdrf.tsv \
    --mzml-info-folder ./mzml_info \
    --output-folder ./qpx_output

# Feature + protein groups
qpxc convert diann \
    --report-path report.tsv \
    --sdrf-file data.sdrf.tsv \
    --mzml-info-folder ./mzml_info \
    --pg-matrix-path report.pg_matrix.tsv \
    --output-folder ./qpx_output

# Feature + XIC traces (DIA-NN --xic exports)
qpxc convert diann \
    --report-path report.tsv \
    --sdrf-file data.sdrf.tsv \
    --xic-folder ./diann_xic \
    --output-folder ./qpx_output

Advanced Example

Convert with a q-value cutoff, mzML info and resource limits:

qpxc convert diann \
    --report-path tests/examples/diann/full/diann_report.tsv.gz \
    --qvalue-threshold 0.01 \
    --mzml-info-folder tests/examples/diann/full/mzml \
    --sdrf-file tests/examples/diann/full/PXD036609.sdrf.tsv \
    --output-folder ./output \
    --max-memory 8GB \
    --max-cpus 4 \
    --verbose

Protein Groups from PG Matrix

Convert DIA-NN protein groups using the pg_matrix file:

qpxc convert diann \
    --report-path tests/examples/diann/full/diann_report.tsv.gz \
    --pg-matrix-path tests/examples/diann/full/diann_report.pg_matrix.tsv \
    --sdrf-file tests/examples/diann/full/PXD036609.sdrf.tsv \
    --output-folder ./output \
    --max-memory 16GB \
    --max-cpus 8 \
    --verbose

XIC Traces from DIA-NN --xic Export

Merge the per-run *.xic.parquet files written by DIA-NN's --xic option into the dataset's single xic view:

qpxc convert diann \
    --report-path tests/examples/diann/full/diann_report.tsv.gz \
    --sdrf-file tests/examples/diann/full/PXD036609.sdrf.tsv \
    --xic-folder ./diann_xic \
    --output-folder ./output

Output Files

Output files generated:

  • Feature: {output-prefix}-{uuid}.feature.parquet (always produced)
  • Protein Group: {output-prefix}-{uuid}.pg.parquet (produced when --pg-matrix-path is provided)
  • Mass spectra: {output-prefix}.mz.parquet (produced when --mzml-info-folder contains *_ms2_info.parquet; feature-matched MS2 spectra only)
  • XIC: {output-prefix}.xic.parquet (produced when --xic-folder contains DIA-NN *.xic.parquet exports)
  • MuData: {output-prefix}.h5mu (written by default; --no-mudata skips it)

Common Issues

Issue: Out of memory errors with large files

  • Solution: Increase --max-memory parameter (e.g., 8GB, 16GB)

Issue: Slow processing

  • Solution: Increase --max-cpus to utilize more CPU cores

Issue: Missing mzML info files

  • Solution: Ensure all mzML info TSV files are in the specified folder with correct naming

Best Practices

  • Use Q-value threshold of 0.05 or lower for high-confidence results
  • Enable partitioning for large datasets to improve memory usage
  • Use verbose mode during initial testing to diagnose issues
  • Ensure SDRF file correctly matches sample names in DIA-NN report
  • For protein groups, ensure both report and pg_matrix files are from the same DIA-NN run

diann-xic

Merge DIA-NN per-run XIC exports into one dataset-level QPX xic.parquet.

Description

DIA-NN writes one ``*.xic.parquet`` per run when ``--xic`` is enabled. This command merges them into a single dataset-level ``{PREFIX}.xic.parquet``, with ``run_file_name`` distinguishing the runs. 

Parameters

ParameterTypeRequiredDefaultDescription
--xic-folder DIRECTORY Yes - Folder containing DIA-NN *.xic.parquet exports (one per run)
--label TEXT No LFQ Channel label written for every trace
--xic-selection TEXT No targets What the XIC export contains: targets, targets_and_decoys or all.
--xic-window TEXT No apex Whether the XIC traces cover only the apex region or the full extraction window.
--xic-extraction-window-seconds FLOAT No - XIC extraction-window width in seconds, stored in the file footer when known.
--xic-qvalue-threshold FLOAT No - Q-value threshold used to select the exported XIC precursors, stored in the footer.
--output-folder DIRECTORY Yes - Output directory for generated QPX files
--output-prefix TEXT No - Prefix for output file names
--verbose FLAG No - Enable verbose logging

Usage Example

qpxc convert diann-xic \
    --xic-folder ./diann_xic \
    --output-folder ./output \
    --output-prefix PXD014414 \
    --xic-selection targets \
    --xic-window apex \
    --xic-extraction-window-seconds 10 \
    --xic-qvalue-threshold 0.01

--xic-folder must contain the *.xic.parquet files written by DIA-NN's --xic option. All runs are merged into PXD014414.xic.parquet; run_file_name distinguishes them. The file footer records xic_selection, xic_window, xic_extraction_window_seconds, xic_qvalue_threshold, xic_smoothed, xic_zero_points, xic_rt_unit and transition_format. Use qpxc convert diann --xic-folder ... instead when you are also converting the DIA-NN report and want the XIC view in the same output folder.

Output Files

  • XIC: {output-prefix}.xic.parquet

spectronaut

Convert Spectronaut report files to QPX format.

Description

Reads a Spectronaut report TSV file and converts feature-level and protein-group quantification data into QPX Parquet format. \b

Parameters

ParameterTypeRequiredDefaultDescription
--report-path FILE Yes - Spectronaut report file path (TSV or Parquet)
--sdrf-file FILE No - SDRF metadata file path
--qvalue-threshold FLOAT No - Optional q-value threshold. Unset (the default) converts the report as reported — no filtering. When given, the feature view filters on the precursor q-value.
--output-folder DIRECTORY Yes - Output directory for generated QPX files
--output-prefix TEXT No - Prefix for output file names
--max-memory TEXT No - Maximum memory limit (e.g. '16GB')
--max-cpus INTEGER No - Maximum number of threads
--project-accession TEXT No - PRIDE / ProteomeXchange accession (e.g. PXD020192)
--compression TEXT No zstd Parquet compression codec.
--verbose FLAG No - Enable verbose logging
--software-name TEXT No - Workflow that produced the input (e.g. nf-core/mhcquant). Sets dataset.software_name/software_version and adds a 'workflow' provenance step.
--software-version TEXT No - Version of --software-name.
--software-config FILE No - JSON file with the workflow parameters (e.g. Nextflow params.json), stored in the workflow provenance step's config.
--enrich-pride FLAG No - Fetch project title, description and PubMed ID from the PRIDE API after conversion (needs --project-accession; best-effort).
--compute-integrity FLAG No - Write file checksums, row counts and sizes for the output folder into dataset.parquet, as the last step.

Usage Examples

Basic Example

Convert Spectronaut data with default settings:

# Feature + protein groups
qpxc convert spectronaut \
    --report-path report.tsv \
    --output-folder ./qpx_output

# With SDRF metadata
qpxc convert spectronaut \
    --report-path report.tsv \
    --sdrf-file data.sdrf.tsv \
    --output-folder ./qpx_output

With SDRF Metadata

qpxc convert spectronaut \
    --report-path report.tsv \
    --sdrf-file data.sdrf.tsv \
    --output-folder ./qpx_output \
    --qvalue-threshold 0.01 \
    --verbose

Large Dataset with Custom DuckDB Settings

qpxc convert spectronaut \
    --report-path large_report.tsv \
    --sdrf-file data.sdrf.tsv \
    --output-folder ./qpx_output \
    --max-memory 16GB \
    --max-cpus 8 \
    --verbose

Output Files

Output files generated:

  • Feature: {output-prefix}.feature.parquet (always produced)
  • Protein Group: {output-prefix}.pg.parquet (always produced)
  • Ontology: {output-prefix}.ontology.parquet (score CV terms)
  • Provenance: {output-prefix}.provenance.parquet (conversion metadata)

Supported Spectronaut Columns

The converter auto-detects column names from the Spectronaut report, supporting both standard and custom column naming. Key mapped columns include:

Spectronaut Column QPX Field Notes
R.FileName run_file_name File extensions auto-stripped
PEP.StrippedSequence sequence Bare amino acid sequence
EG.ModifiedSequence peptidoform Converted to ProForma notation
FG.Charge charge Precursor charge state
FG.Quantity intensities[0].intensity Raw precursor intensity
EG.Qvalue additional_scores Mapped to PSI-MS CV terms
PG.ProteinGroups pg_accessions Semicolon-delimited protein groups
PG.Quantity PG intensities Protein group quantity

Common Issues

Issue: European decimal separator (comma instead of period)

  • Solution: The converter auto-detects decimal separators by inspecting the EG.Qvalue column

Issue: Out of memory with large reports

  • Solution: Increase --max-memory (e.g., 16GB) and --max-cpus

Issue: Missing modifications in output

  • Solution: Ensure EG.ModifiedSequence column is present in the Spectronaut export

Best Practices

  • Export all required columns from Spectronaut (at minimum: R.FileName, PEP.StrippedSequence, EG.ModifiedSequence, FG.Charge, FG.Quantity, PG.ProteinGroups)
  • Provide SDRF file for complete sample and run metadata
  • Use Q-value threshold of 0.01 or 0.05 for high-confidence results
  • For large datasets (>10M rows), increase --max-memory and --max-cpus

maxquant

Convert MaxQuant output to QPX format.

Description

Reads MaxQuant result files (msms.txt, evidence.txt, proteinGroups.txt) and writes corresponding QPX Parquet files. 

Parameters

ParameterTypeRequiredDefaultDescription
--msms-file FILE No - MaxQuant msms.txt file (for PSM conversion)
--evidence-file FILE No - MaxQuant evidence.txt file (for feature conversion)
--protein-groups-file FILE No - MaxQuant proteinGroups.txt file (for PG conversion)
--sdrf-file FILE No - SDRF metadata file (required for feature and PG; its fixed modifications are added to PSM and feature peptidoforms)
--output-folder DIRECTORY Yes - Output directory for generated QPX files
--output-prefix TEXT No - Prefix for output file names
--structures TEXT No - Comma-separated list of structures to produce (psm, feature, pg). Default: all available.
--max-cpus INTEGER No - Maximum number of threads
--max-memory TEXT No - Maximum memory limit (e.g. '16GB')
--spectral-data FLAG No - Include spectral data fields in PSM output
--project-accession TEXT No - PRIDE / ProteomeXchange accession (e.g. PXD020192)
--compression TEXT No zstd Parquet compression codec.
--verbose FLAG No - Enable verbose logging
--software-name TEXT No - Workflow that produced the input (e.g. nf-core/mhcquant). Sets dataset.software_name/software_version and adds a 'workflow' provenance step.
--software-version TEXT No - Version of --software-name.
--software-config FILE No - JSON file with the workflow parameters (e.g. Nextflow params.json), stored in the workflow provenance step's config.
--enrich-pride FLAG No - Fetch project title, description and PubMed ID from the PRIDE API after conversion (needs --project-accession; best-effort).
--compute-integrity FLAG No - Write file checksums, row counts and sizes for the output folder into dataset.parquet, as the last step.

Usage Examples

Basic Example

Convert MaxQuant data with default settings:

# Convert everything
qpxc convert maxquant \
    --msms-file msms.txt \
    --evidence-file evidence.txt \
    --protein-groups-file proteinGroups.txt \
    --sdrf-file metadata.sdrf.tsv \
    --output-folder ./qpx_output

# Convert PSMs only
qpxc convert maxquant \
    --msms-file msms.txt \
    --output-folder ./qpx_output \
    --structures psm

PSM Data Only

qpxc convert maxquant \
    --msms-file tests/examples/maxquant/maxquant_simple/msms.txt \
    --output-folder ./output \
    --structures psm \
    --spectral-data \
    --output-prefix maxquant_psm

Feature Data with Protein Groups

qpxc convert maxquant \
    --evidence-file tests/examples/maxquant/maxquant_full/evidence.txt.gz \
    --protein-groups-file tests/examples/maxquant/maxquant_full/proteinGroups.txt \
    --sdrf-file tests/examples/maxquant/maxquant_full/PXD001819.sdrf.tsv \
    --output-folder ./output \
    --structures feature \
    --verbose

All Structures

qpxc convert maxquant \
    --msms-file tests/examples/maxquant/maxquant_full/msms.txt.gz \
    --evidence-file tests/examples/maxquant/maxquant_full/evidence.txt.gz \
    --protein-groups-file tests/examples/maxquant/maxquant_full/proteinGroups.txt \
    --sdrf-file tests/examples/maxquant/maxquant_full/PXD001819.sdrf.tsv \
    --output-folder ./output \
    --structures psm,feature,pg \
    --verbose

Output Files

Depending on --structures parameter:

  • PSM: {output-prefix}-{uuid}.psm.parquet
  • Feature: {output-prefix}-{uuid}.feature.parquet
  • Protein Group: {output-prefix}-{uuid}.pg.parquet

Common Issues

Issue: Memory errors with compressed evidence files

  • Solution: Increase available RAM

Issue: Missing Q-value information

  • Solution: Provide --protein-groups-file for accurate Q-value mapping

Issue: SDRF labels [...] are not channels of a TMT plex or ... describe a SILAC experiment

  • Solution: Each Reporter intensity N column is read as the channel at that position of the TMT or iTRAQ plex (TMT6 to TMTpro 18, iTRAQ 4 and 8; partial plexes too) that holds all SDRF comment[label] values, so labels from different plexes cannot be mapped. SILAC is not supported yet (#308). A conversion that writes a feature or pg view stops before writing any file; a PSM-only conversion reads no reporter columns and is not affected.

Best Practices

  • Use --structures to control which output files are generated
  • Always provide --protein-groups-file when available: features then take the protein group their Protein group IDs name, the membership the pg view carries
  • Ensure SDRF sample names match MaxQuant experiment names
  • Provide --sdrf-file with the PSM and feature conversions: MaxQuant leaves fixed modifications out of Modified sequence, and the SDRF's MT=fixed modifications (except TMT, iTRAQ and SILAC labels, which MaxQuant does not report as modifications) are added to the peptidoforms so they match calculated_mz
  • Use compressed files (.gz) to save disk space
  • Use --spectral-data flag if downstream analysis requires spectral information

fragpipe

Convert FragPipe output to QPX format.

Description

Reads FragPipe result files and converts them into QPX Parquet format. Supports psm.tsv, combined_ion.tsv, and combined_protein.tsv. 

Parameters

ParameterTypeRequiredDefaultDescription
--psm-file FILE No - FragPipe psm.tsv file
--ion-file FILE No - FragPipe combined_ion.tsv file (for feature conversion)
--pg-file FILE No - FragPipe combined_protein.tsv file (for PG conversion)
--sdrf-file FILE No - SDRF metadata file (for sample/run conversion)
--experiment-annotation-file FILE No - FragPipe experiment_annotation.tsv mapping experiments to member raw files
--output-folder DIRECTORY Yes - Output directory for generated QPX files
--output-prefix TEXT No - Prefix for output file names
--max-memory TEXT No - Maximum memory limit (e.g. '16GB')
--max-cpus INTEGER No - Maximum number of threads
--project-accession TEXT No - PRIDE / ProteomeXchange accession (e.g. PXD020192)
--compression TEXT No zstd Parquet compression codec.
--verbose FLAG No - Enable verbose logging
--software-name TEXT No - Workflow that produced the input (e.g. nf-core/mhcquant). Sets dataset.software_name/software_version and adds a 'workflow' provenance step.
--software-version TEXT No - Version of --software-name.
--software-config FILE No - JSON file with the workflow parameters (e.g. Nextflow params.json), stored in the workflow provenance step's config.
--enrich-pride FLAG No - Fetch project title, description and PubMed ID from the PRIDE API after conversion (needs --project-accession; best-effort).
--compute-integrity FLAG No - Write file checksums, row counts and sizes for the output folder into dataset.parquet, as the last step.

Usage Examples

Basic Example

Convert FragPipe PSM data with default settings:

# Convert PSMs only
qpxc convert fragpipe \
    --psm-file psm.tsv \
    --output-folder ./qpx_output

# Convert features + protein groups
qpxc convert fragpipe \
    --ion-file combined_ion.tsv \
    --pg-file combined_protein.tsv \
    --sdrf-file metadata.sdrf.tsv \
    --experiment-annotation-file experiment_annotation.tsv \
    --output-folder ./qpx_output

With Custom Settings

qpxc convert fragpipe \
    --psm-file /path/to/psm.tsv \
    --output-folder ./output \
    --output-prefix fragpipe_psm

Output Files

  • Output: {output-prefix}-{uuid}.psm.parquet
  • Format: Parquet file containing PSM data
  • Schema: Conforms to QPX PSM specification

mzidentml

Convert mzIdentML (.mzid) files to QPX PSM parquet format.

Description

Supports both standard mzIdentML (1.1/1.2) and mzIdentML 1.3 with cross-linking extensions (inter-peptide, looplinks, noncovalent). Produces a full QPX dataset including PSM, pepmap, provenance, ontology, and dataset metadata. 

Parameters

ParameterTypeRequiredDefaultDescription
--mzid-path FILE Yes - Input mzIdentML (.mzid) file path
--output-folder DIRECTORY Yes - Output directory for generated QPX files
--output-prefix TEXT No mzidentml Prefix for output file names
--mgf-path FILE No - Optional MGF file for spectra attachment
--include-spectra FLAG No - Attach mz_array and intensity_array from MGF to PSM records
--project-accession TEXT No - PRIDE / ProteomeXchange accession (e.g. PXD054720)
--compression TEXT No zstd Parquet compression codec.
--verbose FLAG No - Enable verbose logging
--software-name TEXT No - Workflow that produced the input (e.g. nf-core/mhcquant). Sets dataset.software_name/software_version and adds a 'workflow' provenance step.
--software-version TEXT No - Version of --software-name.
--software-config FILE No - JSON file with the workflow parameters (e.g. Nextflow params.json), stored in the workflow provenance step's config.
--enrich-pride FLAG No - Fetch project title, description and PubMed ID from the PRIDE API after conversion (needs --project-accession; best-effort).
--compute-integrity FLAG No - Write file checksums, row counts and sizes for the output folder into dataset.parquet, as the last step.

Usage Examples

Basic Example

Convert an mzIdentML file with default settings:

# Convert a standard mzIdentML file
qpxc convert mzidentml \
    --mzid-path results.mzid \
    --output-folder ./qpx_output

# Convert an XL-MS mzIdentML 1.3 file
qpxc convert mzidentml \
    --mzid-path crosslinks.mzid \
    --output-folder ./qpx_output \
    --output-prefix xl_experiment

# Convert with spectra from MGF
qpxc convert mzidentml \
    --mzid-path results.mzid \
    --mgf-path spectra.mgf \
    --include-spectra \
    --output-folder ./qpx_output

# Convert with project accession
qpxc convert mzidentml \
    --mzid-path results.mzid \
    --output-folder ./qpx_output \
    --project-accession PXD054720

With Spectral Data from Single mzML

qpxc convert mzidentml \
    --mzid-file /path/to/results.mzid \
    --mzml-file /path/to/spectra.mzML \
    --output-folder ./output \
    --spectral-data \
    --output-prefix psm_with_spectra

With Spectral Data from Multiple mzML Files

When your mzIdentML references multiple mzML files, use the --mzml-folder option:

qpxc convert mzidentml \
    --mzid-file /path/to/results.mzid.gz \
    --mzml-folder /path/to/mzml_files/ \
    --output-folder ./output \
    --spectral-data \
    --output-prefix psm_multi_mzml

The converter automatically matches PSMs to mzML files based on the run_file_name field in the mzIdentML. File matching is case-insensitive and supports both .mzML and .mzML.gz extensions.

Supported Native ID Formats

The converter supports multiple native ID formats for scan number extraction:

Format Vendor/Source Example
scan=XXX Thermo controllerType=0 controllerNumber=1 scan=12345
cycle=XXX Waters/Agilent sample=1 period=1 cycle=1055 experiment=4
index=XXX Generic index=500
spectrum=XXX Various spectrum=999

Output Files

  • Output: {output-prefix}-{uuid}.psm.parquet
  • Format: Parquet file containing PSM-level data
  • Schema: Conforms to QPX PSM specification

Supported mzIdentML Features

  • Compressed files: Supports both .mzid and .mzid.gz formats
  • Modifications: Full support for UNIMOD and custom modifications
  • Scores: Extracts all CV-term scores with higher_better flag annotation
  • Decoy detection: Automatic detection via isDecoy attribute
  • Multi-file support: Handles mzIdentML referencing multiple spectra files

Best Practices

  • Use --mzml-folder when mzIdentML references multiple mzML files
  • Ensure mzML file names match those referenced in mzIdentML (case-insensitive)
  • Use compressed .mzid.gz files to save disk space
  • Enable --spectral-data only when spectral arrays are needed for downstream analysis

Common Issues

Issue: No spectra attached from mzML folder

  • Solution: Verify mzML file names match run_file_name in mzIdentML

Issue: zlib errors when reading mzML.gz files

  • Solution: Decompress mzML.gz files or re-download if corrupted

Issue: Scan numbers not extracted correctly

  • Solution: Check if your native ID format is supported; the converter auto-detects common formats

cdap

Convert CPTAC CDAP .psm files to QPX format.

Description

Reads all *.psm tab-separated files in a study directory (e.g. PDC000440/) and writes psm.parquet, feature.parquet, and pg.parquet. 

Parameters

ParameterTypeRequiredDefaultDescription
--psm-dir DIRECTORY Yes - Directory containing CDAP *.psm files for one study
--output-folder DIRECTORY Yes - Output directory for generated QPX files
--output-prefix TEXT No cdap Prefix for output file names
--structures TEXT No - Comma-separated list of structures to produce (psm, feature, pg). Default: all.
--project-accession TEXT No - PDC / ProteomeXchange accession (e.g. PDC000227)
--compression TEXT No zstd Parquet compression codec.
--max-memory TEXT No - Maximum memory limit (e.g. '16GB')
--max-cpus INTEGER No - Maximum number of threads
--verbose FLAG No - Enable verbose logging
--software-name TEXT No - Workflow that produced the input (e.g. nf-core/mhcquant). Sets dataset.software_name/software_version and adds a 'workflow' provenance step.
--software-version TEXT No - Version of --software-name.
--software-config FILE No - JSON file with the workflow parameters (e.g. Nextflow params.json), stored in the workflow provenance step's config.
--enrich-pride FLAG No - Fetch project title, description and PubMed ID from the PRIDE API after conversion (needs --project-accession; best-effort).
--compute-integrity FLAG No - Write file checksums, row counts and sizes for the output folder into dataset.parquet, as the last step.

Usage Examples

Basic Example

Convert one CPTAC CDAP study directory with default settings:

# Convert a single CPTAC study
qpxc convert cdap \
    --psm-dir /data/CPTAC/PDC000440 \
    --output-folder ./qpx_output/PDC000440 \
    --project-accession PDC000440

# Only produce PSM and Feature (skip PG)
qpxc convert cdap \
    --psm-dir /data/CPTAC/PDC000440 \
    --output-folder ./qpx_output \
    --structures psm,feature

Select Output Structures

qpxc convert cdap \
    --psm-dir /data/CPTAC/PDC000440 \
    --output-folder ./qpx_output/PDC000440 \
    --project-accession PDC000440 \
    --structures psm,feature

Output Files

Depending on --structures:

  • PSM: {output-prefix}.psm.parquet
  • Feature: {output-prefix}.feature.parquet
  • Protein Group: {output-prefix}.pg.parquet
  • Ontology: {output-prefix}.ontology.parquet
  • Provenance: {output-prefix}.provenance.parquet
  • Dataset: {output-prefix}.dataset.parquet

Best Practices

  • Point --psm-dir to one CPTAC study directory containing *.psm files
  • Use --structures to skip views that are not needed
  • Increase --max-memory and --max-cpus for full-scale CPTAC studies

mz

Convert a directory of mzML spectra to a QPX mz.parquet (full spectra).

Description

Reads every .mzML / .mzML.gz file in --mzml-dir and writes scan-level spectral data (m/z and intensity arrays, precursor info) to a single mz.parquet. Each spectrum carries run_file_name + scan so it can be linked back to PSM / feature records. 

Parameters

ParameterTypeRequiredDefaultDescription
--mzml-dir DIRECTORY Yes - Directory containing mzML / mzML.gz spectra files (one study)
--output FILE Yes - Output .mz.parquet file path
--ms-levels TEXT No - Comma-separated MS levels to include (e.g. '2' or '1,2'). Default: all levels.
--verbose FLAG No - Enable verbose logging

Usage Examples

All MS Levels (full spectra)

qpxc convert mz \
    --mzml-dir /data/CPTAC/PDC000109/mzml \
    --output ./qpx_output/PDC000109.mz.parquet

MS2 Only

qpxc convert mz \
    --mzml-dir /data/CPTAC/PDC000109/mzml \
    --output ./PDC000109.mz.parquet \
    --ms-levels 2

Output Files

A single mz.parquet with one row per spectrum:

  • id, run_file_name, scan — spectrum identity and linkage to PSM / feature
  • ms_level, scan_start_time, total_ion_current, centroid
  • precursors — precursor m/z, charge, isolation window (MS2+)
  • mz, intensity — full peak arrays

Best Practices

  • Reads .mzML and .mzML.gz directly (no manual decompression needed)
  • Omit --ms-levels (or use 1,2) for full spectra; precursor-level LFQ reanalysis (e.g. quantms) needs MS1 in addition to MS2
  • Each spectrum carries run_file_name + scan so it joins back to PSM / feature

sdrf

Convert SDRF metadata files to QPX sample and run parquet format.

Description

Reads a Sample and Data Relationship Format (SDRF) file and produces the QPX sample and run data structures as Parquet files. 

Parameters

ParameterTypeRequiredDefaultDescription
--sdrf-file FILE Yes - SDRF metadata file path
--output-folder DIRECTORY Yes - Output directory for generated QPX files
--output-prefix TEXT No sdrf Prefix for output file names
--compression TEXT No zstd Parquet compression codec.
--verbose FLAG No - Enable verbose logging

Usage Examples

Basic Example

Convert SDRF metadata with default settings:

qpxc convert sdrf \
    --sdrf-file metadata.sdrf.tsv \
    --output-folder ./qpx_output

Output Files

  • Sample: {output-prefix}-{uuid}.sample.parquet
  • Run: {output-prefix}-{uuid}.run.parquet
  • Format: Parquet files containing sample and run metadata
  • Schema: Conforms to QPX sample and run specifications

Best Practices

  • Ensure SDRF file follows the PRIDE SDRF specifications
  • Use verbose mode to diagnose parsing issues
  • The converter automatically maps SDRF characteristics to QPX ontology terms

quantms-msstats

Convert a QuantMS-generated *_msstats_in.csv table and its SDRF metadata to QPX. The SDRF is required and is authoritative for run, sample, and label mapping.

Description

Produces Feature, Sample, Run, Dataset, Provenance, and Ontology Parquet files. MSstats does not contain the evidence required to produce PSM or protein-group views, so those views are intentionally not generated. 

Parameters

ParameterTypeRequiredDefaultDescription
--msstats-file FILE Yes - QuantMS-generated *_msstats_in.csv file path
--sdrf-file FILE Yes - SDRF metadata file path
--output-folder DIRECTORY Yes - Output directory for generated QPX files
--output-prefix TEXT No - Prefix for output file names
--project-accession TEXT No - PRIDE / ProteomeXchange accession (e.g. PXD007683)
--max-memory TEXT No - Maximum DuckDB memory limit (e.g. '16GB')
--max-cpus INTEGER No - Maximum number of DuckDB threads
--compression TEXT No zstd Parquet compression codec.
--verbose FLAG No - Enable verbose logging
--software-name TEXT No - Workflow that produced the input (e.g. nf-core/mhcquant). Sets dataset.software_name/software_version and adds a 'workflow' provenance step.
--software-version TEXT No - Version of --software-name.
--software-config FILE No - JSON file with the workflow parameters (e.g. Nextflow params.json), stored in the workflow provenance step's config.
--enrich-pride FLAG No - Fetch project title, description and PubMed ID from the PRIDE API after conversion (needs --project-accession; best-effort).
--compute-integrity FLAG No - Write file checksums, row counts and sizes for the output folder into dataset.parquet, as the last step.

Usage Example

qpxc convert quantms-msstats \
    --msstats-file PXD007683.sdrf_openms_design_msstats_in.csv \
    --sdrf-file PXD007683.sdrf.tsv \
    --output-folder ./qpx_output \
    --project-accession PXD007683

Output and validation

  • Produces feature, sample, run, dataset, ontology, and provenance Parquet files.
  • Does not produce psm.parquet because MSstats does not contain complete spectrum-identification evidence.
  • Does not produce pg.parquet; protein aggregation remains a downstream analysis step.
  • Supports QuantMS ProteinName, PeptideSequence, Charge/PrecursorCharge, Intensity, Run/Reference, optional RetentionTime, and optional Channel columns.
  • Resolves Run and Reference through SDRF aliases and rejects missing, ambiguous, or conflicting mappings.
  • Collapses TMT/iTRAQ channel rows into one Feature while retaining RT and scan location when present.
  • Rejects conflicting intensity values for the same Feature and channel instead of selecting or summing them.

openms

Enrich native OpenMS -out_qpx Parquet output into a full QPX dataset.

Description

DEPRECATED: Some OpenMS exporters assign PSMs to the first run or emit conflicting identities (OpenMS#9872, OpenMS#9871). Prefer ``qpxc convert openms-consensus`` to read the original consensusXML directly. With --consensusxml, uniquely matching spectrum evidence restores PSM runs. Missing or ambiguous spectrum matches fail before existing core outputs are replaced. Duplicate identities are retained with warnings; use ``qpxc validate`` to report them as errors. Rows are not discarded or assigned arbitrary IDs to resolve conflicts. Validates the existing psm/feature/pg parquet files, copies them to the output folder, and generates the missing metadata tables (run, sample, ontology, provenance, dataset) from the SDRF file. \b

Parameters

ParameterTypeRequiredDefaultDescription
--qpx-dir DIRECTORY Yes - Directory containing OpenMS -out_qpx parquet files (*.psm.parquet, *.feature.parquet, *.pg.parquet)
--sdrf-file FILE Yes - SDRF metadata file path (for sample/run generation)
--consensusxml FILE No - OpenMS .consensusXML (the -out_cxml companion of -out_qpx); its ColumnHeaders give the authoritative channel count/order for relabeling. Peptide identifications, when present, recover PSM runs using exact spectrum matches.
--output-folder DIRECTORY Yes - Output directory for the full QPX dataset
--output-prefix TEXT No openms Prefix for output file names
--project-accession TEXT No - PRIDE / ProteomeXchange accession (e.g. PXD001819)
--enrich-pride FLAG No - Fetch project metadata from PRIDE API after conversion
--compression TEXT No zstd Parquet compression codec.
--verbose FLAG No - Enable verbose logging

Usage Examples

# Enrich OpenMS QPX output
qpxc convert openms \\
    --qpx-dir ./openms_qpx_output \\
    --sdrf-file metadata.sdrf.tsv \\
    --output-folder ./qpx_full

# With project accession
qpxc convert openms \\
    --qpx-dir ./openms_qpx_output \\
    --sdrf-file metadata.sdrf.tsv \\
    --output-folder ./qpx_full \\
    --project-accession PXD001819

Output Files

  • Upgrades and validates the OpenMS psm, feature, and pg Parquet files found in --qpx-dir, normalizing run references while preserving supplied IDs.
  • Recovers PSM runs from exact spectrum evidence when the companion --consensusxml contains peptide identifications. Missing or ambiguous spectrum matches stop conversion before existing core outputs are replaced.
  • Preserves records with duplicate IDs and reports warnings without deduplicating rows or inventing replacement IDs. qpxc validate reports these duplicates as errors.
  • Generates run, sample, ontology, provenance, and dataset views.
  • Generates a MuData file when the converted quantification views are sufficient for export.

openms-consensus

Description

Convert an OpenMS .consensusXML (optionally with an SDRF) directly to QPX. This is the interim quantms production path while OpenMS -out_qpx is not yet emitting QPX format 1.1. The consensusXML carries per-run peptide-feature intensities, PSMs, and the protein-inference graph; the SDRF supplies sample/label/fraction metadata and the grouped_runs quantification units.

Several consensusXML files (for example one per sample group, as nf-core/mhcquant writes them) can be converted into one dataset by giving --consensusxml a comma-separated list. Each file is read with its own column-to-run mapping and identification metadata; feature, PSM and pg rows go into the same views, pg spans all inputs, and provenance lists every input file. No run may appear in more than one input.

Runs are taken from the consensusXML column headers. A single-run map promoted by FileConverter has no column filename; when the identifications record exactly one primary MS run, that run's name is used. When the same group-merged identifications were copied into every run's map (FeatureFinderIdentification given a merged idXML, then linked), each copy is attributed to the run its spectrum came from (id_merge_index into its own ProteinIdentification's spectra_data), so every spectrum yields one PSM. Consensus features that are identical in every feature identity column (two isobaric targets linked to the same peak) yield one feature row, from the higher-quality consensus feature.

If PSM output is requested but no exportable PSM records remain (for example, the identifications lack spectrum references), the converter logs a warning and does not create psm.parquet or register it in the returned outputs or provenance. Other requested views are still exported. A PSM-only request with no exportable records completes with a warning and no output files.

Protein properties are taken from the group's existing anchor_protein: ProteinHit.coverage populates pg.sequence_coverage (percent), and Posterior Probability_score is retained in pg.additional_scores as posterior_probability with higher_better: true. These describe the representative protein, not an aggregate probability or coverage of the group. Missing or unknown values remain null. If repeated records for that accession contain conflicting values, the conflicting field remains null; values from other group members are not substituted. Both consensusXML readers use this mapping.

pg.molecular_weight is the theoretical average molecular weight of that same anchor's complete, unmodified ProteinHit.sequence, in kDa. It remains null when the sequence is absent, contains ambiguous residues such as B/Z/X or modification notation, or conflicts across records for the anchor. U/O and the isobaric I/L code J are supported. Other group members and identified peptides are not used to reconstruct the sequence; this path does not load a FASTA.

feature.pg_positions retains the assigned peptide's known positions within the resolved protein group. OpenMS's zero-based inclusive coordinates are converted to QPX's one-based inclusive coordinates. Repeated evidence is deduplicated, while distinct positions for the same protein are preserved. Unknown positions and proteins without direct peptide evidence are omitted. Positions come from the run's own identifications when available; otherwise matching identifications on the consensus feature can supply sequence positions. feature.id_run_file_name is populated only when the run has a resolved direct identification of the exported peptide with a spectrum reference. Transferred features without their own identification, unresolved source runs and conflicting peptide assignments keep this field null.

Protein intensity is an interim, unnormalized rollup

The consensusXML has no protein-level abundance — that quantity lived only in the mzTab (protein_abundance_assay, from ProteinQuantifier). Until OpenMS -out_qpx provides the authoritative number, each (protein group, grouped_runs, label) row's intensity is a stopgap we compute ourselves: the unnormalized sum of the group's unique peptides for that channel (the quantms unique_peptides policy, no normalization). Every quantified row carries a quantification_method cv_param (unnormalized_unique_peptide_sum) so it is never mistaken for the real quant, and rows stay intensity-null where a group has no unique-peptide signal. Use --pg-top 3 to mirror the quantms ProteomicsLFQ/IsobaricWorkflow default (top-3 peptides) instead of summing all.

Parameters

ParameterTypeRequiredDefaultDescription
--consensusxml TEXT Yes - OpenMS .consensusXML file (peptide feature intensities + IDs + protein inference), or a comma-separated list of files (e.g. one per sample group) to convert into one dataset; no run may appear in more than one file.
--sdrf-file FILE No - SDRF metadata (run/sample views + grouped_runs fraction grouping). Optional.
--output-folder DIRECTORY Yes - Output directory for the QPX views.
--output-prefix TEXT No openms
--structures TEXT No feature,psm,pg,run,sample Comma-separated views to write (run/sample require --sdrf-file).
--pg-top INTEGER No 0 Peptides used for the interim pg intensity (unnormalized unique-peptide sum): 0 = all; 3 mirrors the quantms ProteomicsLFQ/IsobaricWorkflow default.
--streaming FLAG No - Force the low-memory streaming reader on/off. Default: auto (streaming for consensusXML files > 4 GB). The in-memory reader peaks at ~6-7x the file size in RAM; streaming uses about half that and takes about twice as long.
--verbose FLAG No - Enable verbose logging.
--project-accession TEXT No - PRIDE / ProteomeXchange accession (e.g. PXD001819)
--include-unassigned-psms FLAG No - Keep unassigned peptide identifications by default to preserve identification evidence. Use --no-include-unassigned-psms to exclude them. Feature links are only written when both feature and PSM views are exported; a null feature_id means no recorded link. Protein inference uses every identification either way.
--compression TEXT No zstd Parquet compression codec.
--fasta FILE No - Optional protein FASTA used for the search. When given, fills null pg.sequence_coverage, pg.molecular_weight and feature.pg_positions for target rows after conversion; proteins absent from it (e.g. DIA-NN internal decoys) stay null. See 'qpxc transform protein-properties'.
--mudata FLAG No - Write the dataset's MuData (.h5mu) view after conversion. Best-effort: a view that cannot be built is reported and the conversion still succeeds. Use --no-mudata to skip the build on very large datasets.
--software-name TEXT No - Workflow that produced the input (e.g. nf-core/mhcquant). Sets dataset.software_name/software_version and adds a 'workflow' provenance step.
--software-version TEXT No - Version of --software-name.
--software-config FILE No - JSON file with the workflow parameters (e.g. Nextflow params.json), stored in the workflow provenance step's config.
--enrich-pride FLAG No - Fetch project title, description and PubMed ID from the PRIDE API after conversion (needs --project-accession; best-effort).
--compute-integrity FLAG No - Write file checksums, row counts and sizes for the output folder into dataset.parquet, as the last step.

Usage Examples

qpxc convert openms-consensus \
  --consensusxml results.consensusXML \
  --sdrf-file experiment.sdrf.tsv \
  --output-folder ./qpx_output \
  --output-prefix PXD001819

Several consensusXML files into one dataset:

qpxc convert openms-consensus \
  --consensusxml PBMC007_1_resolved.consensusXML,PBMC009_1_resolved.consensusXML \
  --sdrf-file PXD011628.sdrf.tsv \
  --structures feature,psm,run,sample \
  --output-folder ./qpx_output \
  --output-prefix PXD011628

Record the workflow, its parameters and PRIDE metadata:

qpxc convert openms-consensus \
  --consensusxml results.consensusXML \
  --sdrf-file experiment.sdrf.tsv \
  --output-folder ./qpx_output \
  --output-prefix PXD001819 \
  --project-accession PXD001819 \
  --software-name nf-core/mhcquant \
  --software-version 3.1.0 \
  --software-config params.json \
  --enrich-pride

Output Files

  • <prefix>.feature.parquet — one row per (peptidoform, charge, run, rt) with per-run/channel intensities.
  • <prefix>.psm.parquet — one row per spectrum match (scan, PEP, q-value, decoy).
  • <prefix>.pg.parquet — protein groups (pg_accessions, grouped_runs, peptide/feature counts, global_qvalue, decoy, genes); one row per channel with a populated label and an interim intensity = unnormalized sum of the group's unique peptides (stamped with a quantification_method cv_param; null where a group has no unique-peptide signal). See --pg-top.
  • <prefix>.run.parquet, <prefix>.sample.parquet — from the SDRF (when provided).
  • <prefix>.h5mu — the dataset's MuData view, written by default; disable with --no-mudata. Best-effort: a view that cannot be built is reported and the conversion still succeeds, because the Parquet views are the dataset's source of truth.