From 76b3230a31022df9ccd25fe29ffad80334f03e25 Mon Sep 17 00:00:00 2001 From: Leonardo Schwarz Date: Fri, 27 Sep 2024 16:42:50 +0200 Subject: [PATCH] add some docs to persistence module --- docs/modules/index.md | 1 + docs/modules/persistence.md | 30 ++++++++++++++++++++++++++ mkdocs.yml | 2 -- src/depiction/persistence/types.py | 34 ++++++++++++++++++------------ 4 files changed, 51 insertions(+), 16 deletions(-) create mode 100644 docs/modules/index.md create mode 100644 docs/modules/persistence.md diff --git a/docs/modules/index.md b/docs/modules/index.md new file mode 100644 index 0000000..8231d04 --- /dev/null +++ b/docs/modules/index.md @@ -0,0 +1 @@ +This section contains documentation about the individual modules of depiction. diff --git a/docs/modules/persistence.md b/docs/modules/persistence.md new file mode 100644 index 0000000..aed6794 --- /dev/null +++ b/docs/modules/persistence.md @@ -0,0 +1,30 @@ +The persistence module contains functionality to read and write mass spectrometry imaging (MSI) data from and to the file system. +To keep the rest of depiction as agnostic of the representation as possible, an abstraction is introduced that allows changing the underlying storage without affecting the rest of the code. +In particular, we can parallelize code with the `parallelization` module and use RAM based storage when needed. + +## General abstraction + +### Reading data + +We have a `GenericReadFile` protocol, which encodes a container file handle, from which we can obtain `GenericReader` instances, +which perform the actual reading of the data. + +In general the idea is that creating the file should be quick, whereas additional parsing might be necessary to create the reader instance. + +::: depiction.persistence.types.GenericReadFile +options: +annotations_path: source +show_category_heading: yes +show_root_heading: yes +show_symbol_type_heading: yes +show_source: no +members_order: alphabetical +heading_level: 4 + +::: depiction.persistence.types.GenericReader + +## ImzML + +Our ImzML functionality, essentially wraps pyImzML. + +## Ram diff --git a/mkdocs.yml b/mkdocs.yml index 67fefc2..e59a941 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,6 +1,4 @@ site_name: depiction docs -nav: - - index.md theme: name: material features: diff --git a/src/depiction/persistence/types.py b/src/depiction/persistence/types.py index 99ea3ca..c60dbee 100644 --- a/src/depiction/persistence/types.py +++ b/src/depiction/persistence/types.py @@ -25,6 +25,8 @@ class GenericReader(Protocol): + """Reader for an .imzML file.""" + def __enter__(self) -> Self: return self @@ -112,41 +114,45 @@ def get_spectra_mz_range(self, i_spectra: list[int] | None) -> tuple[float, floa class GenericReadFile(Protocol): + """Encodes a container file handle, from which we can obtain GenericReader instances.""" + def reader(self) -> Generator[GenericReader, None, None]: """Returns a context manager that yields an `ImzmlReader` instance.""" - ... + raise NotImplementedError - def get_reader(self) -> GenericReader: ... + def get_reader(self) -> GenericReader: + """Returns an instance of the reader.""" + raise NotImplementedError @property def n_spectra(self) -> int: - """Returns the number of spectra in the .imzML file.""" - ... + """Number of spectra in the .imzML file.""" + raise NotImplementedError @property def imzml_mode(self) -> ImzmlModeEnum: - """Returns the mode of the .imzML file (continuous or processed).""" - ... + """Mode of the .imzML file (continuous or processed).""" + raise NotImplementedError @property def coordinates(self) -> NDArray[int]: - """Returns the spatial coordinates of the spectra in the .imzML file. + """Spatial coordinates of the spectra in the .imzML file. Shape: (n_spectra, n_dimensions) where n_dimensions is 2 or 3 depending on the file.""" - ... + raise NotImplementedError @property def coordinates_2d(self) -> NDArray[int]: - """Returns the spatial coordinates of the spectra in the .imzML file. + """Spatial coordinates of the spectra in the .imzML file. Shape: (n_spectra, 2) where the first two columns are the x and y coordinates.""" # TODO double check convention and update docstring accordingly return self.coordinates[:, :2] @property def compact_metadata(self) -> dict[str, int | str | list[float]]: - """Returns a compact representation of general metadata about the .imzML file, useful when comparing a large + """Compact representation of general metadata about the .imzML file, useful when comparing a large number of files.""" # TODO should this really be here - ... + raise NotImplementedError def is_checksum_valid(self) -> bool | None: """Returns True if the checksum of the .ibd file matches the expected value. False otherwise. @@ -154,11 +160,11 @@ def is_checksum_valid(self) -> bool | None: `None` is returned when checksum information is available. """ # TODO should this really be here - ... + raise NotImplementedError def summary(self, checksums: bool = True) -> str: """Returns a summary of the file.""" - ... + raise NotImplementedError def print_summary(self, checksums: bool = True, file: TextIO | None = None) -> None: """Prints a summary of the file.""" @@ -167,7 +173,7 @@ def print_summary(self, checksums: bool = True, file: TextIO | None = None) -> N @property def pixel_size(self) -> PixelSize | None: """Returns pixel size information, if available.""" - ... + raise NotImplementedError # TODO consider including in the generic interface # def copy_to(self, path: Path) -> None: