`mscompress.mszx`¶

MSZX archive support — bundle MSZ spectra with annotation files in a self-describing tar archive.

Single-file (v1) archives use MSZXFile/MSZXBuilder; multi-file (v2 "batch") archives use MSZXBatchFile/MSZXBatchWriter. See the MSZX format spec.

Single-file archives¶

MSZXFile ¶

MSZXFile(path: bytes)

Bases: MSZFile

First-class reader for MSZX (tar) archives.

Extends MSZFile so all spectrum properties and methods work directly on the embedded MSZ payload, while adding access to the archive manifest and bundled annotation readers. Open via the open() classmethod.

manifest `property` ¶

manifest: Any

The archive manifest (MSZXManifest).

archive_path `property` ¶

archive_path: Any

Path to the MSZX archive.

annotations `property` ¶

annotations: Any

Primary annotation reader, or None if no annotations.

annotation_readers `property` ¶

annotation_readers: Dict[str, Any]

Dict of all annotation readers, keyed by filename.

annotation_files `property` ¶

annotation_files: list

List of annotation entries in the archive.

open `classmethod` ¶

open(path: Union[str, PathLike]) -> MSZXFile

Open an MSZX archive for reading.

Mmaps the embedded MSZ payload directly out of the archive (no temp extraction) and eagerly reads annotation entries into memory.

Parameters:

Name	Type	Description	Default
`path`	`Union[str, PathLike]`	Path to the .mszx file.	required

close ¶

close() -> None

Close the archive and release all resources. Idempotent.

get_annotation_reader ¶

get_annotation_reader(filename: str) -> Any

Get the annotation reader for a specific file by name.

get_annotation_readers_by_format ¶

get_annotation_readers_by_format(format: str) -> list

Get all annotation readers matching a specific format.

describe ¶

describe() -> Dict[str, Any]

Description including the archive metadata.

decompress ¶

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

Decompress the embedded MSZ to mzML.

If output is an existing directory or has no file extension, the mzML is written inside it as <archive_stem>.mzML and any cached annotation readers are written alongside. Otherwise output is treated as a single file path and only the mzML is written.

extract ¶

extract(
    output: str | PathLike,
    indicies: list[int] | None = ...,
    scan_numbers: list[int] | None = ...,
    ms_level: int | None = ...,
) -> MSZXFile

Extract a subset of spectra and annotations to a new MSZX archive.

Parameters:

Name	Type	Description	Default
`output`	`str \| PathLike`	Path to the output .mszx file.	required
`indicies`	`list[int] \| None`	List of spectrum indices to extract.	`...`
`scan_numbers`	`list[int] \| None`	List of scan numbers to extract.	`...`
`ms_level`	`int \| None`	Filter by MS level.	`...`

Returns:

Type	Description
`MSZXFile`	New MSZXFile instance for the created archive.

MSZXBuilder ¶

MSZXBuilder(
    msz: MSZFile,
    source_name: Optional[str] = None,
    compression: bool = True,
)

Builder for creating MSZX archives from MSZ files and annotations.

Example

msz = mscompress.read("sample.msz")
builder = MSZXBuilder(msz)
builder.add_annotations(reader, description="Percolator results")
builder.set_description("Proteomics dataset with PSM annotations")
builder.save("sample.mszx")

Initialize the builder with an MSZ file.

Parameters:

Name	Type	Description	Default
`msz`	`MSZFile`	MSZFile object containing spectra.	required
`source_name`	`Optional[str]`	Optional source file name for provenance.	`None`

add_annotations ¶

add_annotations(
    reader: BasePSMReader, description: Optional[str] = None
) -> MSZXBuilder

Add annotations to the archive.

Parameters:

Name	Type	Description	Default
`reader`	`BasePSMReader`	BasePSMReader instance containing the annotations.	required
`description`	`Optional[str]`	Optional description of the annotations.	`None`

Returns: Self for method chaining.

set_description ¶

set_description(description: str) -> MSZXBuilder

Set the archive description.

set_join_key ¶

set_join_key(join_key: str) -> MSZXBuilder

Set the key used to join spectra with search results.

set_extra ¶

set_extra(key: str, value: Any) -> MSZXBuilder

Add extra metadata to the manifest.

save ¶

save(output_path: Union[str, Path]) -> Path

Save the MSZX archive to disk.

Parameters:

Name	Type	Description	Default
`output_path`	`Union[str, Path]`	Output file path (should end with .mszx).	required

Returns:

Type	Description
`Path`	Path to the created archive.

MSZXManifest `dataclass` ¶

