TransitionParquetFile Class Reference

Read OpenSwath Parquet library input (.oswpq) into LightTargetedExperiment. More...

#include <OpenMS/ANALYSIS/OPENSWATH/TransitionParquetFile.h>

Public Member Functions
	TransitionParquetFile ()=default
	Default constructor (the class is stateless; API consists of the two convert* methods)
	~TransitionParquetFile ()=default
	Default destructor.
void	convertParquetToTargetedExperiment (const std::string &oswpq_dir, OpenSwath::LightTargetedExperiment &targeted_exp) const
	Read a .oswpq library and populate a OpenSwath::LightTargetedExperiment.
void	convertParquetToTargetedExperiment (const std::string &oswpq_dir, OpenSwath::LightTargetedExperiment &targeted_exp, OpenSwathLibraryIDNormalizer::SourceIDMapping *source_ids) const
	Read a .oswpq library and additionally return source-ID provenance.
void	convertLightTargetedExperimentToParquet (const std::string &oswpq_path, const OpenSwath::LightTargetedExperiment &targeted_exp) const
	Write a OpenSwath::LightTargetedExperiment to a .oswpq library.
void	convertLightTargetedExperimentToParquet (const std::string &oswpq_path, const OpenSwath::LightTargetedExperiment &targeted_exp, const OpenSwathLibraryIDNormalizer::SourceIDMapping *source_ids) const
	Write a canonical OpenSwath::LightTargetedExperiment with optional source precursor provenance.

Detailed Description

Read OpenSwath Parquet library input (.oswpq) into LightTargetedExperiment.

The Parquet library format is a directory container with separate tables for precursors and transitions. The reader materializes all rows into OpenSwath::LightTargetedExperiment.

The container layout is:

<library>.oswpq
└── library/
    ├── metadata.json
    ├── precursors.parquet
    └── transitions.parquet

The metadata file contains an OpenMS metadata block and QC counts. The new canonical layout (matching OpenSwathOSWParquetWriter) looks like:

{
  "openms": {
    "schema_version": 1,
    "generator": "TransitionParquetFile",
    "openms_version": "<version>",
    "build_time": "<build_time>",
    "tool": {"name": "OpenSwathWorkflow", "version": "<version>"},
    "counts": {
      "proteins": {"total": 0, "target": 0, "decoy": 0},
      "peptides": {"total": 0, "target": 0, "decoy": 0},
      "precursors": {"total": 0, "target": 0, "decoy": 0},
      "compounds": {"total": 0, "target": 0, "decoy": 0},
      "transitions": {"total": 0, "target": 0, "decoy": 0}
    },
    "fragment_type_counts": {
      "target": {"b": 0, "y": 0, "other": 0},
      "decoy": {"b": 0, "y": 0, "other": 0}
    },
    "charge_counts": {
      "precursor": {"target": {"2": 0, "3": 0}, "decoy": {"2": 0, "3": 0}},
      "transition": {"target": {"1": 0, "2": 0}, "decoy": {"1": 0, "2": 0}}
    }
  }
}

Required columns for precursors.parquet:

• precursor_id (int64)
• precursor_mz (float64)
• charge (int32)
• library_rt (float64) Optional columns:
• library_drift_time (float64)
• traml_id (string)
• decoy (bool)
• modified_sequence (string)
• unmodified_sequence (string)
• protein_accessions (string or list<string>)

Required columns for transitions.parquet:

• transition_id (int64)
• precursor_id (int64)
• product_mz (float64)
• charge (int32)
• type (string)
• ordinal (int32)
• detecting (bool)
• identifying (bool)
• quantifying (bool)
• library_intensity (float64)
• decoy (bool) Optional columns:
• traml_id (string)
• annotation (string)

Constructor & Destructor Documentation

TransitionParquetFile()

TransitionParquetFile ( )

default

Default constructor (the class is stateless; API consists of the two convert* methods)

~TransitionParquetFile()

~TransitionParquetFile ( )

default

Default destructor.

Member Function Documentation

convertLightTargetedExperimentToParquet() [1/2]

void convertLightTargetedExperimentToParquet	(	const std::string &	oswpq_path,
		const OpenSwath::LightTargetedExperiment &	targeted_exp
	)		const

Write a OpenSwath::LightTargetedExperiment to a .oswpq library.

