Source code for photon_mosaic.core.binaryrois

"""Binary folder format for ROI data.

Classes
-------
BinaryRois
    ROI extractor that loads image masks from a .npy file on disk.
BinaryFolderRois
    ROI extractor that loads from a folder containing masks, metadata, and provenance.
"""

import json
import shutil
from pathlib import Path

import numpy as np
import sparse
from spikeinterface.core.core_tools import (
    load_annotations_from_folder,
    load_properties_from_folder,
    save_annotations_to_folder,
    save_properties_to_folder,
    save_provenance_to_folder,
)

from .baserois import BaseRois


[docs] class BinaryRois(BaseRois): """ROI extractor backed by .npy or .npz files on disk. Parameters ---------- file_path : str or Path Path to the file containing image masks (num_rois, height, width[, planes]) -- ``.npy`` for a dense array, ``.npz`` for a sparse `pydata/sparse` array. sampling_frequency : float Sampling frequency of the ROIs in Hz. roi_ids : ArrayLike Array of ROI IDs. shape : tuple Shape of the ROI masks (height, width[, planes]). """ def __init__(self, file_path, sampling_frequency, roi_ids, shape): file_path = Path(file_path) roi_ids = np.asarray(roi_ids) BaseRois.__init__( self, sampling_frequency=sampling_frequency, shape=shape, roi_ids=roi_ids, ) self._file_path = file_path self._kwargs = { "file_path": str(file_path.absolute()), "sampling_frequency": sampling_frequency, "roi_ids": roi_ids, "shape": shape, }
[docs] def get_roi_image_masks(self, roi_ids=None): if self._file_path.suffix == ".npz": masks = sparse.load_npz(self._file_path) else: masks = np.load(self._file_path) if roi_ids is None: return masks roi_indices = self.ids_to_indices(roi_ids) return masks[roi_indices]
[docs] class BinaryFolderRois(BinaryRois): """ROI extractor that loads from a folder saved by ``BaseRois.save()``. The folder must contain: - ``roi_image_masks.npy`` (dense) or ``roi_image_masks.npz`` (sparse) — the mask data - ``roi_ids.npy`` — the ROI IDs - ``metadata.json`` — sampling_frequency and shape - ``binary.json`` — provenance file (written by ``BaseRois.save()``) Optionally: - ``properties/`` folder with per-ROI property .npy files - ``annotations.json`` with annotations Parameters ---------- folder_path : str or Path Path to the folder. """ def __init__(self, folder_path): folder_path = Path(folder_path) with open(folder_path / "metadata.json", "r") as f: metadata = json.load(f) roi_ids = np.load(folder_path / "roi_ids.npy") npz_path = folder_path / "roi_image_masks.npz" file_path = npz_path if npz_path.is_file() else folder_path / "roi_image_masks.npy" BinaryRois.__init__( self, file_path=file_path, sampling_frequency=metadata["sampling_frequency"], roi_ids=roi_ids, shape=tuple(metadata["shape"]), ) # Load properties and annotations load_properties_from_folder(folder_path / "properties", self) load_annotations_from_folder(folder_path, self) # Override _kwargs so serialisation round-trips through BinaryFolderRois self._kwargs = dict(folder_path=str(folder_path.absolute()))
[docs] @staticmethod def write_rois( rois: BaseRois, folder_path: str | Path, overwrite: bool = False, ): """Write ROI data as binary into a folder and return a reloaded ROIs. Parameters ---------- rois : BaseRois ROIs instance to write. folder_path : str or pathlib.Path Output path for the Zarr store. overwrite : bool, default: False If ``True``, overwrite an existing store at ``folder_path``. Returns ------- BinaryFolderRois A :class:`BinaryFolderRois` instance. Notes ----- Implemented as a static method so it can be called by :meth:`BaseRois.save` without instantiating :class:`BinaryFolderRois`. This is its only intended use. """ folder_path = Path(folder_path) if folder_path.is_dir(): if not overwrite: raise FileExistsError(f"Folder {folder_path} already exists. Use overwrite=True to overwrite it.") else: shutil.rmtree(folder_path) folder_path.mkdir(exist_ok=False, parents=True) image_masks = rois.get_roi_image_masks() if isinstance(image_masks, sparse.SparseArray): # np.save doesn't understand sparse arrays; sparse.save_npz stores the # data/coords/shape directly instead of densifying. mask_file = folder_path / "roi_image_masks.npz" sparse.save_npz(mask_file, image_masks) else: mask_file = folder_path / "roi_image_masks.npy" np.save(mask_file, image_masks) np.save(folder_path / "roi_ids.npy", np.array(rois.roi_ids)) metadata = dict( sampling_frequency=float(rois.sampling_frequency), shape=list(rois.shape), ) with open(folder_path / "metadata.json", "w") as f: json.dump(metadata, f, indent=4) binary_rois = BinaryRois( file_path=mask_file, sampling_frequency=rois.sampling_frequency, roi_ids=rois.roi_ids, shape=rois.shape, ) binary_rois.dump(folder_path / "binary.json", relative_to=folder_path) save_provenance_to_folder(folder_path, rois, relative_to=folder_path) save_properties_to_folder(folder_path / "properties", rois) save_annotations_to_folder(folder_path, rois) cached = BinaryFolderRois(folder_path=folder_path) return cached