MSZXManifest(
    version: str = "1.0",
    created_at: str = (lambda: isoformat())(),
    spectra_file: str = "spectra.msz",
    num_spectra: int = 0,
    annotations: List[AnnotationEntry] = list(),
    join_key: str = "scan_number",
    description: Optional[str] = None,
    source_file: Optional[str] = None,
    extra: Dict[str, Any] = dict(),
)

Manifest describing the contents of an MSZX archive.

This is stored as manifest.json inside the archive for self-description.

to_dict ¶

to_dict() -> Dict[str, Any]

Convert to dictionary for JSON serialization.

to_json ¶

to_json(indent: int = 2) -> str

Serialize to JSON string.

from_dict `classmethod` ¶

from_dict(data: Dict[str, Any]) -> MSZXManifest

Create from dictionary.

Raises:

Type	Description
`ValueError`	if the manifest is a newer major version than this build supports, or if it is a multi-file/batch archive — those carry N spectra files and must go through :class:`MSZXBatchManifest` instead. Refusing loudly avoids silently mis-reading a batch archive as a single-file one.

from_json `classmethod` ¶

from_json(json_str: str) -> MSZXManifest

Parse from JSON string.

AnnotationEntry `dataclass` ¶

AnnotationEntry(
    filename: str,
    format: AnnotationFormat,
    compressed: bool,
    description: Optional[str] = None,
    num_records: Optional[int] = None,
)

Entry describing an annotation file in the archive.

to_dict ¶

to_dict() -> Dict[str, Any]

Convert to dictionary for JSON serialization.

from_dict `classmethod` ¶

from_dict(data: Dict[str, Any]) -> AnnotationEntry

Create from dictionary.

create_mszx ¶

create_mszx(
    msz: MSZFile,
    output_path: Union[str, Path],
    annotations: Optional[
        List[Union[str, Path, BasePSMReader]]
    ] = None,
    description: Optional[str] = None,
) -> Path

Create an MSZX archive from an MSZ file.

Convenience function for simple archive creation.

Parameters:

Name	Type	Description	Default
`msz`	`MSZFile`	MSZFile object.	required
`output_path`	`Union[str, Path]`	Output path for the .mszx file.	required
`annotations`	`Optional[List[Union[str, Path, BasePSMReader]]]`	List of file paths or readers for annotations.	`None`
`description`	`Optional[str]`	Optional description for the archive.	`None`

Returns:

Type	Description
`Path`	Path to the created archive.

Example

msz = mscompress.read("sample.msz")
create_mszx(
    msz,
    "sample.mszx",
    annotations=["sample.pin", "sample.pepXML"],
    description="Annotated proteomics dataset",
)

Batch archives¶

MSZXBatchFile ¶

MSZXBatchFile(
    path: Union[str, Path], manifest: MSZXBatchManifest
)

An MSZX archive viewed as a collection of MSZ files.

Holds N members for a v2 ("batch") archive and exactly one for a v1 archive, so the same code handles either. Behaves like an ordered, lazily-populated collection of :class:MSZFile:

.. code-block:: python

with mscompress.read("cohort.mszx") as archive:
    print(len(archive), archive.names)
    print(archive.entries[0].num_spectra)   # from the manifest, no open
    for member in archive:                  # opened on demand
        print(len(member.spectra))
    first = archive["a.msz"]                # or archive[0]

Members are cached once opened and released together by :meth:close.

manifest `property` ¶

manifest: MSZXBatchManifest

The archive manifest.

archive_path `property` ¶

archive_path: Path

Path to the .mszx archive.

entries `property` ¶

entries: List[SpectraFileEntry]

Manifest records, including num_spectra where the writer set it.

names `property` ¶

names: List[str]

Tar member names of the MSZ payloads, in archive order.

spectra `property` ¶

spectra

Not available on a collection — pick a member first.

open `classmethod` ¶

open(path: Union[str, Path]) -> MSZXBatchFile

Open any .mszx for reading as a collection.

A v2 batch archive yields N members; a v1 single-file archive yields exactly one. Use this when you want to handle either version uniformly. (:class:~mscompress.MSZXFile remains the flat, is-a-MSZFile reader for v1.)

Raises:

Type	Description
`FileNotFoundError`	if `path` does not exist.
`ValueError`	if the archive has no manifest.

describe ¶

describe() -> Dict[str, Any]

Summary of the archive without opening any member.

get ¶

get(key: Union[int, str]) -> MSZFile

Open a member by index or tar member name.

