`mscompress._core` (Cython)¶

The C-backed core. These classes are defined in the Cython package; the canonical signatures and docstrings come from python/mscompress/_core.pyi.

Files¶

BaseFile ¶

Base class for mzML and MSZ file handlers.

compress_stream ¶

compress_stream(chunk_size: int = ...) -> Iterator[bytes]

Compress this file and yield the MSZ output as byte chunks.

Parameters:

Name	Type	Description	Default
`chunk_size`	`int`	Number of bytes to read per iteration (default 1MB).	`...`

Yields:

Type	Description
`bytes`	Chunks of compressed MSZ data.

decompress_stream ¶

decompress_stream(chunk_size: int = ...) -> Iterator[bytes]

Decompress this file and yield the mzML output as byte chunks.

Parameters:

Name	Type	Description	Default
`chunk_size`	`int`	Number of bytes to read per iteration (default 1MB).	`...`

Yields:

Type	Description
`bytes`	Chunks of decompressed mzML data.

extract_stream ¶

extract_stream(
    indicies: Optional[list[int]] = None,
    scan_numbers: Optional[list[int]] = None,
    ms_level: Optional[int] = None,
    chunk_size: int = ...,
) -> Iterator[bytes]

Extract spectra and yield the mzML output as byte chunks.

Parameters:

Name	Type	Description	Default
`indicies`	`Optional[list[int]]`	List of spectrum indices to extract (optional).	`None`
`scan_numbers`	`Optional[list[int]]`	List of scan numbers to extract (optional).	`None`
`ms_level`	`Optional[int]`	MS level to extract (optional).	`None`
`chunk_size`	`int`	Number of bytes to read per iteration (default 1MB).	`...`

Yields:

Type	Description
`bytes`	Chunks of extracted mzML data.

extract ¶

extract(
    output: Union[str, PathLike],
    indicies: Optional[list[int]] = None,
    scan_numbers: Optional[list[int]] = None,
    ms_level: Optional[int] = None,
) -> Union[MZMLFile, MSZFile]

Extract specific spectra from a file to a new mzML or MSZ file.

Parameters:

Name	Type	Description	Default
`output`	`Union[str, PathLike]`	Output file path (string or path-like), must end in .msz or .mzML.	required
`indicies`	`Optional[list[int]]`	List of spectrum indices to extract (optional).	`None`
`scan_numbers`	`Optional[list[int]]`	List of scan numbers to extract (optional).	`None`
`ms_level`	`Optional[int]`	MS level to extract (optional).	`None`

get_header ¶

get_header() -> str

Extract the complete mzML header as a raw string.

This function extracts the header portion of an mzML file (everything from the start of the file to the first spectrum element).

Returns:

Type	Description
`str`	The raw XML header string.

Raises:

Type	Description
`RuntimeError`	If header extraction fails.

extract_metadata ¶

extract_metadata(tag_name: str) -> Element

Extract and parse a specific XML tag from the mzML file header.

This method extracts the header portion of an mzML file, searches for a specific XML tag (e.g., 'referenceableParamGroupList', 'cvList', 'fileDescription'), strips any content outside of it, and parses that XML element.

Parameters:

Name	Type	Description	Default
`tag_name`	`str`	The name of the XML tag to extract (without namespace).	required

Returns:

Type	Description
`Element`	An xml.etree.ElementTree.Element containing the parsed XML tag.

Raises:

Type	Description
`ValueError`	If the tag is not found in the header.
`RuntimeError`	If header extraction fails.
`ParseError`	If XML parsing fails.

MZMLFile ¶

MZMLFile(path: bytes)

Bases: BaseFile

Handler for mzML format files.

compress ¶

compress(output: Union[str, PathLike]) -> MSZFile

Compress an mzML file to MSZ format.

Parameters:

Name	Type	Description	Default
`output`	`Union[str, PathLike]`	Output file path (string or path-like).	required

compress_stream ¶

compress_stream(chunk_size: int = ...) -> Iterator[bytes]

Compress this mzML file and yield the MSZ output as byte chunks.

