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

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.

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.
`--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

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

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