mscompress.parquet

Optional extra (pip install 'mscompress[parquet]'). Round-trip MSZ / MSZX / mzML with Parquet tables.

from_parquet

from_parquet(
    parquet_path: Union[str, PathLike],
    output_path: Union[str, PathLike],
    *,
    output_type: Optional[_OutputType] = None,
    use_zlib_binary: bool = False,
    ret_time_unit: str = "minute",
    score_column: Optional[str] = None,
    description: Optional[str] = None,
) -> Path

Convert a parquet into .msz, .mszx, or an annotations .tsv.

Output type is inferred from output_path's extension by default (.msz, .mszx, .tsv, case-insensitive); pass output_type= to override or when the extension is unknown / missing.

Parameters:

Name	Type	Description	Default
parquet_path	Union[str, PathLike]	Source parquet.	required
output_path	Union[str, PathLike]	Destination path. Extension determines the format unless overridden by output_type.	required
output_type	Optional[_OutputType]	Explicit format override. One of "msz", "mszx", "tsv".	None
use_zlib_binary	bool	zlib-deflate binary arrays inside the synthesized mzML before base64 encoding. Applies to msz/mszx only.	False
ret_time_unit	str	"minute" (default) or "second". Applies to msz/mszx only.	'minute'
score_column	Optional[str]	Parquet column to surface as PSM score. Applies to mszx/tsv only. None auto-picks max_score/mean_score/ score/Score if present, otherwise leaves the score cells empty. An explicit name absent from the schema raises.	None
description	Optional[str]	Human-readable description embedded in the archive manifest. Applies to mszx only.	None

Returns:

Type	Description
Path	The written output_path.

Raises:

Type	Description
ValueError	If the output type can't be inferred and output_type wasn't provided, or if it isn't one of the supported values.

to_parquet

to_parquet(
    input: Union[str, PathLike, bytes, BaseFile, MSZXFile],
    output_path: Union[str, PathLike],
    *,
    compression: str = "zstd",
    row_group_size: int = 1024,
    multi_psm: _MultiPSM = "best",
) -> Path

Convert an mzML, MSZ, or MSZX file into a spectrum-level parquet.

The output schema is designed to round-trip cleanly through from_parquet: column names and dtypes match what the forward path consumes, including a peptide_charge column built from annotation peptide + charge so the forward path can re-split it.

Retention time unit is auto-detected from the first spectrum's MS:1000016 cvParam — no caller parameter. MSZX annotations (peptide / charge / score / q_value) are included when present.

Parameters:

Name	Type	Description	Default
input	Union[str, PathLike, bytes, BaseFile, MSZXFile]	A path to an mzML / .msz / .mszx file, or an already-open MZMLFile / MSZFile / MSZXFile.	required
output_path	Union[str, PathLike]	Destination .parquet path.	required
compression	str	Parquet compression codec. Default "zstd".	'zstd'
row_group_size	int	Spectra per parquet row group. Default 1024.	1024
multi_psm	_MultiPSM	How to handle scans with multiple PSMs (MSZX only). "best" (default) keeps the max-score PSM, "first" keeps the first, "all" emits one row per PSM (duplicating the spectrum payload). Ignored when input has no annotations.	'best'

Returns:

Type	Description
Path	Path to the written parquet file.