Read and write mass-spectrometry data in the on-disk sqMass (SQLite) format. More...

#include <OpenMS/FORMAT/SqMassFile.h>

Collaboration diagram for SqMassFile:

Classes
struct	SqMassConfig
	Compression / metadata options used when reading or writing an `sqMass` file. More...

Public Types
typedef MSExperiment	MapType
	Convenience alias used by load / store.

Public Member Functions
Constructors and Destructor
	SqMassFile ()
	Default constructor.

	~SqMassFile ()
	Destructor.

Read / Write a complete mass spectrometric experiment
SqMassConfig	config_

void	load (const std::string &filename, MapType &map) const
	Read the contents of an `sqMass` file into an `MSExperiment`.

void	store (const std::string &filename, const MapType &map) const
	Store an `MSExperiment` in `sqMass` format.

void	transform (const std::string &filename_in, Interfaces::IMSDataConsumer *consumer, bool skip_full_count=false, bool skip_first_pass=false) const
	Stream the spectra and chromatograms of an `sqMass` file through `consumer`.

void	convertToXICParquet (const std::string &filename_in, const std::string &xic_filename, UInt64 run_id=0, const std::string &source_file="", const OpenSwath::LightTargetedExperiment &transition_exp=OpenSwath::LightTargetedExperiment()) const
	Convert an sqMass file containing chromatogram data to an XIC Parquet file.

void	setConfig (const SqMassConfig &config)
	Replace the compression / metadata configuration used by subsequent load, store and transform calls.

Detailed Description

Read and write mass-spectrometry data in the on-disk sqMass (SQLite) format.

Persists spectra and chromatograms in a single SQLite database so that large collections can be queried, filtered, or streamed on demand without loading the whole experiment into memory.

For spectra and chromatograms that carry precursor information, the "peptide_sequence" meta-value of the first precursor (if any) is round-tripped alongside the binary data.

Compression and meta-data options are configured via SqMassConfig (see setConfig).

Class Documentation

◆ OpenMS::SqMassFile::SqMassConfig

struct OpenMS::SqMassFile::SqMassConfig

Compression / metadata options used when reading or writing an sqMass file.

Collaboration diagram for SqMassFile::SqMassConfig:

[legend]

Class Members
double	linear_fp_mass_acc {-1}	Target mass accuracy for numpress linear encoding (`-1` has no effect; use e.g. `0.0001` for 0.2 ppm `@` 500 m/z).
bool	use_lossy_numpress {false}	Use lossy numpress compression for the binary data arrays.
bool	write_full_meta {true}	Write full meta data (verbose, lossless).

Member Typedef Documentation

◆ MapType

typedef MSExperiment MapType

Convenience alias used by load / store.

Constructor & Destructor Documentation

◆ SqMassFile()

SqMassFile ( )

Default constructor.

◆ ~SqMassFile()

~SqMassFile ( )

Destructor.

Member Function Documentation

◆ convertToXICParquet()

void convertToXICParquet	(	const std::string &	filename_in,
		const std::string &	xic_filename,
		UInt64	run_id = `0`,
		const std::string &	source_file = `""`,
		const OpenSwath::LightTargetedExperiment &	transition_exp = `OpenSwath::LightTargetedExperiment()`
	)		const

Convert an sqMass file containing chromatogram data to an XIC Parquet file.

This is a convenience function that will stream chromatograms from the input sqMass file into an OpenMS Parquet writer (MSChromatogramParquetConsumer) and write them to disk.

Note: The transition/precursor metadata passed to the underlying Parquet consumer is optional from the API perspective, but the writer expects chromatogram native IDs to have matching transition/precursor metadata in many cases. If required metadata for a chromatogram (precursor or transition) is missing the writer will throw an exception and the conversion will fail. Therefore it is recommended to provide a populated transition experiment when possible.

Parameters

[in]	filename_in	Path to the input sqMass file.
[in]	xic_filename	Path to the output .xic Parquet file.
[in]	run_id	Run identifier to store with each chromatogram (default 0).
[in]	source_file	Source filename to store in the parquet file (if empty, filename_in is used).
[in]	transition_exp	Optional transition/precursor metadata (LightTargetedExperiment) used to annotate chromatograms. If left empty, no transition metadata will be available to the writer and conversion may fail for chromatograms that require such metadata. Prefer supplying a populated transition experiment when available.