Parameters:

Name	Type	Description	Default
`chunk_size`	`int`	Number of bytes to read per iteration (default 1MB).	`...`

Yields:

Type	Description
`bytes`	Chunks of compressed MSZ data.

extract_stream ¶

extract_stream(
    indicies: list[int] | None = ...,
    scan_numbers: list[int] | None = ...,
    ms_level: int | None = ...,
    chunk_size: int = ...,
) -> Iterator[bytes]

Extract spectra from this mzML file and yield mzML output as byte chunks.

Parameters:

Name	Type	Description	Default
`indicies`	`list[int] \| None`	List of spectrum indices to extract (optional).	`...`
`scan_numbers`	`list[int] \| None`	List of scan numbers to extract (optional).	`...`
`ms_level`	`int \| None`	MS level to extract (optional).	`...`
`chunk_size`	`int`	Number of bytes to read per iteration (default 1MB).	`...`

Yields:

Type	Description
`bytes`	Chunks of extracted mzML data.

get_mz_binary ¶

get_mz_binary(
    index: int,
) -> NDArray[Union[float32, float64]]

Extract m/z binary array for a spectrum at the given index.

Parameters:

Name	Type	Description	Default
`index`	`int`	Spectrum index.	required

Returns:

Type	Description
`NDArray[Union[float32, float64]]`	NumPy array of m/z values.

get_inten_binary ¶

get_inten_binary(
    index: int,
) -> NDArray[Union[float32, float64]]

Extract intensity binary array for a spectrum at the given index.

Parameters:

Name	Type	Description	Default
`index`	`int`	Spectrum index.	required

Returns:

Type	Description
`NDArray[Union[float32, float64]]`	NumPy array of intensity values.

get_xml ¶

get_xml(index: int) -> Element

Extract XML element for a spectrum at the given index.

Parameters:

Name	Type	Description	Default
`index`	`int`	Spectrum index.	required

Returns:

Type	Description
`Element`	ElementTree Element containing spectrum metadata.

MSZFile ¶

MSZFile(path: bytes)

Bases: BaseFile

Handler for MSZ (compressed) format files.

decompress ¶

decompress(output: Union[str, PathLike]) -> MZMLFile

Decompress an MSZ file to mzML format.

Parameters:

Name	Type	Description	Default
`output`	`Union[str, PathLike]`	Output file path (string or path-like).	required

decompress_stream ¶

decompress_stream(chunk_size: int = ...) -> Iterator[bytes]

Decompress this MSZ file and yield the mzML output as byte chunks.

Parameters:

Name	Type	Description	Default
`chunk_size`	`int`	Number of bytes to read per iteration (default 1MB).	`...`

Yields:

Type	Description
`bytes`	Chunks of decompressed mzML data.

extract_stream ¶

extract_stream(
    indicies: list[int] | None = ...,
    scan_numbers: list[int] | None = ...,
    ms_level: int | None = ...,
    chunk_size: int = ...,
) -> Iterator[bytes]

Extract spectra from this MSZ file and yield mzML output as byte chunks.

Parameters:

Name	Type	Description	Default
`indicies`	`list[int] \| None`	List of spectrum indices to extract (optional).	`...`
`scan_numbers`	`list[int] \| None`	List of scan numbers to extract (optional).	`...`
`ms_level`	`int \| None`	MS level to extract (optional).	`...`
`chunk_size`	`int`	Number of bytes to read per iteration (default 1MB).	`...`

Yields:

Type	Description
`bytes`	Chunks of extracted mzML data.

get_mz_binary ¶

get_mz_binary(
    index: int,
) -> NDArray[Union[float32, float64]]

Extract m/z binary array for a spectrum at the given index.

Parameters:

Name	Type	Description	Default
`index`	`int`	Spectrum index.	required

Returns:

Type	Description
`NDArray[Union[float32, float64]]`	NumPy array of m/z values.

get_inten_binary ¶

get_inten_binary(
    index: int,
) -> NDArray[Union[float32, float64]]