Output target depends on oswpq_path: if it points at an existing directory, the parquet files are written directly under <oswpq_path>/library/. Otherwise the writer stages the layout in a temporary directory, then assembles a zip archive at oswpq_path via a .tmp staging archive that is renamed into place once complete.

Parameters

[in]	oswpq_path	Destination — existing directory or zip-file path.
[in]	targeted_exp	Canonical library to serialise. Precursor and transition IDs are preserved exactly, including zero and sparse values.

Exceptions

Exception::FileNotWritable	If a generated file inside the staging area cannot be written.
Exception::MissingInformation	If required per-row data (e.g. a transition lacking a peptide ref) is missing from targeted_exp.
Exception::InvalidValue	If row-level invariants are violated (e.g. duplicate precursor ids, schema-incompatible values). Compatibility overload: preserves canonical input as-is, otherwise canonicalizes a source-style Light experiment once before writing.

convertLightTargetedExperimentToParquet() [2/2]

void convertLightTargetedExperimentToParquet	(	const std::string &	oswpq_path,
		const OpenSwath::LightTargetedExperiment &	targeted_exp,
		const OpenSwathLibraryIDNormalizer::SourceIDMapping *	source_ids
	)		const

Write a canonical OpenSwath::LightTargetedExperiment with optional source precursor provenance.

Parameters

[in]	oswpq_path	Destination — existing directory or zip-file path.
[in]	targeted_exp	Canonical library to serialise. Precursor and transition IDs are preserved exactly, including zero and sparse values.
[in]	source_ids	Optional source-ID provenance. When supplied, precursor traml_id stores the original/source identifier while precursor_id remains canonical.

Exceptions

Exception::FileNotWritable	If a generated file inside the staging area cannot be written.
Exception::MissingInformation	If required per-row data is missing from targeted_exp.
Exception::InvalidValue	If row-level invariants are violated.

convertParquetToTargetedExperiment() [1/2]

void convertParquetToTargetedExperiment	(	const std::string &	oswpq_dir,
		OpenSwath::LightTargetedExperiment &	targeted_exp
	)		const

Read a .oswpq library and populate a OpenSwath::LightTargetedExperiment.

Opens library/precursors.parquet and library/transitions.parquet from oswpq_dir (zip archive or extracted directory), validates each table against the OSWPrecursorSchema / OSWTransitionSchema in subset mode (extra columns are tolerated), and materialises the rows into targeted_exp.

targeted_exp is reset to an empty OpenSwath::LightTargetedExperiment at the start of the call — pre-existing contents are discarded rather than appended to.

The persistent precursor_id and transition_id columns define operational identity in the returned experiment. They are converted to decimal strings for LightCompound.id / LightTransition.transition_name, and transition peptide_ref values use the corresponding precursor_id. Optional traml_id columns remain source/provenance metadata and do not replace those canonical IDs.

Parameters

[in]	oswpq_dir	Path to a .oswpq archive or to an already-extracted directory containing library/.
[out]	targeted_exp	Populated targeted experiment; cleared before being filled.

Exceptions

Exception::MissingInformation	If a required parquet entry (precursors / transitions) cannot be located inside oswpq_dir.
Exception::InvalidValue	If a loaded parquet table fails schema validation against the precursor / transition schema, or if any other required row-level field is missing during materialisation. Compatibility overload retaining the existing two-argument API.

convertParquetToTargetedExperiment() [2/2]

void convertParquetToTargetedExperiment	(	const std::string &	oswpq_dir,
		OpenSwath::LightTargetedExperiment &	targeted_exp,
		OpenSwathLibraryIDNormalizer::SourceIDMapping *	source_ids
	)		const

Read a .oswpq library and additionally return source-ID provenance.

Parameters

[in]	oswpq_dir	Path to a .oswpq archive or to an already-extracted directory containing library/.
[out]	targeted_exp	Populated targeted experiment; cleared before being filled.
[out]	source_ids	Optional source-precursor provenance. When provided, non-empty precursor traml_id values are mapped to their canonical precursor_id.

Exceptions

Exception::MissingInformation	If a required parquet entry (precursors / transitions) cannot be located inside oswpq_dir.
Exception::InvalidValue	If a loaded parquet table fails schema validation or required row-level information is missing.