microcorrelate.io ================= .. py:module:: microcorrelate.io .. autoapi-nested-parse:: This module contains various functions to read image and create image objects. Functions --------- .. autoapisummary:: microcorrelate.io.create_itk_image microcorrelate.io.extract_tpef_spacing microcorrelate.io.read_laicp_hdf5 microcorrelate.io.read_ome_zarr microcorrelate.io.read_tofsims microcorrelate.io.read_tpef microcorrelate.io.select_laicp_channels Module Contents --------------- .. py:function:: create_itk_image(image: numpy.ndarray, spacing: float | tuple[float, float] = (1.0, 1.0), origin: tuple[float, float] = (0.0, 0.0), channel_axis: int | None = None) -> SimpleITK.Image Convert a NumPy array to a SimpleITK Image. This is a simple conversion function for creating ITK images from in-memory arrays (e.g., from HDF5 files, zarr arrays, or other sources). Both single- and multi-channel images are supported. Pixel spacing can be isotropic (scalar) or anisotropic (tuple). For a reference of the SimpleITK Image origin and spacing, see: https://itk.org/ITKSoftwareGuide/html/Book1/ITKSoftwareGuide-Book1ch4.html :param image: The input image as a NumPy array. :type image: np.ndarray :param spacing: The pixel spacing in physical units. For isotropic images, this is the distance between pixel centers. Default is (1.0, 1.0). :type spacing: float | tuple of float, optional :param origin: The physical coordinates of the origin (0,0) pixel. Default is (0.0, 0.0). :type origin: tuple of float, optional :param channel_axis: The axis in image that contains channel information, if the image is multichannel. If None, the image is treated as single channel. Default is None. :type channel_axis: int | None, optional :returns: **image_itk** -- SimpleITK Image object with specified spacing and origin. :rtype: SimpleITK.Image .. rubric:: Examples .. code-block:: python import numpy as np from microcorrelate.utils import create_itk_image # Create from HDF5 array import h5py with h5py.File('data.h5', 'r') as f: array = f['images/layer1'][:] image = create_itk_image(array, spacing=0.5) # Create from zarr array import zarr z = zarr.open('data.zarr', mode='r') image = create_itk_image(z['images/0'][:], spacing=1.2) .. py:function:: extract_tpef_spacing(filepath: pathlib.Path | str) -> tuple[float, float] Extract YX spacing values for a TPEF experiment. Input should be an `exp_prop.txt` file, which contains acquisition properties for the experiment. This function currently ignores Z spacing. :param filepath: Path to `exp_prop.txt` file. The file should contain spacing in the format `" X 512 1.381068 µm"` :type filepath: Path | str :returns: **spacing** -- Spacing in micrometers (Y, X). :rtype: tuple[float, float] :raises ValueError: If X or Y spacing was not detected in the file. .. py:function:: read_laicp_hdf5(filepath: pathlib.Path | str, elements: list[str] | str | None = None, quant_suffix: str = '\n') -> tuple[numpy.ndarray, tuple[float, float], list[str]] Read LA-ICP-MS data from a TOFWERK HDF5 file. Reads the reconstructed image data, infers pixel spacing from the position grid, and only keep user selected channels and total ion count. :param filepath: Path to the HDF5 file. :type filepath: Path | str :param elements: Element names to search for in channel labels (e.g. ``['Cu', 'Zn']``). Channels whose label contains any of these names are included in addition to TIC and user-selected channels. If ``None``, no element-based filtering is applied. :type elements: list[str] | str | None, optional :param quant_suffix: Suffix identifying user-defined quantification channels. Default is ``"\n"``. :type quant_suffix: str :returns: * **data** (*np.ndarray*) -- Image array of shape (n_channels, rows, cols). Total ion count, user-selected channels (ending with ``'\n'``), and any element-matched channels are kept. * **spacing** (*tuple[float, float]*) -- Pixel spacing in micrometers (row, col). * **labels** (*list[str]*) -- Channel labels corresponding to axis 0 of the preserved data. .. py:function:: read_ome_zarr(zarr_path: pathlib.Path | str) -> tuple[numpy.ndarray, tuple[float, float]] Read highest resolution level from OME-Zarr with spacing. :param zarr_path: Path to the zarr store. :type zarr_path: Path or str :returns: * **data** (*np.ndarray*) -- Image array at highest resolution. * **spacing** (*tuple[float, float]*) -- Pixel spacing in micrometers (Y, X). :raises ValueError: If unit is not nanometer or micrometer. .. py:function:: read_tofsims(filepath: pathlib.Path) -> tuple[numpy.ndarray, tuple[float, float]] Read ToF-SIMS measurement and returns image data and spacing. :param filepath: Path to the txt file containing the ToF-SIMS data. :type filepath: Path :returns: * **data** (*np.ndarray*) -- Single channel image array. * **spacing** (*tuple[float, float]*) -- Pixel spacing in micrometers (Y, X). .. py:function:: read_tpef(image_path: pathlib.Path, max_level: int = 3) -> tuple[numpy.ndarray, tuple[float, float]] Read TPEF image data and discover pixel spacing from metadata file. Searches for `exp_prop.txt` in the image directory and up to `max_level` parent directories to extract pixel spacing information. :param image_path: Path to the TPEF image file. :type image_path: Path :param max_level: Maximum number of parent directory levels to search for `exp_prop.txt`. Default is 3. :type max_level: int, optional :returns: * **image** (*np.ndarray*) -- Image array with shape (Z, channels, Y, X) or (channels, Y, X). * **spacing** (*tuple[float, float]*) -- Pixel spacing in micrometers (Y, X). :raises FileNotFoundError: If `exp_prop.txt` is not found within the search scope. .. seealso:: :py:obj:`extract_tpef_spacing` Extract spacing from `exp_prop.txt` file. .. py:function:: select_laicp_channels(channels: list[str], elements: list[str] | str | None = None, quant_suffix: str = '\n') -> list[int] Select relevant LA-ICP-MS channel indices from a list of channel labels. This function assumes that the first channel represents the total ion count, and that user-defined quantification channels have a suffix that identifies them. :param channels: All channel names from the measurement. :type channels: list[str] :param elements: Element symbols to retain (e.g. ``["Y", "N", "Ca"]``). If None, keep only quantification channels. Default is None. :type elements: list[str] | None :param quant_suffix: Suffix identifying user-defined quantification channels. Default is ``"\n"``. :type quant_suffix: str :returns: Ordered, deduplicated indices of selected channels. :rtype: list[int]