Extract intensity binary array for a spectrum at the given index.

Parameters:

Name	Type	Description	Default
`index`	`int`	Spectrum index.	required

Returns:

Type	Description
`NDArray[Union[float32, float64]]`	NumPy array of intensity values.

get_xml ¶

get_xml(index: int) -> Element

Extract XML element for a spectrum at the given index.

Parameters:

Name	Type	Description	Default
`index`	`int`	Spectrum index.	required

Returns:

Type	Description
`Element`	ElementTree Element containing spectrum metadata.

Spectra¶

Spectrum ¶

Spectrum(
    index: int,
    scan: int,
    ms_level: int,
    retention_time: float,
    file: BaseFile,
    transform: Optional[SpectrumTransform] = None,
)

Represents a single mass spectrum.

xml `property` ¶

xml: Element

XML metadata for this spectrum.

size `property` ¶

size: int

Number of m/z - intensity pairs (pre-transform).

retention_time `property` ¶

retention_time: float

Retention time of this spectrum.

raw_mz `property` ¶

raw_mz: NDArray[Union[float32, float64]]

Raw m/z values array (before any transform).

raw_intensity `property` ¶

raw_intensity: NDArray[Union[float32, float64]]

Raw intensity values array (before any transform).

mz `property` ¶

mz: NDArray[Union[float32, float64]]

m/z values array (after transform, if set).

intensity `property` ¶

intensity: NDArray[Union[float32, float64]]

Intensity values array (after transform, if set).

peaks `property` ¶

peaks: NDArray[Union[float32, float64]]

Combined m/z and intensity as 2D array (after transform, if set).

Spectra ¶

Spectra(f: BaseFile, df: DataFormat, positions: Division)

Collection of spectra with lazy loading and iteration support.

Allows indexing and iteration over all spectra in a file.

set_transform ¶

set_transform(
    transform: Optional[SpectrumTransform],
) -> None

Set a transform function applied lazily to all spectra.

Parameters:

Name	Type	Description	Default
`transform`	`Optional[SpectrumTransform]`	A callable (SpectrumDict) -> SpectrumDict, or None to clear.	required

with_transform ¶

with_transform(
    transform: Optional[SpectrumTransform],
) -> Spectra

Return a new Spectra with the given transform, without modifying this one.

Parameters:

Name	Type	Description	Default
`transform`	`Optional[SpectrumTransform]`	A callable (SpectrumDict) -> SpectrumDict, or None.	required

Returns:

Type	Description
`Spectra`	A new Spectra instance with the transform set.

Metadata structures¶

DataFormat ¶

Data format information for mzML/MSZ files.

DataPositions ¶

Position information for data blocks in files.

Division ¶

Division structure containing data positions and scan information.

Configuration¶

RuntimeArguments ¶

RuntimeArguments()

Runtime configuration arguments for compression/decompression operations.

mscompress._core (Cython)¶

Files¶

BaseFile ¶

compress_stream ¶

decompress_stream ¶

extract_stream ¶

extract ¶

get_header ¶

extract_metadata ¶

MZMLFile ¶

compress ¶

compress_stream ¶

extract_stream ¶

get_mz_binary ¶

get_inten_binary ¶

get_xml ¶

MSZFile ¶

decompress ¶

decompress_stream ¶

extract_stream ¶

get_mz_binary ¶

get_inten_binary ¶

get_xml ¶

Spectra¶

Spectrum ¶

xml property ¶

size property ¶

retention_time property ¶

raw_mz property ¶

raw_intensity property ¶

mz property ¶

intensity property ¶

peaks property ¶

Spectra ¶

set_transform ¶

with_transform ¶

Metadata structures¶

DataFormat ¶

DataPositions ¶

Division ¶

Configuration¶

RuntimeArguments ¶

`mscompress._core` (Cython)¶

xml `property` ¶

size `property` ¶

retention_time `property` ¶

raw_mz `property` ¶

raw_intensity `property` ¶

mz `property` ¶

intensity `property` ¶

peaks `property` ¶