Exceptions

Exception::InvalidValue	If a chromatogram refers to a precursor or transition for which no matching metadata entry exists, or if Arrow/Parquet operations fail while assembling/writing the table.
Exception::FileNotWritable	If the output parquet file cannot be opened for writing.
Exception::NotImplemented	If Parquet support was not compiled in.
Exception::BaseException	Other OpenMS exceptions propagated from the writer/encoding layers may also be thrown.

◆ load()

void load	(	const std::string &	filename,
		MapType &	map
	)		const

Read the contents of an sqMass file into an MSExperiment.

Loads all spectra, chromatograms and experimental metadata from filename into map. The current SqMassConfig is applied to the read.

Parameters

[in]	filename	Path to the `sqMass` file to read.
[out]	map	Destination experiment; populated with the file's spectra, chromatograms and metadata.

Exceptions

Exception::IllegalArgument	On malformed or inconsistent rows in the sqMass tables (mismatched native id, missing data type, ...) or when the file contains more than one run.
Exception::ConversionError	When a binary buffer's size does not match its declared data type.
Exception::SqlOperationFailed	When the file's `RUN` table advertises an unsupported configuration.

◆ setConfig()

void setConfig ( const SqMassConfig & config )

inline

Replace the compression / metadata configuration used by subsequent load, store and transform calls.

Parameters

[in] config New configuration.

◆ store()

void store	(	const std::string &	filename,
		const MapType &	map
	)		const

Store an MSExperiment in sqMass format.

Writes the spectra, chromatograms and experimental metadata of map to filename, creating the file (and the required SQLite tables) if necessary. The current SqMassConfig is applied.

The sqMass RUN::ID column is taken from MSExperiment::getSqlRunID; populate it via MSExperiment::setSqlRunID before calling store if a specific value is required.

Parameters

[in]	filename	Path to the output `sqMass` file.
[in]	map	Experiment to serialise.

Exceptions

Exception::IllegalArgument	When SQL commands fail during table creation or data insertion.
Exception::SqlOperationFailed	When the database file cannot be created or opened for writing.

◆ transform()

void transform	(	const std::string &	filename_in,
		Interfaces::IMSDataConsumer *	consumer,
		bool	skip_full_count = `false`,
		bool	skip_first_pass = `false`
	)		const

Stream the spectra and chromatograms of an sqMass file through consumer.

Reads filename and feeds every spectrum and chromatogram to consumer in input order. The consumer is informed of the expected counts (via IMSDataConsumer::setExpectedSize) and of the experimental metadata (via setExperimentalSettings) before the per-element callbacks are invoked. The full experiment is not held in memory.

Note: The skip_full_count and skip_first_pass parameters are currently unused and have no effect; they are retained for API compatibility.

Parameters

[in]	filename_in	Path to the input `sqMass` file.
[in]	consumer	Receives the streamed spectra and chromatograms. Must remain valid for the duration of the call.
[in]	skip_full_count	Currently ignored.
[in]	skip_first_pass	Currently ignored.

Exceptions

Exception::IllegalArgument	On malformed or inconsistent rows in the sqMass tables (mismatched native id, missing data type, ...) or when the file contains more than one run.
Exception::ConversionError	When a binary buffer's size does not match its declared data type.
Exception::SqlOperationFailed	When the file's `RUN` table advertises an unsupported configuration.

Member Data Documentation

◆ config_

SqMassConfig config_

protected

Classes

Public Types

Public Member Functions

Read / Write a complete mass spectrometric experiment

Detailed Description

Class Documentation

◆ OpenMS::SqMassFile::SqMassConfig

Member Typedef Documentation

◆ MapType

Constructor & Destructor Documentation

◆ SqMassFile()

◆ ~SqMassFile()

Member Function Documentation

◆ convertToXICParquet()

◆ load()

◆ setConfig()

◆ store()

◆ transform()

Member Data Documentation

◆ config_