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.

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
• 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

Parameter	Type	Required	Default	Description
--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)
--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 view filters on precursor Q.Value and the pg view on PG-level q-value at their own levels.
--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)
--protein-file	FILE	No	-	Protein file for filtering
--partitions	TEXT	No	-	Field(s) for splitting output files (comma-separated)
--max-memory	TEXT	No	-	Maximum memory limit (e.g. '16GB')
--max-cpus	INTEGER	No	-	Maximum number of threads
--batch-size	INTEGER	No	100	Number of files to process simultaneously
--standardized-intensities	FLAG	No	-	Calculate standardized intensity metrics for PG output
--project-accession	TEXT	No	-	PRIDE / ProteomeXchange accession (e.g. PXD020192)
--enrich-pride	FLAG	No	-	Fetch project metadata from PRIDE API after conversion
--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

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 \
    --standardized-intensities

Advanced Example with Partitioning

Convert with file partitioning based on run_file_name:

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 \
    --partitions run_file_name \
    --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

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)
• 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

---

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

Parameter	Type	Required	Default	Description
--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)
--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

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

Parameter	Type	Required	Default	Description
--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)
--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.
--protein-file	FILE	No	-	Protein list file for filtering feature output
--batch-size	INTEGER	No	100000	Processing batch size
--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
--standardized-intensities	FLAG	No	-	Calculate standardized intensity metrics for PG output
--project-accession	TEXT	No	-	PRIDE / ProteomeXchange accession (e.g. PXD020192)
--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
--fixed-mod-only	FLAG	No	-	Only include features with fixed modifications (Unmodified or Carbamidomethyl C)

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 \
    --batch-size 500000 \
    --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 \
    --batch-size 500000 \
    --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: Reduce --batch-size or increase available RAM

Issue: Missing Q-value information

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

Best Practices

• Use --structures to control which output files are generated
• Always provide --protein-groups-file when available for better data quality
• Ensure SDRF sample names match MaxQuant experiment names
• Use compressed files (.gz) to save disk space
• Adjust --batch-size based on available memory
• 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

Parameter	Type	Required	Default	Description
--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
--batch-size	INTEGER	No	1000000	Processing batch size
--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)
--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

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 \
    --msms-file /path/to/psm.tsv \
    --output-folder ./output \
    --batch-size 500000 \
    --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

Parameter	Type	Required	Default	Description
--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)
--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

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

Parameter	Type	Required	Default	Description
--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.
--batch-size	INTEGER	No	200000	Processing batch size
--project-accession	TEXT	No	-	PDC / ProteomeXchange accession (e.g. PDC000227)
--compression	TEXT	No	zstd	Parquet compression codec.
--max-memory	TEXT	No	16GB	Maximum memory limit (e.g. '16GB')
--max-cpus	INTEGER	No	4	Maximum number of threads
--verbose	FLAG	No	-	Enable verbose logging

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
• Use --batch-size to tune processing throughput for large study directories

---

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

Parameter	Type	Required	Default	Description
--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

Parameter	Type	Required	Default	Description
--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

Parameter	Type	Required	Default	Description
--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	16GB	Maximum DuckDB memory limit
--max-cpus	INTEGER	No	4	Maximum number of DuckDB threads
--batch-size	INTEGER	No	50000	Number of Feature records written per batch
--compression	TEXT	No	zstd	Parquet compression codec.
--verbose	FLAG	No	-	Enable verbose logging

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: OpenMS -out_qpx mis-assigns every PSM's run_file_name to the first run (OpenMS#9872) and emits duplicate PSMs (OpenMS#9871). Use ``qpxc convert openms-consensus`` — it reads the consensusXML directly and resolves the correct run per PSM. This command is kept for now and will be reconsidered once OpenMS ships an -out_qpx with the correct per-PSM run. 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

Parameter	Type	Required	Default	Description
--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.
--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

• Copies and validates the OpenMS psm, feature, and pg Parquet files found in --qpx-dir.
• 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

Option	Required	Description
--consensusxml	yes	OpenMS .consensusXML file, or a comma-separated list of files to write into one dataset.
--sdrf-file	no	SDRF metadata (run/sample views + grouped_runs fraction grouping).
--output-folder	yes	Output directory for the QPX views.
--output-prefix	no	Prefix for output file names (default openms).
--structures	no	Comma-separated views (default feature,psm,pg,run,sample; run/sample require --sdrf-file).
--pg-top	no	Peptides used for the interim pg intensity: 0 (default) sums all unique peptides; 3 mirrors the quantms ProteomicsLFQ/IsobaricWorkflow default.

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

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.

---

Related Commands

• Transform Commands - Further process converted data
• Visualization Commands - Create plots from converted data
• Statistics Commands - Generate statistics from converted data