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]). 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_qpxoutput into a full QPX dataset - openms-consensus - Convert an OpenMS consensusXML (+ SDRF) to QPX (interim; pg intensity = OpenMS abundance or 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
- proteome-discoverer - Convert Proteome Discoverer text exports to QPX format
- mzidentml - Convert mzIdentML file to PSM format
- cdap - Convert CPTAC CDAP
.psmfiles 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.csvplus SDRF to QPX
Memory¶
--max-memory limits DuckDB's buffer pool. Above that limit DuckDB spills to --temp-dir, so a lower limit usually gives a lower peak, while the Python side of the converter comes on top in every case.
| Converter | Options | What sets the peak | If it runs out of memory |
|---|---|---|---|
diann |
--max-memory |
DuckDB, plus Python columns of about one million report rows at a time. A 10× Parquet report peaked at 3.8 GB by default or with 8GB, and at 2.4 GB with 2GB |
Lower --max-memory and put --temp-dir on a large disk. Convert a Parquet report rather than a TSV one |
spectronaut, cdap, quantms-msstats |
--max-memory |
DuckDB plus one batch of Python rows | Lower --max-memory and put --temp-dir on a large disk |
proteome-discoverer |
--max-memory |
DuckDB holds the PSM export twice, once per view; Proteins.txt is read whole in pandas |
Lower --max-memory, then use a machine with more RAM |
fragpipe |
--max-memory |
DuckDB, batches in pandas and the protein table | Lower --max-memory, then use a machine with more RAM |
maxquant |
--max-memory, with no real effect |
Python batches of 100,000 rows and the deduplicated tables | Use a machine with more RAM; a larger --max-memory does not help |
mzidentml |
None | The parsed document and the spectra index | Use a machine with more RAM |
openms-consensus |
--streaming |
The in-memory reader peaks near 7× the file size. The streaming reader is the default above 1 GB | Force --streaming |
Writing the output as Hive partitions does not lower the conversion's peak: partition afterwards (Hive partitioning).
diann¶
Convert DIA-NN report files to QPX format.
Description¶
Reads a DIA-NN report.tsv file and converts its precursor and protein-group quantification data into QPX Parquet format.
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). 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 |
--fragments |
FLAG | No | - | Also write the fragment view, from Fragment.Quant.* (1.x) or Fr.N.* (2.x --export-quant) |
--output-prefix |
TEXT | No | - | Prefix for output file names |
--pg-matrix-path |
FILE | No | - | DIA-NN protein-group matrix (optional). The pg view comes from the report; the matrix fills a label-free group's MaxLFQ when the report lacks it. |
--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 | - | DuckDB memory limit (e.g. '16GB'); the converter's Python row batches come on top |
--max-cpus |
INTEGER | No | - | Maximum number of threads |
--temp-dir |
DIRECTORY | No | .tmp in the output folder, or in the working directory without one | Directory for DuckDB spill files (default: .tmp in the output folder, or in the working directory without one) |
--project-accession |
TEXT | No | - | PRIDE / ProteomeXchange accession (e.g. PXD020192) |
--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 and protein-group conversion
qpxc convert diann \
--report-path report.tsv \
--sdrf-file data.sdrf.tsv \
--mzml-info-folder ./mzml_info \
--output-folder ./qpx_output
# With the protein-group matrix
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 with the PG Matrix¶
The pg view comes from the report. The pg_matrix file is optional: it fills the MaxLFQ quantity of a label-free group the report has none for.
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}.feature.parquet(always produced) - Protein Group:
{output-prefix}.pg.parquet(produced with--pg-matrix-path) - Peptide-protein map:
{output-prefix}.pepmap.parquet(every protein inProtein.Idsfor each converted peptidoform) - Mass spectra:
{output-prefix}.mz.parquet(produced when--mzml-info-foldercontains*_ms2_info.parquet; feature-matched MS2 spectra only) - XIC:
{output-prefix}.xic.parquet(produced when--xic-foldercontains DIA-NN*.xic.parquetexports) - MuData:
{output-prefix}.h5mu(written by default;--no-mudataskips it)
Common Issues¶
Issue: Out of memory errors with large files
- Solution: Lower
--max-memory, do not raise it: see Memory. A Parquet report is read in place; a TSV report is first converted once to a temporary Parquet file in the temp directory (--temp-dir).
Issue: Slow processing
- Solution: Increase
--max-cpusto 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
- See Memory for large reports, and Hive partitioning for partitioning the output afterwards
- Use verbose mode during initial testing to diagnose issues
- Ensure SDRF file correctly matches sample names in DIA-NN report
- When passing a pg_matrix, ensure it comes from the same DIA-NN run as the report
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¶
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
--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.
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 |
--fragments |
FLAG | No | - | Also write the report's F.* columns as the fragment view |
--output-prefix |
TEXT | No | - | Prefix for output file names |
--max-memory |
TEXT | No | - | DuckDB memory limit (e.g. '16GB'); the converter's Python row batches come on top |
--max-cpus |
INTEGER | No | - | Maximum number of threads |
--temp-dir |
DIRECTORY | No | .tmp in the output folder, or in the working directory without one | Directory for DuckDB spill files (default: .tmp in the output folder, or in the working directory without one) |
--project-accession |
TEXT | No | - | PRIDE / ProteomeXchange accession (e.g. PXD020192) |
--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
Report Layouts¶
Both Spectronaut layouts are read: the long report and the pivot report, whose
columns are one per run and quantity ([1] run.raw.EG.Channel1Quantity). A
pivot report is melted to one row per precursor and run, and a run where all of
a precursor's quantities are Filtered has no feature row. Pivot reports
usually carry no scores, so --qvalue-threshold warns and applies no filter
when EG.Qvalue is absent.
EG.Channel<N>Quantity columns become one intensities entry per label.
Spectronaut does not name its channels: they are assumed lightest first, and
take the SDRF's SILAC labels in that order, or SILAC light, medium and
heavy without an SDRF. If channel 1 of your workflow is not the lightest
label, the labels are wrong. Check them against the workflow's labeling setup.
A report converts to the views it has columns for, and warns about the others.
A report with channels writes no pg view, because PG.Quantity is not per
channel. A protein-level report, without precursor columns, writes no feature
view.
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.Qvaluecolumn
Issue: Out of memory with large reports
- Solution: Lower
--max-memoryso DuckDB spills to disk, as Memory describes
Issue: Missing modifications in output
- Solution: Ensure
EG.ModifiedSequencecolumn 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
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) |
--sites-file |
FILE | No | - | MaxQuant |
--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 | - | DuckDB memory limit (e.g. '16GB'); the converter's Python row batches come on top |
--temp-dir |
DIRECTORY | No | .tmp in the output folder, or in the working directory without one | Directory for DuckDB spill files (default: .tmp in the output folder, or in the working directory without one) |
--spectral-data |
FLAG | No | - | Include spectral data fields in PSM output |
--project-accession |
TEXT | No | - | PRIDE / ProteomeXchange accession (e.g. PXD020192) |
--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
Modification sites¶
--sites-file converts a <modification>Sites.txt table into the site view. Repeat it for several modifications. Each experiment's runs come from --evidence-file or the SDRF.
qpxc convert maxquant \
--evidence-file evidence.txt \
--protein-groups-file proteinGroups.txt \
--sites-file "Phospho (STY)Sites.txt" \
--output-folder ./qpx_output
Output Files¶
Depending on --structures parameter:
- PSM:
{output-prefix}.psm.parquet - Feature:
{output-prefix}.feature.parquet - Protein Group:
{output-prefix}.pg.parquet - Peptide-protein map:
{output-prefix}.pepmap.parquet, fromProteinsofevidence.txt - Protein:
{output-prefix}.protein.parquet, fromproteinGroups.txt - Site:
{output-prefix}.site.parquet, with--sites-file
Common Issues¶
Issue: Memory errors with large evidence files
- Solution: Use a machine with more RAM:
--max-memorydoes not change MaxQuant's peak (Memory)
Issue: Missing Q-value information
- Solution: Provide
--protein-groups-filefor accurate Q-value mapping
Issue: The SDRF TMT labels [...] match no TMT plex
- Solution: Each
Reporter intensity Ncolumn 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 SDRFcomment[label]values, so labels from different plexes cannot be mapped. Every conversion given--sdrf-file, a PSM-only one too, resolves the plex first and stops before writing any file.
Best Practices¶
- Use
--structuresto control which output files are generated - Always provide
--protein-groups-filewhen available: features then take the protein group theirProtein group IDsname, the membership the pg view carries - Ensure SDRF sample names match MaxQuant experiment names
- Provide
--sdrf-filewith the PSM and feature conversions: MaxQuant leaves fixed modifications out ofModified sequence, so the SDRF'sMT=fixedmodifications, else those of theparameters.txtorsummary.txtnext to the input, are added to the peptidoforms to matchcalculated_mz. TMT, iTRAQ and SILAC labels among the SDRF's are skipped: the isobaric label comes from the SDRF channel labels, a SILAC label fromLabeling state. A warning is logged for each fixed modification that cannot be placed, and when no source declares one - Use compressed files (.gz) to save disk space
- Use
--spectral-dataflag 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, or a plex's ion.tsv with --annotation-file (for feature conversion) |
--pg-file |
FILE | No | - | FragPipe combined_protein.tsv file, or a plex's protein.tsv with --annotation-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; --ion-file and --pg-file need it unless the SDRF source names are the experiments |
--annotation-file |
FILE | No | - | annotation.txt of one TMT/iTRAQ plex, whose lines map a channel to its sample column; reads the reporter quantities of --ion-file and --pg-file, and needs --psm-file for the plex's raw runs |
--tmt-report |
FILE | No | - | TMT-Integrator abundance_protein_*.tsv, added to the pg view as the log2 abundance of each channel |
--output-folder |
DIRECTORY | Yes | - | Output directory for generated QPX files |
--output-prefix |
TEXT | No | - | Prefix for output file names |
--max-memory |
TEXT | No | - | DuckDB memory limit (e.g. '16GB'); the converter's Python row batches come on top |
--max-cpus |
INTEGER | No | - | Maximum number of threads |
--temp-dir |
DIRECTORY | No | .tmp in the output folder, or in the working directory without one | Directory for DuckDB spill files (default: .tmp in the output folder, or in the working directory without one) |
--project-accession |
TEXT | No | - | PRIDE / ProteomeXchange accession (e.g. PXD020192) |
--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
# One TMT plex: convert each plex with its own prefix
qpxc convert fragpipe \
--psm-file plex1/psm.tsv \
--ion-file plex1/ion.tsv \
--pg-file plex1/protein.tsv \
--annotation-file plex1/annotation.txt \
--sdrf-file study.sdrf.tsv \
--output-folder ./qpx_output \
--output-prefix plex1
With Custom Settings¶
qpxc convert fragpipe \
--psm-file /path/to/psm.tsv \
--output-folder ./output \
--output-prefix fragpipe_psm
TMT and iTRAQ¶
combined_ion.tsv and combined_protein.tsv hold MS1 intensities only, so convert each plex from its own reports. Its annotation.txt names the channel columns, and its psm.tsv the raw runs:
qpxc convert fragpipe \
--psm-file plex1/psm.tsv \
--ion-file plex1/ion.tsv \
--pg-file plex1/protein.tsv \
--annotation-file plex1/annotation.txt \
--tmt-report tmt-report/abundance_protein_MD.tsv \
--sdrf-file study.sdrf.tsv \
--output-folder ./output \
--output-prefix plex1
The labels come from the channel of each annotation line (127N is TMT127N), and they must match the SDRF comment[label] values for qpxc validate and design_matrix() to resolve the samples.
Output Files¶
- Output:
{output-prefix}.psm.parquet - Format: Parquet file containing PSM data
- Schema: Conforms to QPX PSM specification
proteome-discoverer¶
Convert the text exports of a Proteome Discoverer consensus result to QPX format. Export PSMs, Proteins and Input Files from the result; the .pdResult file itself is not read.
Parameters¶
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
--psm-file |
FILE | Yes | - | Proteome Discoverer PSMs.txt export |
--proteins-file |
FILE | No | - | Proteome Discoverer Proteins.txt export (for PG conversion and protein group members) |
--input-files |
FILE | No | - | Proteome Discoverer InputFiles.txt export; needed when the PSM export has no Spectrum File column |
--sdrf-file |
FILE | No | - | SDRF metadata file (for sample/run conversion); its comment[label] values must match the reporter channels |
--rank1-only |
FLAG | No | - | Keep only the first-ranked hit of each spectrum in the PSM view |
--output-folder |
DIRECTORY | Yes | - | Output directory for generated QPX files |
--output-prefix |
TEXT | No | - | Prefix for output file names |
--max-memory |
TEXT | No | - | DuckDB memory limit (e.g. '16GB'); the converter's Python row batches come on top |
--max-cpus |
INTEGER | No | - | Maximum number of threads |
--temp-dir |
DIRECTORY | No | .tmp in the output folder, or in the working directory without one | Directory for DuckDB spill files (default: .tmp in the output folder, or in the working directory without one) |
--project-accession |
TEXT | No | - | PRIDE / ProteomeXchange accession (e.g. PXD020192) |
--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¶
qpxc convert proteome-discoverer \
--psm-file study_PSMs.txt \
--proteins-file study_Proteins.txt \
--input-files study_InputFiles.txt \
--sdrf-file study.sdrf.tsv \
--output-folder ./output
What each view takes from the exports is in Converter coverage.
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: index= spectrum references become the scan numbers it records |
--include-spectra |
FLAG | No | - | Attach mz_array and intensity_array from MGF to PSM records |
--rank1-only |
FLAG | No | - | Keep only the first-ranked hit of each spectrum |
--project-accession |
TEXT | No | - | PRIDE / ProteomeXchange accession (e.g. PXD054720) |
--temp-dir |
DIRECTORY | No | .tmp in the output folder, or in the working directory without one | Directory for DuckDB spill files (default: .tmp in the output folder, or in the working directory without one) |
--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 an MGF¶
qpxc convert mzidentml \
--mzid-path /path/to/results.mzid \
--mgf-path /path/to/spectra.mgf \
--include-spectra \
--output-folder ./output \
--output-prefix psm_with_spectra
--mgf-path alone fills scan numbers and m/z; --include-spectra also attaches the whole spectrum of each PSM as mz_array and intensity_array.
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}.psm.parquet - Format: Parquet file containing PSM-level data
- Schema: Conforms to QPX PSM specification
Supported mzIdentML Features¶
- Compressed files: Supports both
.mzidand.mzid.gzformats - Modifications: Full support for UNIMOD and custom modifications
- Scores: Extracts all CV-term scores with
higher_betterflag annotation - Decoy detection: Automatic detection via
isDecoyattribute - Multi-file support: Handles mzIdentML referencing multiple spectra files
Best Practices¶
- Use compressed
.mzid.gzfiles to save disk space - Enable
--include-spectraonly when spectral arrays are needed for downstream analysis
Common Issues¶
Issue: No spectra attached from the MGF
- Solution: Pass
--include-spectrawith--mgf-path, and check that the MGF'sindex=values match the spectrum references of the mzIdentML
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. |
--project-accession |
TEXT | No | - | PDC / ProteomeXchange accession (e.g. PDC000227) |
--sdrf-file |
FILE | No | - | SDRF defining which runs form one quantification unit. Default: runs that differ only in a _fNN suffix. |
--max-memory |
TEXT | No | - | DuckDB memory limit (e.g. '16GB'); the converter's Python row batches come on top |
--max-cpus |
INTEGER | No | - | Maximum number of threads |
--temp-dir |
DIRECTORY | No | .tmp in the output folder, or in the working directory without one | Directory for DuckDB spill files (default: .tmp in the output folder, or in the working directory without one) |
--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, one row per peptidoform, charge and fraction run, with oneintensitiesentry per channel (null where CDAP reports no signal) - Protein Group:
{output-prefix}.pg.parquet, one row per group, channel and quantification unit.grouped_runsis the plex: from--sdrf-file, else the runs that differ only in a_fNNsuffix.pdc2qpxtakes it from PDC metadata - Ontology:
{output-prefix}.ontology.parquet - Provenance:
{output-prefix}.provenance.parquet - Dataset:
{output-prefix}.dataset.parquet
Best Practices¶
- Point
--psm-dirto one CPTAC study directory containing*.psmfiles - Use
--structuresto skip views that are not needed - See Memory 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¶
| 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 / featurems_level,scan_start_time,total_ion_current,centroidprecursors— precursor m/z, charge, isolation window (MS2+)mz,intensity— full peak arrays
Best Practices¶
- Reads
.mzMLand.mzML.gzdirectly (no manual decompression needed) - Omit
--ms-levels(or use1,2) for full spectra; precursor-level LFQ reanalysis (e.g. quantms) needs MS1 in addition to MS2 - Each spectrum carries
run_file_name+scanso it joins back to PSM / feature
sdrf¶
Convert SDRF metadata files to QPX sample and run parquet format.
run.acquisition_start keeps the first valid comment[acquisition date] per run. The optional --mzml-dir reads mzML run/@startTimeStamp headers for runs without an SDRF date. SDRF takes precedence; text, fractional seconds and timezone suffixes are preserved without parsing, timezone conversion or added time components. This mzML source is currently available only with qpxc convert sdrf --mzml-dir.
Description¶
Reads a Sample and Data Relationship Format (SDRF) file and produces the QPX sample and run data structures as Parquet files. Acquisition starts come from comment[acquisition date], or mzML headers with --mzml-dir, and retain the source text without timezone conversion.
Parameters¶
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
--sdrf-file |
FILE | Yes | - | SDRF metadata file path |
--mzml-dir |
DIRECTORY | No | - | Directory containing mzML / mzML.gz files for acquisition starts missing from the SDRF |
--output-folder |
DIRECTORY | Yes | - | Output directory for generated QPX files |
--output-prefix |
TEXT | No | sdrf |
Prefix for output file names |
--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}.sample.parquet - Run:
{output-prefix}.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 | - | Maximum DuckDB memory limit (e.g. '16GB') |
--max-cpus |
INTEGER | No | - | Maximum number of DuckDB threads |
--temp-dir |
DIRECTORY | No | .tmp in the output folder, or in the working directory without one | Directory for DuckDB spill files (default: .tmp in the output folder, or in the working directory without one) |
--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, andprovenanceParquet files. - Does not produce
psm.parquetbecause 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, optionalRetentionTime, and optionalChannelcolumns. - Resolves
RunandReferencethrough 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.
- Ignores MSstats
IsotopeLabelType. A labelled table needs aChannelcolumn holding the SDRF labels:Hin MSstats means a reference standard, not a heavy channel of the experiment, so it cannot be aliased to a label.
openms¶
Enrich native OpenMS -out_qpx Parquet output into a full QPX dataset.
Deprecated
Use openms-consensus, which reads the consensusXML and is the supported OpenMS route. What OpenMS calls a "QPX collection" is the files of one dataset, not a collection. OpenMS quantification tools write no run, sample or provenance view, so without this enrichment pg rows cannot be mapped to samples and design_matrix raises.
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.
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. 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 |
--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, andpgParquet files found in--qpx-dir, normalizing run references while preserving supplied IDs. - Recovers PSM runs from exact spectrum evidence when the companion
--consensusxmlcontains 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 validatereports these duplicates as errors. - Generates
run,sample,ontology,provenance, anddatasetviews. - 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 OpenMS' abundance or an unnormalized rollup
ProteomicsLFQ, IsobaricWorkflow and MS1LabeledWorkflow record their protein
abundance in the consensusXML header (fraction_group_level_abundance), and
intensity is that value (quantification_method = openms_protein_abundance);
a zero is "not quantified" and becomes null. Files without one (quantms runs
ProteinQuantifier separately) get a stopgap instead: the unnormalized sum of
the group's unique peptides for that channel (the quantms unique_peptides
policy, no normalization), marked unnormalized_unique_peptide_sum. Where
OpenMS' abundance is present, the sum stays in additional_intensities under
that name. The sum does not reproduce OpenMS' aggregation, which depends on its
own settings.
Quantification units
grouped_runs comes from the SDRF, else from the fraction_group of the map
list. Without either, each run is its own unit, with a warning: fractions of one
sample then stay separate, which an SDRF fixes.
MS1 labels (SILAC, dimethyl, mTRAQ)
One feature row per multiplet per run, one intensities entry per channel. A
two-plex calls its non-light channel SILAC heavy and a three-plex is
light/medium/heavy, as the native OpenMS writer does; labels that cannot be
resolved stop the conversion. The feature peptidoform is the lightest partner's:
unlabelled for SILAC, with the lightest label for dimethyl and mTRAQ, restored
from MS1Label:labeled_sequence and that channel's channel_description.
observed_mz and rt are the lightest measured partner's; when that is not the
run's lightest channel, mass_error_ppm is null. A PSM is the partner the
spectrum was matched with (MS1Label:labeled_sequence), with psm.label, and
the label state is kept in cv_params. Ratios go to the numerator label as
ratio_h_l and ratio_h_l_normalized (feature: MS1Label:evidence_ratio; pg:
fraction_group_level_ratio), relative to the run's or fraction group's lowest
channel.
Parameters¶
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
--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). |
--streaming |
FLAG | No | - | Force the low-memory streaming reader on/off. Default: auto (streaming for consensusXML files > 1 GB). The in-memory reader peaks at ~7x the file size in RAM; streaming peaks at ~2.3x and takes ~1.7x 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. |
--temp-dir |
DIRECTORY | No | .tmp in the output folder, or in the working directory without one | Directory for DuckDB spill files (default: .tmp in the output folder, or in the working directory without one) |
--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 populatedlabeland anintensity= unnormalized sum of the group's unique peptides (stamped with aquantification_methodcv_param; null where a group has no unique-peptide signal).<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