The returned :class:MSZFile is owned by this archive — it is cached and closed by :meth:close. Do not close it yourself.

get_annotation ¶

get_annotation(
    key: Union[int, str], filename: str
) -> bytes

Raw bytes of an annotation member attached to a spectra entry.

Payloads flagged compressed in the manifest are returned as stored; the caller decompresses (the writer does not compress on your behalf).

decompress ¶

decompress(output_dir: Union[str, Path]) -> List[Path]

Expand every member to <output_dir>/<entry stem>.mzML.

Returns the written paths, in archive order.

close ¶

close() -> None

Close every opened member and release the archive. Idempotent.

MSZXBatchWriter ¶

MSZXBatchWriter(
    path: Union[str, bytes, PathLike], **kwargs: Any
)

Incremental writer for a v2 multi-file ("batch") .mszx archive.

Wraps the same C writer the CLI drives, so an archive written from Python is byte-identical to one the CLI produces from the same inputs and settings. Entries stream straight into the archive file — no temp .msz staging — which is why the output must be a seekable regular file.

The archive only becomes valid once finish() succeeds. Leaving the with block via an exception calls abort(), removing the partial file.

Open an archive for writing.

Parameters:

Name	Type	Description	Default
`path`	`Union[str, bytes, PathLike]`	Output .mszx path. Must be a seekable regular file.	required
`**kwargs`	`Any`	Compression settings forwarded to RuntimeArguments (threads, blocksize, mz_lossy, int_lossy, mz_scale_factor, int_scale_factor, target_xml_format, target_mz_format, target_inten_format, zstd_compression_level).	`{}`

path `property` ¶

path: Union[str, bytes]

Output archive path.

entries `property` ¶

entries: list

Source paths added so far, in archive order.

add ¶

add(
    source: Union[str, bytes, PathLike, MZMLFile],
    name: Optional[str] = None,
) -> int

Compress one mzML into the archive as a new entry.

Parameters:

Name	Type	Description	Default
`source`	`Union[str, bytes, PathLike, MZMLFile]`	mzML to compress. An already-open MZMLFile reuses its existing mapping.	required
`name`	`Optional[str]`	Entry name inside the archive. Defaults to ".msz"; collisions get __2, __3, ... suffixes. Naming is handled by the C writer so the CLI and every binding agree.	`None`

Returns:

Type	Description
`int`	Index of the new entry, for add_annotation/set_join_key.

add_annotation ¶

add_annotation(
    entry_index: int,
    data: bytes,
    filename: str,
    format: str = "tsv",
    compressed: bool = False,
    num_records: Optional[int] = None,
) -> None

Attach an annotation file to a spectra entry, as its own member.

Compression is the caller's job — pass already-compressed bytes and set compressed=True.

set_join_key ¶

set_join_key(entry_index: int, join_key: str) -> None

Set the column used to join annotations to spectra for one entry.

set_description ¶

set_description(description: str) -> None

Set an archive-level free-text description.

set_extra ¶

set_extra(extra: dict) -> None

Set the archive-level extra metadata object.

finish ¶

finish() -> None

Write manifest.json and the end-of-archive marker, then close.

On failure the partial archive is removed. The writer is unusable afterwards either way.

abort ¶

abort() -> None

Discard the archive, removing the partial file. Idempotent.

compress_batch ¶

compress_batch(
    inputs: Union[str, Path, Iterable[Union[str, Path]]],
    output: Union[str, Path],
    *,
    recursive: bool = False,
    description: Optional[str] = None,
    extra: Optional[Dict[str, Any]] = None,
    on_progress: Optional[Any] = None,
    **compress_args: Any,
) -> Path

Compress many mzML into one v2 .mszx archive.

Parameters:

Name	Type	Description	Default
`inputs`	`Union[str, Path, Iterable[Union[str, Path]]]`	A path, directory, glob, or iterable of any of those.	required
`output`	`Union[str, Path]`	Destination .mszx. Must be a seekable regular file.	required
`recursive`	`bool`	Descend into subdirectories for directory inputs.	`False`
`description`	`Optional[str]`	Archive-level free-text description.	`None`
`extra`	`Optional[Dict[str, Any]]`	Archive-level metadata dict, embedded in the manifest.	`None`
`on_progress`	`Optional[Any]`	Optional `callable(index, total, path)` invoked before each entry is compressed.	`None`
`**compress_args`	`Any`	Forwarded to :class:`RuntimeArguments` (`threads`, `blocksize`, `mz_lossy`, `int_lossy`, ...).	`{}`

Returns:

Type	Description
`Path`	Path to the written archive.

Raises:

Type	Description
`ValueError`	if no input matched, or an input could not be compressed.

Example

compress_batch("runs/", "cohort.mszx", recursive=True, threads=8)

MSZXBatchManifest `dataclass` ¶

MSZXBatchManifest(
    version: str = "2.0",
    container: str = "batch",
    spectra_files: List[SpectraFileEntry] = list(),
    description: Optional[str] = None,
    extra: Dict[str, Any] = dict(),
)

Manifest of a v2 multi-file ("batch") MSZX archive.

A batch archive bundles N independent MSZ files written by the shared C batch writer. Unlike :class:MSZXManifest it carries no created_at — the format is deliberately timestamp-free so identical inputs produce byte-identical archives.

Every field beyond entry/original/size is optional, so archives written before those fields existed still parse.

from_dict `classmethod` ¶

from_dict(data: Dict[str, Any]) -> MSZXBatchManifest

Create from dictionary.

Raises:

Type	Description
`ValueError`	if the manifest is a newer major version than this build supports, or is not a batch manifest at all.

from_single_file `classmethod` ¶

from_single_file(
    manifest: MSZXManifest,
) -> MSZXBatchManifest

Adapt a v1 single-file manifest into a one-member batch manifest.

Lets one container type read every .mszx: a v1 archive is simply a collection of one. container is reported as "single" and version is preserved, so callers can still tell the two apart.

size is left at 0 — the v1 manifest does not record the payload length. :meth:MSZXBatchFile.open fills it in from the tar header.

SpectraFileEntry `dataclass` ¶

SpectraFileEntry(
    entry: str,
    original: str = "",
    size: int = 0,
    num_spectra: Optional[int] = None,
    join_key: str = "scan_number",
    annotations: List[AnnotationEntry] = list(),
)

One member of a v2 ("batch") MSZX archive.

Attributes:

Name	Type	Description
`entry`	`str`	Tar member name of the MSZ payload (e.g. `"sample.msz"`).
`original`	`str`	Basename of the source mzML. Only the basename is recorded, so the source directory is not recoverable from the archive.
`size`	`int`	Payload size in bytes, matching the tar header.
`num_spectra`	`Optional[int]`	Spectrum count, or `None` when the writer omitted it (archives produced before this field was added).
`join_key`	`str`	Column used to join annotations to spectra.
`annotations`	`List[AnnotationEntry]`	Annotation members attached to this entry.

mscompress.mszx¶

Single-file archives¶

MSZXFile ¶

manifest property ¶

archive_path property ¶

annotations property ¶

annotation_readers property ¶

annotation_files property ¶

open classmethod ¶

close ¶

get_annotation_reader ¶

get_annotation_readers_by_format ¶

describe ¶

decompress ¶

extract ¶

MSZXBuilder ¶

add_annotations ¶

set_description ¶

set_join_key ¶

set_extra ¶

save ¶

MSZXManifest dataclass ¶

to_dict ¶

to_json ¶

from_dict classmethod ¶

from_json classmethod ¶

AnnotationEntry dataclass ¶

to_dict ¶

from_dict classmethod ¶

create_mszx ¶

Batch archives¶

MSZXBatchFile ¶

manifest property ¶

archive_path property ¶

entries property ¶

names property ¶

spectra property ¶

open classmethod ¶

describe ¶

get ¶

get_annotation ¶

decompress ¶

close ¶

MSZXBatchWriter ¶

path property ¶

entries property ¶

add ¶

add_annotation ¶

set_join_key ¶

set_description ¶

set_extra ¶

finish ¶

abort ¶

compress_batch ¶

MSZXBatchManifest dataclass ¶

from_dict classmethod ¶

from_single_file classmethod ¶

SpectraFileEntry dataclass ¶

`mscompress.mszx`¶

manifest `property` ¶

archive_path `property` ¶

annotations `property` ¶

annotation_readers `property` ¶

annotation_files `property` ¶

open `classmethod` ¶

MSZXManifest `dataclass` ¶

from_dict `classmethod` ¶

from_json `classmethod` ¶

AnnotationEntry `dataclass` ¶

from_dict `classmethod` ¶

manifest `property` ¶

archive_path `property` ¶

entries `property` ¶

names `property` ¶

spectra `property` ¶

open `classmethod` ¶

path `property` ¶

entries `property` ¶

MSZXBatchManifest `dataclass` ¶

from_dict `classmethod` ¶

from_single_file `classmethod` ¶

SpectraFileEntry `dataclass` ¶