Skip to content

Commit

Permalink
add some docs to persistence module
Browse files Browse the repository at this point in the history
  • Loading branch information
leoschwarz committed Sep 27, 2024
1 parent aeacc27 commit 76b3230
Show file tree
Hide file tree
Showing 4 changed files with 51 additions and 16 deletions.
1 change: 1 addition & 0 deletions docs/modules/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
This section contains documentation about the individual modules of depiction.
30 changes: 30 additions & 0 deletions docs/modules/persistence.md
Original file line number Diff line number Diff line change
@@ -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
2 changes: 0 additions & 2 deletions mkdocs.yml
Original file line number Diff line number Diff line change
@@ -1,6 +1,4 @@
site_name: depiction docs
nav:
- index.md
theme:
name: material
features:
Expand Down
34 changes: 20 additions & 14 deletions src/depiction/persistence/types.py
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,8 @@


class GenericReader(Protocol):
"""Reader for an .imzML file."""

def __enter__(self) -> Self:
return self

Expand Down Expand Up @@ -112,53 +114,57 @@ 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.
This operation can be slow for large files, but will be cached after the first call.
`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."""
Expand All @@ -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:
Expand Down

0 comments on commit 76b3230

Please sign in to comment.