DataStore Class

Interface to qi2lab MERFISH datastore.

This module provides methods and attributes to create or interact with the qi2lab MERFISH datastore. The filestore structure is further described in the merfish3d-analysis documentation.

History:

2024/12: Refactored repo structure.
2024/12: Updated docstrings and exception types.
2024/07: Initial commit.

Classes:

Name	Description
`qi2labDataStore`	API to qi2lab MERFISH store.

`qi2labDataStore`

API to qi2lab MERFISH store.

Parameters:

Name	Type	Description	Default
`datastore_path`	`str or Path`	Path to qi2lab MERFISH store	required
`validate`	`bool`	Validate datastore contents on open. Set False to skip expensive zarr readability checks and load only metadata/path structure.	`True`

Methods:

Name	Description
`__init__`	Initialize a qi2lab datastore handle.
`baysor_3d_available`	Return whether Baysor 3D molecules and cell boundaries are present.
`decoded_temporary_dir`	Return the temporary decoded-output directory for a decode run.
`fused_image_path`	Return the OME-Zarr path for a fused image.
`image_shape`	Read image shape without loading all pixels.
`initialize_tile`	Initialize directory structure for a tile.
`list_proseg_3d_runs`	List available Proseg 3D output runs.
`load_baysor_cell_boundaries_3d`	Load Baysor 3D cell boundary polygons.
`load_baysor_molecules_3d`	Load Baysor 3D molecule assignments.
`load_chromatic_affine_transform_zyx_um`	Load one chromatic affine transform with identity fallback.
`load_chromatic_affine_transforms_zyx_um`	Load chromatic affine calibration metadata.
`load_codebook_parsed`	Load and split codebook into gene_ids and codebook matrix.
`load_coord_of_xform_px`	Local fiducial optical flow matrix for one round and tile.
`load_decode_normalization_metadata`	Load provenance for default or run-scoped normalization vectors.
`load_decode_normalization_vectors`	Load run-scoped normalization and background vectors.
`load_global_cellpose_outlines`	Load Cellpose max projection cell outlines.
`load_global_cellpose_roi_zip`	Load global Cellpose outlines from an ImageJ ROI zip.
`load_global_cellpose_segmentation_image`	Load Cellpose max projection, downsampled segmentation image.
`load_global_coord_xforms_um`	Load global registration transform for one tile.
`load_global_fiducial_image`	Load downsampled, fused fiducial image.
`load_global_filtered_decoded_spots`	Load all decoded and filtered spots.
`load_image_metadata`	Load extra attributes through yaozarrs.
`load_local_bit_linker`	Load readout bits linked to fiducial round for one tile.
`load_local_corrected_image`	Load gain and offset corrected image for fiducial OR readout bit for one tile.
`load_local_decoded_spots`	Load decoded spots and features for one tile.
`load_local_deconvolved_fiducial_image`	Load a native-frame deconvolved fiducial image.
`load_local_deconvolved_readout_image`	Load a native-frame deconvolved readout bit image.
`load_local_feature_predictor_image`	Load readout bit feature_predictor prediction image for one tile.
`load_local_feature_predictor_spots`	Load feature_predictor spot localizations and features for one tile.
`load_local_fiducial_image`	Load the best available native-frame fiducial image.
`load_local_image_metadata`	Load image and sidecar metadata for one fiducial round or readout bit.
`load_local_readout_image`	Load the best available native-frame readout bit image.
`load_local_rigid_xform_xyz_px`	Load calculated rigid registration transform for one round and tile.
`load_local_round_linker`	Load fiducial round linked to readout bit for one tile.
`load_local_round_transform_zyx_um`	Load the local fiducial round transform for one tile.
`load_local_sofima_flow_field`	Load the SOFIMA flow field for one local fiducial round.
`load_local_stage_position_zyx_um`	Load tile stage position for one tile.
`load_local_wavelengths_um`	Load wavelengths for fiducial OR readout bit for one tile.
`load_proseg_cell_polygons_3d`	Load Proseg 3D refined cell polygons.
`load_proseg_transcripts_3d`	Load Proseg 3D transcript metadata.
`local_feature_predictor_spots_path`	Return the localization table path for a tile and readout identifier.
`local_image_path`	Return a native fiducial or readout OME-Zarr image path.
`save_chromatic_affine_transforms_zyx_um`	Save chromatic affine calibration metadata.
`save_coord_of_xform_px`	Save fiducial optical flow matrix for one round and tile.
`save_decode_normalization_vectors`	Save default or run-scoped normalization and background vectors.
`save_global_cellpose_segmentation_image`	Save Cellpose max projection, downsampled segmentation image.
`save_global_coord_xforms_um`	Save global registration transform for one tile.
`save_global_fiducial_image`	Save downsampled, fused fiducial image.
`save_global_filtered_decoded_spots`	Save all decoded and filtered spots.
`save_image_metadata`	Write image-level extra attributes for externally-created OME-Zarr stores.
`save_local_bit_linker`	Save readout bits linked to fiducial round for one tile.
`save_local_corrected_image`	Save gain and offset corrected image.
`save_local_decoded_spots`	Save decoded spots and features for one tile.
`save_local_deconvolved_fiducial_image`	Save a native-frame deconvolved fiducial image.
`save_local_deconvolved_readout_image`	Save a native-frame deconvolved readout bit image.
`save_local_feature_predictor_image`	Save feature_predictor prediction image.
`save_local_feature_predictor_spots`	Save feature_predictor localizations and features.
`save_local_rigid_xform_xyz_px`	Save calculated rigid registration transform for one round and tile.
`save_local_round_linker`	Save fiducial round linker attribute to readout bit for one tile.
`save_local_round_transform_zyx_um`	Save the local fiducial round transform for one tile.
`save_local_sofima_flow_field`	Save the SOFIMA flow field for one local fiducial round.
`save_local_stage_position_zyx_um`	Save tile stage position for one tile.
`save_local_wavelengths_um`	Save wavelengths for fiducial OR readout bit for one tile.

Attributes:

Name	Type	Description
`binning`	`int \| None`	Camera binning.
`bit_ids`	`Collection[str] \| None`	Bit IDs.
`camera_model`	`str \| None`	Camera model.
`channel_psfs`	`ArrayLike \| None`	Channel point spread functions (PSF).
`channel_shading_maps`	`ArrayLike \| None`	Channel shaiding images.
`channels_in_data`	`Collection[int] \| None`	Channel indices.
`codebook`	`DataFrame \| None`	Codebook.
`datastore_path`	`Path`	Experiment datastore directory.
`datastore_state`	`dict \| None`	Datastore state.
`e_per_ADU`	`float \| None`	Electrons per camera ADU.
`experiment_order`	`DataFrame \| None`	Round and bit order.
`global_background_vector`	`ArrayLike \| None`	Global background vector.
`global_normalization_vector`	`ArrayLike \| None`	Global normalization vector.
`iterative_background_vector`	`ArrayLike \| None`	Iterative background vector.
`iterative_normalization_vector`	`ArrayLike \| None`	Iterative normalization vector.
`microscope_type`	`str \| None`	Microscope type.
`na`	`float \| None`	Detection objective numerical aperture (NA).
`noise_map`	`ArrayLike \| None`	Camera noise image.
`num_bits`	`int`	Number of bits.
`num_rounds`	`int \| None`	Number of rounds.
`num_tiles`	`int \| None`	Number of tiles.
`ri`	`float \| None`	Detection objective refractive index (RI).
`round_ids`	`Collection[str] \| None`	Round IDs.
`tile_ids`	`Collection[str] \| None`	Tile IDs.
`tile_overlap`	`float \| None`	XY tile overlap.
`voxel_size_zyx_um`	`ArrayLike \| None`	Voxel size, zyx order (microns).

Source code in src/merfish3danalysis/qi2labDataStore.py

class qi2labDataStore:
    """API to qi2lab MERFISH store.

    Parameters
    ----------
    datastore_path : str or Path
        Path to qi2lab MERFISH store
    validate : bool, default True
        Validate datastore contents on open. Set False to skip expensive
        zarr readability checks and load only metadata/path structure.

    """

    def __init__(self, datastore_path: str | Path, validate: bool = True) -> None:
        """
        Initialize a qi2lab datastore handle.

        Parameters
        ----------
        datastore_path : str | Path
            Datastore root path.
        validate : bool
            Whether to validate existing image arrays while parsing the store.
        """
        self._datastore_path = Path(datastore_path)
        if self._datastore_path.exists():
            self._parse_datastore(validate=validate)
        else:
            self._init_datastore()

    @property
    def datastore_path(self) -> Path:
        """Experiment datastore directory."""
        return self._datastore_path

    def fused_image_path(self, image_name: str | None = None) -> Path:
        """Return the OME-Zarr path for a fused image.

        Parameters
        ----------
        image_name : str or None
            Logical image name. None selects the fused fiducial volume.

        Returns
        -------
        Path
            Fused image directory, without opening or creating it.
        """
        if image_name is None:
            image_name = f"fused_{self.fiducial_folder_name}_zyx"
        return self._image_store_path(self._fused_root_path / image_name)

    def local_image_path(
        self,
        tile: int | str,
        image_name: str,
        *,
        round: int | str | None = None,
        bit: int | str | None = None,
    ) -> Path:
        """Return a native fiducial or readout OME-Zarr image path.

        Parameters
        ----------
        tile : int or str
            Zero-based tile index or stored tile identifier.
        image_name : str
            Logical image name such as corrected_data or decon_data.
        round : int or str or None
            Zero-based fiducial round index or identifier; excludes bit.
        bit : int or str or None
            Zero-based readout bit index or identifier; excludes round.

        Returns
        -------
        Path
            Image path without loading pixels or creating directories.
        """
        if (round is None) == (bit is None):
            raise ValueError("Provide exactly one of round or bit.")
        if isinstance(tile, int) and not 0 <= tile < len(self._tile_ids):
            raise ValueError(f"Invalid tile: {tile}")
        tile_id = self._tile_ids[tile] if isinstance(tile, int) else tile
        if tile_id not in self._tile_ids:
            raise ValueError(f"Invalid tile: {tile}")
        ids = self._round_ids if round is not None else self._bit_ids
        selection = round if round is not None else bit
        if isinstance(selection, int) and not 0 <= selection < len(ids):
            raise ValueError(f"Invalid round or bit: {selection}")
        entity_id = ids[selection] if isinstance(selection, int) else selection
        if entity_id not in ids:
            raise ValueError(f"Invalid round or bit: {selection}")
        root = (
            self._fiducial_root_path if round is not None else self._readouts_root_path
        )
        return self._image_store_path(root / tile_id / entity_id / image_name)

    def local_feature_predictor_spots_path(self, tile: str, bit: str) -> Path:
        """Return the localization table path for a tile and readout identifier."""
        if tile not in self._tile_ids or bit not in self._bit_ids:
            raise ValueError(f"Invalid tile or bit: {tile}, {bit}")
        return (
            self._feature_predictor_localizations_root_path / tile / (bit + ".parquet")
        )

    def load_local_image_metadata(
        self,
        tile: int | str,
        *,
        round: int | str | None = None,
        bit: int | str | None = None,
        image_names: Sequence[str] | None = None,
    ) -> dict[str, Any]:
        """Load image and sidecar metadata for one fiducial round or readout bit.

        Parameters
        ----------
        tile : int or str
            Tile index or identifier.
        round : int or str or None
            Fiducial round index or identifier; excludes bit.
        bit : int or str or None
            Readout bit index or identifier; excludes round.

        image_names : Sequence[str] or None
            Image names to inspect, in metadata precedence order.

        Returns
        -------
        dict[str, Any]
            Merged image metadata, with sidecar values taking precedence.
        """
        path = self.local_image_path(tile, "corrected_data", round=round, bit=bit)
        return self._load_entity_attributes(path.parent, image_names=image_names)

    @property
    def datastore_state(self) -> dict | None:
        """Datastore state.

        Returns
        -------
        datastore_state : dict or None
            Datastore state.
        """
        return getattr(self, "_datastore_state", None)

    @datastore_state.setter
    def datastore_state(self, value: dict) -> None:
        """Set the datastore state.

        Parameters
        ----------
        value : dict
            New datastore state.
        """
        state = dict(self.datastore_state or {})
        state.update(value)
        self._save_to_json(state, self._datastore_state_json_path)
        self._datastore_state = state

    def _calibrations_attributes_path(self) -> Path:
        """
        Path to calibrations metadata sidecar.

        Returns
        -------
        Path
            Path to ``calibrations/attributes.json``.
        """
        return self._calibrations_zarr_path / Path("attributes.json")

    def _load_calibrations_attributes(self) -> dict[str, Any]:
        """
        Load calibrations metadata sidecar.

        Returns
        -------
        dict[str, Any]
            Calibration metadata loaded from disk.
        """
        attributes_path = self._calibrations_attributes_path()
        if not attributes_path.is_file():
            raise FileNotFoundError(
                f"Calibration attributes not found: {attributes_path}"
            )
        return self._load_from_json(attributes_path)

    def _save_calibrations_attributes(self, attributes: Mapping[str, Any]) -> None:
        """
        Persist calibrations metadata sidecar.

        Parameters
        ----------
        attributes : Mapping[str, Any]
            Calibration metadata to write.

        Returns
        -------
        None
            No return value.
        """
        self._save_to_json(
            {str(k): self._to_json_compatible(v) for k, v in dict(attributes).items()},
            self._calibrations_attributes_path(),
        )

    def _set_calibration_attribute(self, key: str, value: Any) -> None:
        """
        Update one calibration metadata field.

        Parameters
        ----------
        key : str
            Calibration metadata key.
        value : Any
            Value to store after JSON conversion.

        Returns
        -------
        None
            No return value.
        """
        attributes = self._load_calibrations_attributes()
        attributes[str(key)] = self._to_json_compatible(value)
        self._save_calibrations_attributes(attributes)

    def save_chromatic_affine_transforms_zyx_um(
        self,
        calibration: Mapping[str, Any],
    ) -> None:
        """
        Save chromatic affine calibration metadata.

        Parameters
        ----------
        calibration : Mapping[str, Any]
            Calibration metadata containing one 4x4 ``affine_zyx_um`` matrix
            per channel. Each affine maps that channel's physical Z, Y, X
            coordinates onto the lowest-wavelength reference channel.

        Returns
        -------
        None
            Metadata are written to ``calibrations/attributes.json``.
        """
        calibration = dict(calibration)
        if "voxel_size_zyx_um" in calibration:
            calibration["voxel_size_zyx_um"] = round_spacing_um(
                calibration["voxel_size_zyx_um"]
            ).tolist()
        self._set_calibration_attribute(
            "chromatic_affine_transforms_zyx_um",
            calibration,
        )

    def load_chromatic_affine_transforms_zyx_um(self) -> dict[str, Any]:
        """
        Load chromatic affine calibration metadata.

        Returns
        -------
        dict[str, Any]
            Stored calibration metadata. Returns an empty dictionary when no
            chromatic calibration is present.
        """
        try:
            attributes = self._load_calibrations_attributes()
        except (FileNotFoundError, json.JSONDecodeError, ValueError):
            return {}
        calibration = attributes.get("chromatic_affine_transforms_zyx_um", {})
        if isinstance(calibration, dict):
            if "voxel_size_zyx_um" in calibration:
                calibration["voxel_size_zyx_um"] = round_spacing_um(
                    calibration["voxel_size_zyx_um"]
                ).tolist()
            return calibration
        return {}

    def load_chromatic_affine_transform_zyx_um(
        self,
        channel_name: str | None = None,
        channel_index: int | None = None,
        wavelength_um: float | None = None,
    ) -> np.ndarray:
        """
        Load one chromatic affine transform with identity fallback.

        Parameters
        ----------
        channel_name : str or None, default=None
            Channel name from the calibration metadata.
        channel_index : int or None, default=None
            Channel index from the calibration metadata.
        wavelength_um : float or None, default=None
            Channel wavelength in microns. Used only when channel name/index do
            not find a match.

        Returns
        -------
        numpy.ndarray
            4x4 affine matrix in physical Z, Y, X microns. Identity is returned
            if the calibration or requested channel is absent.
        """
        calibration = self.load_chromatic_affine_transforms_zyx_um()
        channels = calibration.get("channels", {})
        if not isinstance(channels, Mapping):
            return np.eye(4, dtype=np.float32)

        candidates = []
        if channel_name is not None:
            channel = channels.get(str(channel_name))
            if isinstance(channel, Mapping):
                candidates.append(channel)
        if channel_index is not None:
            for channel in channels.values():
                if isinstance(channel, Mapping) and int(
                    channel.get("channel_index", -1)
                ) == int(channel_index):
                    candidates.append(channel)
        if wavelength_um is not None:
            wavelength = float(wavelength_um)
            for channel in channels.values():
                if not isinstance(channel, Mapping):
                    continue
                stored = channel.get("wavelength_um")
                if stored is not None and np.isclose(float(stored), wavelength):
                    candidates.append(channel)

        for channel in candidates:
            affine = channel.get("affine_zyx_um")
            if affine is not None:
                return np.asarray(affine, dtype=np.float32)
        return np.eye(4, dtype=np.float32)

    @staticmethod
    def _strict_id_sort_key(name: str, prefix: str, width: int) -> int:
        """
        Validate and parse strict zero-padded identifiers.

        Parameters
        ----------
        name : str
            Identifier to validate.
        prefix : str
            Required identifier prefix.
        width : int
            Required number of zero-padded digits.

        Returns
        -------
        int
            Parsed numeric identifier.
        """
        match = re.fullmatch(rf"{re.escape(prefix)}(\d{{{width}}})", name)
        if match is None:
            raise ValueError(
                f"Invalid identifier '{name}'. Expected '{prefix}' followed by {width} digits."
            )
        return int(match.group(1))

    @classmethod
    def _collect_strict_ids(cls, parent: Path, prefix: str, width: int) -> list[str]:
        """
        Collect and sort strict identifiers under a folder.

        Parameters
        ----------
        parent : Path
            Folder containing identifier-named child directories.
        prefix : str
            Required identifier prefix.
        width : int
            Required number of zero-padded digits.

        Returns
        -------
        list[str]
            Strict identifiers sorted by numeric value.
        """

        def sort_id(value: str) -> tuple[int, int, str]:
            """
            Return the strict identifier sort key.

            Parameters
            ----------
            value : str
                Identifier string.

            Returns
            -------
            tuple[int, int, str]
                Numeric and lexical sort key.
            """
            return cls._strict_id_sort_key(value, prefix, width)

        ids = [entry.name for entry in parent.iterdir() if entry.is_dir()]
        ids.sort(key=sort_id)
        return ids

    @property
    def microscope_type(self) -> str | None:
        """Microscope type.

        Returns
        -------
        microscope_type : str or None
            Microscope type.
        """
        return getattr(self, "_microscope_type", None)

    @microscope_type.setter
    def microscope_type(self, value: str) -> None:
        """Set the microscope type.

        Parameters
        ----------
        value : str
            New microscope type.
        """
        self._microscope_type = value
        self._set_calibration_attribute("microscope_type", value)

    @property
    def camera_model(self) -> str | None:
        """Camera model.

        Returns
        -------
        camera_model : str or None
            Camera model.
        """
        return getattr(self, "_camera_model", None)

    @camera_model.setter
    def camera_model(self, value: str) -> None:
        """Set the camera model.

        Parameters
        ----------
        value : str
            New camera model.
        """
        self._camera_model = value
        self._set_calibration_attribute("camera_model", value)

    @property
    def num_rounds(self) -> int | None:
        """Number of rounds.

        Returns
        -------
        num_rounds : int
            Number of rounds.
        """
        return getattr(self, "_num_rounds", None)

    @num_rounds.setter
    def num_rounds(self, value: int) -> None:
        """Set the number of rounds.

        Parameters
        ----------
        value : int
            New number of rounds.
        """
        self._num_rounds = value
        self._set_calibration_attribute("num_rounds", value)

    @property
    def num_bits(self) -> int:
        """Number of bits.

        Returns
        -------
        num_bits : int
            Number of bits.
        """
        return getattr(self, "_num_bits", None)

    @num_bits.setter
    def num_bits(self, value: int) -> None:
        """Set the number of bits.

        Parameters
        ----------
        value : int
            Number of bits.
        """
        self._num_bits = value
        self._set_calibration_attribute("num_bits", value)

    @property
    def num_tiles(self) -> int | None:
        """Number of tiles.

        Returns
        -------
        num_tiles : int
            Number of tiles.
        """
        return getattr(self, "_num_tiles", None)

    @num_tiles.setter
    def num_tiles(self, value: int) -> None:
        """Set the number of tiles.

        Parameters
        ----------
        value : int
            New number of tiles.
        """
        self._num_tiles = value
        self._set_calibration_attribute("num_tiles", value)

        self._tile_ids = []
        for tile_idx in range(value):
            self._tile_ids.append("tile" + str(tile_idx).zfill(4))

    @property
    def channels_in_data(self) -> Collection[int] | None:
        """Channel indices.

        Returns
        -------
        channels_in_data : Collection[int]
            Channel indices.
        """
        return getattr(self, "_channels_in_data", None)

    @channels_in_data.setter
    def channels_in_data(self, value: Collection[int]) -> None:
        """Set the channels in the data.

        Parameters
        ----------
        value : Collection[int]
            New channels in data (int values starting from zero).
        """
        self._channels_in_data = value
        self._set_calibration_attribute("channels_in_data", value)

    @property
    def tile_overlap(self) -> float | None:
        """XY tile overlap.

        Returns
        -------
        tile_overlap : float
            XY tile overlap.
        """
        return getattr(self, "_tile_overlap", None)

    @tile_overlap.setter
    def tile_overlap(self, value: float) -> None:
        """Set the tile overlap.

        Parameters
        ----------
        value : float
            New tile overlap.
        """
        self._tile_overlap = value
        self._set_calibration_attribute("tile_overlap", value)

    @property
    def binning(self) -> int | None:
        """Camera binning.

        Returns
        -------
        binning : int
            Camera binning.
        """
        return getattr(self, "_binning", None)

    @binning.setter
    def binning(self, value: int) -> None:
        """Set the camera binning.

        Parameters
        ----------
        value : int
            New camera binning.
        """
        self._binning = value
        self._set_calibration_attribute("binning", value)

    @property
    def e_per_ADU(self) -> float | None:
        """Electrons per camera ADU.

        Returns
        -------
        e_per_ADU : float
            Electrons per camera ADU.
        """
        return getattr(self, "_e_per_ADU", None)

    @e_per_ADU.setter
    def e_per_ADU(self, value: float) -> None:
        """Set the camera conversion (e- per ADU).

        Parameters
        ----------
        value : float
            New camera conversion (e- per ADU).
        """
        self._e_per_ADU = value
        self._set_calibration_attribute("e_per_ADU", value)

    @property
    def na(self) -> float | None:
        """Detection objective numerical aperture (NA).

        Returns
        -------
        na : float
            Detection objective numerical aperture (NA).
        """
        return getattr(self, "_na", None)

    @na.setter
    def na(self, value: float) -> None:
        """Set detection objective numerical aperture (NA).

        Parameters
        ----------
        value: float
            New detection objective numerical aperture (NA)
        """
        self._na = value
        self._set_calibration_attribute("na", value)

    @property
    def ri(self) -> float | None:
        """Detection objective refractive index (RI).

        Returns
        -------
        ri : float
            Detection objective refractive index (RI).
        """
        return getattr(self, "_ri", None)

    @ri.setter
    def ri(self, value: float) -> None:
        """Set detection objective refractive index (RI).

        Parameters
        ----------
        value: float
            New detection objective refractive index (RI)
        """
        self._ri = value
        self._set_calibration_attribute("ri", value)

    @property
    def noise_map(self) -> ArrayLike | None:
        """Camera noise image.

        Returns
        -------
        noise_map : ArrayLike
            Camera noise image.
        """
        return getattr(self, "_noise_map", None)

    @noise_map.setter
    def noise_map(self, value: ArrayLike) -> None:
        """Set the camera noise image.

        Parameters
        ----------
        value : ArrayLike
            New camera noise image.
        """
        current_local_zarr_path = str(self._calibrations_zarr_path / Path("noise_map"))

        self._save_to_zarr_array(value, current_local_zarr_path, return_future=False)
        self._noise_map = value

    @property
    def channel_shading_maps(self) -> ArrayLike | None:
        """Channel shaiding images.

        Returns
        -------
        channel_shading_maps : ArrayLike
            Channel shading images.
        """
        return getattr(self, "_shading_maps", None)

    @channel_shading_maps.setter
    def channel_shading_maps(self, value: ArrayLike) -> None:
        """Set the channel shading images.

        Parameters
        ----------
        value : ArrayLike
            New channel shading images.
        """
        shading_maps = np.asarray(value, dtype=np.float32)
        if shading_maps.ndim == 2:
            shading_maps = np.expand_dims(shading_maps, axis=0)
        if shading_maps.ndim != 3:
            raise ValueError(
                f"Shading maps must be 2D or 3D, got shape {shading_maps.shape}"
            )
        if shading_maps.shape[0] > 1:
            reference_shape = tuple(shading_maps[0].shape)
            for channel_map in shading_maps[1:]:
                if tuple(channel_map.shape) != reference_shape:
                    raise ValueError(
                        "All shading maps must share the same YX shape "
                        f"(expected {reference_shape}, got {tuple(channel_map.shape)})."
                    )

        current_local_zarr_path = str(
            self._calibrations_zarr_path / Path("shading_maps")
        )

        self._save_to_zarr_array(
            shading_maps, current_local_zarr_path, return_future=False
        )
        self._shading_maps = shading_maps

    @property
    def channel_psfs(self) -> ArrayLike | None:
        """Channel point spread functions (PSF).

        Returns
        -------
        channel_psfs : ArrayLike
            Channel point spread functions (PSF).
        """
        psfs = getattr(self, "_psfs", None)
        if psfs is None:
            return None
        if isinstance(psfs, list):
            if len(psfs) == 0:
                return []
            shapes = {tuple(np.asarray(psf).shape) for psf in psfs}
            if len(shapes) == 1:
                return np.stack(psfs, axis=0)
            return psfs
        return psfs

    @channel_psfs.setter
    def channel_psfs(self, value: ArrayLike) -> None:
        """Set the channel point spread functions (PSF).

        Parameters
        ----------
        value : ArrayLike
            New channel point spread functions (PSF).
        """
        if isinstance(value, np.ndarray):
            if value.dtype == object:
                psf_list = [np.asarray(psf, dtype=np.float32) for psf in list(value)]
            elif value.ndim >= 3:
                psf_list = [
                    np.asarray(value[idx], dtype=np.float32)
                    for idx in range(value.shape[0])
                ]
            else:
                psf_list = [np.asarray(value, dtype=np.float32)]
        else:
            psf_list = [np.asarray(psf, dtype=np.float32) for psf in list(value)]

        if len(psf_list) == 0:
            raise ValueError("channel_psfs cannot be empty.")

        psf_root_path = self._calibrations_zarr_path / Path("psf_data")
        psf_root_path.mkdir(exist_ok=True, parents=True)
        psf_manifest: dict[str, Any] = {}

        for psf_idx, psf_array in enumerate(psf_list):
            psf_id = f"psf_{psf_idx:03d}"
            current_psf_path = psf_root_path / Path(psf_id)
            self._save_to_zarr_array(psf_array, current_psf_path, return_future=False)
            psf_manifest[str(psf_idx)] = {
                "id": psf_id,
                "shape_zyx": list(psf_array.shape),
            }

        self._set_calibration_attribute("psf_manifest", psf_manifest)
        self._psfs = psf_list

    @property
    def experiment_order(self) -> pd.DataFrame | None:
        """Round and bit order.

        Returns
        -------
        experiment_order : pd.DataFrame
            Round and bit order.
        """
        experiment_order = getattr(self, "_experiment_order", None)
        if experiment_order is not None:
            return experiment_order

        legacy_experiment_order = getattr(self, "_exp_order", None)
        if legacy_experiment_order is None:
            return None

        self._experiment_order = self._coerce_experiment_order_dataframe(
            legacy_experiment_order
        )
        return self._experiment_order

    def _coerce_experiment_order_dataframe(
        self, value: ArrayLike | pd.DataFrame
    ) -> pd.DataFrame:
        """
        Normalize experiment order into the canonical DataFrame form.

        Parameters
        ----------
        value : ArrayLike | pd.DataFrame
            Experiment order table or array to normalize.

        Returns
        -------
        pd.DataFrame
            Experiment order as a DataFrame with channel columns.
        """
        if isinstance(value, pd.DataFrame):
            return value

        channel_list = [str(channel) for channel in self._channels_in_data]
        return pd.DataFrame(value, columns=channel_list, dtype="int64")

    @experiment_order.setter
    def experiment_order(self, value: ArrayLike | pd.DataFrame) -> None:
        """Set the round and bit order.

        Parameters
        ----------
        value : ArrayLike or pandas.DataFrame
            New round and bit order.
        """
        self._experiment_order = self._coerce_experiment_order_dataframe(value)

        self._set_calibration_attribute("exp_order", self._experiment_order.values)

        if self.num_rounds is None:
            self.num_rounds = int(value[-1, 0])
        else:
            assert self.num_rounds == int(value[-1, 0]), (
                "Number of rounds does not match experiment order file."
            )

        if self.num_bits is None:
            self.num_bits = int(np.max(value[:, 1:]))
        else:
            assert self.num_bits == int(np.max(value[:, 1:])), (
                "Number of bits does not match experiment order file."
            )

        self._round_ids = []
        for round_idx in range(self.num_rounds):
            self._round_ids.append("round" + str(round_idx + 1).zfill(3))

        self._bit_ids = []
        for bit_idx in range(self.num_bits):
            self._bit_ids.append("bit" + str(bit_idx + 1).zfill(3))

    @property
    def codebook(self) -> pd.DataFrame | None:
        """Codebook.

        Returns
        -------
        codebook : pd.DataFrame
            Codebook.
        """
        data = getattr(self, "_codebook", None)

        if data is None:
            return None
        num_columns = len(data[0]) if data else 0
        columns = ["gene_id"] + [f"bit{i:02d}" for i in range(1, num_columns)]

        return pd.DataFrame(data, columns=columns)

    @codebook.setter
    def codebook(self, value: pd.DataFrame) -> None:
        """Set the codebook.

        Parameters
        ----------
        value : pd.DataFrame
            New codebook.
        """
        self._codebook = value
        self._set_calibration_attribute("codebook", self._codebook.values)

    @property
    def voxel_size_zyx_um(self) -> ArrayLike | None:
        """Voxel size, zyx order (microns).

        Returns
        -------
        voxel_size_zyx_um : ArrayLike
            Voxel size, zyx order (microns).
        """
        value = getattr(self, "_voxel_size_zyx_um", None)
        return None if value is None else self._normalize_voxel_size_zyx_um(value)

    @voxel_size_zyx_um.setter
    def voxel_size_zyx_um(self, value: ArrayLike) -> None:
        """Set the voxel size, zyx order (microns).

        Parameters
        ----------
        value : ArrayLike
            New voxel size, zyx order (microns).
        """
        spacing = self._normalize_voxel_size_zyx_um(value)
        self._set_calibration_attribute("voxel_size_zyx_um", spacing)
        self._voxel_size_zyx_um = spacing

    @staticmethod
    def _normalize_voxel_size_zyx_um(value: ArrayLike) -> list[float]:
        """Validate three positive finite ZYX spacings at stored precision."""
        spacing = round_spacing_um(value)
        if (
            spacing.shape != (3,)
            or not np.all(np.isfinite(spacing))
            or np.any(spacing <= 0)
        ):
            raise ValueError(
                "voxel_size_zyx_um must contain three positive finite ZYX spacings."
            )
        return spacing.tolist()

    @property
    def global_normalization_vector(self) -> ArrayLike | None:
        """Global normalization vector.

        Returns
        -------
        global_normalization_vector : ArrayLike
            Global normalization vector.
        """
        value = getattr(self, "_global_normalization_vector", None)
        if value is None:
            calib_attrs = self._load_calibrations_attributes()

            try:
                value = np.asarray(
                    calib_attrs["global_normalization_vector"], dtype=np.float32
                )
                return value
            except KeyError:
                print("Global normalization vector not calculated.")
                return None
        else:
            return value

    @global_normalization_vector.setter
    def global_normalization_vector(self, value: ArrayLike) -> None:
        """Set the global normalization vector.

        Parameters
        ----------
        value : ArrayLike
            New global normalization vector.
        """
        self._global_normalization_vector = np.asarray(value, dtype=np.float32)
        self._set_calibration_attribute(
            "global_normalization_vector",
            self._global_normalization_vector,
        )

    @property
    def global_background_vector(self) -> ArrayLike | None:
        """Global background vector.

        Returns
        -------
        global_background_vector : ArrayLike
            Global background vector.
        """
        value = getattr(self, "_global_background_vector", None)
        if value is None:
            calib_attrs = self._load_calibrations_attributes()
            try:
                value = np.asarray(
                    calib_attrs["global_background_vector"], dtype=np.float32
                )
                return value
            except KeyError:
                print("Global background vector not calculated.")
                return None
        else:
            return value

    @global_background_vector.setter
    def global_background_vector(self, value: ArrayLike) -> None:
        """Set the global background vector.

        Parameters
        ----------
        value : ArrayLike
            New global background vector.
        """
        self._global_background_vector = np.asarray(value, dtype=np.float32)
        self._set_calibration_attribute(
            "global_background_vector",
            self._global_background_vector,
        )

    @property
    def iterative_normalization_vector(self) -> ArrayLike | None:
        """Iterative normalization vector.

        Returns
        -------
        iterative_normalization_vector : ArrayLike
            Iterative normalization vector.
        """
        value = getattr(self, "_iterative_normalization_vector", None)
        if value is None:
            calib_attrs = self._load_calibrations_attributes()
            try:
                value = np.asarray(
                    calib_attrs["iterative_normalization_vector"], dtype=np.float32
                )
            except KeyError:
                value = None

            if value is None:
                print("Iterative normalization vector not calculated.")
                return None

            return value
        else:
            return value

    @iterative_normalization_vector.setter
    def iterative_normalization_vector(self, value: ArrayLike) -> None:
        """Set the iterative normalization vector.

        Parameters
        ----------
        value : ArrayLike
            New iterative normalization vector.
        """
        self._iterative_normalization_vector = value
        self._set_calibration_attribute(
            "iterative_normalization_vector",
            self._iterative_normalization_vector,
        )

    @property
    def iterative_background_vector(self) -> ArrayLike | None:
        """Iterative background vector.

        Returns
        -------
        iterative_background_vector : ArrayLike
            Iterative background vector.
        """
        value = getattr(self, "_iterative_background_vector", None)
        if value is None:
            calib_attrs = self._load_calibrations_attributes()
            try:
                value = np.asarray(
                    calib_attrs["iterative_background_vector"], dtype=np.float32
                )
            except KeyError:
                value = None
            if value is None:
                print("Iterative background vector not calculated.")
                return None

            return value
        else:
            return value

    @iterative_background_vector.setter
    def iterative_background_vector(self, value: ArrayLike) -> None:
        """Set the iterative background vector.

        Parameters
        ----------
        value : ArrayLike
            New iterative background vector.
        """
        self._iterative_background_vector = value
        self._set_calibration_attribute(
            "iterative_background_vector",
            self._iterative_background_vector,
        )

    @staticmethod
    def _validate_decode_run_key(decode_run_key: str | None) -> str | None:
        """
        Validate an optional decoded-output run key.

        Parameters
        ----------
        decode_run_key : str or None
            Optional subfolder name under decoded-output roots.

        Returns
        -------
        str or None
            Validated run key.
        """
        if decode_run_key is None:
            return None
        decode_run_key = str(decode_run_key)
        if not re.fullmatch(r"[A-Za-z0-9_.-]+", decode_run_key):
            raise ValueError(
                "decode_run_key may only contain letters, numbers, '.', '_', and '-'."
            )
        return decode_run_key

    def _decoded_run_root(self, decode_run_key: str | None = None) -> Path:
        """
        Return the local decoded output root for an optional decode run.

        Parameters
        ----------
        decode_run_key : str or None, default None
            Optional decoded-output run key.

        Returns
        -------
        pathlib.Path
            Decoded output root.
        """
        decode_run_key = self._validate_decode_run_key(decode_run_key)
        if decode_run_key is None:
            return self._decoded_root_path
        return self._decoded_root_path / Path(decode_run_key)

    def decoded_temporary_dir(
        self,
        decode_run_key: str | None = None,
        iteration: int | None = None,
    ) -> Path:
        """
        Return the temporary decoded-output directory for a decode run.

        Parameters
        ----------
        decode_run_key : str or None, default None
            Optional decoded-output run key.
        iteration : int or None, default None
            Optional optimization iteration index.

        Returns
        -------
        pathlib.Path
            Temporary decoded-output directory.
        """
        root = self._decoded_run_root(decode_run_key) / Path("temporary")
        if iteration is not None:
            root = root / Path(f"iteration_{int(iteration):03d}")
        return root

    def _global_filtered_decoded_root(
        self,
        decode_run_key: str | None = None,
    ) -> Path:
        """
        Return the global filtered decoded-output root for an optional decode run.

        Parameters
        ----------
        decode_run_key : str or None, default None
            Optional decoded-output run key.

        Returns
        -------
        pathlib.Path
            Global filtered decoded-output root.
        """
        root = self._datastore_path / Path("all_tiles_filtered_decoded_features")
        decode_run_key = self._validate_decode_run_key(decode_run_key)
        if decode_run_key is None:
            return root
        return root / Path(decode_run_key)

    def load_decode_normalization_vectors(
        self,
        decode_run_key: str | None,
        kind: str,
    ) -> tuple[np.ndarray | None, np.ndarray | None]:
        """
        Load run-scoped normalization and background vectors.

        Parameters
        ----------
        decode_run_key : str or None
            Optional decoded-output run key. None reads the default vectors.
        kind : {'global', 'iterative'}
            Normalization vector kind.

        Returns
        -------
        tuple[numpy.ndarray or None, numpy.ndarray or None]
            Normalization and background vectors.
        """
        if kind == "global":
            if decode_run_key is None:
                return self.global_normalization_vector, self.global_background_vector
            norm_key = "global_normalization_vector"
            background_key = "global_background_vector"
        elif kind == "iterative":
            if decode_run_key is None:
                return (
                    self.iterative_normalization_vector,
                    self.iterative_background_vector,
                )
            norm_key = "iterative_normalization_vector"
            background_key = "iterative_background_vector"
        else:
            raise ValueError("kind must be one of 'global' or 'iterative'.")

        decode_run_key = self._validate_decode_run_key(decode_run_key)
        calib_attrs = self._load_calibrations_attributes()
        run_attrs = calib_attrs.get("decode_normalization_runs", {}).get(
            decode_run_key, {}
        )
        normalization_vector = run_attrs.get(norm_key)
        background_vector = run_attrs.get(background_key)
        if normalization_vector is None or background_vector is None:
            return None, None
        return (
            np.asarray(normalization_vector, dtype=np.float32),
            np.asarray(background_vector, dtype=np.float32),
        )

    def save_decode_normalization_vectors(
        self,
        decode_run_key: str | None,
        kind: str,
        normalization_vector: ArrayLike,
        background_vector: ArrayLike,
        decode_mode: str | None = None,
        metadata: Mapping[str, Any] | None = None,
    ) -> None:
        """
        Save default or run-scoped normalization and background vectors.

        Parameters
        ----------
        decode_run_key : str or None
            Optional decoded-output run key. None writes the default vectors.
        kind : {'global', 'iterative'}
            Normalization vector kind.
        normalization_vector : ArrayLike
            Foreground normalization vector.
        background_vector : ArrayLike
            Background vector.
        decode_mode : str or None, default None
            Decode mode metadata.
        metadata : Mapping[str, Any] or None, default None
            Additional provenance for these normalization vectors.
        """
        if kind == "global":
            if decode_run_key is None:
                self.global_normalization_vector = normalization_vector
                self.global_background_vector = background_vector
                self._save_default_decode_normalization_metadata(kind, metadata)
                return
            norm_key = "global_normalization_vector"
            background_key = "global_background_vector"
        elif kind == "iterative":
            if decode_run_key is None:
                self.iterative_normalization_vector = normalization_vector
                self.iterative_background_vector = background_vector
                self._save_default_decode_normalization_metadata(kind, metadata)
                return
            norm_key = "iterative_normalization_vector"
            background_key = "iterative_background_vector"
        else:
            raise ValueError("kind must be one of 'global' or 'iterative'.")

        decode_run_key = self._validate_decode_run_key(decode_run_key)
        calib_attrs = self._load_calibrations_attributes()
        runs = dict(calib_attrs.get("decode_normalization_runs", {}))
        run_attrs = dict(runs.get(decode_run_key, {}))
        if decode_mode is not None:
            run_attrs["decode_mode"] = str(decode_mode)
        if metadata is not None:
            run_attrs[f"{kind}_metadata"] = dict(metadata)
        run_attrs[norm_key] = np.asarray(normalization_vector, dtype=np.float32)
        run_attrs[background_key] = np.asarray(background_vector, dtype=np.float32)
        runs[decode_run_key] = run_attrs
        calib_attrs["decode_normalization_runs"] = runs
        self._save_calibrations_attributes(calib_attrs)

    def _save_default_decode_normalization_metadata(
        self,
        kind: str,
        metadata: Mapping[str, Any] | None,
    ) -> None:
        """Save provenance for default, non-run-scoped normalization vectors."""
        if metadata is None:
            return
        calib_attrs = self._load_calibrations_attributes()
        all_metadata = dict(calib_attrs.get("decode_normalization_metadata", {}))
        all_metadata[kind] = dict(metadata)
        calib_attrs["decode_normalization_metadata"] = all_metadata
        self._save_calibrations_attributes(calib_attrs)

    def load_decode_normalization_metadata(
        self,
        decode_run_key: str | None,
        kind: str,
    ) -> dict[str, Any] | None:
        """Load provenance for default or run-scoped normalization vectors."""
        if kind not in {"global", "iterative"}:
            raise ValueError("kind must be one of 'global' or 'iterative'.")
        calib_attrs = self._load_calibrations_attributes()
        if decode_run_key is None:
            metadata = calib_attrs.get("decode_normalization_metadata", {}).get(kind)
        else:
            decode_run_key = self._validate_decode_run_key(decode_run_key)
            metadata = (
                calib_attrs.get("decode_normalization_runs", {})
                .get(decode_run_key, {})
                .get(f"{kind}_metadata")
            )
        return dict(metadata) if isinstance(metadata, Mapping) else None

    @property
    def tile_ids(self) -> Collection[str] | None:
        """Tile IDs.

        Returns
        -------
        tile_ids : Collection[str]
            Tile IDs.
        """
        return getattr(self, "_tile_ids", None)

    @property
    def round_ids(self) -> Collection[str] | None:
        """Round IDs.

        Returns
        -------
        round_ids : Collection[str]
            Round IDs.
        """
        return getattr(self, "_round_ids", None)

    @property
    def bit_ids(self) -> Collection[str] | None:
        """Bit IDs.

        Returns
        -------
        bit_ids : Collection[str]
            Bit IDs.
        """
        return getattr(self, "_bit_ids", None)

    def _init_datastore(self) -> None:
        """Initialize datastore.

        Create directory structure and initialize datastore state.
        """
        self._datastore_path.mkdir(parents=True)
        self._calibrations_zarr_path = self._datastore_path / Path(r"calibrations")
        self._calibrations_zarr_path.mkdir()
        self._save_to_json({}, self._calibrations_attributes_path())
        self.fiducial_folder_name = r"fiducial"
        self._fiducial_root_path = self._datastore_path / Path(
            self.fiducial_folder_name
        )
        self._fiducial_root_path.mkdir()
        self._readouts_root_path = self._datastore_path / Path(r"readouts")
        self._readouts_root_path.mkdir()
        self.feature_predictor_folder_name = r"feature_predictor"
        self._feature_predictor_localizations_root_path = self._datastore_path / Path(
            f"{self.feature_predictor_folder_name}_localizations"
        )
        self._feature_predictor_localizations_root_path.mkdir()
        self._decoded_root_path = self._datastore_path / Path(r"decoded")
        self._decoded_root_path.mkdir()
        self._fused_root_path = self._datastore_path / Path(r"fused")
        self._fused_root_path.mkdir()
        self._segmentation_root_path = self._datastore_path / Path(r"segmentation")
        self._segmentation_root_path.mkdir()

        # initialize datastore state
        self._datastore_state_json_path = self._datastore_path / Path(
            r"datastore_state.json"
        )
        self._datastore_state = {
            "Version": 0.6,
            "Initialized": True,
            "Calibrations": False,
            "Corrected": False,
            "LocalRegistered": False,
            "GlobalRegistered": False,
            "Fused": False,
            "SegmentedCells": False,
            "DecodedSpots": False,
            "FilteredSpots": False,
        }

        self._save_to_json(self._datastore_state, self._datastore_state_json_path)

    @staticmethod
    def _create_array_tensorstore_qi2lab(
        path: Path,
        shape: tuple[int, ...],
        dtype: Any,
        chunks: tuple[int, ...],
        *,
        shards: tuple[int, ...] | None,
        dimension_names: list[str] | None,
        overwrite: bool,
        compression: str,
    ) -> Any:
        """
        Create a Zarr v3 array for the yaozarrs image writer.

        yaozarrs accepts a custom array creator but does not expose compression
        level or shuffle settings. This TensorStore adapter preserves the
        datastore's Blosc level 5 and bitshuffle settings; yaozarrs handles
        the OME group, axes, and image metadata.

        Parameters
        ----------
        path : Path
            Destination zarr array path.
        shape : tuple[int, ...]
            Array shape.
        dtype : Any
            Array dtype.
        chunks : tuple[int, ...]
            Chunk shape.
        shards : tuple[int, ...] | None
            Optional shard shape.
        dimension_names : list[str] | None
            Optional dimension names for metadata.
        overwrite : bool
            Whether to replace an existing array.
        compression : str
            Compression preset name.

        Returns
        -------
        Any
            Open tensorstore array handle.
        """
        import tensorstore as ts

        if compression == "blosc-zstd":
            chunk_codecs = [
                {
                    "name": "blosc",
                    "configuration": {
                        "cname": "zstd",
                        "clevel": 5,
                        "shuffle": "bitshuffle",
                    },
                }
            ]
        elif compression == "blosc-lz4":
            chunk_codecs = [
                {
                    "name": "blosc",
                    "configuration": {
                        "cname": "lz4",
                        "clevel": 5,
                        "shuffle": "bitshuffle",
                    },
                }
            ]
        elif compression == "zstd":
            chunk_codecs = [{"name": "zstd", "configuration": {"level": 3}}]
        elif compression == "none":
            chunk_codecs = []
        else:
            raise ValueError(f"Unknown compression: {compression}")

        codecs = chunk_codecs
        chunk_layout: dict[str, Any] = {"chunk": {"shape": list(chunks)}}
        if shards is not None:
            codecs = [
                {
                    "name": "sharding_indexed",
                    "configuration": {
                        "chunk_shape": list(chunks),
                        "codecs": chunk_codecs,
                    },
                }
            ]
            chunk_layout = {"write_chunk": {"shape": list(shards)}}

        domain: dict[str, Any] = {"shape": list(shape)}
        if dimension_names:
            domain["labels"] = dimension_names

        try:
            dtype_str = dtype.name
        except AttributeError:
            dtype_str = str(dtype)

        return ts.open(
            {
                "driver": "zarr3",
                "kvstore": {"driver": "file", "path": str(path)},
                "schema": {
                    "dtype": dtype_str,
                    "domain": domain,
                    "chunk_layout": chunk_layout,
                    "codec": {"driver": "zarr3", "codecs": codecs},
                },
                "create": True,
                "delete_existing": overwrite,
            }
        ).result()

    @staticmethod
    def _normalize_transform(
        values: Sequence[float] | None, ndim: int, fill: float
    ) -> list[float]:
        """
        Normalize transform vectors to match array dimensionality.

        Parameters
        ----------
        values : Sequence[float] | None
            Optional transform vector.
        ndim : int
            Target array dimensionality.
        fill : float
            Fill value for missing leading dimensions.

        Returns
        -------
        list[float]
            Transform vector with one value per array dimension.
        """
        if values is None:
            return [fill] * ndim
        cast = [float(v) for v in values]
        if len(cast) == ndim:
            return cast
        if len(cast) == 3:
            if ndim == 2:
                return cast[1:]
            if ndim >= 3:
                return [fill] * (ndim - 3) + cast
        raise ValueError(f"Cannot map {len(cast)} transform values onto {ndim} axes.")

    @staticmethod
    def _default_chunks(
        array: np.ndarray,
        spatial_chunk_zyx: tuple[int, int, int] = (16, 512, 512),
    ) -> list[int]:
        """
        Create sane default chunk sizes based on dimensionality.

        Parameters
        ----------
        array : np.ndarray
            Array that will be written.
        spatial_chunk_zyx : tuple[int, int, int], default=(16, 512, 512)
            Desired Z, Y, X storage chunks for local fiducial and readout images.

        Returns
        -------
        list[int]
            Chunk shape matched to the array dimensionality.
        """
        z_chunk, y_chunk, x_chunk = (int(value) for value in spatial_chunk_zyx)
        if array.ndim == 2:
            return [
                min(int(array.shape[0]), y_chunk),
                min(int(array.shape[1]), x_chunk),
            ]
        if array.ndim == 3:
            return [
                min(int(array.shape[0]), z_chunk),
                min(int(array.shape[1]), y_chunk),
                min(int(array.shape[2]), x_chunk),
            ]
        if array.ndim == 4:
            return [
                1,
                min(int(array.shape[1]), z_chunk),
                min(int(array.shape[2]), y_chunk),
                min(int(array.shape[3]), x_chunk),
            ]
        if array.ndim == 5:
            return [
                1,
                1,
                min(int(array.shape[2]), z_chunk),
                min(int(array.shape[3]), y_chunk),
                min(int(array.shape[4]), x_chunk),
            ]
        return list(array.shape)

    @staticmethod
    def _fused_image_chunks(array: np.ndarray) -> list[int]:
        """
        Create chunk sizes tailored for fused image storage.

        Parameters
        ----------
        array : np.ndarray
            Fused image array that will be written.

        Returns
        -------
        list[int]
            Chunk shape for fused image storage.
        """
        shape = [int(dim) for dim in array.shape]
        if array.ndim == 2:
            return [min(shape[0], 2048), min(shape[1], 2048)]
        if array.ndim == 3:
            return [min(shape[0], 16), min(shape[1], 512), min(shape[2], 512)]
        if array.ndim == 4:
            return [
                min(shape[0], 1),
                min(shape[1], 16),
                min(shape[2], 512),
                min(shape[3], 512),
            ]
        if array.ndim == 5:
            return [
                min(shape[0], 1),
                min(shape[1], 1),
                min(shape[2], 16),
                min(shape[3], 512),
                min(shape[4], 512),
            ]
        return list(array.shape)

    @staticmethod
    def _build_axes(v05: Any, ndim: int) -> list[Any]:
        """
        Build NGFF axes models for a given dimensionality.

        Parameters
        ----------
        v05 : Any
            yaozarrs NGFF model namespace.
        ndim : int
            Number of array dimensions.

        Returns
        -------
        list[Any]
            NGFF axis models ordered to match array dimensions.
        """
        axis_names = ["t", "c", "z", "y", "x"][-ndim:]
        axes: list[Any] = []
        for axis_name in axis_names:
            if axis_name in {"z", "y", "x"}:
                axes.append(v05.SpaceAxis(name=axis_name, unit="micrometer"))
            elif axis_name == "c":
                axes.append(v05.ChannelAxis(name="c"))
            else:
                axes.append(v05.TimeAxis(name="t", unit="second"))
        return axes

    @staticmethod
    def _entity_attributes_path(entity_root_path: Path | str) -> Path:
        """
        Path to per-entity metadata sidecar.

        Parameters
        ----------
        entity_root_path : Path | str
            Entity folder path.

        Returns
        -------
        Path
            Entity metadata sidecar path.
        """
        return Path(entity_root_path) / Path("attributes.json")

    @staticmethod
    def _image_store_path(image_path: Path | str) -> Path:
        """
        Normalize image path to the *.ome.zarr folder naming scheme.

        Parameters
        ----------
        image_path : Path | str
            Logical image path or OME-Zarr path.

        Returns
        -------
        Path
            Normalized path ending in ``.ome.zarr``.
        """
        path = Path(image_path)
        if path.name.endswith(".ome.zarr"):
            return path
        if path.name.endswith(".zarr"):
            raise ValueError(
                f"Invalid image store name '{path.name}'. Expected '.ome.zarr' suffix."
            )
        if path.suffixes:
            raise ValueError(
                f"Invalid image store name '{path.name}'. Use bare logical names or '.ome.zarr'."
            )
        return path.with_name(path.name + ".ome.zarr")

    @staticmethod
    def load_image_metadata(image_path: Path | str) -> dict[str, Any]:
        """
        Load extra attributes through yaozarrs.

        Parameters
        ----------
        image_path : Path | str
            Image store path.

        Returns
        -------
        dict[str, Any]
            Extra attributes stored on the image root.
        """
        image_root = qi2labDataStore._image_store_path(image_path)
        attrs = dict(open_group(str(image_root)).attrs)
        attrs.pop("ome", None)
        for key in ("spacing_zyx_um", "voxel_size_zyx_um"):
            if key in attrs:
                attrs[key] = round_spacing_um(attrs[key]).tolist()
        return attrs

    @staticmethod
    def save_image_metadata(
        image_path: Path | str,
        extra_attributes: Mapping[str, Any],
        merge: bool = True,
    ) -> None:
        """
        Write image-level extra attributes for externally-created OME-Zarr stores.

        Parameters
        ----------
        image_path : Path | str
            Image group path. Both the directory path and the corresponding
            OME-Zarr store path are accepted.
        extra_attributes : Mapping[str, Any]
            Attribute updates to write at the image root.
        merge : bool, default=True
            If True, merge updates into existing attributes. If False, replace
            the existing image-level attributes with ``extra_attributes``.

        Returns
        -------
        None
            Attributes are written to the Zarr v3 ``zarr.json``. The OME
            metadata is preserved when replacing extra attributes.
        """
        image_root = qi2labDataStore._image_store_path(image_path)
        payload = {
            str(k): qi2labDataStore._to_json_compatible(v)
            for k, v in dict(extra_attributes).items()
        }

        for key in ("spacing_zyx_um", "voxel_size_zyx_um"):
            if key in payload:
                payload[key] = round_spacing_um(payload[key]).tolist()

        group = open_group(image_root)
        metadata = group.metadata.model_dump(mode="json", exclude_none=True)
        if metadata["zarr_format"] != 3:
            raise ValueError("Datastore images must use OME-Zarr on Zarr v3.")
        existing = dict(group.attrs)
        attributes = existing if merge else {"ome": existing["ome"]}
        attributes.update(payload)
        round_ome_spatial_scales(attributes)
        metadata["attributes"] = attributes
        # yaozarrs exposes attributes read-only. Updating metadata for an
        # externally fused image requires replacing the local Zarr v3 JSON.
        qi2labDataStore._save_to_json(metadata, image_root / "zarr.json")

    @staticmethod
    def _to_json_compatible(value: Any) -> Any:
        """
        Convert numpy/scalar containers to JSON-compatible values.

        Parameters
        ----------
        value : Any
            Value to convert before JSON serialization.

        Returns
        -------
        Any
            JSON-compatible representation.
        """
        if isinstance(value, np.ndarray):
            return value.tolist()
        if isinstance(value, np.generic):
            return value.item()
        if isinstance(value, Mapping):
            return {
                str(k): qi2labDataStore._to_json_compatible(v) for k, v in value.items()
            }
        if isinstance(value, tuple):
            return [qi2labDataStore._to_json_compatible(v) for v in value]
        if isinstance(value, list):
            return [qi2labDataStore._to_json_compatible(v) for v in value]
        return value

    @staticmethod
    def image_shape(image_path: Path | str) -> tuple[int, ...] | None:
        """
        Read image shape without loading all pixels.

        Parameters
        ----------
        image_path : Path | str
            Image store path.

        Returns
        -------
        tuple[int, ...] | None
            Image array shape, or ``None`` when the image is unavailable.
        """
        path = qi2labDataStore._image_store_path(image_path)
        if not path.exists():
            return None

        try:
            group = open_group(str(path))
            array_0 = group["0"]
            shape = array_0.metadata.shape
            return tuple(int(dim) for dim in shape)
        except (FileNotFoundError, KeyError):
            return None

    def _load_entity_attributes(
        self,
        entity_root_path: Path | str,
        image_names: Sequence[str] | None = None,
    ) -> dict[str, Any]:
        """
        Load entity metadata from sidecar + image extra_attributes.

        Parameters
        ----------
        entity_root_path : Path | str
            Entity folder path.
        image_names : Sequence[str] | None
            Optional image names whose extra attributes should be merged.

        Returns
        -------
        dict[str, Any]
            Merged entity metadata.
        """
        entity_root = Path(entity_root_path)
        merged: dict[str, Any] = {}

        default_images = (
            "corrected_data",
            "decon_data",
            f"{self.feature_predictor_folder_name}_data",
            "opticalflow_xform_px",
        )
        candidate_names = image_names if image_names is not None else default_images
        for image_name in candidate_names:
            image_path = self._image_store_path(entity_root / Path(image_name))
            if not image_path.exists():
                continue
            merged.update(self.load_image_metadata(image_path))

        merged.update(self._load_from_json(self._entity_attributes_path(entity_root)))

        return merged

    def _save_entity_attributes(
        self,
        entity_root_path: Path | str,
        updates: Mapping[str, Any],
    ) -> None:
        """
        Save metadata to the entity sidecar.

        Parameters
        ----------
        entity_root_path : Path | str
            Entity folder path.
        updates : Mapping[str, Any]
            Metadata updates to persist.

        Returns
        -------
        None
            No return value.
        """
        if not updates:
            return

        entity_root = Path(entity_root_path)
        payload = {
            str(k): self._to_json_compatible(v) for k, v in dict(updates).items()
        }

        sidecar_path = self._entity_attributes_path(entity_root)
        sidecar_attrs = self._load_from_json(sidecar_path)
        sidecar_attrs.update(payload)
        self._save_to_json(sidecar_attrs, sidecar_path)

    def _update_image_translation_transform(
        self,
        image_root: Path,
        stage_zyx_um: Sequence[float],
    ) -> None:
        """
        Update an existing OME-Zarr image translation transform.

        Parameters
        ----------
        image_root : Path
            Image root path, without or with the ``.ome.zarr`` suffix.
        stage_zyx_um : Sequence[float]
            Physical Z, Y, X translation to write into the image metadata.

        Returns
        -------
        None
            The image metadata is updated in place when it already exists.
        """
        image_path = self._image_store_path(image_root)
        metadata_path = image_path / Path("zarr.json")
        if not metadata_path.exists():
            return

        metadata = open_group(image_path).metadata.model_dump(
            mode="json", exclude_none=True
        )

        transforms = (
            metadata.get("attributes", {})
            .get("ome", {})
            .get("multiscales", [{}])[0]
            .get("datasets", [{}])[0]
            .get("coordinateTransformations", [])
        )
        for transform in transforms:
            if transform.get("type") == "translation":
                transform["translation"] = [float(v) for v in stage_zyx_um]
                self._save_to_json(metadata, metadata_path)
                return

    @staticmethod
    def _normalize_stage_position_zyx_um(stage_zyx_um: ArrayLike) -> np.ndarray:
        """Return ZYX stage coordinates, padding legacy YX positions with Z=0."""
        stage = np.asarray(stage_zyx_um, dtype=np.float32)
        if stage.shape == (2,):
            return np.asarray((0.0, stage[0], stage[1]), dtype=np.float32)
        if stage.shape != (3,):
            raise ValueError(
                "Stage position must contain two (Y, X) or three (Z, Y, X) "
                f"coordinates; got shape {stage.shape}."
            )
        return stage

    def _resolve_original_tile_position_zyx_um(
        self,
        tile_id: str,
        round_id: str | None = None,
        bit_id: str | None = None,
    ) -> list[float] | None:
        """
        Resolve original tile stage position used for OME translation.

        Parameters
        ----------
        tile_id : str
            Tile identifier.
        round_id : str | None
            Optional fiducial round identifier.
        bit_id : str | None
            Optional readout bit identifier.

        Returns
        -------
        list[float] | None
            Original stage position in Z, Y, X microns, if available.
        """
        if round_id is not None:
            fiducial_entity = self._fiducial_root_path / Path(tile_id) / Path(round_id)
            attrs = self._load_entity_attributes(fiducial_entity)
            stage = attrs.get("stage_zyx_um")
            if stage is not None:
                return self._normalize_stage_position_zyx_um(stage).tolist()

        if bit_id is not None:
            round_linker = self.load_local_round_linker(tile=tile_id, bit=bit_id)
            if round_linker is not None and int(round_linker) > 0:
                linked_round_id = self._round_ids[int(round_linker) - 1]
                fiducial_entity = (
                    self._fiducial_root_path / Path(tile_id) / Path(linked_round_id)
                )
                attrs = self._load_entity_attributes(fiducial_entity)
                stage = attrs.get("stage_zyx_um")
                if stage is not None:
                    return self._normalize_stage_position_zyx_um(stage).tolist()

        if getattr(self, "_round_ids", None):
            fiducial_entity = (
                self._fiducial_root_path / Path(tile_id) / Path(self._round_ids[0])
            )
            attrs = self._load_entity_attributes(fiducial_entity)
            stage = attrs.get("stage_zyx_um")
            if stage is not None:
                return self._normalize_stage_position_zyx_um(stage).tolist()
        return None

    def _resolve_reference_tile_position_zyx_um(
        self, tile_id: str
    ) -> list[float] | None:
        """
        Resolve the first-round reference stage position for derived outputs.

        Parameters
        ----------
        tile_id : str
            Tile identifier.

        Returns
        -------
        list[float] or None
            First fiducial round stage position in Z, Y, X microns.
        """
        if not getattr(self, "_round_ids", None):
            return None
        return self._resolve_original_tile_position_zyx_um(
            tile_id=tile_id, round_id=self._round_ids[0]
        )

    def _validate_core_image_shape(
        self,
        entity_root_path: Path | str,
        image_name: str,
        image: ArrayLike,
    ) -> None:
        """
        Enforce corrected/deconvolved/feature image shape consistency.

        Parameters
        ----------
        entity_root_path : Path | str
            Entity folder path.
        image_name : str
            Logical image name being validated.
        image : ArrayLike
            Image data to validate.

        Returns
        -------
        None
            No return value.
        """
        entity_root = Path(entity_root_path)
        shape = tuple(int(v) for v in np.asarray(image).shape)
        required_names = {
            "corrected_data",
            "decon_data",
            f"{self.feature_predictor_folder_name}_data",
        }
        for candidate_name in required_names:
            if candidate_name == image_name:
                continue
            candidate_shape = self.image_shape(entity_root / Path(candidate_name))
            if candidate_shape is None:
                continue
            if tuple(candidate_shape) != shape:
                raise ValueError(
                    f"Image shape mismatch in {entity_root.name}: "
                    f"{image_name}={shape} but {candidate_name}={candidate_shape}. "
                    "corrected_data, optional decon_data, and "
                    "feature_predictor_data must match."
                )

    @staticmethod
    def _load_from_json(dictionary_path: Path | str) -> dict:
        """Load json as dictionary.

        Parameters
        ----------
        dictionary_path : Path or str
            Path to json file.

        Returns
        -------
        dictionary : dict
            Dictionary from json file.
        """
        try:
            with open(dictionary_path) as f:
                dictionary = json.load(f)
        except FileNotFoundError:
            return {}
        if not isinstance(dictionary, dict):
            raise ValueError(f"Expected a JSON object in {dictionary_path}")
        return dictionary

    @staticmethod
    def _save_to_json(dictionary: dict, dictionary_path: Path | str) -> None:
        """Save dictionary to json.

        Parameters
        ----------
        dictionary : dict
            The data to be saved.
        dictionary_path : Path or str
            The path to the JSON file where the data will be saved.
        """
        serialized = json.dumps(dictionary, indent=4)
        with open(dictionary_path, "w", encoding="utf-8") as file:
            file.write(serialized)

    @staticmethod
    def _load_from_microjson(dictionary_path: Path | str) -> dict:
        """Load cell outlines outlines microjson as dictionary.

        Parameters
        ----------
        dictionary_path : Path or str
            Path to microjson file.

        Returns
        -------
        outlines : dict
            Cell outlines dictionary.
        """
        try:
            with open(dictionary_path) as f:
                data = json.load(f)
                outlines = {}
                for feature in data["features"]:
                    cell_id = feature["properties"]["cell_id"]
                    coordinates = feature["geometry"]["coordinates"][0]
                    outlines[cell_id] = np.array(coordinates)
        except (
            FileNotFoundError,
            json.JSONDecodeError,
            KeyError,
            TypeError,
            ValueError,
        ):
            outlines = {}
        return outlines

    @staticmethod
    def _check_for_zarr_array(image_path: Path | str) -> None:
        """Check if image exists and is readable via yaozarrs.

        Parameters
        ----------
        image_path : Path or str
            Image store path.
        """
        image_path = qi2labDataStore._image_store_path(image_path)
        if not image_path.exists():
            raise FileNotFoundError(image_path)

        group = open_group(str(image_path))
        _ = group["0"]

    @staticmethod
    def _load_from_zarr_array(
        image_path: Path | str, return_future: bool | None = True
    ) -> "np.ndarray | Future | TensorStore":
        """Read image data via yaozarrs.

        Parameters
        ----------
        image_path : Path or str
            Image store path.
        return_future : bool or None
            Return read future (True), immediately read (False), or return the
            TensorStore array without issuing a read (None).

        Returns
        -------
        array : tensorstore.Future or numpy.ndarray or tensorstore.TensorStore
            Read future, immediate array, or lazy TensorStore handle obtained
            through yaozarrs.
        """
        image_path = qi2labDataStore._image_store_path(image_path)
        group = open_group(str(image_path))
        current_array = group["0"].to_tensorstore()

        if return_future is None:
            return current_array
        read_future = current_array.read()
        return read_future if return_future else read_future.result()

    @staticmethod
    def _save_to_zarr_array(
        array: ArrayLike,
        image_path: Path | str,
        return_future: bool | None = False,
        *,
        chunks: Sequence[int] | None = None,
        ome_scale: Sequence[float] | None = None,
        ome_translation: Sequence[float] | None = None,
        extra_attributes: Mapping[str, Any] | None = None,
    ) -> "WriteFutures | None":
        """Save image data as OME-Zarr v0.5 using yaozarrs tensorstore writer.

        Parameters
        ----------
        array : ArrayLike
            Array to save.
        image_path : Path or str
            Image store path.
        chunks : Sequence[int] or None
            Storage chunk shape. None selects the datastore default.
        ome_scale : Sequence[float] or None
            Pixel spacing in microns, in image-axis order or ZYX order.
        ome_translation : Sequence[float] or None
            Image origin in microns, in image-axis order or ZYX order.
        extra_attributes : Mapping or None
            Additional image metadata.
        return_future : bool or None
            Return the write-completion handle (True), or wait for the write
            to finish and return None (False or None).

        Returns
        -------
        write_future : tensorstore.WriteFutures or None
            Pixel-write completion handle when return_future is True.

        Raises
        ------
        OSError, ValueError
            Storage or metadata errors. Failed writes are not reported as success.
        """
        image_path = qi2labDataStore._image_store_path(image_path)
        image_path.parent.mkdir(parents=True, exist_ok=True)

        image_array = np.asarray(array)
        if image_array.dtype == np.float64:
            image_array = image_array.astype(np.float32)

        if image_array.ndim < 2 or image_array.ndim > 5:
            raise ValueError(
                f"Unsupported array ndim for image write: {image_array.ndim}"
            )

        if chunks is None:
            chunks = qi2labDataStore._default_chunks(image_array)
        scale = qi2labDataStore._normalize_transform(ome_scale, image_array.ndim, 1.0)
        translation = qi2labDataStore._normalize_transform(
            ome_translation, image_array.ndim, 0.0
        )

        axes = qi2labDataStore._build_axes(v05, image_array.ndim)
        scale[-3:] = round_spacing_um(scale[-3:]).tolist()
        transforms = [
            v05.ScaleTransformation(scale=scale),
            v05.TranslationTransformation(translation=translation),
        ]
        datasets = [v05.Dataset(path="0", coordinateTransformations=transforms)]
        multiscales = [v05.Multiscale(axes=axes, datasets=datasets)]

        image_metadata = v05.Image(multiscales=multiscales)

        chunk_spec = tuple(int(c) for c in chunks)
        write_options = {
            "extra_attributes": qi2labDataStore._to_json_compatible(extra_attributes)
            if extra_attributes
            else None,
            "writer": qi2labDataStore._create_array_tensorstore_qi2lab,
            "overwrite": True,
            "chunks": chunk_spec,
            "compression": "blosc-zstd",
        }
        if return_future:
            from yaozarrs.write.v05 import prepare_image

            # yaozarrs creates the complete OME-Zarr v3 structure. Its write_image
            # API is synchronous; writing the prepared array is necessary to
            # preserve the datastore's TensorStore write-completion handle.
            _, arrays = prepare_image(
                dest=str(image_path),
                image=image_metadata,
                datasets=(image_array.shape, image_array.dtype),
                **write_options,
            )
            return arrays["0"].write(image_array)
        write_image(
            dest=str(image_path),
            image=image_metadata,
            datasets=image_array,
            **write_options,
        )
        return None

    @staticmethod
    def _load_from_parquet(parquet_path: Path | str) -> pd.DataFrame:
        """Load dataframe from parquet.

        Parameters
        ----------
        parquet_path : Path or str
            Path to parquet file.

        Returns
        -------
        df : pd.DataFrame
            Dataframe from parquet file.
        """
        return pd.read_parquet(parquet_path)

    @staticmethod
    def _save_to_parquet(df: pd.DataFrame, parquet_path: Path | str) -> None:
        """Save dataframe to parquet.

        Parameters
        ----------
        df : pd.DataFrame
            Dataframe to save.
        parquet_path : Path or str
            Path to parquet file.
        """
        df.to_parquet(parquet_path, engine="fastparquet", index=False)

    @staticmethod
    def _save_to_csv_gz(df: pd.DataFrame, csv_gz_path: Path | str) -> None:
        """Save dataframe to gzipped CSV.

        Parameters
        ----------
        df : pd.DataFrame
            Dataframe to save.
        csv_gz_path : Path or str
            Path to gzipped CSV file.
        """
        df.to_csv(csv_gz_path, index=False, compression="gzip")

    def _parse_datastore(self, validate: bool = True) -> None:
        """
        Parse datastore to discover available components.

        Parameters
        ----------
        validate : bool
            Whether to validate existing zarr arrays while parsing.

        Returns
        -------
        None
            No return value.
        """
        # directory structure as defined by qi2lab spec
        self._datastore_state_json_path = self._datastore_path / Path(
            r"datastore_state.json"
        )
        # read in .json in root directory that indicates what steps have been run
        with open(self._datastore_state_json_path) as json_file:
            self._datastore_state = json.load(json_file)
        if float(self._datastore_state["Version"]) != 0.6:
            raise ValueError("Only datastore version 0.6 is supported by this build.")

        self.fiducial_folder_name = "fiducial"
        self.feature_predictor_folder_name = "feature_predictor"
        self._fiducial_root_path = self._datastore_path / Path(
            self.fiducial_folder_name
        )
        self._feature_predictor_localizations_root_path = self._datastore_path / Path(
            f"{self.feature_predictor_folder_name}_localizations"
        )
        self._calibrations_zarr_path = self._datastore_path / Path(r"calibrations")
        self._readouts_root_path = self._datastore_path / Path(r"readouts")
        self._decoded_root_path = self._datastore_path / Path(r"decoded")
        self._fused_root_path = self._datastore_path / Path(r"fused")
        self._segmentation_root_path = self._datastore_path / Path(r"segmentation")

        # validate calibrations
        if self._datastore_state["Calibrations"]:
            if not (self._calibrations_zarr_path.exists()):
                raise FileNotFoundError("Calibration data directory is missing.")
            attributes = self._load_calibrations_attributes()

            keys_to_check = [
                "num_rounds",
                "num_tiles",
                "channels_in_data",
                "tile_overlap",
                "binning",
                "e_per_ADU",
                "na",
                "ri",
                "exp_order",
                "codebook",
                "num_bits",
                "microscope_type",
                "camera_model",
                "voxel_size_zyx_um",
            ]
            for key in keys_to_check:
                if key not in attributes.keys():
                    raise KeyError("Calibration attributes incomplete")

            self._num_rounds = attributes["num_rounds"]
            self._num_tiles = attributes["num_tiles"]
            self._channels_in_data = attributes["channels_in_data"]
            self._tile_overlap = attributes["tile_overlap"]
            self._binning = attributes["binning"]
            self._e_per_ADU = attributes["e_per_ADU"]
            self._na = attributes["na"]
            self._ri = attributes["ri"]
            self._exp_order = attributes["exp_order"]
            self._codebook = attributes["codebook"]
            self._num_bits = attributes["num_bits"]
            self._microscope_type = attributes["microscope_type"]
            self._camera_model = attributes["camera_model"]
            self._voxel_size_zyx_um = self._normalize_voxel_size_zyx_um(
                attributes["voxel_size_zyx_um"]
            )

            if getattr(self, "_exp_order", None) is not None:
                self._experiment_order = self._coerce_experiment_order_dataframe(
                    self._exp_order
                )

            if getattr(self, "_num_tiles", None) is not None:
                self._tile_ids = [
                    "tile" + str(tile_idx).zfill(4)
                    for tile_idx in range(self._num_tiles)
                ]
            if getattr(self, "_num_rounds", None) is not None:
                self._round_ids = [
                    "round" + str(round_idx + 1).zfill(3)
                    for round_idx in range(self._num_rounds)
                ]
            if getattr(self, "_num_bits", None) is not None:
                self._bit_ids = [
                    "bit" + str(bit_idx + 1).zfill(3)
                    for bit_idx in range(self._num_bits)
                ]

            if validate:
                psf_root_path = self._calibrations_zarr_path / Path("psf_data")
                try:
                    if psf_root_path.exists():

                        def psf_sort_key(path: Path) -> int:
                            """
                            Return the numeric PSF directory index.

                            Parameters
                            ----------
                            path : Path
                                PSF directory path.

                            Returns
                            -------
                            int
                                PSF directory index.
                            """
                            return int(path.name[len("psf_") : len("psf_") + 3])

                        psf_dirs = sorted(
                            [
                                entry
                                for entry in psf_root_path.iterdir()
                                if entry.is_dir()
                                and re.fullmatch(r"psf_\d{3}\.ome\.zarr", entry.name)
                            ],
                            key=psf_sort_key,
                        )
                    else:
                        psf_dirs = []

                    if len(psf_dirs) > 0:
                        psf_list = []
                        for psf_dir in psf_dirs:
                            psf_array = self._load_from_zarr_array(
                                psf_dir, return_future=False
                            )
                            psf_list.append(np.asarray(psf_array, dtype=np.float32))
                        self._psfs = psf_list
                except (OSError, ValueError):
                    print("Calibration psfs missing.")

        # validate fiducial and readout bits data
        if self._datastore_state["Corrected"] and validate:
            if not (self._fiducial_root_path.exists()):
                raise FileNotFoundError("fiducial directory not initialized")
            else:
                fiducial_tile_ids = self._collect_strict_ids(
                    self._fiducial_root_path, prefix="tile", width=4
                )
                if len(fiducial_tile_ids) == 0:
                    raise FileNotFoundError("No tile folders found under fiducial/")
                current_tile_dir_path = self._fiducial_root_path / Path(
                    fiducial_tile_ids[0]
                )
                self._round_ids = self._collect_strict_ids(
                    current_tile_dir_path, prefix="round", width=3
                )
            if not (self._readouts_root_path.exists()):
                raise FileNotFoundError("Readout directory not initialized")
            else:
                readout_tile_ids = self._collect_strict_ids(
                    self._readouts_root_path, prefix="tile", width=4
                )
                if len(readout_tile_ids) == 0:
                    raise FileNotFoundError("No tile folders found under readouts/")
                current_tile_dir_path = self._readouts_root_path / Path(
                    readout_tile_ids[0]
                )
                self._bit_ids = self._collect_strict_ids(
                    current_tile_dir_path, prefix="bit", width=3
                )
            assert fiducial_tile_ids == readout_tile_ids, (
                "fiducial and readout tile ids do not match. Conversion error."
            )
            self._tile_ids = fiducial_tile_ids.copy()
            del fiducial_tile_ids, readout_tile_ids

            for tile_id, round_id in product(self._tile_ids, self._round_ids):
                entity_root = self._fiducial_root_path / Path(tile_id) / Path(round_id)
                attributes = self._load_entity_attributes(entity_root)

                keys_to_check = [
                    "stage_zyx_um",
                    "excitation_um",
                    "emission_um",
                    # "exposure_ms",
                    "psf_idx",
                ]

                for key in keys_to_check:
                    if key not in attributes.keys():
                        print(tile_id, round_id, key)
                        raise KeyError("Corrected fiducial attributes incomplete")
                if "bit_linker" not in attributes:
                    print(tile_id, round_id, "bit_linker")
                    raise KeyError("Corrected fiducial attributes incomplete")

                current_local_zarr_path = str(entity_root / Path("corrected_data"))

                try:
                    self._check_for_zarr_array(current_local_zarr_path)
                except (OSError, ValueError):
                    print(tile_id, round_id)
                    print("Corrected fiducial data missing.")

            for tile_id, bit_id in product(self._tile_ids, self._bit_ids):
                entity_root = self._readouts_root_path / Path(tile_id) / Path(bit_id)
                attributes = self._load_entity_attributes(entity_root)

                keys_to_check = [
                    "excitation_um",
                    "emission_um",
                    # "exposure_ms",
                    "psf_idx",
                ]
                for key in keys_to_check:
                    if key not in attributes.keys():
                        raise KeyError("Corrected readout attributes incomplete")
                if "round_linker" not in attributes:
                    raise KeyError("Corrected readout attributes incomplete")

                current_local_zarr_path = str(entity_root / Path("corrected_data"))

                try:
                    self._check_for_zarr_array(current_local_zarr_path)
                except (OSError, ValueError):
                    print(tile_id, bit_id)
                    print("Corrected readout data missing.")

        # check and validate local transform and preprocessing data
        if self._datastore_state["LocalRegistered"] and validate:
            for tile_id, round_id in product(self._tile_ids, self._round_ids):
                entity_root = self._fiducial_root_path / Path(tile_id) / Path(round_id)
                if round_id != self._round_ids[0]:
                    attributes = self._load_entity_attributes(entity_root)

                    keys_to_check = ["local_round_transform_zyx_um"]

                    for key in keys_to_check:
                        if key not in attributes.keys():
                            raise KeyError(
                                f"{round_id, tile_id} local round transform missing"
                            )

                    current_local_zarr_path = str(
                        entity_root / Path("opticalflow_xform_px")
                    )

                    try:
                        self._check_for_zarr_array(current_local_zarr_path)
                    except (OSError, ValueError):
                        # print(tile_id, round_id)
                        # print("Optical flow registration data missing.")
                        pass

                corrected_shape = self.image_shape(entity_root / Path("corrected_data"))
                decon_shape = self.image_shape(entity_root / Path("decon_data"))
                if (
                    corrected_shape is not None
                    and decon_shape is not None
                    and corrected_shape != decon_shape
                ):
                    raise ValueError(
                        f"{tile_id} {round_id} corrected and decon shapes differ: "
                        f"{corrected_shape} != {decon_shape}"
                    )

            for tile_id, bit_id in product(self._tile_ids, self._bit_ids):
                entity_root = self._readouts_root_path / Path(tile_id) / Path(bit_id)
                current_local_zarr_path = str(
                    entity_root / Path(f"{self.feature_predictor_folder_name}_data")
                )

                try:
                    self._check_for_zarr_array(current_local_zarr_path)
                except (OSError, ValueError):
                    print(tile_id, bit_id)
                    print("feature_predictor prediction missing.")
                corrected_shape = self.image_shape(entity_root / Path("corrected_data"))
                decon_shape = self.image_shape(entity_root / Path("decon_data"))
                feature_shape = self.image_shape(
                    entity_root / Path(f"{self.feature_predictor_folder_name}_data")
                )
                shapes = [
                    shape
                    for shape in (corrected_shape, decon_shape, feature_shape)
                    if shape is not None
                ]
                if len(shapes) > 1 and any(shape != shapes[0] for shape in shapes[1:]):
                    raise ValueError(
                        f"{tile_id} {bit_id} corrected/decon/feature image shapes differ: "
                        f"{corrected_shape}, {decon_shape}, {feature_shape}"
                    )

            for tile_id, bit_id in product(self._tile_ids, self._bit_ids):
                current_feature_predictor_path = (
                    self._feature_predictor_localizations_root_path
                    / Path(tile_id)
                    / Path(bit_id + ".parquet")
                )
                if not (current_feature_predictor_path.exists()):
                    raise FileNotFoundError(
                        tile_id
                        + " "
                        + bit_id
                        + " feature_predictor localization missing"
                    )

        # check and validate global registered data
        if self._datastore_state["GlobalRegistered"] and validate:
            for tile_id in self._tile_ids:
                entity_root = (
                    self._fiducial_root_path / Path(tile_id) / Path(self._round_ids[0])
                )
                attributes = self._load_entity_attributes(entity_root)

                keys_to_check = ["affine_zyx_um", "origin_zyx_um", "spacing_zyx_um"]

                for key in keys_to_check:
                    if key not in attributes.keys():
                        raise KeyError("Global registration missing")

        # check and validate fused
        if self._datastore_state["Fused"] and validate:
            fused_image_path = self._fused_root_path / Path(
                f"fused_{self.fiducial_folder_name}_zyx"
            )
            attributes = self.load_image_metadata(fused_image_path)

            keys_to_check = ["affine_zyx_um", "origin_zyx_um", "spacing_zyx_um"]

            for key in keys_to_check:
                if key not in attributes.keys():
                    raise KeyError("Fused image metadata missing")

            current_local_zarr_path = str(fused_image_path)

            try:
                self._check_for_zarr_array(current_local_zarr_path)
            except (OSError, ValueError):
                print("Fused data missing.")

        # check and validate cellpose segmentation
        if self._datastore_state["SegmentedCells"] and validate:
            current_local_zarr_path = str(
                self._segmentation_root_path
                / Path("cellpose")
                / Path(f"masks_{self.fiducial_folder_name}_iso_zyx")
            )

            try:
                self._check_for_zarr_array(current_local_zarr_path)
            except (OSError, ValueError):
                print("Cellpose data missing.")

            cell_outlines_path = (
                self._segmentation_root_path
                / Path("cellpose")
                / Path("imagej_rois")
                / Path("global_coords_rois.zip")
            )
            if not (cell_outlines_path.exists()):
                raise FileNotFoundError("Cellpose cell outlines missing.")

        # check and validate decoded spots
        if self._datastore_state["DecodedSpots"] and validate:
            for tile_id in self._tile_ids:
                decoded_path = self._decoded_root_path / Path(
                    tile_id + "_decoded_features.parquet"
                )

                if not (decoded_path.exists()):
                    raise FileNotFoundError(tile_id + " decoded spots missing.")

        # check and validate filtered decoded spots
        if self._datastore_state["FilteredSpots"] and validate:
            filtered_path = self._decoded_root_path / Path(
                "all_tiles_filtered_decoded_features.parquet"
            )

            if not (filtered_path.exists()):
                raise FileNotFoundError("filtered decoded spots missing.")

    def load_codebook_parsed(
        self,
    ) -> tuple[Collection[str], ArrayLike] | None:
        """Load and split codebook into gene_ids and codebook matrix.

        Returns
        -------
        gene_ids : Collection[str]
            Gene IDs.
        codebook_matrix : ArrayLike
            Codebook matrix.
        """
        try:
            data = getattr(self, "_codebook", None)

            if data is None:
                return None
            num_columns = len(data[0]) if data else 0
            columns = ["gene_id"] + [f"bit{i:02d}" for i in range(1, num_columns)]
            codebook_df = pd.DataFrame(data, columns=columns)

            gene_ids = codebook_df.iloc[:, 0].tolist()
            codebook_matrix = codebook_df.iloc[:, 1:].to_numpy().astype(int)
            del data, codebook_df
            return gene_ids, codebook_matrix
        except (KeyError, ValueError, TypeError):
            print("Error parsing codebook.")
            return None

    def initialize_tile(
        self,
        tile: int | str,
    ) -> None:
        """Initialize directory structure for a tile.

        Parameters
        ----------
        tile : int or str
            Tile index or tile id.
        """
        if getattr(self, "_experiment_order", None) is None:
            print("Assign experimental order before creating tiles.")
            return None

        if getattr(self, "_num_tiles", None) is None:
            print("Assign number of tiles before creating tiles.")
            return None

        if isinstance(tile, int):
            if tile < 0 or tile >= self._num_tiles:
                print("Set tile index >=0 and <" + str(self._num_tiles))
                return None
            else:
                tile_id = self._tile_ids[tile]
        elif isinstance(tile, str):
            if tile not in self._tile_ids:
                print("set valid tile id.")
                return None
            else:
                tile_id = tile
        else:
            print("'tile' must be integer index or string identifier")
            return None

        try:
            fiducial_tile_path = self._fiducial_root_path / Path(tile_id)
            fiducial_tile_path.mkdir()
            for round_idx, round_id in enumerate(self._round_ids):
                fiducial_round_path = fiducial_tile_path / Path(round_id)
                fiducial_round_path.mkdir()
                fiducial_round_attrs_path = self._entity_attributes_path(
                    fiducial_round_path
                )
                round_attrs = {
                    "bit_linker": self._experiment_order.to_numpy()[round_idx, 1:]
                    .astype(int)
                    .tolist(),
                }
                self._save_to_json(round_attrs, fiducial_round_attrs_path)
        except FileExistsError:
            print("Error creating fiducial tile. Does it exist already?")

        try:
            readout_tile_path = self._readouts_root_path / Path(tile_id)
            readout_tile_path.mkdir()
            for bit_idx, bit_id in enumerate(self._bit_ids):
                readout_bit_path = readout_tile_path / Path(bit_id)
                readout_bit_path.mkdir()
                readout_bit_attrs_path = self._entity_attributes_path(readout_bit_path)
                fiducial_channel = str(self._channels_in_data[0])
                readout_one_channel = str(self._channels_in_data[1])

                if len(self._channels_in_data) == 3:
                    readout_two_channel = str(self._channels_in_data[2])
                    condition_one = self._experiment_order[readout_one_channel] == (
                        bit_idx + 1
                    )
                    condition_two = self._experiment_order[readout_two_channel] == (
                        bit_idx + 1
                    )
                    combined_condition = condition_one | condition_two

                else:
                    combined_condition = self._experiment_order[
                        readout_one_channel
                    ] == (bit_idx + 1)
                matching_rows = self._experiment_order.loc[combined_condition]

                bit_attrs = {
                    "round_linker": int(matching_rows[fiducial_channel].values[0])
                }
                self._save_to_json(bit_attrs, readout_bit_attrs_path)
        except FileExistsError:
            print("Error creating readout tile. Does it exist already?")

    def load_local_bit_linker(
        self,
        tile: int | str,
        round: int | str,
    ) -> Sequence[int] | None:
        """Load readout bits linked to fiducial round for one tile.

        Parameters
        ----------
        tile : int or str
            Tile index or tile id.
        round : int or str
            Round index or round id.

        Returns
        -------
        bit_linker : Sequence[int] or None
            Readout bits linked to fiducial round for one tile.
        """
        if isinstance(tile, int):
            if tile < 0 or tile >= self._num_tiles:
                print("Set tile index >=0 and <" + str(self._num_tiles))
                return None
            else:
                tile_id = self._tile_ids[tile]
        elif isinstance(tile, str):
            if tile not in self._tile_ids:
                print("set valid tiled id.")
                return None
            else:
                tile_id = tile
        else:
            print("'tile' must be integer index or string identifier")
            return None

        if isinstance(round, int):
            if round < 0 or round >= len(self._round_ids):
                print("Set round index >=0 and <" + str(self._num_rounds))
                return None
            else:
                round_id = self._round_ids[round]
        elif isinstance(round, str):
            if round not in self._round_ids:
                print("Set valid round id.")
                return None
            else:
                round_id = round
        else:
            print("'round' must be integer index or string identifier")
            return None

        try:
            entity_root = self._fiducial_root_path / Path(tile_id) / Path(round_id)
            attributes = self._load_entity_attributes(entity_root)
            bit_linker = attributes.get("bit_linker")
            if bit_linker is None:
                print(tile_id, round_id)
                print("Bit linker attribute not found.")
                return None
            return [int(v) for v in list(bit_linker)]
        except (TypeError, ValueError):
            print(tile_id, round_id)
            print("Bit linker attribute not found.")
            return None

    def save_local_bit_linker(
        self,
        bit_linker: Sequence[int],
        tile: int | str,
        round: int | str,
    ) -> None:
        """Save readout bits linked to fiducial round for one tile.

        Parameters
        ----------
        bit_linker : Sequence[int]
            Readout bits linked to fiducial round for one tile.
        tile : int or str
            Tile index or tile id.
        round : int or str
            Round index or round id.
        """
        if isinstance(tile, int):
            if tile < 0 or tile >= self._num_tiles:
                print("Set tile index >=0 and <" + str(self._num_tiles))
                return None
            else:
                tile_id = self._tile_ids[tile]
        elif isinstance(tile, str):
            if tile not in self._tile_ids:
                print("set valid tiled id.")
                return None
            else:
                tile_id = tile
        else:
            print("'tile' must be integer index or string identifier")
            return None

        if isinstance(round, int):
            if round < 0 or round >= len(self._round_ids):
                print("Set round index >=0 and <" + str(self._num_rounds))
                return None
            else:
                round_id = self._round_ids[round]
        elif isinstance(round, str):
            if round not in self._round_ids:
                print("Set valid round id.")
                return None
            else:
                round_id = round
        else:
            print("'round' must be integer index or string identifier")
            return None

        try:
            entity_root = self._fiducial_root_path / Path(tile_id) / Path(round_id)
            values = [int(v) for v in list(bit_linker)]
            self._save_entity_attributes(
                entity_root_path=entity_root, updates={"bit_linker": values}
            )
        except (TypeError, ValueError):
            print(tile_id, round_id)
            print("Error writing bit linker attribute.")
            return None

    def load_local_round_linker(
        self,
        tile: int | str,
        bit: int | str,
    ) -> Sequence[int] | None:
        """Load fiducial round linked to readout bit for one tile.

        Parameters
        ----------
        tile : int or str
            Tile index or tile id.
        bit : int or str
            Bit index or bit id.

        Returns
        -------
        round_linker : Sequence[int] or None
            Fiducial round linked to readout bit for one tile.
        """
        if isinstance(tile, int):
            if tile < 0 or tile >= self._num_tiles:
                print("Set tile index >=0 and <" + str(self._num_tiles))
                return None
            else:
                tile_id = self._tile_ids[tile]
        elif isinstance(tile, str):
            if tile not in self._tile_ids:
                print("set valid tiled id.")
                return None
            else:
                tile_id = tile
        else:
            print("'tile' must be integer index or string identifier")
            return None

        if isinstance(bit, int):
            if bit < 0 or bit >= len(self._bit_ids):
                print("Set bit index >=0 and <" + str(len(self._bit_ids)))
                return None
            else:
                bit_id = self._bit_ids[bit]
        elif isinstance(bit, str):
            if bit not in self._bit_ids:
                print("Set valid bit id.")
                return None
            else:
                bit_id = bit
        else:
            print("'bit' must be integer index or string identifier")
            return None

        try:
            entity_root = self._readouts_root_path / Path(tile_id) / Path(bit_id)
            attributes = self._load_entity_attributes(entity_root)
            round_linker = attributes.get("round_linker")
            if round_linker is None:
                print(tile_id, bit_id)
                print("Round linker attribute not found.")
                return None
            return int(round_linker)
        except (TypeError, ValueError):
            print(tile_id, bit_id)
            print("Round linker attribute not found.")
            return None

    def save_local_round_linker(
        self,
        round_linker: int,
        tile: int | str,
        bit: int | str,
    ) -> None:
        """Save fiducial round linker attribute to readout bit for one tile.

        Parameters
        ----------
        round_linker : int
            Fiducial round linked to readout bit for one tile.
        tile : int or str
            Tile index or tile id.
        bit : int or str
            Bit index or bit id.
        """
        if isinstance(tile, int):
            if tile < 0 or tile >= self._num_tiles:
                print("Set tile index >=0 and <" + str(self._num_tiles))
                return None
            else:
                tile_id = self._tile_ids[tile]
        elif isinstance(tile, str):
            if tile not in self._tile_ids:
                print("set valid tiled id.")
                return None
            else:
                tile_id = tile
        else:
            print("'tile' must be integer index or string identifier")
            return None

        if isinstance(bit, int):
            if bit < 0 or bit >= len(self._bit_ids):
                print("Set bit index >=0 and <" + str(len(self._bit_ids)))
                return None
            else:
                bit_id = self._bit_ids[bit]
        elif isinstance(bit, str):
            if bit not in self._bit_ids:
                print("Set valid bit id.")
                return None
            else:
                bit_id = bit
        else:
            print("'bit' must be integer index or string identifier")
            return None

        try:
            entity_root = self._readouts_root_path / Path(tile_id) / Path(bit_id)
            self._save_entity_attributes(
                entity_root_path=entity_root,
                updates={"round_linker": int(round_linker)},
            )
        except (TypeError, ValueError):
            print(tile_id, bit_id)
            print("Error writing round linker attribute.")
            return None

    def load_local_stage_position_zyx_um(
        self,
        tile: int | str,
        round: int | str,
    ) -> tuple[np.ndarray, np.ndarray] | None:
        """Load tile stage position for one tile.

        Parameters
        ----------
        tile : int or str
            Tile index or tile id.
        round : int or str
            Round index or round id.

        Returns
        -------
        stage_zyx_um : ArrayLike or None
            Tile stage position in Z, Y, X microns. Legacy two-coordinate Y, X
            metadata is returned with Z=0 without modifying the stored data.
        affine_zyx_um: ArrayLike or None
            Affine transformation between stage and camera
        """
        if isinstance(tile, int):
            if tile < 0 or tile >= self._num_tiles:
                print("Set tile index >=0 and <" + str(self._num_tiles))
                return None
            else:
                tile_id = self._tile_ids[tile]
        elif isinstance(tile, str):
            if tile not in self._tile_ids:
                print("set valid tiled id.")
                return None
            else:
                tile_id = tile
        else:
            print("'tile' must be integer index or string identifier")
            return None

        if isinstance(round, int):
            if round < 0 or round >= len(self._round_ids):
                print("Set round index >=0 and <" + str(self._num_rounds))
                return None
            else:
                round_id = self._round_ids[round]
        elif isinstance(round, str):
            if round not in self._round_ids:
                print("Set valid round id.")
                return None
            else:
                round_id = round
        else:
            print("'round' must be integer index or string identifier")
            return None

        try:
            entity_root = self._fiducial_root_path / Path(tile_id) / Path(round_id)
            attributes = self._load_entity_attributes(entity_root)
            stage_zyx_um = attributes.get("stage_zyx_um")
            affine_zyx_px = attributes.get("affine_zyx_px")
            if stage_zyx_um is None or affine_zyx_px is None:
                print(tile_id, round_id)
                print("Stage position attribute not found.")
                return None
            return self._normalize_stage_position_zyx_um(stage_zyx_um), np.asarray(
                affine_zyx_px, dtype=np.float32
            )
        except (TypeError, ValueError):
            print(tile_id, round_id)
            print("Stage position attribute not found.")
            return None

    def save_local_stage_position_zyx_um(
        self,
        stage_zyx_um: ArrayLike,
        affine_zyx_px: ArrayLike,
        tile: int | str,
        round: int | str,
    ) -> None:
        """Save tile stage position for one tile.

        Parameters
        ----------
        stage_zyx_um : ArrayLike
            Tile stage position in Z, Y, X microns. Two-coordinate Y, X input
            is accepted and stored as Z, Y, X with Z=0.
        affine_zyx_px: ArrayLike
            4x4 homogeneous affine matrix for stage transformation
        tile : int or str
            Tile index or tile id.
        round : int or str
            Round index or round id.
        """
        if isinstance(tile, int):
            if tile < 0 or tile >= self._num_tiles:
                print("Set tile index >=0 and <" + str(self._num_tiles))
                return None
            else:
                tile_id = self._tile_ids[tile]
        elif isinstance(tile, str):
            if tile not in self._tile_ids:
                print("set valid tiled id.")
                return None
            else:
                tile_id = tile
        else:
            print("'tile' must be integer index or string identifier")
            return None

        if isinstance(round, int):
            if round < 0 or round >= len(self._round_ids):
                print("Set round index >=0 and <" + str(self._num_rounds))
                return None
            else:
                round_id = self._round_ids[round]
        elif isinstance(round, str):
            if round not in self._round_ids:
                print("Set valid round id.")
                return None
            else:
                round_id = round
        else:
            print("'round' must be integer index or string identifier")
            return None

        try:
            entity_root = self._fiducial_root_path / Path(tile_id) / Path(round_id)
            stage_zyx_um = self._normalize_stage_position_zyx_um(stage_zyx_um)
            self._save_entity_attributes(
                entity_root_path=entity_root,
                updates={
                    "stage_zyx_um": stage_zyx_um.tolist(),
                    "affine_zyx_px": np.asarray(
                        affine_zyx_px, dtype=np.float32
                    ).tolist(),
                },
            )
            self._update_image_translation_transform(
                entity_root / Path("corrected_data"), stage_zyx_um
            )
        except (TypeError, ValueError):
            print(tile_id, round_id)
            print("Error writing stage position attribute.")
            return None

    def load_local_wavelengths_um(
        self,
        tile: int | str,
        round: int | str | None = None,
        bit: int | str | None = None,
    ) -> tuple[float, float] | None:
        """Load wavelengths for fiducial OR readout bit for one tile.

        Parameters
        ----------
        tile : int or str
            Tile index or tile id.
        round : int or str or None
            Round index or round id.
        bit : int or str or None
            Bit index or bit id.

        Returns
        -------
        wavelengths_um : tuple[float, float] or None
            Wavelengths for fiducial OR readout bit for one tile.
        """
        if (round is None and bit is None) or (round is not None and bit is not None):
            print("Provide either 'round' or 'bit', but not both")
            return None

        if isinstance(tile, int):
            if tile < 0 or tile >= self._num_tiles:
                print("Set tile index >=0 and <" + str(self._num_tiles))
                return None
            else:
                tile_id = self._tile_ids[tile]
        elif isinstance(tile, str):
            if tile not in self._tile_ids:
                print("set valid tiled id")
                return None
            else:
                tile_id = tile
        else:
            print("'tile' must be integer index or string identifier")
            return None

        if bit is not None:
            if isinstance(bit, int):
                if bit < 0 or bit >= len(self._bit_ids):
                    print("Set bit index >=0 and <" + str(len(self._bit_ids)))
                    return None
                else:
                    local_id = self._bit_ids[bit]
            elif isinstance(bit, str):
                if bit not in self._bit_ids:
                    print("Set valid bit id")
                    return None
                else:
                    local_id = bit
            else:
                print("'bit' must be integer index or string identifier")
                return None
            entity_root = self._readouts_root_path / Path(tile_id) / Path(local_id)
        else:
            if isinstance(round, int):
                if round < 0 or round >= len(self._round_ids):
                    print("Set round index >=0 and <" + str(self._num_rounds))
                    return None
                else:
                    local_id = self._round_ids[round]
            elif isinstance(round, str):
                if round not in self._round_ids:
                    print("Set valid round id")
                    return None
                else:
                    local_id = round
            else:
                print("'round' must be integer index or string identifier")
                return None
            entity_root = self._fiducial_root_path / Path(tile_id) / Path(local_id)

        try:
            attributes = self._load_entity_attributes(entity_root)
            ex_wavelength_um = attributes["excitation_um"]
            em_wavelength_um = attributes["emission_um"]
            return (ex_wavelength_um, em_wavelength_um)
        except KeyError:
            print("Wavelength attributes not found.")
            return None

    def save_local_wavelengths_um(
        self,
        wavelengths_um: tuple[float, float],
        tile: int | str,
        round: int | str | None = None,
        bit: int | str | None = None,
    ) -> tuple[float, float] | None:
        """Save wavelengths for fiducial OR readout bit for one tile.

        Parameters
        ----------
        wavelengths_um : tuple[float, float]
            Wavelengths for fiducial OR readout bit for one tile.
        tile : int or str
            Tile index or tile id.
        round : int or str or None
            Round index or round id.
        bit : int or str or None
            Bit index or bit id.

        Returns
        -------
        wavelengths_um : tuple[float, float] or None
            Wavelengths for fiducial OR readout bit for one tile.
        """
        if (round is None and bit is None) or (round is not None and bit is not None):
            print("Provide either 'round' or 'bit', but not both")
            return None

        if isinstance(tile, int):
            if tile < 0 or tile >= self._num_tiles:
                print("Set tile index >=0 and <" + str(self._num_tiles))
                return None
            else:
                tile_id = self._tile_ids[tile]
        elif isinstance(tile, str):
            if tile not in self._tile_ids:
                print("set valid tiled id")
                return None
            else:
                tile_id = tile
        else:
            print("'tile' must be integer index or string identifier")
            return None

        if bit is not None:
            if isinstance(bit, int):
                if bit < 0 or bit >= len(self._bit_ids):
                    print("Set bit index >=0 and <" + str(len(self._bit_ids)))
                    return None
                else:
                    local_id = self._bit_ids[bit]
            elif isinstance(bit, str):
                if bit not in self._bit_ids:
                    print("Set valid bit id")
                    return None
                else:
                    local_id = bit
            else:
                print("'bit' must be integer index or string identifier")
                return None
            entity_root = self._readouts_root_path / Path(tile_id) / Path(local_id)
        else:
            if isinstance(round, int):
                if round < 0 or round >= len(self._round_ids):
                    print("Set round index >=0 and <" + str(self._num_rounds))
                    return None
                else:
                    local_id = self._round_ids[round]
            elif isinstance(round, str):
                if round not in self._round_ids:
                    print("Set valid round id")
                    return None
                else:
                    local_id = round
            else:
                print("'round' must be integer index or string identifier")
                return None
            entity_root = self._fiducial_root_path / Path(tile_id) / Path(local_id)

        try:
            self._save_entity_attributes(
                entity_root_path=entity_root,
                updates={
                    "excitation_um": float(wavelengths_um[0]),
                    "emission_um": float(wavelengths_um[1]),
                },
            )
        except (FileNotFoundError, json.JSONDecodeError, TypeError, ValueError):
            print("Error writing wavelength attributes.")
            return None

    def load_local_corrected_image(
        self,
        tile: int | str,
        round: int | str | None = None,
        bit: int | str | None = None,
        return_future: bool | None = True,
    ) -> "np.ndarray | Future | TensorStore | None":
        """Load gain and offset corrected image for fiducial OR readout bit for one tile.

        Parameters
        ----------
        tile : int or str
            Tile index or tile id.
        round : int or str or None
            Round index or round id.
        bit : int or str or None
            Bit index or bit id.
        return_future : bool or None
            True returns a read future, False returns a NumPy array, and None
            returns a sliceable TensorStore handle opened through yaozarrs.

        Returns
        -------
        corrected_image : numpy.ndarray or tensorstore.Future or tensorstore.TensorStore or None
            Gain and offset corrected image for fiducial OR readout bit for one tile.
        """
        if (round is None and bit is None) or (round is not None and bit is not None):
            print("Provide either 'round' or 'bit', but not both")
            return None

        if isinstance(tile, int):
            if tile < 0 or tile >= self._num_tiles:
                print("Set tile index >=0 and <" + str(self._num_tiles))
                return None
            else:
                tile_id = self._tile_ids[tile]
        elif isinstance(tile, str):
            if tile not in self._tile_ids:
                print("set valid tiled id")
                return None
            else:
                tile_id = tile
        else:
            print("'tile' must be integer index or string identifier")
            return None

        if bit is not None:
            if isinstance(bit, int):
                if bit < 0 or bit >= len(self._bit_ids):
                    print("Set bit index >=0 and <" + str(len(self._bit_ids)))
                    return None
                else:
                    local_id = self._bit_ids[bit]
            elif isinstance(bit, str):
                if bit not in self._bit_ids:
                    print("Set valid bit id")
                    return None
                else:
                    local_id = bit
            else:
                print("'bit' must be integer index or string identifier")
                return None
            current_local_zarr_path = str(
                self._readouts_root_path
                / Path(tile_id)
                / Path(local_id)
                / Path("corrected_data")
            )
        else:
            if isinstance(round, int):
                if round < 0 or round >= len(self._round_ids):
                    print("Set round index >=0 and <" + str(self._num_rounds))
                    return None
                else:
                    local_id = self._round_ids[round]
            elif isinstance(round, str):
                if round not in self._round_ids:
                    print("Set valid round id")
                    return None
                else:
                    local_id = round
            else:
                print("'round' must be integer index or string identifier")
                return None
            current_local_zarr_path = str(
                self._fiducial_root_path
                / Path(tile_id)
                / Path(local_id)
                / Path("corrected_data")
            )

        image_path = self._image_store_path(current_local_zarr_path)
        if not image_path.exists():
            print("Corrected image not found.")
            return None

        try:
            corrected_image = self._load_from_zarr_array(image_path, return_future)
            return corrected_image
        except (OSError, ValueError):
            print("Error loading corrected image.")
            return None

    def save_local_corrected_image(
        self,
        image: ArrayLike,
        tile: int | str,
        gain_correction: bool = True,
        hotpixel_correction: bool = True,
        shading_correction: bool = False,
        psf_idx: int = 0,
        round: int | str | None = None,
        bit: int | str | None = None,
        return_future: bool | None = False,
    ) -> "WriteFutures | None":
        """Save gain and offset corrected image.

        Parameters
        ----------
        image : ArrayLike
            Local corrected image.
        tile : int or str
            Tile index or tile id.
        gain_correction : bool
            Gain correction applied (True) or not (False).
        hotpixel_correction : bool
            Hotpixel correction applied (True) or not (False).
        shading_correction : bool
            Shading correction applied (True) or not (False).
        psf_idx : int
            PSF index.
        round : int or str or None
            Round index or round id.
        bit : int or str or None
            Bit index or bit id.
        return_future : bool or None
            Return the completed TensorStore write handle when True. Writes
            finish before associated metadata is reported as saved.

        Returns
        -------
        tensorstore.WriteFutures or None
            Completed pixel-write handle when return_future is True; otherwise
            None. Invalid tile/round/bit selections also return None.
        """
        if (round is None and bit is None) or (round is not None and bit is not None):
            print("Provide either 'round' or 'bit', but not both")
            return None

        if isinstance(tile, int):
            if tile < 0 or tile >= self._num_tiles:
                print("Set tile index >=0 and <" + str(self._num_tiles))
                return None
            else:
                tile_id = self._tile_ids[tile]
        elif isinstance(tile, str):
            if tile not in self._tile_ids:
                print("set valid tiled id")
                return None
            else:
                tile_id = tile
        else:
            print("'tile' must be integer index or string identifier")
            return None

        if bit is not None:
            if isinstance(bit, int):
                if bit < 0 or bit >= len(self._bit_ids):
                    print("Set bit index >=0 and <" + str(len(self._bit_ids)))
                    return None
                else:
                    local_id = self._bit_ids[bit]
            elif isinstance(bit, str):
                if bit not in self._bit_ids:
                    print("Set valid bit id")
                    return None
                else:
                    local_id = bit
            else:
                print("'bit' must be integer index or string identifier")
                return None
            entity_root = self._readouts_root_path / Path(tile_id) / Path(local_id)
            current_local_zarr_path = entity_root / Path("corrected_data")
            stage_position = self._resolve_original_tile_position_zyx_um(
                tile_id=tile_id, bit_id=local_id
            )
        else:
            if isinstance(round, int):
                if round < 0 or round >= len(self._round_ids):
                    print("Set round index >=0 and <" + str(self._num_rounds))
                    return None
                else:
                    local_id = self._round_ids[round]
            elif isinstance(round, str):
                if round not in self._round_ids:
                    print("Set valid round id")
                    return None
                else:
                    local_id = round
            else:
                print("'round' must be integer index or string identifier")
                return None
            entity_root = self._fiducial_root_path / Path(tile_id) / Path(local_id)
            current_local_zarr_path = entity_root / Path("corrected_data")
            stage_position = self._resolve_original_tile_position_zyx_um(
                tile_id=tile_id, round_id=local_id
            )

        try:
            self._validate_core_image_shape(
                entity_root_path=entity_root, image_name="corrected_data", image=image
            )
            attributes = self._load_entity_attributes(entity_root)
            attributes.update(
                {
                    "gain_correction": bool(gain_correction),
                    "hotpixel_correction": bool(hotpixel_correction),
                    "shading_correction": bool(shading_correction),
                    "psf_idx": int(psf_idx),
                }
            )
            write_future = self._save_to_zarr_array(
                image,
                current_local_zarr_path,
                return_future,
                ome_scale=self.voxel_size_zyx_um,
                ome_translation=stage_position,
                extra_attributes=attributes,
            )
            if write_future is not None:
                write_future.result()
            self._save_entity_attributes(
                entity_root_path=entity_root, updates=attributes
            )
            return write_future
        except (OSError, TimeoutError, ValueError) as e:
            print(e)
            print("Error saving corrected image.")
            raise

    def load_local_rigid_xform_xyz_px(
        self,
        tile: int | str,
        round: int | str,
    ) -> ArrayLike | None:
        """Load calculated rigid registration transform for one round and tile.

        Parameters
        ----------
        tile : int or str
            Tile index or tile id.
        round : int or str
            Round index or round id.

        Returns
        -------
        rigid_xform_xyz_px : ArrayLike or None
            Local rigid registration transform for one round and tile.
        """
        if isinstance(tile, int):
            if tile < 0 or tile >= self._num_tiles:
                print("Set tile index >=0 and <" + str(self._num_tiles))
                return None
            else:
                tile_id = self._tile_ids[tile]
        elif isinstance(tile, str):
            if tile not in self._tile_ids:
                print("set valid tiled id")
                return None
            else:
                tile_id = tile
        else:
            print("'tile' must be integer index or string identifier")
            return None

        if isinstance(round, int):
            if round < 0 or round >= len(self._round_ids):
                print("Set round index >=0 and <" + str(self._num_rounds))
                return None
            else:
                round_id = self._round_ids[round]
        elif isinstance(round, str):
            if round not in self._round_ids:
                print("Set valid round id")
                return None
            else:
                round_id = round
        else:
            print("'round' must be integer index or string identifier")
            return None
        try:
            entity_root = self._fiducial_root_path / Path(tile_id) / Path(round_id)
            attributes = self._load_entity_attributes(entity_root)
            rigid_xform_xyz_px = np.asarray(
                attributes["rigid_xform_xyz_px"], dtype=np.float32
            )
            return rigid_xform_xyz_px
        except (FileNotFoundError, json.JSONDecodeError, KeyError):
            print(tile_id, round_id)
            print("Rigid transform mapping back to first round not found.")
            return None

    def save_local_rigid_xform_xyz_px(
        self,
        rigid_xform_xyz_px: ArrayLike,
        tile: int | str,
        round: int | str,
    ) -> ArrayLike | None:
        """Save calculated rigid registration transform for one round and tile.

        Parameters
        ----------
        rigid_xform_xyz_px : ArrayLike
            Local rigid registration transform for one round and tile.
        tile : int or str
            Tile index or tile id.
        round : int or str
            Round index or round id.

        Returns
        -------
        rigid_xform_xyz_px : ArrayLike or None
            Local rigid registration transform for one round and tile.
        """
        if isinstance(tile, int):
            if tile < 0 or tile >= self._num_tiles:
                print("Set tile index >=0 and <" + str(self._num_tiles))
                return None
            else:
                tile_id = self._tile_ids[tile]
        elif isinstance(tile, str):
            if tile not in self._tile_ids:
                print("set valid tiled id")
                return None
            else:
                tile_id = tile
        else:
            print("'tile' must be integer index or string identifier")
            return None

        if isinstance(round, int):
            if round < 0 or round >= len(self._round_ids):
                print("Set round index >=0 and <" + str(self._num_rounds))
                return None
            else:
                round_id = self._round_ids[round]
        elif isinstance(round, str):
            if round not in self._round_ids:
                print("Set valid round id")
                return None
            else:
                round_id = round
        else:
            print("'round' must be integer index or string identifier")
            return None
        try:
            entity_root = self._fiducial_root_path / Path(tile_id) / Path(round_id)
            self._save_entity_attributes(
                entity_root_path=entity_root,
                updates={
                    "rigid_xform_xyz_px": np.asarray(
                        rigid_xform_xyz_px, dtype=np.float32
                    ).tolist()
                },
            )
        except (FileNotFoundError, json.JSONDecodeError, TypeError, ValueError):
            print("Error writing rigid transform attribute.")
            return None

    def load_local_round_transform_zyx_um(
        self,
        tile: int | str,
        round: int | str,
    ) -> ArrayLike | None:
        """
        Load the local fiducial round transform for one tile.

        Parameters
        ----------
        tile : int | str
            Tile index or tile identifier.
        round : int | str
            Fiducial round index or round identifier.

        Returns
        -------
        ArrayLike or None
            Homogeneous 4x4 affine transform in physical Z, Y, X microns. The
            transform maps first-round reference coordinates to coordinates in
            the requested moving round. Returns None when the transform is not
            present.
        """
        if isinstance(tile, int):
            if tile < 0 or tile >= self._num_tiles:
                print("Set tile index >=0 and <" + str(self._num_tiles))
                return None
            tile_id = self._tile_ids[tile]
        elif isinstance(tile, str):
            if tile not in self._tile_ids:
                print("set valid tiled id")
                return None
            tile_id = tile
        else:
            print("'tile' must be integer index or string identifier")
            return None

        if isinstance(round, int):
            if round < 0 or round >= len(self._round_ids):
                print("Set round index >=0 and <" + str(self._num_rounds))
                return None
            round_id = self._round_ids[round]
        elif isinstance(round, str):
            if round not in self._round_ids:
                print("Set valid round id")
                return None
            round_id = round
        else:
            print("'round' must be integer index or string identifier")
            return None
        try:
            entity_root = self._fiducial_root_path / Path(tile_id) / Path(round_id)
            attributes = self._load_entity_attributes(entity_root)
            return np.asarray(
                attributes["local_round_transform_zyx_um"], dtype=np.float32
            )
        except (FileNotFoundError, json.JSONDecodeError, KeyError):
            print(tile_id, round_id)
            print("Local round transform mapping back to first round not found.")
            return None

    def save_local_round_transform_zyx_um(
        self,
        transform_zyx_um: ArrayLike,
        tile: int | str,
        round: int | str,
    ) -> None:
        """
        Save the local fiducial round transform for one tile.

        Parameters
        ----------
        transform_zyx_um : ArrayLike
            Homogeneous 4x4 affine transform in physical Z, Y, X microns. The
            transform maps first-round reference coordinates to coordinates in
            the requested moving round.
        tile : int | str
            Tile index or tile identifier.
        round : int | str
            Fiducial round index or round identifier.

        Returns
        -------
        None
            The transform is stored in the entity attributes for the requested
            fiducial tile and round.
        """
        if isinstance(tile, int):
            if tile < 0 or tile >= self._num_tiles:
                print("Set tile index >=0 and <" + str(self._num_tiles))
                return None
            tile_id = self._tile_ids[tile]
        elif isinstance(tile, str):
            if tile not in self._tile_ids:
                print("set valid tiled id")
                return None
            tile_id = tile
        else:
            print("'tile' must be integer index or string identifier")
            return None

        if isinstance(round, int):
            if round < 0 or round >= len(self._round_ids):
                print("Set round index >=0 and <" + str(self._num_rounds))
                return None
            round_id = self._round_ids[round]
        elif isinstance(round, str):
            if round not in self._round_ids:
                print("Set valid round id")
                return None
            round_id = round
        else:
            print("'round' must be integer index or string identifier")
            return None
        try:
            entity_root = self._fiducial_root_path / Path(tile_id) / Path(round_id)
            self._save_entity_attributes(
                entity_root_path=entity_root,
                updates={
                    "local_round_transform_zyx_um": np.asarray(
                        transform_zyx_um, dtype=np.float32
                    ).tolist()
                },
            )
        except (FileNotFoundError, json.JSONDecodeError, TypeError, ValueError):
            print("Error writing local round transform attribute.")
            return None

    def load_coord_of_xform_px(
        self,
        tile: int | str | None,
        round: int | str | None,
        return_future: bool | None = True,
    ) -> "tuple[np.ndarray | Future | TensorStore, np.ndarray, np.ndarray] | None":
        """Local fiducial optical flow matrix for one round and tile.

        Parameters
        ----------
        tile : int or str or None
            Tile index or tile id.
        round : int or str or None
            Round index or round id.
        return_future : bool or None
            True returns a read future, False returns a NumPy array, and None
            returns a sliceable TensorStore handle opened through yaozarrs.

        Returns
        -------
        of_xform_px : numpy.ndarray or tensorstore.Future or tensorstore.TensorStore
            Local fiducial optical flow matrix for one round and tile.
        block_size : numpy.ndarray
            Block size used for the pixel warp.
        block_stride : numpy.ndarray
            Block stride used for the pixel warp.

        Returns None when the image or required metadata is unavailable.
        """
        if isinstance(tile, int):
            if tile < 0 or tile >= self._num_tiles:
                print("Set tile index >=0 and <" + str(self._num_tiles))
                return None
            else:
                tile_id = self._tile_ids[tile]
        elif isinstance(tile, str):
            if tile not in self._tile_ids:
                print("set valid tiled id")
                return None
            else:
                tile_id = tile
        else:
            print("'tile' must be integer index or string identifier")
            return None

        if isinstance(round, int):
            if round < 0 or round >= len(self._round_ids):
                print("Set round index >=0 and <" + str(self._num_rounds))
                return None
            else:
                round_id = self._round_ids[round]
        elif isinstance(round, str):
            if round not in self._round_ids:
                print("Set valid round id")
                return None
            else:
                round_id = round
        else:
            print("'round' must be integer index or string identifier")
            return None

        entity_root = self._fiducial_root_path / Path(tile_id) / Path(round_id)
        current_local_zarr_path = entity_root / Path("opticalflow_xform_px")

        image_path = self._image_store_path(current_local_zarr_path)
        if not image_path.exists():
            print("Optical flow transform mapping back to first round not found.")
            return None

        try:
            of_xform_px = self._load_from_zarr_array(image_path, return_future)
            attributes = self._load_entity_attributes(
                entity_root, image_names=("opticalflow_xform_px",)
            )
            block_size = np.asarray(attributes["block_size"], dtype=np.float32)
            block_stride = np.asarray(attributes["block_stride"], dtype=np.float32)

            return (of_xform_px, block_size, block_stride)
        except (OSError, ValueError, KeyError) as e:
            print(e)
            print("Error loading optical flow transform.")
            return None

    def save_coord_of_xform_px(
        self,
        of_xform_px: ArrayLike,
        tile: int | str,
        block_size: Sequence[float],
        block_stride: Sequence[float],
        round: int | str,
        return_future: bool | None = False,
    ) -> "WriteFutures | None":
        """Save fiducial optical flow matrix for one round and tile.

        Parameters
        ----------
        of_xform_px : ArrayLike
            Local fiducial optical flow matrix for one round and tile.
        tile : int or str
            Tile index or tile id.
        block_size : Sequence[float]
            Block size for pixel warp
        block_stride: Sequence[float]
            Block stride for pixel warp
        round : int or str
            Round index or round id.
        return_future : bool or None
            Return the completed TensorStore write handle when True. Writes
            finish before associated metadata is reported as saved.

        Returns
        -------
        tensorstore.WriteFutures or None
            Completed pixel-write handle when return_future is True; otherwise
            None. Invalid tile/round/bit selections also return None.
        """
        if isinstance(tile, int):
            if tile < 0 or tile >= self._num_tiles:
                print("Set tile index >=0 and <" + str(self._num_tiles))
                return None
            else:
                tile_id = self._tile_ids[tile]
        elif isinstance(tile, str):
            if tile not in self._tile_ids:
                print("set valid tiled id")
                return None
            else:
                tile_id = tile
        else:
            print("'tile' must be integer index or string identifier")
            return None

        if isinstance(round, int):
            if round < 0 or round >= len(self._round_ids):
                print("Set round index >=0 and <" + str(self._num_rounds))
                return None
            else:
                local_id = self._round_ids[round]
        elif isinstance(round, str):
            if round not in self._round_ids:
                print("Set valid round id")
                return None
            else:
                local_id = round
        else:
            print("'round' must be integer index or string identifier")
            return None
        entity_root = self._fiducial_root_path / Path(tile_id) / Path(local_id)
        current_local_zarr_path = entity_root / Path("opticalflow_xform_px")

        try:
            opticalflow_attrs = {
                "block_size": np.asarray(block_size, dtype=np.float32).tolist(),
                "block_stride": np.asarray(block_stride, dtype=np.float32).tolist(),
            }
            # Optical flow is a dense pixel-space field, so we do not encode
            # physical voxel scale or stage translation transforms here.
            write_future = self._save_to_zarr_array(
                of_xform_px,
                current_local_zarr_path,
                return_future,
                extra_attributes=opticalflow_attrs,
            )
            if write_future is not None:
                write_future.result()
            self._save_entity_attributes(
                entity_root_path=entity_root, updates=opticalflow_attrs
            )
            return write_future
        except (OSError, TimeoutError):
            print("Error saving optical flow transform.")
            raise

    def load_local_sofima_flow_field(
        self,
        *,
        tile: int | str,
        round: int | str,
        return_future: bool | None = True,
    ) -> "tuple[np.ndarray | Future | TensorStore, dict] | None":
        """
        Load the SOFIMA flow field for one local fiducial round.

        Parameters
        ----------
        tile : int or str
            Tile index or tile identifier.
        round : int or str
            Moving fiducial round index or identifier.
        return_future : bool or None, default=True
            True returns a read future, False returns a NumPy array, and None
            returns a sliceable TensorStore handle opened through yaozarrs.

        Returns
        -------
        tuple[numpy.ndarray or tensorstore.Future or tensorstore.TensorStore, dict] or None
            SOFIMA flow field and metadata attributes. The map channels are X,
            Y, Z and spatial axes are Z, Y, X. ``map_stride_zyx_px`` is stored
            in Z, Y, X order. ``map_box_start_xyz_px`` is stored in X, Y, Z
            order and gives the reference-grid coordinate of the first flow
            sample. For fields produced by SOFIMA this is the patch center
            coordinate, not the image corner.
        """
        if isinstance(tile, int):
            if tile < 0 or tile >= self._num_tiles:
                print("Set tile index >=0 and <" + str(self._num_tiles))
                return None
            tile_id = self._tile_ids[tile]
        elif isinstance(tile, str):
            if tile not in self._tile_ids:
                print("set valid tiled id")
                return None
            tile_id = tile
        else:
            print("'tile' must be integer index or string identifier")
            return None

        if isinstance(round, int):
            if round < 0 or round >= len(self._round_ids):
                print("Set round index >=0 and <" + str(self._num_rounds))
                return None
            round_id = self._round_ids[round]
        elif isinstance(round, str):
            if round not in self._round_ids:
                print("Set valid round id")
                return None
            round_id = round
        else:
            print("'round' must be integer index or string identifier")
            return None

        image_name = "local_sofima_flow_field"
        entity_root = self._fiducial_root_path / Path(tile_id) / Path(round_id)
        current_local_zarr_path = entity_root / Path(image_name)
        image_path = self._image_store_path(current_local_zarr_path)
        if not image_path.exists():
            print("SOFIMA flow field not found.")
            return None

        try:
            sofima_flow_field = self._load_from_zarr_array(image_path, return_future)
            attributes = self._load_entity_attributes(
                entity_root,
                image_names=(image_name,),
            )
            return sofima_flow_field, attributes
        except (OSError, ValueError, KeyError) as e:
            print(e)
            print("Error loading SOFIMA flow field.")
            return None

    def save_local_sofima_flow_field(
        self,
        sofima_flow_field_xyz_px: ArrayLike,
        *,
        tile: int | str,
        round: int | str,
        reference_round: int | str,
        map_stride_zyx_px: Sequence[float],
        map_box_start_xyz_px: Sequence[float],
        map_box_size_xyz_px: Sequence[float],
        reference_shape_zyx_px: Sequence[int],
        moving_shape_zyx_px: Sequence[int],
        sofima_status: str = "ok",
        valid_flow_vectors: int | None = None,
        return_future: bool | None = False,
    ) -> "WriteFutures | None":
        """
        Save the SOFIMA flow field for one local fiducial round.

        The saved OME-Zarr image stores the raw float32 SOFIMA map exactly as
        used in memory. The package convention is channel-first ``(3, z, y,
        x)`` with channels ``X, Y, Z`` and spatial axes ``Z, Y, X``. Flow
        values are relative displacements in reference-image pixels from a
        reference coordinate to the affine-initialized moving coordinate.
        ``map_box_start_xyz_px`` is the reference coordinate of the first flow
        sample in ``X, Y, Z`` order. SOFIMA patch-correlation vectors are
        patch-centered, so this is normally half the patch size.

        Parameters
        ----------
        sofima_flow_field_xyz_px : ArrayLike
            Relative SOFIMA flow field with channels X, Y, Z and spatial axes
            Z, Y, X.
        tile : int or str
            Tile index or tile identifier.
        round : int or str
            Moving fiducial round index or identifier.
        reference_round : int or str
            Reference fiducial round index or identifier.
        map_stride_zyx_px : Sequence[float]
            Flow-field stride in reference pixels in Z, Y, X order.
        map_box_start_xyz_px : Sequence[float]
            Reference pixel coordinate of the first flow sample in X, Y, Z
            order.
        map_box_size_xyz_px : Sequence[float]
            Flow-field sample-lattice extent in X, Y, Z order, measured from
            ``map_box_start_xyz_px`` through the last stored map sample.
        reference_shape_zyx_px : Sequence[int]
            Reference image shape in Z, Y, X order.
        moving_shape_zyx_px : Sequence[int]
            Moving native image shape in Z, Y, X order.
        sofima_status : str, default="ok"
            Status reported by the SOFIMA estimator.
        valid_flow_vectors : int or None, default=None
            Number of valid local vectors before missing-vector fill.
        return_future : bool or None, default=False
            Return the completed TensorStore write handle when True. Writes
            finish before associated metadata is reported as saved.

        Returns
        -------
        tensorstore.WriteFutures or None
            Completed pixel-write handle when return_future is True; otherwise
            None. Invalid tile or round selections also return None.
        """
        if isinstance(tile, int):
            if tile < 0 or tile >= self._num_tiles:
                print("Set tile index >=0 and <" + str(self._num_tiles))
                return None
            tile_id = self._tile_ids[tile]
        elif isinstance(tile, str):
            if tile not in self._tile_ids:
                print("set valid tiled id")
                return None
            tile_id = tile
        else:
            print("'tile' must be integer index or string identifier")
            return None

        if isinstance(round, int):
            if round < 0 or round >= len(self._round_ids):
                print("Set round index >=0 and <" + str(self._num_rounds))
                return None
            round_id = self._round_ids[round]
        elif isinstance(round, str):
            if round not in self._round_ids:
                print("Set valid round id")
                return None
            round_id = round
        else:
            print("'round' must be integer index or string identifier")
            return None

        if isinstance(reference_round, int):
            if reference_round < 0 or reference_round >= len(self._round_ids):
                print("Set reference round index >=0 and <" + str(len(self._round_ids)))
                return None
            reference_round_id = self._round_ids[reference_round]
        elif isinstance(reference_round, str):
            if reference_round not in self._round_ids:
                print("Set valid reference round id")
                return None
            reference_round_id = reference_round
        else:
            print("'reference_round' must be integer index or string identifier")
            return None

        image_name = "local_sofima_flow_field"
        entity_root = self._fiducial_root_path / Path(tile_id) / Path(round_id)
        current_local_zarr_path = entity_root / Path(image_name)
        attributes = {
            "registration_backend": "sofima",
            "initial_registration_source": "stored_local_affine_transform",
            "flow_field_name": image_name,
            "flow_direction": (
                f"{reference_round_id}_reference_xyz_px_to_affine_initialized_"
                f"{round_id}_xyz_px"
            ),
            "final_render_direction": (
                f"{reference_round_id}_reference_xyz_px_to_moving_native_xyz_px"
            ),
            "flow_representation": "sofima_relative_coordinate_map",
            "flow_channel_order": "xyz",
            "flow_spatial_order": "zyx",
            "map_stride_zyx_px": np.asarray(
                map_stride_zyx_px, dtype=np.float32
            ).tolist(),
            "map_box_start_xyz_px": np.asarray(
                map_box_start_xyz_px, dtype=np.float32
            ).tolist(),
            "map_box_size_xyz_px": np.asarray(
                map_box_size_xyz_px, dtype=np.float32
            ).tolist(),
            "reference_shape_zyx_px": np.asarray(
                reference_shape_zyx_px, dtype=np.int64
            ).tolist(),
            "moving_shape_zyx_px": np.asarray(
                moving_shape_zyx_px, dtype=np.int64
            ).tolist(),
            "sofima_status": str(sofima_status),
            "interpolation_count_final_image": 1,
        }
        if valid_flow_vectors is not None:
            attributes["valid_flow_vectors"] = int(valid_flow_vectors)

        try:
            write_future = self._save_to_zarr_array(
                np.asarray(sofima_flow_field_xyz_px, dtype=np.float32),
                current_local_zarr_path,
                return_future,
                ome_scale=self.voxel_size_zyx_um,
                extra_attributes=attributes,
            )
            if write_future is not None:
                write_future.result()
            self._save_entity_attributes(
                entity_root_path=entity_root, updates=attributes
            )
            return write_future
        except (OSError, TimeoutError):
            print("Error saving SOFIMA flow field.")
            raise

    def load_local_deconvolved_fiducial_image(
        self,
        tile: int | str,
        round: int | str,
        return_future: bool | None = True,
    ) -> "np.ndarray | Future | TensorStore | None":
        """Load a native-frame deconvolved fiducial image.

        Deconvolved fiducials are loaded from ``decon_data`` in their native,
        unwarped tile frame. This image exists only when fiducial deconvolution
        was run during preprocessing.

        Parameters
        ----------
        tile : int or str
            Tile index or tile id.
        round : int or str
            Round index or round id.
        return_future : bool or None
            True returns a read future, False returns a NumPy array, and None
            returns a sliceable TensorStore handle opened through yaozarrs.

        Returns
        -------
        numpy.ndarray or tensorstore.Future or tensorstore.TensorStore or None
            Native-frame deconvolved fiducial image.
        """
        if isinstance(tile, int):
            if tile < 0 or tile >= self._num_tiles:
                print("Set tile index >=0 and <" + str(self._num_tiles))
                return None
            tile_id = self._tile_ids[tile]
        elif isinstance(tile, str):
            if tile not in self._tile_ids:
                print("set valid tiled id")
                return None
            tile_id = tile
        else:
            print("'tile' must be integer index or string identifier")
            return None

        if isinstance(round, int):
            if round < 0 or round >= len(self._round_ids):
                print("Set round index >=0 and <" + str(self._num_rounds))
                return None
            round_id = self._round_ids[round]
        elif isinstance(round, str):
            if round not in self._round_ids:
                print("Set valid round id")
                return None
            round_id = round
        else:
            print("'round' must be integer index or string identifier")
            return None

        decon_path = self._fiducial_root_path / tile_id / round_id / Path("decon_data")
        image_path = self._image_store_path(decon_path)
        if not image_path.exists():
            return None

        try:
            return self._load_from_zarr_array(image_path, return_future)
        except (OSError, ValueError) as e:
            print(e)
            print("Error loading local deconvolved fiducial image.")
            return None

    def load_local_fiducial_image(
        self,
        tile: int | str,
        round: int | str,
        return_future: bool | None = True,
    ) -> "np.ndarray | Future | TensorStore | None":
        """Load the best available native-frame fiducial image.

        Deconvolved fiducial data are returned when ``decon_data`` exists;
        otherwise corrected fiducial data are returned.

        Parameters
        ----------
        tile : int or str
            Tile index or tile id.
        round : int or str
            Round index or round id.
        return_future : bool or None
            True returns a read future, False returns a NumPy array, and None
            returns a sliceable TensorStore handle opened through yaozarrs.

        Returns
        -------
        numpy.ndarray or tensorstore.Future or tensorstore.TensorStore or None
            Deconvolved fiducial image if available, otherwise corrected image.
        """
        image = self.load_local_deconvolved_fiducial_image(
            tile=tile,
            round=round,
            return_future=return_future,
        )
        if image is not None:
            return image
        return self.load_local_corrected_image(
            tile=tile,
            round=round,
            return_future=return_future,
        )

    def save_local_deconvolved_fiducial_image(
        self,
        image: ArrayLike,
        tile: int | str,
        round: int | str,
        return_future: bool | None = False,
    ) -> "WriteFutures | None":
        """
        Save a native-frame deconvolved fiducial image.

        Deconvolved fiducials are saved under ``decon_data`` in their native,
        unwarped tile frame.

        Parameters
        ----------
        image : ArrayLike
            Image to save.
        tile : int or str
            Tile index or tile id.
        round : int or str
            Round index or round id.
        return_future : bool or None
            Return the completed TensorStore write handle when True. Writes
            finish before associated metadata is reported as saved.

        Returns
        -------
        tensorstore.WriteFutures or None
            Completed pixel-write handle when return_future is True; otherwise
            None. Invalid tile/round/bit selections also return None.
        """
        if isinstance(tile, int):
            if tile < 0 or tile >= self._num_tiles:
                print("Set tile index >=0 and <" + str(self._num_tiles))
                return None
            tile_id = self._tile_ids[tile]
        elif isinstance(tile, str):
            if tile not in self._tile_ids:
                print("set valid tiled id")
                return None
            tile_id = tile
        else:
            print("'tile' must be integer index or string identifier")
            return None

        if isinstance(round, int):
            if round < 0 or round >= len(self._round_ids):
                print("Set round index >=0 and <" + str(self._num_rounds))
                return None
            round_id = self._round_ids[round]
        elif isinstance(round, str):
            if round not in self._round_ids:
                print("Set valid round id")
                return None
            round_id = round
        else:
            print("'round' must be integer index or string identifier")
            return None

        entity_root = self._fiducial_root_path / tile_id / round_id
        decon_path = entity_root / Path("decon_data")
        stage_position = self._resolve_reference_tile_position_zyx_um(tile_id)

        try:
            self._validate_core_image_shape(
                entity_root_path=entity_root,
                image_name="decon_data",
                image=image,
            )
            attributes = self._load_entity_attributes(entity_root)
            attributes["deconvolution"] = True
            write_future = self._save_to_zarr_array(
                image,
                decon_path,
                return_future,
                ome_scale=self.voxel_size_zyx_um,
                ome_translation=stage_position,
                extra_attributes=attributes,
            )
            if write_future is not None:
                write_future.result()
            self._save_entity_attributes(
                entity_root_path=entity_root, updates=attributes
            )
            return write_future
        except (OSError, TimeoutError, ValueError):
            print("Error saving local deconvolved fiducial image.")
            raise

    def load_local_deconvolved_readout_image(
        self,
        tile: int | str,
        bit: int | str,
        return_future: bool | None = True,
    ) -> "np.ndarray | Future | TensorStore | None":
        """Load a native-frame deconvolved readout bit image.

        Deconvolved readout bits are loaded from ``decon_data`` in their
        native, unwarped tile frame. This image exists only when readout
        deconvolution was run during preprocessing.

        Parameters
        ----------
        tile : int or str
            Tile index or tile id.
        bit : int or str
            Bit index or bit id.
        return_future : bool or None
            True returns a read future, False returns a NumPy array, and None
            returns a sliceable TensorStore handle opened through yaozarrs.

        Returns
        -------
        numpy.ndarray or tensorstore.Future or tensorstore.TensorStore or None
            Native-frame deconvolved readout image.
        """
        if isinstance(tile, int):
            if tile < 0 or tile >= self._num_tiles:
                print("Set tile index >=0 and <" + str(self._num_tiles))
                return None
            tile_id = self._tile_ids[tile]
        elif isinstance(tile, str):
            if tile not in self._tile_ids:
                print("set valid tiled id")
                return None
            tile_id = tile
        else:
            print("'tile' must be integer index or string identifier")
            return None

        if isinstance(bit, int):
            if bit < 0 or bit >= len(self._bit_ids):
                print("Set bit index >=0 and <" + str(len(self._bit_ids)))
                return None
            bit_id = self._bit_ids[bit]
        elif isinstance(bit, str):
            if bit not in self._bit_ids:
                print("Set valid bit id")
                return None
            bit_id = bit
        else:
            print("'bit' must be integer index or string identifier")
            return None

        readout_path = (
            self._readouts_root_path / Path(tile_id) / Path(bit_id) / Path("decon_data")
        )
        image_path = self._image_store_path(readout_path)
        if not image_path.exists():
            return None

        try:
            return self._load_from_zarr_array(image_path, return_future)
        except (OSError, ValueError) as e:
            print(e)
            print("Error loading local deconvolved readout image.")
            return None

    def load_local_readout_image(
        self,
        tile: int | str,
        bit: int | str,
        return_future: bool | None = True,
    ) -> "np.ndarray | Future | TensorStore | None":
        """Load the best available native-frame readout bit image.

        Deconvolved readout data are returned when ``decon_data`` exists;
        otherwise corrected readout data are returned.

        Parameters
        ----------
        tile : int or str
            Tile index or tile id.
        bit : int or str
            Bit index or bit id.
        return_future : bool or None
            True returns a read future, False returns a NumPy array, and None
            returns a sliceable TensorStore handle opened through yaozarrs.

        Returns
        -------
        numpy.ndarray or tensorstore.Future or tensorstore.TensorStore or None
            Deconvolved readout image if available, otherwise corrected image.
        """
        image = self.load_local_deconvolved_readout_image(
            tile=tile,
            bit=bit,
            return_future=return_future,
        )
        if image is not None:
            return image
        return self.load_local_corrected_image(
            tile=tile,
            bit=bit,
            return_future=return_future,
        )

    def save_local_deconvolved_readout_image(
        self,
        image: ArrayLike,
        tile: int | str,
        bit: int | str,
        return_future: bool | None = False,
    ) -> "WriteFutures | None":
        """
        Save a native-frame deconvolved readout bit image.

        Deconvolved readout bits are saved under ``decon_data`` in their
        native, unwarped tile frame.

        Parameters
        ----------
        image : ArrayLike
            Image to save.
        tile : int or str
            Tile index or tile id.
        bit : int or str
            Bit index or bit id.
        return_future : bool or None
            Return the completed TensorStore write handle when True. Writes
            finish before associated metadata is reported as saved.

        Returns
        -------
        tensorstore.WriteFutures or None
            Completed pixel-write handle when return_future is True; otherwise
            None. Invalid tile/round/bit selections also return None.
        """
        if isinstance(tile, int):
            if tile < 0 or tile >= self._num_tiles:
                print("Set tile index >=0 and <" + str(self._num_tiles))
                return None
            tile_id = self._tile_ids[tile]
        elif isinstance(tile, str):
            if tile not in self._tile_ids:
                print("set valid tiled id")
                return None
            tile_id = tile
        else:
            print("'tile' must be integer index or string identifier")
            return None

        if isinstance(bit, int):
            if bit < 0 or bit >= len(self._bit_ids):
                print("Set bit index >=0 and <" + str(len(self._bit_ids)))
                return None
            bit_id = self._bit_ids[bit]
        elif isinstance(bit, str):
            if bit not in self._bit_ids:
                print("Set valid bit id")
                return None
            bit_id = bit
        else:
            print("'bit' must be integer index or string identifier")
            return None

        entity_root = self._readouts_root_path / Path(tile_id) / Path(bit_id)
        readout_path = entity_root / Path("decon_data")
        stage_position = self._resolve_original_tile_position_zyx_um(
            tile_id=tile_id,
            bit_id=bit_id,
        )

        try:
            self._validate_core_image_shape(
                entity_root_path=entity_root,
                image_name="decon_data",
                image=image,
            )
            attributes = self._load_entity_attributes(entity_root)
            attributes["deconvolution"] = True
            write_future = self._save_to_zarr_array(
                image,
                readout_path,
                return_future,
                ome_scale=self.voxel_size_zyx_um,
                ome_translation=stage_position,
                extra_attributes=attributes,
            )
            if write_future is not None:
                write_future.result()
            self._save_entity_attributes(
                entity_root_path=entity_root, updates=attributes
            )
            return write_future
        except (OSError, TimeoutError, ValueError):
            print("Error saving local deconvolved readout image.")
            raise

    def load_local_feature_predictor_image(
        self,
        tile: int | str,
        bit: int | str,
        return_future: bool | None = True,
    ) -> "np.ndarray | Future | TensorStore | None":
        """Load readout bit feature_predictor prediction image for one tile.

        Parameters
        ----------
        tile : int or str
            Tile index or tile id.
        bit : int or str
            Bit index or bit id.
        return_future : bool or None
            True returns a read future, False returns a NumPy array, and None
            returns a sliceable TensorStore handle opened through yaozarrs.

        Returns
        -------
        feature_predictor_image : numpy.ndarray or tensorstore.Future or tensorstore.TensorStore or None
            feature_predictor prediction image for one tile.
        """
        if isinstance(tile, int):
            if tile < 0 or tile >= self._num_tiles:
                print("Set tile index >=0 and <" + str(self._num_tiles))
                return None
            else:
                tile_id = self._tile_ids[tile]
        elif isinstance(tile, str):
            if tile not in self._tile_ids:
                print("set valid tiled id")
                return None
            else:
                tile_id = tile
        else:
            print("'tile' must be integer index or string identifier")
            return None

        if isinstance(bit, int):
            if bit < 0 or bit >= len(self._bit_ids):
                print("Set bit index >=0 and <" + str(len(self._bit_ids)))
                return None
            else:
                bit_id = self._bit_ids[bit]
        elif isinstance(bit, str):
            if bit not in self._bit_ids:
                print("Set valid bit id")
                return None
            else:
                bit_id = bit
        else:
            print("'bit' must be integer index or string identifier")
            return None

        current_local_zarr_path = str(
            self._readouts_root_path
            / Path(tile_id)
            / Path(bit_id)
            / Path(f"{self.feature_predictor_folder_name}_data")
        )

        image_path = self._image_store_path(current_local_zarr_path)
        if not image_path.exists():
            print("feature_predictor prediction image not found.")
            return None

        try:
            feature_predictor_image = self._load_from_zarr_array(
                image_path, return_future
            )
            return feature_predictor_image
        except (OSError, ValueError) as e:
            print(e)
            print("Error loading feature_predictor image.")
            return None

    def save_local_feature_predictor_image(
        self,
        feature_predictor_image: ArrayLike,
        tile: int | str,
        bit: int | str,
        return_future: bool | None = False,
    ) -> "WriteFutures | None":
        """Save feature_predictor prediction image.

        Parameters
        ----------
        feature_predictor_image : ArrayLike
            feature_predictor prediction image.
        tile : int or str
            Tile index or tile id.
        bit : int or str
            Bit index or bit id.
        return_future : bool or None
            Return the completed TensorStore write handle when True. Writes
            finish before associated metadata is reported as saved.

        Returns
        -------
        tensorstore.WriteFutures or None
            Completed pixel-write handle when return_future is True; otherwise
            None. Invalid tile/round/bit selections also return None.
        """
        if isinstance(tile, int):
            if tile < 0 or tile >= self._num_tiles:
                print("Set tile index >=0 and <" + str(self._num_tiles))
                return None
            else:
                tile_id = self._tile_ids[tile]
        elif isinstance(tile, str):
            if tile not in self._tile_ids:
                print("set valid tiled id")
                return None
            else:
                tile_id = tile
        else:
            print("'tile' must be integer index or string identifier")
            return None

        if isinstance(bit, int):
            if bit < 0 or bit >= len(self._bit_ids):
                print("Set bit index >=0 and <" + str(len(self._bit_ids)))
                return None
            else:
                local_id = self._bit_ids[bit]
        elif isinstance(bit, str):
            if bit not in self._bit_ids:
                print("Set valid bit id")
                return None
            else:
                local_id = bit
        else:
            print("'bit' must be integer index or string identifier")
            return None
        entity_root = self._readouts_root_path / Path(tile_id) / Path(local_id)
        current_local_zarr_path = entity_root / Path(
            f"{self.feature_predictor_folder_name}_data"
        )

        try:
            self._validate_core_image_shape(
                entity_root_path=entity_root,
                image_name=f"{self.feature_predictor_folder_name}_data",
                image=feature_predictor_image,
            )
            stage_position = self._resolve_original_tile_position_zyx_um(
                tile_id=tile_id, bit_id=local_id
            )
            attributes = self._load_entity_attributes(entity_root)
            write_future = self._save_to_zarr_array(
                feature_predictor_image,
                current_local_zarr_path,
                return_future,
                ome_scale=self.voxel_size_zyx_um,
                ome_translation=stage_position,
                extra_attributes=attributes,
            )
            if write_future is not None:
                write_future.result()
            self._save_entity_attributes(
                entity_root_path=entity_root, updates=attributes
            )
            return write_future
        except (OSError, ValueError) as e:
            print(e)
            print("Error saving feature_predictor image.")
            raise

    def load_local_feature_predictor_spots(
        self,
        tile: int | str,
        bit: int | str,
    ) -> pd.DataFrame | None:
        """Load feature_predictor spot localizations and features for one tile.

        Parameters
        ----------
        tile : int or str
            Tile index or tile id.
        bit : int or str
            Bit index or bit id.

        Returns
        -------
        feature_predictor_localizations : pandas.DataFrame or None
            feature_predictor localizations and features for one tile.
        """
        if isinstance(tile, int):
            if tile < 0 or tile >= self._num_tiles:
                print("Set tile index >=0 and <" + str(self._num_tiles))
                return None
            else:
                tile_id = self._tile_ids[tile]
        elif isinstance(tile, str):
            if tile not in self._tile_ids:
                print("set valid tiled id")
                return None
            else:
                tile_id = tile
        else:
            print("'tile' must be integer index or string identifier")
            return None

        if isinstance(bit, int):
            if bit < 0 or bit >= len(self._bit_ids):
                print("Set bit index >=0 and <" + str(len(self._bit_ids)))
                return None
            else:
                bit_id = self._bit_ids[bit]
        elif isinstance(bit, str):
            if bit not in self._bit_ids:
                print("Set valid bit id")
                return None
            else:
                bit_id = bit
        else:
            print("'bit' must be integer index or string identifier")
            return None

        current_feature_predictor_localizations_path = (
            self._feature_predictor_localizations_root_path
            / Path(tile_id)
            / Path(bit_id + ".parquet")
        )

        if not current_feature_predictor_localizations_path.exists():
            print("feature_predictor localizations not found.")
            return None
        else:
            feature_predictor_localizations = self._load_from_parquet(
                current_feature_predictor_localizations_path
            )
            return feature_predictor_localizations

    def save_local_feature_predictor_spots(
        self,
        spot_df: pd.DataFrame,
        tile: int | str,
        bit: int | str,
    ) -> None:
        """Save feature_predictor localizations and features.

        Parameters
        ----------
        spot_df : pd.DataFrame
            feature_predictor localizations and features.
        tile : int or str
            Tile index or tile id.
        bit : int or str
            Bit index or bit id.
        """
        if isinstance(tile, int):
            if tile < 0 or tile >= self._num_tiles:
                print("Set tile index >=0 and <" + str(self._num_tiles))
                return None
            else:
                tile_id = self._tile_ids[tile]
        elif isinstance(tile, str):
            if tile not in self._tile_ids:
                print("set valid tiled id")
                return None
            else:
                tile_id = tile
        else:
            print("'tile' must be integer index or string identifier")
            return None

        if isinstance(bit, int):
            if bit < 0 or bit >= len(self._bit_ids):
                print("Set bit index >=0 and <" + str(len(self._bit_ids)))
                return None
            else:
                bit_id = self._bit_ids[bit]
        elif isinstance(bit, str):
            if bit not in self._bit_ids:
                print("Set valid bit id")
                return None
            else:
                bit_id = bit
        else:
            print("'bit' must be integer index or string identifier")
            return None

        tile_localizations_path = (
            self._feature_predictor_localizations_root_path / Path(tile_id)
        )
        tile_localizations_path.mkdir(parents=True, exist_ok=True)

        current_feature_predictor_localizations_path = tile_localizations_path / Path(
            bit_id + ".parquet"
        )

        try:
            self._save_to_parquet(spot_df, current_feature_predictor_localizations_path)
        except OSError as e:
            print(e)
            print("Error saving feature_predictor localizations.")
            return None

    def load_global_coord_xforms_um(
        self,
        tile: int | str,
    ) -> tuple[ArrayLike | None, ArrayLike | None, ArrayLike | None] | None:
        """Load global registration transform for one tile.

        Parameters
        ----------
        tile : int or str
            Tile index or tile id.

        Returns
        -------
        affine_zyx_um : ArrayLike or None
            Global affine registration transform for one tile.
        origin_zyx_um : ArrayLike or None
            Global origin registration transform for one tile.
        spacing_zyx_um : ArrayLike or None
            Global spacing registration transform for one tile.
        """
        if isinstance(tile, int):
            if tile < 0 or tile >= self._num_tiles:
                print("Set tile index >=0 and <" + str(self._num_tiles))
                return None, None, None
            else:
                tile_id = self._tile_ids[tile]
        elif isinstance(tile, str):
            if tile not in self._tile_ids:
                print("set valid tiled id")
                return None, None, None
            else:
                tile_id = tile
        else:
            print("'tile' must be integer index or string identifier")
            return None

        try:
            entity_root = (
                self._fiducial_root_path / Path(tile_id) / Path(self._round_ids[0])
            )
            attributes = self._load_entity_attributes(entity_root)
            affine_zyx_um = np.asarray(attributes["affine_zyx_um"], dtype=np.float32)
            origin_zyx_um = np.asarray(attributes["origin_zyx_um"], dtype=np.float32)
            spacing_zyx_um = round_spacing_um(attributes["spacing_zyx_um"])
            return (affine_zyx_um, origin_zyx_um, spacing_zyx_um)
        except (FileNotFoundError, json.JSONDecodeError, KeyError):
            print(tile_id, self._round_ids[0])
            print("Global coordinate transforms not found")
            return None, None, None

    def save_global_coord_xforms_um(
        self,
        affine_zyx_um: ArrayLike,
        origin_zyx_um: ArrayLike,
        spacing_zyx_um: ArrayLike,
        tile: int | str,
    ) -> None:
        """Save global registration transform for one tile.

        Parameters
        ----------
        affine_zyx_um : ArrayLike
            Final 4x4 registration correction in physical Z, Y, X coordinates,
            applied after the separately stored camera-to-stage transform.
        origin_zyx_um : ArrayLike
            Native image origin in Z, Y, X micrometers, before camera mapping.
        spacing_zyx_um : ArrayLike
            Native Z, Y, X voxel spacing in micrometers.
        tile : int or str
            Tile index or tile id.
        """
        if isinstance(tile, int):
            if tile < 0 or tile >= self._num_tiles:
                print("Set tile index >=0 and <" + str(self._num_tiles))
                return None
            else:
                tile_id = self._tile_ids[tile]
        elif isinstance(tile, str):
            if tile not in self._tile_ids:
                print("set valid tiled id")
                return None
            else:
                tile_id = tile
        else:
            print("'tile' must be integer index or string identifier")
            return None

        try:
            entity_root = (
                self._fiducial_root_path / Path(tile_id) / Path(self._round_ids[0])
            )
            self._save_entity_attributes(
                entity_root_path=entity_root,
                updates={
                    "affine_zyx_um": np.asarray(
                        affine_zyx_um, dtype=np.float32
                    ).tolist(),
                    "origin_zyx_um": np.asarray(
                        origin_zyx_um, dtype=np.float32
                    ).tolist(),
                    "spacing_zyx_um": round_spacing_um(spacing_zyx_um).tolist(),
                },
            )
        except (FileNotFoundError, json.JSONDecodeError, TypeError, ValueError) as e:
            print(e)
            print("Could not save global coordinate transforms.")

    def load_global_fiducial_image(
        self,
        return_future: bool | None = True,
    ) -> "tuple[np.ndarray | Future | TensorStore, ArrayLike, ArrayLike, ArrayLike] | None":
        """Load downsampled, fused fiducial image.

        Parameters
        ----------
        return_future : bool or None
            True returns a read future, False returns a NumPy array, and None
            returns a sliceable TensorStore handle opened through yaozarrs.

        Returns
        -------
        fused_image : numpy.ndarray or tensorstore.Future or tensorstore.TensorStore or None
            Downsampled, fused fiducial image.
        affine_zyx_um : ArrayLike or None
            Global affine registration transform for fused image.
        origin_zyx_um : ArrayLike or None
            Global origin registration transform for fused image.
        spacing_zyx_um : ArrayLike or None
            Global spacing registration transform for fused image.
        """
        current_local_zarr_path = self._fused_root_path / Path(
            f"fused_{self.fiducial_folder_name}_zyx"
        )

        image_path = self._image_store_path(current_local_zarr_path)
        if not image_path.exists():
            print("Globally registered, fused image not found.")
            return None

        try:
            fused_image = self._load_from_zarr_array(image_path, return_future)
            attributes = self.load_image_metadata(image_path)
            affine_zyx_um = np.asarray(attributes["affine_zyx_um"], dtype=np.float32)
            origin_zyx_um = np.asarray(attributes["origin_zyx_um"], dtype=np.float32)
            spacing_zyx_um = round_spacing_um(attributes["spacing_zyx_um"])
            return fused_image, affine_zyx_um, origin_zyx_um, spacing_zyx_um
        except (OSError, ValueError, KeyError):
            print("Error loading globally registered, fused image.")
            return None

    def save_global_fiducial_image(
        self,
        fused_image: ArrayLike,
        affine_zyx_um: ArrayLike,
        origin_zyx_um: ArrayLike,
        spacing_zyx_um: ArrayLike,
        fusion_type: str = "fiducial",
        return_future: bool | None = False,
    ) -> "WriteFutures | None":
        """Save downsampled, fused fiducial image.

        The caller selects the fusion grid. This method stores the supplied
        image and spacing without choosing a dataset-specific downsampling.

        Parameters
        ----------
        fused_image : ArrayLike
            Downsampled, fused fiducial image.
        affine_zyx_um : ArrayLike
            Global affine registration transform for fused image.
        origin_zyx_um : ArrayLike
            Global origin registration transform for fused image.
        spacing_zyx_um : ArrayLike
            Caller-selected fused voxel spacing in Z, Y, X microns.
        fusion_type : str
            Type of fusion (fiducial or all_channels).
        return_future : bool or None
            Return the completed TensorStore write handle when True. Writes
            finish before associated metadata is reported as saved.

        Returns
        -------
        tensorstore.WriteFutures or None
            Completed pixel-write handle when return_future is True; otherwise
            None.
        """
        if fusion_type == "fiducial":
            filename = f"fused_{self.fiducial_folder_name}_zyx"
        else:
            filename = "fused_all_channels_zyx"
        current_local_zarr_path = self._fused_root_path / Path(filename)

        metadata_attrs = {
            "affine_zyx_um": np.asarray(affine_zyx_um, dtype=np.float32).tolist(),
            "origin_zyx_um": np.asarray(origin_zyx_um, dtype=np.float32).tolist(),
            "spacing_zyx_um": round_spacing_um(spacing_zyx_um).tolist(),
        }
        fused_array = np.asarray(fused_image)
        try:
            write_future = self._save_to_zarr_array(
                fused_array.astype(np.uint16),
                current_local_zarr_path,
                return_future,
                ome_scale=metadata_attrs["spacing_zyx_um"],
                extra_attributes=metadata_attrs,
                chunks=self._fused_image_chunks(fused_array),
            )
            if write_future is not None:
                write_future.result()
            return write_future
        except (OSError, TimeoutError):
            print("Error saving fused image.")
            raise

    def load_local_decoded_spots(
        self,
        tile: int | str,
        decode_run_key: str | None = None,
    ) -> pd.DataFrame | None:
        """Load decoded spots and features for one tile.

        Parameters
        ----------
        tile : int or str
            Tile index or tile id.
        decode_run_key : str or None, default None
            Optional decoded-output run key.

        Returns
        -------
        tile_features : pandas.DataFrame or None
            Decoded spots and features for one tile.
        """
        if isinstance(tile, int):
            if tile < 0 or tile >= self._num_tiles:
                print("Set tile index >=0 and <" + str(self._num_tiles))
                return None
            else:
                tile_id = self._tile_ids[tile]
        elif isinstance(tile, str):
            if tile not in self._tile_ids:
                print("set valid tiled id")
                return None
            else:
                tile_id = tile
        else:
            print("'tile' must be integer index or string identifier")
            return None

        current_tile_features_path = self._decoded_run_root(decode_run_key) / Path(
            tile_id + "_decoded_features.parquet"
        )

        if not current_tile_features_path.exists():
            print("Decoded spots not found.")
            return None
        else:
            tile_features = self._load_from_parquet(current_tile_features_path)
            return tile_features

    def save_local_decoded_spots(
        self,
        features_df: pd.DataFrame,
        tile: int | str,
        decode_run_key: str | None = None,
    ) -> None:
        """Save decoded spots and features for one tile.

        Parameters
        ----------
        features_df : pd.DataFrame
            Decoded spots and features for one tile.
        tile : int or str
            Tile index or tile id.
        decode_run_key : str or None, default None
            Optional decoded-output run key.
        """
        if isinstance(tile, int):
            if tile < 0 or tile >= self._num_tiles:
                print("Set tile index >=0 and <" + str(self._num_tiles))
                return None
            else:
                tile_id = self._tile_ids[tile]
        elif isinstance(tile, str):
            if tile not in self._tile_ids:
                print("set valid tiled id")
                return None
            else:
                tile_id = tile
        else:
            print("'tile' must be integer index or string identifier")
            return None

        decoded_root_path = self._decoded_run_root(decode_run_key)
        decoded_root_path.mkdir(parents=True, exist_ok=True)
        current_tile_features_path = decoded_root_path / Path(
            tile_id + "_decoded_features.parquet"
        )

        self._save_to_parquet(features_df, current_tile_features_path)

    def load_global_filtered_decoded_spots(
        self,
        decode_run_key: str | None = None,
        gene_ids: Collection[str] | None = None,
        columns: Collection[str] | None = None,
    ) -> pd.DataFrame | None:
        """Load all decoded and filtered spots.

        Parameters
        ----------
        decode_run_key : str or None, default None
            Optional decoded-output run key.
        gene_ids : Collection[str] or None, default None
            Optional gene ids to load.
        columns : Collection[str] or None, default None
            Optional columns to load.

        Returns
        -------
        all_tiles_filtered : pandas.DataFrame or None
            All decoded and filtered spots.
        """
        current_global_filtered_decoded_dir_path = self._global_filtered_decoded_root(
            decode_run_key
        )
        current_global_filtered_decoded_path = (
            current_global_filtered_decoded_dir_path / Path("decoded_features.parquet")
        )

        if not current_global_filtered_decoded_path.exists():
            print("Global, filtered, decoded spots not found.")
            return None
        elif gene_ids is not None or columns is not None:
            selected_gene_ids = (
                [str(gene_id) for gene_id in gene_ids] if gene_ids is not None else []
            )
            filters = (
                [("gene_id", "in", selected_gene_ids)] if gene_ids is not None else None
            )
            all_tiles_filtered = pd.read_parquet(
                current_global_filtered_decoded_path,
                columns=None if columns is None else list(columns),
                filters=filters,
            )
            if gene_ids is not None and "gene_id" in all_tiles_filtered.columns:
                all_tiles_filtered = all_tiles_filtered[
                    all_tiles_filtered["gene_id"].astype(str).isin(selected_gene_ids)
                ]
            return all_tiles_filtered
        else:
            all_tiles_filtered = self._load_from_parquet(
                current_global_filtered_decoded_path
            )
            return all_tiles_filtered

    def save_global_filtered_decoded_spots(
        self,
        filtered_decoded_df: pd.DataFrame,
        decode_run_key: str | None = None,
    ) -> None:
        """Save all decoded and filtered spots.

        Parameters
        ----------
        filtered_decoded_df : pd.DataFrame
            All decoded and filtered spots.
        decode_run_key : str or None, default None
            Optional decoded-output run key.
        """
        current_global_filtered_decoded_dir_path = self._global_filtered_decoded_root(
            decode_run_key
        )

        if not current_global_filtered_decoded_dir_path.exists():
            current_global_filtered_decoded_dir_path.mkdir(parents=True)

        current_global_filtered_decoded_path = (
            current_global_filtered_decoded_dir_path / Path("decoded_features.parquet")
        )
        current_global_filtered_decoded_csv_gz_path = (
            current_global_filtered_decoded_dir_path / Path("decoded_features.csv.gz")
        )

        self._save_to_parquet(filtered_decoded_df, current_global_filtered_decoded_path)
        self._save_to_csv_gz(
            filtered_decoded_df, current_global_filtered_decoded_csv_gz_path
        )

    def load_global_cellpose_outlines(
        self,
    ) -> dict | None:
        """Load Cellpose max projection cell outlines.

        Returns
        -------
        cellpose_outlines : dict or None
            Cellpose cell mask outlines.
        """
        current_cellpose_outlines_path = (
            self._segmentation_root_path / Path("cellpose") / Path("cell_outlines.json")
        )

        if not current_cellpose_outlines_path.exists():
            print("Cellpose cell mask outlines not found.")
            return None
        else:
            cellpose_outlines = self._load_from_microjson(
                current_cellpose_outlines_path
            )
            return cellpose_outlines

    def load_global_cellpose_roi_zip(
        self,
    ) -> dict[int, ArrayLike] | None:
        """Load global Cellpose outlines from an ImageJ ROI zip.

        Returns
        -------
        cellpose_outlines : dict[int, ArrayLike] or None
            Cellpose ROI outlines with global X, Y coordinates.
        """
        roi_path = (
            self._segmentation_root_path
            / Path("cellpose")
            / Path("imagej_rois")
            / Path("global_coords_rois.zip")
        )
        if not roi_path.exists():
            print("Cellpose global ROI zip not found.")
            return None

        try:
            from roifile import roiread
        except ImportError:
            print("roifile is required to load Cellpose ROI zip.")
            return None

        outlines: dict[int, ArrayLike] = {}
        try:
            for idx, roi in enumerate(roiread(roi_path)):
                coordinates = getattr(roi, "subpixel_coordinates", None)
                if coordinates is None:
                    coordinates = roi.coordinates()
                if coordinates is not None:
                    outlines[idx + 1] = np.asarray(coordinates, dtype=float)
            return outlines
        except (OSError, ValueError) as exc:
            print(exc)
            print("Error loading Cellpose ROI zip.")
            return None

    def _proseg_3d_root(self) -> Path:
        """
        Return the root path for Proseg 3D outputs.

        Returns
        -------
        Path
            Proseg 3D output root.
        """
        return self._datastore_path / Path("proseg") / Path("3D")

    def _proseg_3d_run_root(self, run_name: str | None = None) -> Path:
        """
        Return one Proseg 3D run root path.

        Parameters
        ----------
        run_name : str or None, default None
            Proseg run name. ``None`` or ``"default"`` selects ``proseg/3D``.

        Returns
        -------
        Path
            Proseg run root path.
        """
        proseg_root = self._proseg_3d_root()
        if run_name is None or run_name == "default":
            return proseg_root
        return proseg_root / Path(run_name)

    def list_proseg_3d_runs(self) -> list[str]:
        """List available Proseg 3D output runs.

        Returns
        -------
        proseg_runs : list[str]
            Available Proseg 3D run names. The direct ``proseg/3D`` output is
            named ``"default"``.
        """
        proseg_root = self._proseg_3d_root()
        if not proseg_root.exists():
            return []

        run_names: list[str] = []
        candidate_roots = [proseg_root]
        candidate_roots.extend(
            path for path in sorted(proseg_root.iterdir()) if path.is_dir()
        )
        for root in candidate_roots:
            transcript_path = root / Path("transcript_metadata_3D.csv.gz")
            polygon_path = root / Path("cell_polygons_3D.geojson.gz")
            if transcript_path.exists() and polygon_path.exists():
                run_names.append("default" if root == proseg_root else root.name)
        return sorted(run_names)

    def load_proseg_transcripts_3d(
        self,
        run_name: str | None = None,
    ) -> pd.DataFrame | None:
        """Load Proseg 3D transcript metadata.

        Parameters
        ----------
        run_name : str or None, default None
            Proseg run name. ``None`` or ``"default"`` selects ``proseg/3D``.

        Returns
        -------
        transcripts : pandas.DataFrame or None
            Proseg transcript metadata.
        """
        transcript_path = self._proseg_3d_run_root(run_name) / Path(
            "transcript_metadata_3D.csv.gz"
        )
        if not transcript_path.exists():
            print("Proseg transcript metadata not found.")
            return None
        try:
            return pd.read_csv(transcript_path, compression="gzip")
        except (OSError, ValueError) as exc:
            print(exc)
            print("Error loading Proseg transcript metadata.")
            return None

    def load_proseg_cell_polygons_3d(
        self,
        run_name: str | None = None,
    ) -> dict[Any, ArrayLike] | None:
        """Load Proseg 3D refined cell polygons.

        Parameters
        ----------
        run_name : str or None, default None
            Proseg run name. ``None`` or ``"default"`` selects ``proseg/3D``.

        Returns
        -------
        polygons : dict[Any, ArrayLike] or None
            Cell identifiers mapped to polygon vertices in X, Y order.
        """
        polygon_path = self._proseg_3d_run_root(run_name) / Path(
            "cell_polygons_3D.geojson.gz"
        )
        if not polygon_path.exists():
            print("Proseg cell polygons not found.")
            return None

        try:
            with gzip.open(polygon_path, "rt", encoding="utf-8") as file:
                geojson = json.load(file)
        except (OSError, json.JSONDecodeError) as exc:
            print(exc)
            print("Error loading Proseg cell polygons.")
            return None

        polygons: dict[Any, ArrayLike] = {}
        for idx, feature in enumerate(geojson.get("features", [])):
            properties = feature.get("properties", {})
            cell_id = properties.get("cell", idx)
            geometry = feature.get("geometry", {})
            coordinates = geometry.get("coordinates", [])
            rings: list[np.ndarray] = []
            if geometry.get("type") == "Polygon":
                rings.extend(np.asarray(ring, dtype=float) for ring in coordinates)
            elif geometry.get("type") == "MultiPolygon":
                for polygon in coordinates:
                    rings.extend(np.asarray(ring, dtype=float) for ring in polygon)
            if rings:
                polygons[cell_id] = max(rings, key=len)

        return polygons

    def baysor_3d_available(self) -> bool:
        """Return whether Baysor 3D molecules and cell boundaries are present."""
        baysor_root = self._segmentation_root_path / Path("baysor") / Path("3D")
        return (baysor_root / Path("molecules.parquet")).exists() and (
            baysor_root / Path("cell_boundaries_3d.parquet")
        ).exists()

    def load_baysor_molecules_3d(self) -> pd.DataFrame | None:
        """
        Load Baysor 3D molecule assignments.

        Returns
        -------
        pandas.DataFrame or None
            Baysor molecule table, if present.
        """
        molecules_path = (
            self._segmentation_root_path
            / Path("baysor")
            / Path("3D")
            / Path("molecules.parquet")
        )
        if not molecules_path.exists():
            print("Baysor molecules not found.")
            return None
        try:
            return self._load_from_parquet(molecules_path)
        except (OSError, ValueError) as exc:
            print(exc)
            print("Error loading Baysor molecules.")
            return None

    def load_baysor_cell_boundaries_3d(self) -> pd.DataFrame | None:
        """
        Load Baysor 3D cell boundary polygons.

        Returns
        -------
        pandas.DataFrame or None
            Baysor cell boundary table, if present.
        """
        boundaries_path = (
            self._segmentation_root_path
            / Path("baysor")
            / Path("3D")
            / Path("cell_boundaries_3d.parquet")
        )
        if not boundaries_path.exists():
            print("Baysor cell boundaries not found.")
            return None
        try:
            return self._load_from_parquet(boundaries_path)
        except (OSError, ValueError) as exc:
            print(exc)
            print("Error loading Baysor cell boundaries.")
            return None

    def load_global_cellpose_segmentation_image(
        self,
        return_future: bool | None = True,
    ) -> "np.ndarray | Future | TensorStore | None":
        """Load Cellpose max projection, downsampled segmentation image.

        Parameters
        ----------
        return_future : bool or None
            True returns a read future, False returns a NumPy array, and None
            returns a sliceable TensorStore handle opened through yaozarrs.

        Returns
        -------
        fused_image : numpy.ndarray or tensorstore.Future or tensorstore.TensorStore or None
            Cellpose max projection, downsampled segmentation image.
        """
        current_local_zarr_path = (
            self._segmentation_root_path
            / Path("cellpose")
            / Path(f"masks_{self.fiducial_folder_name}_iso_zyx")
        )

        image_path = self._image_store_path(current_local_zarr_path)
        if not image_path.exists():
            print("Cellpose prediction on global fused image not found.")
            return None

        try:
            fused_image = self._load_from_zarr_array(image_path, return_future)
            return fused_image
        except (OSError, ValueError):
            print("Error loading Cellpose image.")
            return None

    def save_global_cellpose_segmentation_image(
        self,
        cellpose_image: ArrayLike,
        downsampling: Sequence[float],
        return_future: bool | None = False,
    ) -> "WriteFutures | None":
        """Save Cellpose max projection, downsampled segmentation image.

        The caller runs segmentation and selects its image grid. This method
        stores the supplied labels unchanged and derives their physical scale
        from the native voxel calibration and supplied downsampling factors.

        Parameters
        ----------
        cellpose_image : ArrayLike
            Cellpose max projection, downsampled segmentation image.
        downsampling : Sequence[float]
            Caller-selected Z, Y, X factors: segmentation spacing divided by
            native voxel spacing. Two-dimensional masks use the resulting YX
            physical scale while retaining all three factors in metadata.
        return_future : bool or None
            Return the completed TensorStore write handle when True. Writes
            finish before associated metadata is reported as saved.

        Returns
        -------
        tensorstore.WriteFutures or None
            Completed pixel-write handle when return_future is True; otherwise
            None.
        """
        current_local_zarr_path = (
            self._segmentation_root_path
            / Path("cellpose")
            / Path(f"masks_{self.fiducial_folder_name}_iso_zyx")
        )

        downsampling = np.asarray(downsampling, dtype=np.float64)
        if (
            downsampling.shape != (3,)
            or not np.all(np.isfinite(downsampling))
            or np.any(downsampling <= 0)
        ):
            raise ValueError(
                "Downsampling must contain three positive finite Z, Y, X factors."
            )
        spacing = round_spacing_um(self.voxel_size_zyx_um) * downsampling
        attributes = {"downsampling": downsampling.tolist()}

        try:
            write_future = self._save_to_zarr_array(
                cellpose_image,
                current_local_zarr_path,
                return_future,
                ome_scale=round_spacing_um(spacing).tolist(),
                extra_attributes=attributes,
            )
            if write_future is not None:
                write_future.result()
            return write_future
        except (OSError, TimeoutError):
            print("Error saving Cellpose image.")
            raise

`binning` `property` `writable`

Camera binning.

Returns:

Name	Type	Description
`binning`	`int`	Camera binning.

`bit_ids` `property`

Bit IDs.

Returns:

Name	Type	Description
`bit_ids`	`Collection[str]`	Bit IDs.

`camera_model` `property` `writable`

Camera model.

Returns:

Name	Type	Description
`camera_model`	`str or None`	Camera model.

`channel_psfs` `property` `writable`

Channel point spread functions (PSF).

Returns:

Name	Type	Description
`channel_psfs`	`ArrayLike`	Channel point spread functions (PSF).

`channel_shading_maps` `property` `writable`

Channel shaiding images.

Returns:

Name	Type	Description
`channel_shading_maps`	`ArrayLike`	Channel shading images.

`channels_in_data` `property` `writable`

Channel indices.

Returns:

Name	Type	Description
`channels_in_data`	`Collection[int]`	Channel indices.

`codebook` `property` `writable`

Codebook.

Returns:

Name	Type	Description
`codebook`	`DataFrame`	Codebook.

`datastore_path` `property`

Experiment datastore directory.

`datastore_state` `property` `writable`

Datastore state.

Returns:

Name	Type	Description
`datastore_state`	`dict or None`	Datastore state.

`e_per_ADU` `property` `writable`

Electrons per camera ADU.

Returns:

Name	Type	Description
`e_per_ADU`	`float`	Electrons per camera ADU.

`experiment_order` `property` `writable`

Round and bit order.

Returns:

Name	Type	Description
`experiment_order`	`DataFrame`	Round and bit order.

`global_background_vector` `property` `writable`

Global background vector.

Returns:

Name	Type	Description
`global_background_vector`	`ArrayLike`	Global background vector.

`global_normalization_vector` `property` `writable`

Global normalization vector.

Returns:

Name	Type	Description
`global_normalization_vector`	`ArrayLike`	Global normalization vector.

`iterative_background_vector` `property` `writable`

Iterative background vector.

Returns:

Name	Type	Description
`iterative_background_vector`	`ArrayLike`	Iterative background vector.

`iterative_normalization_vector` `property` `writable`

Iterative normalization vector.

Returns:

Name	Type	Description
`iterative_normalization_vector`	`ArrayLike`	Iterative normalization vector.

`microscope_type` `property` `writable`

Microscope type.

Returns:

Name	Type	Description
`microscope_type`	`str or None`	Microscope type.

`na` `property` `writable`

Detection objective numerical aperture (NA).

Returns:

Name	Type	Description
`na`	`float`	Detection objective numerical aperture (NA).

`noise_map` `property` `writable`

Camera noise image.

Returns:

Name	Type	Description
`noise_map`	`ArrayLike`	Camera noise image.

`num_bits` `property` `writable`

Number of bits.

Returns:

Name	Type	Description
`num_bits`	`int`	Number of bits.

`num_rounds` `property` `writable`

Number of rounds.

Returns:

Name	Type	Description
`num_rounds`	`int`	Number of rounds.

`num_tiles` `property` `writable`

Number of tiles.

Returns:

Name	Type	Description
`num_tiles`	`int`	Number of tiles.

`ri` `property` `writable`

Detection objective refractive index (RI).

Returns:

Name	Type	Description
`ri`	`float`	Detection objective refractive index (RI).

`round_ids` `property`

Round IDs.

Returns:

Name	Type	Description
`round_ids`	`Collection[str]`	Round IDs.

`tile_ids` `property`

Tile IDs.

Returns:

Name	Type	Description
`tile_ids`	`Collection[str]`	Tile IDs.

`tile_overlap` `property` `writable`

XY tile overlap.

Returns:

Name	Type	Description
`tile_overlap`	`float`	XY tile overlap.

`voxel_size_zyx_um` `property` `writable`

Voxel size, zyx order (microns).

Returns:

Name	Type	Description
`voxel_size_zyx_um`	`ArrayLike`	Voxel size, zyx order (microns).

`init(datastore_path, validate=True)`

Initialize a qi2lab datastore handle.

Parameters:

Name	Type	Description	Default
`datastore_path`	`str \| Path`	Datastore root path.	required
`validate`	`bool`	Whether to validate existing image arrays while parsing the store.	`True`

Source code in src/merfish3danalysis/qi2labDataStore.py

def __init__(self, datastore_path: str | Path, validate: bool = True) -> None:
    """
    Initialize a qi2lab datastore handle.

    Parameters
    ----------
    datastore_path : str | Path
        Datastore root path.
    validate : bool
        Whether to validate existing image arrays while parsing the store.
    """
    self._datastore_path = Path(datastore_path)
    if self._datastore_path.exists():
        self._parse_datastore(validate=validate)
    else:
        self._init_datastore()

`_build_axes(v05, ndim)` `staticmethod`

Build NGFF axes models for a given dimensionality.

Parameters:

Name	Type	Description	Default
`v05`	`Any`	yaozarrs NGFF model namespace.	required
`ndim`	`int`	Number of array dimensions.	required

Returns:

Type	Description
`list[Any]`	NGFF axis models ordered to match array dimensions.

Source code in src/merfish3danalysis/qi2labDataStore.py

@staticmethod
def _build_axes(v05: Any, ndim: int) -> list[Any]:
    """
    Build NGFF axes models for a given dimensionality.

    Parameters
    ----------
    v05 : Any
        yaozarrs NGFF model namespace.
    ndim : int
        Number of array dimensions.

    Returns
    -------
    list[Any]
        NGFF axis models ordered to match array dimensions.
    """
    axis_names = ["t", "c", "z", "y", "x"][-ndim:]
    axes: list[Any] = []
    for axis_name in axis_names:
        if axis_name in {"z", "y", "x"}:
            axes.append(v05.SpaceAxis(name=axis_name, unit="micrometer"))
        elif axis_name == "c":
            axes.append(v05.ChannelAxis(name="c"))
        else:
            axes.append(v05.TimeAxis(name="t", unit="second"))
    return axes

`_calibrations_attributes_path()`

Path to calibrations metadata sidecar.

Returns:

Type	Description
`Path`	Path to `calibrations/attributes.json`.

Source code in src/merfish3danalysis/qi2labDataStore.py

def _calibrations_attributes_path(self) -> Path:
    """
    Path to calibrations metadata sidecar.

    Returns
    -------
    Path
        Path to ``calibrations/attributes.json``.
    """
    return self._calibrations_zarr_path / Path("attributes.json")

`_check_for_zarr_array(image_path)` `staticmethod`

Check if image exists and is readable via yaozarrs.

Parameters:

Name	Type	Description	Default
`image_path`	`Path or str`	Image store path.	required

Source code in src/merfish3danalysis/qi2labDataStore.py

@staticmethod
def _check_for_zarr_array(image_path: Path | str) -> None:
    """Check if image exists and is readable via yaozarrs.

    Parameters
    ----------
    image_path : Path or str
        Image store path.
    """
    image_path = qi2labDataStore._image_store_path(image_path)
    if not image_path.exists():
        raise FileNotFoundError(image_path)

    group = open_group(str(image_path))
    _ = group["0"]

`_coerce_experiment_order_dataframe(value)`

Normalize experiment order into the canonical DataFrame form.

Parameters:

Name	Type	Description	Default
`value`	`ArrayLike \| DataFrame`	Experiment order table or array to normalize.	required

Returns:

Type	Description
`DataFrame`	Experiment order as a DataFrame with channel columns.

Source code in src/merfish3danalysis/qi2labDataStore.py

def _coerce_experiment_order_dataframe(
    self, value: ArrayLike | pd.DataFrame
) -> pd.DataFrame:
    """
    Normalize experiment order into the canonical DataFrame form.

    Parameters
    ----------
    value : ArrayLike | pd.DataFrame
        Experiment order table or array to normalize.

    Returns
    -------
    pd.DataFrame
        Experiment order as a DataFrame with channel columns.
    """
    if isinstance(value, pd.DataFrame):
        return value

    channel_list = [str(channel) for channel in self._channels_in_data]
    return pd.DataFrame(value, columns=channel_list, dtype="int64")

`_collect_strict_ids(parent, prefix, width)` `classmethod`

Collect and sort strict identifiers under a folder.

Parameters:

Name	Type	Description	Default
`parent`	`Path`	Folder containing identifier-named child directories.	required
`prefix`	`str`	Required identifier prefix.	required
`width`	`int`	Required number of zero-padded digits.	required

Returns:

Type	Description
`list[str]`	Strict identifiers sorted by numeric value.

Source code in src/merfish3danalysis/qi2labDataStore.py

@classmethod
def _collect_strict_ids(cls, parent: Path, prefix: str, width: int) -> list[str]:
    """
    Collect and sort strict identifiers under a folder.

    Parameters
    ----------
    parent : Path
        Folder containing identifier-named child directories.
    prefix : str
        Required identifier prefix.
    width : int
        Required number of zero-padded digits.

    Returns
    -------
    list[str]
        Strict identifiers sorted by numeric value.
    """

    def sort_id(value: str) -> tuple[int, int, str]:
        """
        Return the strict identifier sort key.

        Parameters
        ----------
        value : str
            Identifier string.

        Returns
        -------
        tuple[int, int, str]
            Numeric and lexical sort key.
        """
        return cls._strict_id_sort_key(value, prefix, width)

    ids = [entry.name for entry in parent.iterdir() if entry.is_dir()]
    ids.sort(key=sort_id)
    return ids

`_create_array_tensorstore_qi2lab(path, shape, dtype, chunks, *, shards, dimension_names, overwrite, compression)` `staticmethod`

Create a Zarr v3 array for the yaozarrs image writer.

yaozarrs accepts a custom array creator but does not expose compression level or shuffle settings. This TensorStore adapter preserves the datastore's Blosc level 5 and bitshuffle settings; yaozarrs handles the OME group, axes, and image metadata.

Parameters:

Name	Type	Description	Default
`path`	`Path`	Destination zarr array path.	required
`shape`	`tuple[int, ...]`	Array shape.	required
`dtype`	`Any`	Array dtype.	required
`chunks`	`tuple[int, ...]`	Chunk shape.	required
`shards`	`tuple[int, ...] \| None`	Optional shard shape.	required
`dimension_names`	`list[str] \| None`	Optional dimension names for metadata.	required
`overwrite`	`bool`	Whether to replace an existing array.	required
`compression`	`str`	Compression preset name.	required

Returns:

Type	Description
`Any`	Open tensorstore array handle.

Source code in src/merfish3danalysis/qi2labDataStore.py

@staticmethod
def _create_array_tensorstore_qi2lab(
    path: Path,
    shape: tuple[int, ...],
    dtype: Any,
    chunks: tuple[int, ...],
    *,
    shards: tuple[int, ...] | None,
    dimension_names: list[str] | None,
    overwrite: bool,
    compression: str,
) -> Any:
    """
    Create a Zarr v3 array for the yaozarrs image writer.

    yaozarrs accepts a custom array creator but does not expose compression
    level or shuffle settings. This TensorStore adapter preserves the
    datastore's Blosc level 5 and bitshuffle settings; yaozarrs handles
    the OME group, axes, and image metadata.

    Parameters
    ----------
    path : Path
        Destination zarr array path.
    shape : tuple[int, ...]
        Array shape.
    dtype : Any
        Array dtype.
    chunks : tuple[int, ...]
        Chunk shape.
    shards : tuple[int, ...] | None
        Optional shard shape.
    dimension_names : list[str] | None
        Optional dimension names for metadata.
    overwrite : bool
        Whether to replace an existing array.
    compression : str
        Compression preset name.

    Returns
    -------
    Any
        Open tensorstore array handle.
    """
    import tensorstore as ts

    if compression == "blosc-zstd":
        chunk_codecs = [
            {
                "name": "blosc",
                "configuration": {
                    "cname": "zstd",
                    "clevel": 5,
                    "shuffle": "bitshuffle",
                },
            }
        ]
    elif compression == "blosc-lz4":
        chunk_codecs = [
            {
                "name": "blosc",
                "configuration": {
                    "cname": "lz4",
                    "clevel": 5,
                    "shuffle": "bitshuffle",
                },
            }
        ]
    elif compression == "zstd":
        chunk_codecs = [{"name": "zstd", "configuration": {"level": 3}}]
    elif compression == "none":
        chunk_codecs = []
    else:
        raise ValueError(f"Unknown compression: {compression}")

    codecs = chunk_codecs
    chunk_layout: dict[str, Any] = {"chunk": {"shape": list(chunks)}}
    if shards is not None:
        codecs = [
            {
                "name": "sharding_indexed",
                "configuration": {
                    "chunk_shape": list(chunks),
                    "codecs": chunk_codecs,
                },
            }
        ]
        chunk_layout = {"write_chunk": {"shape": list(shards)}}

    domain: dict[str, Any] = {"shape": list(shape)}
    if dimension_names:
        domain["labels"] = dimension_names

    try:
        dtype_str = dtype.name
    except AttributeError:
        dtype_str = str(dtype)

    return ts.open(
        {
            "driver": "zarr3",
            "kvstore": {"driver": "file", "path": str(path)},
            "schema": {
                "dtype": dtype_str,
                "domain": domain,
                "chunk_layout": chunk_layout,
                "codec": {"driver": "zarr3", "codecs": codecs},
            },
            "create": True,
            "delete_existing": overwrite,
        }
    ).result()

`_decoded_run_root(decode_run_key=None)`

Return the local decoded output root for an optional decode run.

Parameters:

Name	Type	Description	Default
`decode_run_key`	`str or None`	Optional decoded-output run key.	`None`

Returns:

Type	Description
`Path`	Decoded output root.

Source code in src/merfish3danalysis/qi2labDataStore.py

def _decoded_run_root(self, decode_run_key: str | None = None) -> Path:
    """
    Return the local decoded output root for an optional decode run.

    Parameters
    ----------
    decode_run_key : str or None, default None
        Optional decoded-output run key.

    Returns
    -------
    pathlib.Path
        Decoded output root.
    """
    decode_run_key = self._validate_decode_run_key(decode_run_key)
    if decode_run_key is None:
        return self._decoded_root_path
    return self._decoded_root_path / Path(decode_run_key)

`_default_chunks(array, spatial_chunk_zyx=(16, 512, 512))` `staticmethod`

Create sane default chunk sizes based on dimensionality.

Parameters:

Name	Type	Description	Default
`array`	`ndarray`	Array that will be written.	required
`spatial_chunk_zyx`	`tuple[int, int, int]`	Desired Z, Y, X storage chunks for local fiducial and readout images.	`(16, 512, 512)`

Returns:

Type	Description
`list[int]`	Chunk shape matched to the array dimensionality.

Source code in src/merfish3danalysis/qi2labDataStore.py

@staticmethod
def _default_chunks(
    array: np.ndarray,
    spatial_chunk_zyx: tuple[int, int, int] = (16, 512, 512),
) -> list[int]:
    """
    Create sane default chunk sizes based on dimensionality.

    Parameters
    ----------
    array : np.ndarray
        Array that will be written.
    spatial_chunk_zyx : tuple[int, int, int], default=(16, 512, 512)
        Desired Z, Y, X storage chunks for local fiducial and readout images.

    Returns
    -------
    list[int]
        Chunk shape matched to the array dimensionality.
    """
    z_chunk, y_chunk, x_chunk = (int(value) for value in spatial_chunk_zyx)
    if array.ndim == 2:
        return [
            min(int(array.shape[0]), y_chunk),
            min(int(array.shape[1]), x_chunk),
        ]
    if array.ndim == 3:
        return [
            min(int(array.shape[0]), z_chunk),
            min(int(array.shape[1]), y_chunk),
            min(int(array.shape[2]), x_chunk),
        ]
    if array.ndim == 4:
        return [
            1,
            min(int(array.shape[1]), z_chunk),
            min(int(array.shape[2]), y_chunk),
            min(int(array.shape[3]), x_chunk),
        ]
    if array.ndim == 5:
        return [
            1,
            1,
            min(int(array.shape[2]), z_chunk),
            min(int(array.shape[3]), y_chunk),
            min(int(array.shape[4]), x_chunk),
        ]
    return list(array.shape)

`_entity_attributes_path(entity_root_path)` `staticmethod`

Path to per-entity metadata sidecar.

Parameters:

Name	Type	Description	Default
`entity_root_path`	`Path \| str`	Entity folder path.	required

Returns:

Type	Description
`Path`	Entity metadata sidecar path.

Source code in src/merfish3danalysis/qi2labDataStore.py

@staticmethod
def _entity_attributes_path(entity_root_path: Path | str) -> Path:
    """
    Path to per-entity metadata sidecar.

    Parameters
    ----------
    entity_root_path : Path | str
        Entity folder path.

    Returns
    -------
    Path
        Entity metadata sidecar path.
    """
    return Path(entity_root_path) / Path("attributes.json")

`_fused_image_chunks(array)` `staticmethod`

Create chunk sizes tailored for fused image storage.

Parameters:

Name	Type	Description	Default
`array`	`ndarray`	Fused image array that will be written.	required

Returns:

Type	Description
`list[int]`	Chunk shape for fused image storage.

Source code in src/merfish3danalysis/qi2labDataStore.py

@staticmethod
def _fused_image_chunks(array: np.ndarray) -> list[int]:
    """
    Create chunk sizes tailored for fused image storage.

    Parameters
    ----------
    array : np.ndarray
        Fused image array that will be written.

    Returns
    -------
    list[int]
        Chunk shape for fused image storage.
    """
    shape = [int(dim) for dim in array.shape]
    if array.ndim == 2:
        return [min(shape[0], 2048), min(shape[1], 2048)]
    if array.ndim == 3:
        return [min(shape[0], 16), min(shape[1], 512), min(shape[2], 512)]
    if array.ndim == 4:
        return [
            min(shape[0], 1),
            min(shape[1], 16),
            min(shape[2], 512),
            min(shape[3], 512),
        ]
    if array.ndim == 5:
        return [
            min(shape[0], 1),
            min(shape[1], 1),
            min(shape[2], 16),
            min(shape[3], 512),
            min(shape[4], 512),
        ]
    return list(array.shape)

`_global_filtered_decoded_root(decode_run_key=None)`

Return the global filtered decoded-output root for an optional decode run.

Parameters:

Name	Type	Description	Default
`decode_run_key`	`str or None`	Optional decoded-output run key.	`None`

Returns:

Type	Description
`Path`	Global filtered decoded-output root.

Source code in src/merfish3danalysis/qi2labDataStore.py

def _global_filtered_decoded_root(
    self,
    decode_run_key: str | None = None,
) -> Path:
    """
    Return the global filtered decoded-output root for an optional decode run.

    Parameters
    ----------
    decode_run_key : str or None, default None
        Optional decoded-output run key.

    Returns
    -------
    pathlib.Path
        Global filtered decoded-output root.
    """
    root = self._datastore_path / Path("all_tiles_filtered_decoded_features")
    decode_run_key = self._validate_decode_run_key(decode_run_key)
    if decode_run_key is None:
        return root
    return root / Path(decode_run_key)

`_image_store_path(image_path)` `staticmethod`

Normalize image path to the *.ome.zarr folder naming scheme.

Parameters:

Name	Type	Description	Default
`image_path`	`Path \| str`	Logical image path or OME-Zarr path.	required

Returns:

Type	Description
`Path`	Normalized path ending in `.ome.zarr`.

Source code in src/merfish3danalysis/qi2labDataStore.py

@staticmethod
def _image_store_path(image_path: Path | str) -> Path:
    """
    Normalize image path to the *.ome.zarr folder naming scheme.

    Parameters
    ----------
    image_path : Path | str
        Logical image path or OME-Zarr path.

    Returns
    -------
    Path
        Normalized path ending in ``.ome.zarr``.
    """
    path = Path(image_path)
    if path.name.endswith(".ome.zarr"):
        return path
    if path.name.endswith(".zarr"):
        raise ValueError(
            f"Invalid image store name '{path.name}'. Expected '.ome.zarr' suffix."
        )
    if path.suffixes:
        raise ValueError(
            f"Invalid image store name '{path.name}'. Use bare logical names or '.ome.zarr'."
        )
    return path.with_name(path.name + ".ome.zarr")

`_init_datastore()`

Initialize datastore.

Create directory structure and initialize datastore state.

Source code in src/merfish3danalysis/qi2labDataStore.py

def _init_datastore(self) -> None:
    """Initialize datastore.

    Create directory structure and initialize datastore state.
    """
    self._datastore_path.mkdir(parents=True)
    self._calibrations_zarr_path = self._datastore_path / Path(r"calibrations")
    self._calibrations_zarr_path.mkdir()
    self._save_to_json({}, self._calibrations_attributes_path())
    self.fiducial_folder_name = r"fiducial"
    self._fiducial_root_path = self._datastore_path / Path(
        self.fiducial_folder_name
    )
    self._fiducial_root_path.mkdir()
    self._readouts_root_path = self._datastore_path / Path(r"readouts")
    self._readouts_root_path.mkdir()
    self.feature_predictor_folder_name = r"feature_predictor"
    self._feature_predictor_localizations_root_path = self._datastore_path / Path(
        f"{self.feature_predictor_folder_name}_localizations"
    )
    self._feature_predictor_localizations_root_path.mkdir()
    self._decoded_root_path = self._datastore_path / Path(r"decoded")
    self._decoded_root_path.mkdir()
    self._fused_root_path = self._datastore_path / Path(r"fused")
    self._fused_root_path.mkdir()
    self._segmentation_root_path = self._datastore_path / Path(r"segmentation")
    self._segmentation_root_path.mkdir()

    # initialize datastore state
    self._datastore_state_json_path = self._datastore_path / Path(
        r"datastore_state.json"
    )
    self._datastore_state = {
        "Version": 0.6,
        "Initialized": True,
        "Calibrations": False,
        "Corrected": False,
        "LocalRegistered": False,
        "GlobalRegistered": False,
        "Fused": False,
        "SegmentedCells": False,
        "DecodedSpots": False,
        "FilteredSpots": False,
    }

    self._save_to_json(self._datastore_state, self._datastore_state_json_path)

`_load_calibrations_attributes()`

Load calibrations metadata sidecar.

Returns:

Type	Description
`dict[str, Any]`	Calibration metadata loaded from disk.

Source code in src/merfish3danalysis/qi2labDataStore.py

def _load_calibrations_attributes(self) -> dict[str, Any]:
    """
    Load calibrations metadata sidecar.

    Returns
    -------
    dict[str, Any]
        Calibration metadata loaded from disk.
    """
    attributes_path = self._calibrations_attributes_path()
    if not attributes_path.is_file():
        raise FileNotFoundError(
            f"Calibration attributes not found: {attributes_path}"
        )
    return self._load_from_json(attributes_path)

`_load_entity_attributes(entity_root_path, image_names=None)`

Load entity metadata from sidecar + image extra_attributes.

Parameters:

Name	Type	Description	Default
`entity_root_path`	`Path \| str`	Entity folder path.	required
`image_names`	`Sequence[str] \| None`	Optional image names whose extra attributes should be merged.	`None`

Returns:

Type	Description
`dict[str, Any]`	Merged entity metadata.

Source code in src/merfish3danalysis/qi2labDataStore.py

def _load_entity_attributes(
    self,
    entity_root_path: Path | str,
    image_names: Sequence[str] | None = None,
) -> dict[str, Any]:
    """
    Load entity metadata from sidecar + image extra_attributes.

    Parameters
    ----------
    entity_root_path : Path | str
        Entity folder path.
    image_names : Sequence[str] | None
        Optional image names whose extra attributes should be merged.

    Returns
    -------
    dict[str, Any]
        Merged entity metadata.
    """
    entity_root = Path(entity_root_path)
    merged: dict[str, Any] = {}

    default_images = (
        "corrected_data",
        "decon_data",
        f"{self.feature_predictor_folder_name}_data",
        "opticalflow_xform_px",
    )
    candidate_names = image_names if image_names is not None else default_images
    for image_name in candidate_names:
        image_path = self._image_store_path(entity_root / Path(image_name))
        if not image_path.exists():
            continue
        merged.update(self.load_image_metadata(image_path))

    merged.update(self._load_from_json(self._entity_attributes_path(entity_root)))

    return merged

`_load_from_json(dictionary_path)` `staticmethod`

Load json as dictionary.

Parameters:

Name	Type	Description	Default
`dictionary_path`	`Path or str`	Path to json file.	required

Returns:

Name	Type	Description
`dictionary`	`dict`	Dictionary from json file.

Source code in src/merfish3danalysis/qi2labDataStore.py

@staticmethod
def _load_from_json(dictionary_path: Path | str) -> dict:
    """Load json as dictionary.

    Parameters
    ----------
    dictionary_path : Path or str
        Path to json file.

    Returns
    -------
    dictionary : dict
        Dictionary from json file.
    """
    try:
        with open(dictionary_path) as f:
            dictionary = json.load(f)
    except FileNotFoundError:
        return {}
    if not isinstance(dictionary, dict):
        raise ValueError(f"Expected a JSON object in {dictionary_path}")
    return dictionary

`_load_from_microjson(dictionary_path)` `staticmethod`

Load cell outlines outlines microjson as dictionary.

Parameters:

Name	Type	Description	Default
`dictionary_path`	`Path or str`	Path to microjson file.	required

Returns:

Name	Type	Description
`outlines`	`dict`	Cell outlines dictionary.

Source code in src/merfish3danalysis/qi2labDataStore.py

@staticmethod
def _load_from_microjson(dictionary_path: Path | str) -> dict:
    """Load cell outlines outlines microjson as dictionary.

    Parameters
    ----------
    dictionary_path : Path or str
        Path to microjson file.

    Returns
    -------
    outlines : dict
        Cell outlines dictionary.
    """
    try:
        with open(dictionary_path) as f:
            data = json.load(f)
            outlines = {}
            for feature in data["features"]:
                cell_id = feature["properties"]["cell_id"]
                coordinates = feature["geometry"]["coordinates"][0]
                outlines[cell_id] = np.array(coordinates)
    except (
        FileNotFoundError,
        json.JSONDecodeError,
        KeyError,
        TypeError,
        ValueError,
    ):
        outlines = {}
    return outlines

`_load_from_parquet(parquet_path)` `staticmethod`

Load dataframe from parquet.

Parameters:

Name	Type	Description	Default
`parquet_path`	`Path or str`	Path to parquet file.	required

Returns:

Name	Type	Description
`df`	`DataFrame`	Dataframe from parquet file.

Source code in src/merfish3danalysis/qi2labDataStore.py

@staticmethod
def _load_from_parquet(parquet_path: Path | str) -> pd.DataFrame:
    """Load dataframe from parquet.

    Parameters
    ----------
    parquet_path : Path or str
        Path to parquet file.

    Returns
    -------
    df : pd.DataFrame
        Dataframe from parquet file.
    """
    return pd.read_parquet(parquet_path)

`_load_from_zarr_array(image_path, return_future=True)` `staticmethod`

Read image data via yaozarrs.

Parameters:

Name	Type	Description	Default
`image_path`	`Path or str`	Image store path.	required
`return_future`	`bool or None`	Return read future (True), immediately read (False), or return the TensorStore array without issuing a read (None).	`True`

Returns:

Name	Type	Description
`array`	`Future or ndarray or TensorStore`	Read future, immediate array, or lazy TensorStore handle obtained through yaozarrs.

Source code in src/merfish3danalysis/qi2labDataStore.py

@staticmethod
def _load_from_zarr_array(
    image_path: Path | str, return_future: bool | None = True
) -> "np.ndarray | Future | TensorStore":
    """Read image data via yaozarrs.

    Parameters
    ----------
    image_path : Path or str
        Image store path.
    return_future : bool or None
        Return read future (True), immediately read (False), or return the
        TensorStore array without issuing a read (None).

    Returns
    -------
    array : tensorstore.Future or numpy.ndarray or tensorstore.TensorStore
        Read future, immediate array, or lazy TensorStore handle obtained
        through yaozarrs.
    """
    image_path = qi2labDataStore._image_store_path(image_path)
    group = open_group(str(image_path))
    current_array = group["0"].to_tensorstore()

    if return_future is None:
        return current_array
    read_future = current_array.read()
    return read_future if return_future else read_future.result()

`_normalize_stage_position_zyx_um(stage_zyx_um)` `staticmethod`

Return ZYX stage coordinates, padding legacy YX positions with Z=0.

Source code in src/merfish3danalysis/qi2labDataStore.py

@staticmethod
def _normalize_stage_position_zyx_um(stage_zyx_um: ArrayLike) -> np.ndarray:
    """Return ZYX stage coordinates, padding legacy YX positions with Z=0."""
    stage = np.asarray(stage_zyx_um, dtype=np.float32)
    if stage.shape == (2,):
        return np.asarray((0.0, stage[0], stage[1]), dtype=np.float32)
    if stage.shape != (3,):
        raise ValueError(
            "Stage position must contain two (Y, X) or three (Z, Y, X) "
            f"coordinates; got shape {stage.shape}."
        )
    return stage

`_normalize_transform(values, ndim, fill)` `staticmethod`

Normalize transform vectors to match array dimensionality.

Parameters:

Name	Type	Description	Default
`values`	`Sequence[float] \| None`	Optional transform vector.	required
`ndim`	`int`	Target array dimensionality.	required
`fill`	`float`	Fill value for missing leading dimensions.	required

Returns:

Type	Description
`list[float]`	Transform vector with one value per array dimension.

Source code in src/merfish3danalysis/qi2labDataStore.py

@staticmethod
def _normalize_transform(
    values: Sequence[float] | None, ndim: int, fill: float
) -> list[float]:
    """
    Normalize transform vectors to match array dimensionality.

    Parameters
    ----------
    values : Sequence[float] | None
        Optional transform vector.
    ndim : int
        Target array dimensionality.
    fill : float
        Fill value for missing leading dimensions.

    Returns
    -------
    list[float]
        Transform vector with one value per array dimension.
    """
    if values is None:
        return [fill] * ndim
    cast = [float(v) for v in values]
    if len(cast) == ndim:
        return cast
    if len(cast) == 3:
        if ndim == 2:
            return cast[1:]
        if ndim >= 3:
            return [fill] * (ndim - 3) + cast
    raise ValueError(f"Cannot map {len(cast)} transform values onto {ndim} axes.")

`_normalize_voxel_size_zyx_um(value)` `staticmethod`

Validate three positive finite ZYX spacings at stored precision.

Source code in src/merfish3danalysis/qi2labDataStore.py

@staticmethod
def _normalize_voxel_size_zyx_um(value: ArrayLike) -> list[float]:
    """Validate three positive finite ZYX spacings at stored precision."""
    spacing = round_spacing_um(value)
    if (
        spacing.shape != (3,)
        or not np.all(np.isfinite(spacing))
        or np.any(spacing <= 0)
    ):
        raise ValueError(
            "voxel_size_zyx_um must contain three positive finite ZYX spacings."
        )
    return spacing.tolist()

`_parse_datastore(validate=True)`

Parse datastore to discover available components.

Parameters:

Name	Type	Description	Default
`validate`	`bool`	Whether to validate existing zarr arrays while parsing.	`True`

Returns:

Type	Description
`None`	No return value.

Source code in src/merfish3danalysis/qi2labDataStore.py

def _parse_datastore(self, validate: bool = True) -> None:
    """
    Parse datastore to discover available components.

    Parameters
    ----------
    validate : bool
        Whether to validate existing zarr arrays while parsing.

    Returns
    -------
    None
        No return value.
    """
    # directory structure as defined by qi2lab spec
    self._datastore_state_json_path = self._datastore_path / Path(
        r"datastore_state.json"
    )
    # read in .json in root directory that indicates what steps have been run
    with open(self._datastore_state_json_path) as json_file:
        self._datastore_state = json.load(json_file)
    if float(self._datastore_state["Version"]) != 0.6:
        raise ValueError("Only datastore version 0.6 is supported by this build.")

    self.fiducial_folder_name = "fiducial"
    self.feature_predictor_folder_name = "feature_predictor"
    self._fiducial_root_path = self._datastore_path / Path(
        self.fiducial_folder_name
    )
    self._feature_predictor_localizations_root_path = self._datastore_path / Path(
        f"{self.feature_predictor_folder_name}_localizations"
    )
    self._calibrations_zarr_path = self._datastore_path / Path(r"calibrations")
    self._readouts_root_path = self._datastore_path / Path(r"readouts")
    self._decoded_root_path = self._datastore_path / Path(r"decoded")
    self._fused_root_path = self._datastore_path / Path(r"fused")
    self._segmentation_root_path = self._datastore_path / Path(r"segmentation")

    # validate calibrations
    if self._datastore_state["Calibrations"]:
        if not (self._calibrations_zarr_path.exists()):
            raise FileNotFoundError("Calibration data directory is missing.")
        attributes = self._load_calibrations_attributes()

        keys_to_check = [
            "num_rounds",
            "num_tiles",
            "channels_in_data",
            "tile_overlap",
            "binning",
            "e_per_ADU",
            "na",
            "ri",
            "exp_order",
            "codebook",
            "num_bits",
            "microscope_type",
            "camera_model",
            "voxel_size_zyx_um",
        ]
        for key in keys_to_check:
            if key not in attributes.keys():
                raise KeyError("Calibration attributes incomplete")

        self._num_rounds = attributes["num_rounds"]
        self._num_tiles = attributes["num_tiles"]
        self._channels_in_data = attributes["channels_in_data"]
        self._tile_overlap = attributes["tile_overlap"]
        self._binning = attributes["binning"]
        self._e_per_ADU = attributes["e_per_ADU"]
        self._na = attributes["na"]
        self._ri = attributes["ri"]
        self._exp_order = attributes["exp_order"]
        self._codebook = attributes["codebook"]
        self._num_bits = attributes["num_bits"]
        self._microscope_type = attributes["microscope_type"]
        self._camera_model = attributes["camera_model"]
        self._voxel_size_zyx_um = self._normalize_voxel_size_zyx_um(
            attributes["voxel_size_zyx_um"]
        )

        if getattr(self, "_exp_order", None) is not None:
            self._experiment_order = self._coerce_experiment_order_dataframe(
                self._exp_order
            )

        if getattr(self, "_num_tiles", None) is not None:
            self._tile_ids = [
                "tile" + str(tile_idx).zfill(4)
                for tile_idx in range(self._num_tiles)
            ]
        if getattr(self, "_num_rounds", None) is not None:
            self._round_ids = [
                "round" + str(round_idx + 1).zfill(3)
                for round_idx in range(self._num_rounds)
            ]
        if getattr(self, "_num_bits", None) is not None:
            self._bit_ids = [
                "bit" + str(bit_idx + 1).zfill(3)
                for bit_idx in range(self._num_bits)
            ]

        if validate:
            psf_root_path = self._calibrations_zarr_path / Path("psf_data")
            try:
                if psf_root_path.exists():

                    def psf_sort_key(path: Path) -> int:
                        """
                        Return the numeric PSF directory index.

                        Parameters
                        ----------
                        path : Path
                            PSF directory path.

                        Returns
                        -------
                        int
                            PSF directory index.
                        """
                        return int(path.name[len("psf_") : len("psf_") + 3])

                    psf_dirs = sorted(
                        [
                            entry
                            for entry in psf_root_path.iterdir()
                            if entry.is_dir()
                            and re.fullmatch(r"psf_\d{3}\.ome\.zarr", entry.name)
                        ],
                        key=psf_sort_key,
                    )
                else:
                    psf_dirs = []

                if len(psf_dirs) > 0:
                    psf_list = []
                    for psf_dir in psf_dirs:
                        psf_array = self._load_from_zarr_array(
                            psf_dir, return_future=False
                        )
                        psf_list.append(np.asarray(psf_array, dtype=np.float32))
                    self._psfs = psf_list
            except (OSError, ValueError):
                print("Calibration psfs missing.")

    # validate fiducial and readout bits data
    if self._datastore_state["Corrected"] and validate:
        if not (self._fiducial_root_path.exists()):
            raise FileNotFoundError("fiducial directory not initialized")
        else:
            fiducial_tile_ids = self._collect_strict_ids(
                self._fiducial_root_path, prefix="tile", width=4
            )
            if len(fiducial_tile_ids) == 0:
                raise FileNotFoundError("No tile folders found under fiducial/")
            current_tile_dir_path = self._fiducial_root_path / Path(
                fiducial_tile_ids[0]
            )
            self._round_ids = self._collect_strict_ids(
                current_tile_dir_path, prefix="round", width=3
            )
        if not (self._readouts_root_path.exists()):
            raise FileNotFoundError("Readout directory not initialized")
        else:
            readout_tile_ids = self._collect_strict_ids(
                self._readouts_root_path, prefix="tile", width=4
            )
            if len(readout_tile_ids) == 0:
                raise FileNotFoundError("No tile folders found under readouts/")
            current_tile_dir_path = self._readouts_root_path / Path(
                readout_tile_ids[0]
            )
            self._bit_ids = self._collect_strict_ids(
                current_tile_dir_path, prefix="bit", width=3
            )
        assert fiducial_tile_ids == readout_tile_ids, (
            "fiducial and readout tile ids do not match. Conversion error."
        )
        self._tile_ids = fiducial_tile_ids.copy()
        del fiducial_tile_ids, readout_tile_ids

        for tile_id, round_id in product(self._tile_ids, self._round_ids):
            entity_root = self._fiducial_root_path / Path(tile_id) / Path(round_id)
            attributes = self._load_entity_attributes(entity_root)

            keys_to_check = [
                "stage_zyx_um",
                "excitation_um",
                "emission_um",
                # "exposure_ms",
                "psf_idx",
            ]

            for key in keys_to_check:
                if key not in attributes.keys():
                    print(tile_id, round_id, key)
                    raise KeyError("Corrected fiducial attributes incomplete")
            if "bit_linker" not in attributes:
                print(tile_id, round_id, "bit_linker")
                raise KeyError("Corrected fiducial attributes incomplete")

            current_local_zarr_path = str(entity_root / Path("corrected_data"))

            try:
                self._check_for_zarr_array(current_local_zarr_path)
            except (OSError, ValueError):
                print(tile_id, round_id)
                print("Corrected fiducial data missing.")

        for tile_id, bit_id in product(self._tile_ids, self._bit_ids):
            entity_root = self._readouts_root_path / Path(tile_id) / Path(bit_id)
            attributes = self._load_entity_attributes(entity_root)

            keys_to_check = [
                "excitation_um",
                "emission_um",
                # "exposure_ms",
                "psf_idx",
            ]
            for key in keys_to_check:
                if key not in attributes.keys():
                    raise KeyError("Corrected readout attributes incomplete")
            if "round_linker" not in attributes:
                raise KeyError("Corrected readout attributes incomplete")

            current_local_zarr_path = str(entity_root / Path("corrected_data"))

            try:
                self._check_for_zarr_array(current_local_zarr_path)
            except (OSError, ValueError):
                print(tile_id, bit_id)
                print("Corrected readout data missing.")

    # check and validate local transform and preprocessing data
    if self._datastore_state["LocalRegistered"] and validate:
        for tile_id, round_id in product(self._tile_ids, self._round_ids):
            entity_root = self._fiducial_root_path / Path(tile_id) / Path(round_id)
            if round_id != self._round_ids[0]:
                attributes = self._load_entity_attributes(entity_root)

                keys_to_check = ["local_round_transform_zyx_um"]

                for key in keys_to_check:
                    if key not in attributes.keys():
                        raise KeyError(
                            f"{round_id, tile_id} local round transform missing"
                        )

                current_local_zarr_path = str(
                    entity_root / Path("opticalflow_xform_px")
                )

                try:
                    self._check_for_zarr_array(current_local_zarr_path)
                except (OSError, ValueError):
                    # print(tile_id, round_id)
                    # print("Optical flow registration data missing.")
                    pass

            corrected_shape = self.image_shape(entity_root / Path("corrected_data"))
            decon_shape = self.image_shape(entity_root / Path("decon_data"))
            if (
                corrected_shape is not None
                and decon_shape is not None
                and corrected_shape != decon_shape
            ):
                raise ValueError(
                    f"{tile_id} {round_id} corrected and decon shapes differ: "
                    f"{corrected_shape} != {decon_shape}"
                )

        for tile_id, bit_id in product(self._tile_ids, self._bit_ids):
            entity_root = self._readouts_root_path / Path(tile_id) / Path(bit_id)
            current_local_zarr_path = str(
                entity_root / Path(f"{self.feature_predictor_folder_name}_data")
            )

            try:
                self._check_for_zarr_array(current_local_zarr_path)
            except (OSError, ValueError):
                print(tile_id, bit_id)
                print("feature_predictor prediction missing.")
            corrected_shape = self.image_shape(entity_root / Path("corrected_data"))
            decon_shape = self.image_shape(entity_root / Path("decon_data"))
            feature_shape = self.image_shape(
                entity_root / Path(f"{self.feature_predictor_folder_name}_data")
            )
            shapes = [
                shape
                for shape in (corrected_shape, decon_shape, feature_shape)
                if shape is not None
            ]
            if len(shapes) > 1 and any(shape != shapes[0] for shape in shapes[1:]):
                raise ValueError(
                    f"{tile_id} {bit_id} corrected/decon/feature image shapes differ: "
                    f"{corrected_shape}, {decon_shape}, {feature_shape}"
                )

        for tile_id, bit_id in product(self._tile_ids, self._bit_ids):
            current_feature_predictor_path = (
                self._feature_predictor_localizations_root_path
                / Path(tile_id)
                / Path(bit_id + ".parquet")
            )
            if not (current_feature_predictor_path.exists()):
                raise FileNotFoundError(
                    tile_id
                    + " "
                    + bit_id
                    + " feature_predictor localization missing"
                )

    # check and validate global registered data
    if self._datastore_state["GlobalRegistered"] and validate:
        for tile_id in self._tile_ids:
            entity_root = (
                self._fiducial_root_path / Path(tile_id) / Path(self._round_ids[0])
            )
            attributes = self._load_entity_attributes(entity_root)

            keys_to_check = ["affine_zyx_um", "origin_zyx_um", "spacing_zyx_um"]

            for key in keys_to_check:
                if key not in attributes.keys():
                    raise KeyError("Global registration missing")

    # check and validate fused
    if self._datastore_state["Fused"] and validate:
        fused_image_path = self._fused_root_path / Path(
            f"fused_{self.fiducial_folder_name}_zyx"
        )
        attributes = self.load_image_metadata(fused_image_path)

        keys_to_check = ["affine_zyx_um", "origin_zyx_um", "spacing_zyx_um"]

        for key in keys_to_check:
            if key not in attributes.keys():
                raise KeyError("Fused image metadata missing")

        current_local_zarr_path = str(fused_image_path)

        try:
            self._check_for_zarr_array(current_local_zarr_path)
        except (OSError, ValueError):
            print("Fused data missing.")

    # check and validate cellpose segmentation
    if self._datastore_state["SegmentedCells"] and validate:
        current_local_zarr_path = str(
            self._segmentation_root_path
            / Path("cellpose")
            / Path(f"masks_{self.fiducial_folder_name}_iso_zyx")
        )

        try:
            self._check_for_zarr_array(current_local_zarr_path)
        except (OSError, ValueError):
            print("Cellpose data missing.")

        cell_outlines_path = (
            self._segmentation_root_path
            / Path("cellpose")
            / Path("imagej_rois")
            / Path("global_coords_rois.zip")
        )
        if not (cell_outlines_path.exists()):
            raise FileNotFoundError("Cellpose cell outlines missing.")

    # check and validate decoded spots
    if self._datastore_state["DecodedSpots"] and validate:
        for tile_id in self._tile_ids:
            decoded_path = self._decoded_root_path / Path(
                tile_id + "_decoded_features.parquet"
            )

            if not (decoded_path.exists()):
                raise FileNotFoundError(tile_id + " decoded spots missing.")

    # check and validate filtered decoded spots
    if self._datastore_state["FilteredSpots"] and validate:
        filtered_path = self._decoded_root_path / Path(
            "all_tiles_filtered_decoded_features.parquet"
        )

        if not (filtered_path.exists()):
            raise FileNotFoundError("filtered decoded spots missing.")

`_proseg_3d_root()`

Return the root path for Proseg 3D outputs.

Returns:

Type	Description
`Path`	Proseg 3D output root.

Source code in src/merfish3danalysis/qi2labDataStore.py

def _proseg_3d_root(self) -> Path:
    """
    Return the root path for Proseg 3D outputs.

    Returns
    -------
    Path
        Proseg 3D output root.
    """
    return self._datastore_path / Path("proseg") / Path("3D")

`_proseg_3d_run_root(run_name=None)`

Return one Proseg 3D run root path.

Parameters:

Name	Type	Description	Default
`run_name`	`str or None`	Proseg run name. `None` or `"default"` selects `proseg/3D`.	`None`

Returns:

Type	Description
`Path`	Proseg run root path.

Source code in src/merfish3danalysis/qi2labDataStore.py

def _proseg_3d_run_root(self, run_name: str | None = None) -> Path:
    """
    Return one Proseg 3D run root path.

    Parameters
    ----------
    run_name : str or None, default None
        Proseg run name. ``None`` or ``"default"`` selects ``proseg/3D``.

    Returns
    -------
    Path
        Proseg run root path.
    """
    proseg_root = self._proseg_3d_root()
    if run_name is None or run_name == "default":
        return proseg_root
    return proseg_root / Path(run_name)

`_resolve_original_tile_position_zyx_um(tile_id, round_id=None, bit_id=None)`

Resolve original tile stage position used for OME translation.

Parameters:

Name	Type	Description	Default
`tile_id`	`str`	Tile identifier.	required
`round_id`	`str \| None`	Optional fiducial round identifier.	`None`
`bit_id`	`str \| None`	Optional readout bit identifier.	`None`

Returns:

Type	Description
`list[float] \| None`	Original stage position in Z, Y, X microns, if available.

Source code in src/merfish3danalysis/qi2labDataStore.py

def _resolve_original_tile_position_zyx_um(
    self,
    tile_id: str,
    round_id: str | None = None,
    bit_id: str | None = None,
) -> list[float] | None:
    """
    Resolve original tile stage position used for OME translation.

    Parameters
    ----------
    tile_id : str
        Tile identifier.
    round_id : str | None
        Optional fiducial round identifier.
    bit_id : str | None
        Optional readout bit identifier.

    Returns
    -------
    list[float] | None
        Original stage position in Z, Y, X microns, if available.
    """
    if round_id is not None:
        fiducial_entity = self._fiducial_root_path / Path(tile_id) / Path(round_id)
        attrs = self._load_entity_attributes(fiducial_entity)
        stage = attrs.get("stage_zyx_um")
        if stage is not None:
            return self._normalize_stage_position_zyx_um(stage).tolist()

    if bit_id is not None:
        round_linker = self.load_local_round_linker(tile=tile_id, bit=bit_id)
        if round_linker is not None and int(round_linker) > 0:
            linked_round_id = self._round_ids[int(round_linker) - 1]
            fiducial_entity = (
                self._fiducial_root_path / Path(tile_id) / Path(linked_round_id)
            )
            attrs = self._load_entity_attributes(fiducial_entity)
            stage = attrs.get("stage_zyx_um")
            if stage is not None:
                return self._normalize_stage_position_zyx_um(stage).tolist()

    if getattr(self, "_round_ids", None):
        fiducial_entity = (
            self._fiducial_root_path / Path(tile_id) / Path(self._round_ids[0])
        )
        attrs = self._load_entity_attributes(fiducial_entity)
        stage = attrs.get("stage_zyx_um")
        if stage is not None:
            return self._normalize_stage_position_zyx_um(stage).tolist()
    return None

`_resolve_reference_tile_position_zyx_um(tile_id)`

Resolve the first-round reference stage position for derived outputs.

Parameters:

Name	Type	Description	Default
`tile_id`	`str`	Tile identifier.	required

Returns:

Type	Description
`list[float] or None`	First fiducial round stage position in Z, Y, X microns.

Source code in src/merfish3danalysis/qi2labDataStore.py

def _resolve_reference_tile_position_zyx_um(
    self, tile_id: str
) -> list[float] | None:
    """
    Resolve the first-round reference stage position for derived outputs.

    Parameters
    ----------
    tile_id : str
        Tile identifier.

    Returns
    -------
    list[float] or None
        First fiducial round stage position in Z, Y, X microns.
    """
    if not getattr(self, "_round_ids", None):
        return None
    return self._resolve_original_tile_position_zyx_um(
        tile_id=tile_id, round_id=self._round_ids[0]
    )

`_save_calibrations_attributes(attributes)`

Persist calibrations metadata sidecar.

Parameters:

Name	Type	Description	Default
`attributes`	`Mapping[str, Any]`	Calibration metadata to write.	required

Returns:

Type	Description
`None`	No return value.

Source code in src/merfish3danalysis/qi2labDataStore.py

def _save_calibrations_attributes(self, attributes: Mapping[str, Any]) -> None:
    """
    Persist calibrations metadata sidecar.

    Parameters
    ----------
    attributes : Mapping[str, Any]
        Calibration metadata to write.

    Returns
    -------
    None
        No return value.
    """
    self._save_to_json(
        {str(k): self._to_json_compatible(v) for k, v in dict(attributes).items()},
        self._calibrations_attributes_path(),
    )

`_save_default_decode_normalization_metadata(kind, metadata)`

Save provenance for default, non-run-scoped normalization vectors.

Source code in src/merfish3danalysis/qi2labDataStore.py

def _save_default_decode_normalization_metadata(
    self,
    kind: str,
    metadata: Mapping[str, Any] | None,
) -> None:
    """Save provenance for default, non-run-scoped normalization vectors."""
    if metadata is None:
        return
    calib_attrs = self._load_calibrations_attributes()
    all_metadata = dict(calib_attrs.get("decode_normalization_metadata", {}))
    all_metadata[kind] = dict(metadata)
    calib_attrs["decode_normalization_metadata"] = all_metadata
    self._save_calibrations_attributes(calib_attrs)

`_save_entity_attributes(entity_root_path, updates)`

Save metadata to the entity sidecar.

Parameters:

Name	Type	Description	Default
`entity_root_path`	`Path \| str`	Entity folder path.	required
`updates`	`Mapping[str, Any]`	Metadata updates to persist.	required

Returns:

Type	Description
`None`	No return value.

Source code in src/merfish3danalysis/qi2labDataStore.py

def _save_entity_attributes(
    self,
    entity_root_path: Path | str,
    updates: Mapping[str, Any],
) -> None:
    """
    Save metadata to the entity sidecar.

    Parameters
    ----------
    entity_root_path : Path | str
        Entity folder path.
    updates : Mapping[str, Any]
        Metadata updates to persist.

    Returns
    -------
    None
        No return value.
    """
    if not updates:
        return

    entity_root = Path(entity_root_path)
    payload = {
        str(k): self._to_json_compatible(v) for k, v in dict(updates).items()
    }

    sidecar_path = self._entity_attributes_path(entity_root)
    sidecar_attrs = self._load_from_json(sidecar_path)
    sidecar_attrs.update(payload)
    self._save_to_json(sidecar_attrs, sidecar_path)

`_save_to_csv_gz(df, csv_gz_path)` `staticmethod`

Save dataframe to gzipped CSV.

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	Dataframe to save.	required
`csv_gz_path`	`Path or str`	Path to gzipped CSV file.	required

Source code in src/merfish3danalysis/qi2labDataStore.py

@staticmethod
def _save_to_csv_gz(df: pd.DataFrame, csv_gz_path: Path | str) -> None:
    """Save dataframe to gzipped CSV.

    Parameters
    ----------
    df : pd.DataFrame
        Dataframe to save.
    csv_gz_path : Path or str
        Path to gzipped CSV file.
    """
    df.to_csv(csv_gz_path, index=False, compression="gzip")

`_save_to_json(dictionary, dictionary_path)` `staticmethod`

Save dictionary to json.

Parameters:

Name	Type	Description	Default
`dictionary`	`dict`	The data to be saved.	required
`dictionary_path`	`Path or str`	The path to the JSON file where the data will be saved.	required

Source code in src/merfish3danalysis/qi2labDataStore.py

@staticmethod
def _save_to_json(dictionary: dict, dictionary_path: Path | str) -> None:
    """Save dictionary to json.

    Parameters
    ----------
    dictionary : dict
        The data to be saved.
    dictionary_path : Path or str
        The path to the JSON file where the data will be saved.
    """
    serialized = json.dumps(dictionary, indent=4)
    with open(dictionary_path, "w", encoding="utf-8") as file:
        file.write(serialized)

`_save_to_parquet(df, parquet_path)` `staticmethod`

Save dataframe to parquet.

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	Dataframe to save.	required
`parquet_path`	`Path or str`	Path to parquet file.	required

Source code in src/merfish3danalysis/qi2labDataStore.py

@staticmethod
def _save_to_parquet(df: pd.DataFrame, parquet_path: Path | str) -> None:
    """Save dataframe to parquet.

    Parameters
    ----------
    df : pd.DataFrame
        Dataframe to save.
    parquet_path : Path or str
        Path to parquet file.
    """
    df.to_parquet(parquet_path, engine="fastparquet", index=False)

`_save_to_zarr_array(array, image_path, return_future=False, *, chunks=None, ome_scale=None, ome_translation=None, extra_attributes=None)` `staticmethod`

Save image data as OME-Zarr v0.5 using yaozarrs tensorstore writer.

Parameters:

Name	Type	Description	Default
`array`	`ArrayLike`	Array to save.	required
`image_path`	`Path or str`	Image store path.	required
`chunks`	`Sequence[int] or None`	Storage chunk shape. None selects the datastore default.	`None`
`ome_scale`	`Sequence[float] or None`	Pixel spacing in microns, in image-axis order or ZYX order.	`None`
`ome_translation`	`Sequence[float] or None`	Image origin in microns, in image-axis order or ZYX order.	`None`
`extra_attributes`	`Mapping or None`	Additional image metadata.	`None`
`return_future`	`bool or None`	Return the write-completion handle (True), or wait for the write to finish and return None (False or None).	`False`

Returns:

Name	Type	Description
`write_future`	`WriteFutures or None`	Pixel-write completion handle when return_future is True.

Raises:

Type	Description
`(OSError, ValueError)`	Storage or metadata errors. Failed writes are not reported as success.

Source code in src/merfish3danalysis/qi2labDataStore.py

@staticmethod
def _save_to_zarr_array(
    array: ArrayLike,
    image_path: Path | str,
    return_future: bool | None = False,
    *,
    chunks: Sequence[int] | None = None,
    ome_scale: Sequence[float] | None = None,
    ome_translation: Sequence[float] | None = None,
    extra_attributes: Mapping[str, Any] | None = None,
) -> "WriteFutures | None":
    """Save image data as OME-Zarr v0.5 using yaozarrs tensorstore writer.

    Parameters
    ----------
    array : ArrayLike
        Array to save.
    image_path : Path or str
        Image store path.
    chunks : Sequence[int] or None
        Storage chunk shape. None selects the datastore default.
    ome_scale : Sequence[float] or None
        Pixel spacing in microns, in image-axis order or ZYX order.
    ome_translation : Sequence[float] or None
        Image origin in microns, in image-axis order or ZYX order.
    extra_attributes : Mapping or None
        Additional image metadata.
    return_future : bool or None
        Return the write-completion handle (True), or wait for the write
        to finish and return None (False or None).

    Returns
    -------
    write_future : tensorstore.WriteFutures or None
        Pixel-write completion handle when return_future is True.

    Raises
    ------
    OSError, ValueError
        Storage or metadata errors. Failed writes are not reported as success.
    """
    image_path = qi2labDataStore._image_store_path(image_path)
    image_path.parent.mkdir(parents=True, exist_ok=True)

    image_array = np.asarray(array)
    if image_array.dtype == np.float64:
        image_array = image_array.astype(np.float32)

    if image_array.ndim < 2 or image_array.ndim > 5:
        raise ValueError(
            f"Unsupported array ndim for image write: {image_array.ndim}"
        )

    if chunks is None:
        chunks = qi2labDataStore._default_chunks(image_array)
    scale = qi2labDataStore._normalize_transform(ome_scale, image_array.ndim, 1.0)
    translation = qi2labDataStore._normalize_transform(
        ome_translation, image_array.ndim, 0.0
    )

    axes = qi2labDataStore._build_axes(v05, image_array.ndim)
    scale[-3:] = round_spacing_um(scale[-3:]).tolist()
    transforms = [
        v05.ScaleTransformation(scale=scale),
        v05.TranslationTransformation(translation=translation),
    ]
    datasets = [v05.Dataset(path="0", coordinateTransformations=transforms)]
    multiscales = [v05.Multiscale(axes=axes, datasets=datasets)]

    image_metadata = v05.Image(multiscales=multiscales)

    chunk_spec = tuple(int(c) for c in chunks)
    write_options = {
        "extra_attributes": qi2labDataStore._to_json_compatible(extra_attributes)
        if extra_attributes
        else None,
        "writer": qi2labDataStore._create_array_tensorstore_qi2lab,
        "overwrite": True,
        "chunks": chunk_spec,
        "compression": "blosc-zstd",
    }
    if return_future:
        from yaozarrs.write.v05 import prepare_image

        # yaozarrs creates the complete OME-Zarr v3 structure. Its write_image
        # API is synchronous; writing the prepared array is necessary to
        # preserve the datastore's TensorStore write-completion handle.
        _, arrays = prepare_image(
            dest=str(image_path),
            image=image_metadata,
            datasets=(image_array.shape, image_array.dtype),
            **write_options,
        )
        return arrays["0"].write(image_array)
    write_image(
        dest=str(image_path),
        image=image_metadata,
        datasets=image_array,
        **write_options,
    )
    return None

`_set_calibration_attribute(key, value)`

Update one calibration metadata field.

Parameters:

Name	Type	Description	Default
`key`	`str`	Calibration metadata key.	required
`value`	`Any`	Value to store after JSON conversion.	required

Returns:

Type	Description
`None`	No return value.

Source code in src/merfish3danalysis/qi2labDataStore.py

def _set_calibration_attribute(self, key: str, value: Any) -> None:
    """
    Update one calibration metadata field.

    Parameters
    ----------
    key : str
        Calibration metadata key.
    value : Any
        Value to store after JSON conversion.

    Returns
    -------
    None
        No return value.
    """
    attributes = self._load_calibrations_attributes()
    attributes[str(key)] = self._to_json_compatible(value)
    self._save_calibrations_attributes(attributes)

`_strict_id_sort_key(name, prefix, width)` `staticmethod`

Validate and parse strict zero-padded identifiers.

Parameters:

Name	Type	Description	Default
`name`	`str`	Identifier to validate.	required
`prefix`	`str`	Required identifier prefix.	required
`width`	`int`	Required number of zero-padded digits.	required

Returns:

Type	Description
`int`	Parsed numeric identifier.

Source code in src/merfish3danalysis/qi2labDataStore.py

@staticmethod
def _strict_id_sort_key(name: str, prefix: str, width: int) -> int:
    """
    Validate and parse strict zero-padded identifiers.

    Parameters
    ----------
    name : str
        Identifier to validate.
    prefix : str
        Required identifier prefix.
    width : int
        Required number of zero-padded digits.

    Returns
    -------
    int
        Parsed numeric identifier.
    """
    match = re.fullmatch(rf"{re.escape(prefix)}(\d{{{width}}})", name)
    if match is None:
        raise ValueError(
            f"Invalid identifier '{name}'. Expected '{prefix}' followed by {width} digits."
        )
    return int(match.group(1))

`_to_json_compatible(value)` `staticmethod`

Convert numpy/scalar containers to JSON-compatible values.

Parameters:

Name	Type	Description	Default
`value`	`Any`	Value to convert before JSON serialization.	required

Returns:

Type	Description
`Any`	JSON-compatible representation.

Source code in src/merfish3danalysis/qi2labDataStore.py

@staticmethod
def _to_json_compatible(value: Any) -> Any:
    """
    Convert numpy/scalar containers to JSON-compatible values.

    Parameters
    ----------
    value : Any
        Value to convert before JSON serialization.

    Returns
    -------
    Any
        JSON-compatible representation.
    """
    if isinstance(value, np.ndarray):
        return value.tolist()
    if isinstance(value, np.generic):
        return value.item()
    if isinstance(value, Mapping):
        return {
            str(k): qi2labDataStore._to_json_compatible(v) for k, v in value.items()
        }
    if isinstance(value, tuple):
        return [qi2labDataStore._to_json_compatible(v) for v in value]
    if isinstance(value, list):
        return [qi2labDataStore._to_json_compatible(v) for v in value]
    return value

`_update_image_translation_transform(image_root, stage_zyx_um)`

Update an existing OME-Zarr image translation transform.

Parameters:

Name	Type	Description	Default
`image_root`	`Path`	Image root path, without or with the `.ome.zarr` suffix.	required
`stage_zyx_um`	`Sequence[float]`	Physical Z, Y, X translation to write into the image metadata.	required

Returns:

Type	Description
`None`	The image metadata is updated in place when it already exists.

Source code in src/merfish3danalysis/qi2labDataStore.py

def _update_image_translation_transform(
    self,
    image_root: Path,
    stage_zyx_um: Sequence[float],
) -> None:
    """
    Update an existing OME-Zarr image translation transform.

    Parameters
    ----------
    image_root : Path
        Image root path, without or with the ``.ome.zarr`` suffix.
    stage_zyx_um : Sequence[float]
        Physical Z, Y, X translation to write into the image metadata.

    Returns
    -------
    None
        The image metadata is updated in place when it already exists.
    """
    image_path = self._image_store_path(image_root)
    metadata_path = image_path / Path("zarr.json")
    if not metadata_path.exists():
        return

    metadata = open_group(image_path).metadata.model_dump(
        mode="json", exclude_none=True
    )

    transforms = (
        metadata.get("attributes", {})
        .get("ome", {})
        .get("multiscales", [{}])[0]
        .get("datasets", [{}])[0]
        .get("coordinateTransformations", [])
    )
    for transform in transforms:
        if transform.get("type") == "translation":
            transform["translation"] = [float(v) for v in stage_zyx_um]
            self._save_to_json(metadata, metadata_path)
            return

`_validate_core_image_shape(entity_root_path, image_name, image)`

Enforce corrected/deconvolved/feature image shape consistency.

Parameters:

Name	Type	Description	Default
`entity_root_path`	`Path \| str`	Entity folder path.	required
`image_name`	`str`	Logical image name being validated.	required
`image`	`ArrayLike`	Image data to validate.	required

Returns:

Type	Description
`None`	No return value.

Source code in src/merfish3danalysis/qi2labDataStore.py

def _validate_core_image_shape(
    self,
    entity_root_path: Path | str,
    image_name: str,
    image: ArrayLike,
) -> None:
    """
    Enforce corrected/deconvolved/feature image shape consistency.

    Parameters
    ----------
    entity_root_path : Path | str
        Entity folder path.
    image_name : str
        Logical image name being validated.
    image : ArrayLike
        Image data to validate.

    Returns
    -------
    None
        No return value.
    """
    entity_root = Path(entity_root_path)
    shape = tuple(int(v) for v in np.asarray(image).shape)
    required_names = {
        "corrected_data",
        "decon_data",
        f"{self.feature_predictor_folder_name}_data",
    }
    for candidate_name in required_names:
        if candidate_name == image_name:
            continue
        candidate_shape = self.image_shape(entity_root / Path(candidate_name))
        if candidate_shape is None:
            continue
        if tuple(candidate_shape) != shape:
            raise ValueError(
                f"Image shape mismatch in {entity_root.name}: "
                f"{image_name}={shape} but {candidate_name}={candidate_shape}. "
                "corrected_data, optional decon_data, and "
                "feature_predictor_data must match."
            )

`_validate_decode_run_key(decode_run_key)` `staticmethod`

Validate an optional decoded-output run key.

Parameters:

Name	Type	Description	Default
`decode_run_key`	`str or None`	Optional subfolder name under decoded-output roots.	required

Returns:

Type	Description
`str or None`	Validated run key.

Source code in src/merfish3danalysis/qi2labDataStore.py

@staticmethod
def _validate_decode_run_key(decode_run_key: str | None) -> str | None:
    """
    Validate an optional decoded-output run key.

    Parameters
    ----------
    decode_run_key : str or None
        Optional subfolder name under decoded-output roots.

    Returns
    -------
    str or None
        Validated run key.
    """
    if decode_run_key is None:
        return None
    decode_run_key = str(decode_run_key)
    if not re.fullmatch(r"[A-Za-z0-9_.-]+", decode_run_key):
        raise ValueError(
            "decode_run_key may only contain letters, numbers, '.', '_', and '-'."
        )
    return decode_run_key

`baysor_3d_available()`

Return whether Baysor 3D molecules and cell boundaries are present.

Source code in src/merfish3danalysis/qi2labDataStore.py

def baysor_3d_available(self) -> bool:
    """Return whether Baysor 3D molecules and cell boundaries are present."""
    baysor_root = self._segmentation_root_path / Path("baysor") / Path("3D")
    return (baysor_root / Path("molecules.parquet")).exists() and (
        baysor_root / Path("cell_boundaries_3d.parquet")
    ).exists()

`decoded_temporary_dir(decode_run_key=None, iteration=None)`

Return the temporary decoded-output directory for a decode run.

Parameters:

Name	Type	Description	Default
`decode_run_key`	`str or None`	Optional decoded-output run key.	`None`
`iteration`	`int or None`	Optional optimization iteration index.	`None`

Returns:

Type	Description
`Path`	Temporary decoded-output directory.

Source code in src/merfish3danalysis/qi2labDataStore.py

def decoded_temporary_dir(
    self,
    decode_run_key: str | None = None,
    iteration: int | None = None,
) -> Path:
    """
    Return the temporary decoded-output directory for a decode run.

    Parameters
    ----------
    decode_run_key : str or None, default None
        Optional decoded-output run key.
    iteration : int or None, default None
        Optional optimization iteration index.

    Returns
    -------
    pathlib.Path
        Temporary decoded-output directory.
    """
    root = self._decoded_run_root(decode_run_key) / Path("temporary")
    if iteration is not None:
        root = root / Path(f"iteration_{int(iteration):03d}")
    return root

`fused_image_path(image_name=None)`

Return the OME-Zarr path for a fused image.

Parameters:

Name	Type	Description	Default
`image_name`	`str or None`	Logical image name. None selects the fused fiducial volume.	`None`

Returns:

Type	Description
`Path`	Fused image directory, without opening or creating it.

Source code in src/merfish3danalysis/qi2labDataStore.py

def fused_image_path(self, image_name: str | None = None) -> Path:
    """Return the OME-Zarr path for a fused image.

    Parameters
    ----------
    image_name : str or None
        Logical image name. None selects the fused fiducial volume.

    Returns
    -------
    Path
        Fused image directory, without opening or creating it.
    """
    if image_name is None:
        image_name = f"fused_{self.fiducial_folder_name}_zyx"
    return self._image_store_path(self._fused_root_path / image_name)

`image_shape(image_path)` `staticmethod`

Read image shape without loading all pixels.

Parameters:

Name	Type	Description	Default
`image_path`	`Path \| str`	Image store path.	required

Returns:

Type	Description
`tuple[int, ...] \| None`	Image array shape, or `None` when the image is unavailable.

Source code in src/merfish3danalysis/qi2labDataStore.py

@staticmethod
def image_shape(image_path: Path | str) -> tuple[int, ...] | None:
    """
    Read image shape without loading all pixels.

    Parameters
    ----------
    image_path : Path | str
        Image store path.

    Returns
    -------
    tuple[int, ...] | None
        Image array shape, or ``None`` when the image is unavailable.
    """
    path = qi2labDataStore._image_store_path(image_path)
    if not path.exists():
        return None

    try:
        group = open_group(str(path))
        array_0 = group["0"]
        shape = array_0.metadata.shape
        return tuple(int(dim) for dim in shape)
    except (FileNotFoundError, KeyError):
        return None

`initialize_tile(tile)`

Initialize directory structure for a tile.

Parameters:

Name	Type	Description	Default
`tile`	`int or str`	Tile index or tile id.	required

Source code in src/merfish3danalysis/qi2labDataStore.py

def initialize_tile(
    self,
    tile: int | str,
) -> None:
    """Initialize directory structure for a tile.

    Parameters
    ----------
    tile : int or str
        Tile index or tile id.
    """
    if getattr(self, "_experiment_order", None) is None:
        print("Assign experimental order before creating tiles.")
        return None

    if getattr(self, "_num_tiles", None) is None:
        print("Assign number of tiles before creating tiles.")
        return None

    if isinstance(tile, int):
        if tile < 0 or tile >= self._num_tiles:
            print("Set tile index >=0 and <" + str(self._num_tiles))
            return None
        else:
            tile_id = self._tile_ids[tile]
    elif isinstance(tile, str):
        if tile not in self._tile_ids:
            print("set valid tile id.")
            return None
        else:
            tile_id = tile
    else:
        print("'tile' must be integer index or string identifier")
        return None

    try:
        fiducial_tile_path = self._fiducial_root_path / Path(tile_id)
        fiducial_tile_path.mkdir()
        for round_idx, round_id in enumerate(self._round_ids):
            fiducial_round_path = fiducial_tile_path / Path(round_id)
            fiducial_round_path.mkdir()
            fiducial_round_attrs_path = self._entity_attributes_path(
                fiducial_round_path
            )
            round_attrs = {
                "bit_linker": self._experiment_order.to_numpy()[round_idx, 1:]
                .astype(int)
                .tolist(),
            }
            self._save_to_json(round_attrs, fiducial_round_attrs_path)
    except FileExistsError:
        print("Error creating fiducial tile. Does it exist already?")

    try:
        readout_tile_path = self._readouts_root_path / Path(tile_id)
        readout_tile_path.mkdir()
        for bit_idx, bit_id in enumerate(self._bit_ids):
            readout_bit_path = readout_tile_path / Path(bit_id)
            readout_bit_path.mkdir()
            readout_bit_attrs_path = self._entity_attributes_path(readout_bit_path)
            fiducial_channel = str(self._channels_in_data[0])
            readout_one_channel = str(self._channels_in_data[1])

            if len(self._channels_in_data) == 3:
                readout_two_channel = str(self._channels_in_data[2])
                condition_one = self._experiment_order[readout_one_channel] == (
                    bit_idx + 1
                )
                condition_two = self._experiment_order[readout_two_channel] == (
                    bit_idx + 1
                )
                combined_condition = condition_one | condition_two

            else:
                combined_condition = self._experiment_order[
                    readout_one_channel
                ] == (bit_idx + 1)
            matching_rows = self._experiment_order.loc[combined_condition]

            bit_attrs = {
                "round_linker": int(matching_rows[fiducial_channel].values[0])
            }
            self._save_to_json(bit_attrs, readout_bit_attrs_path)
    except FileExistsError:
        print("Error creating readout tile. Does it exist already?")

`list_proseg_3d_runs()`

List available Proseg 3D output runs.

Returns:

Name	Type	Description
`proseg_runs`	`list[str]`	Available Proseg 3D run names. The direct `proseg/3D` output is named `"default"`.

Source code in src/merfish3danalysis/qi2labDataStore.py

def list_proseg_3d_runs(self) -> list[str]:
    """List available Proseg 3D output runs.

    Returns
    -------
    proseg_runs : list[str]
        Available Proseg 3D run names. The direct ``proseg/3D`` output is
        named ``"default"``.
    """
    proseg_root = self._proseg_3d_root()
    if not proseg_root.exists():
        return []

    run_names: list[str] = []
    candidate_roots = [proseg_root]
    candidate_roots.extend(
        path for path in sorted(proseg_root.iterdir()) if path.is_dir()
    )
    for root in candidate_roots:
        transcript_path = root / Path("transcript_metadata_3D.csv.gz")
        polygon_path = root / Path("cell_polygons_3D.geojson.gz")
        if transcript_path.exists() and polygon_path.exists():
            run_names.append("default" if root == proseg_root else root.name)
    return sorted(run_names)

`load_baysor_cell_boundaries_3d()`

Load Baysor 3D cell boundary polygons.

Returns:

Type	Description
`DataFrame or None`	Baysor cell boundary table, if present.

Source code in src/merfish3danalysis/qi2labDataStore.py

def load_baysor_cell_boundaries_3d(self) -> pd.DataFrame | None:
    """
    Load Baysor 3D cell boundary polygons.

    Returns
    -------
    pandas.DataFrame or None
        Baysor cell boundary table, if present.
    """
    boundaries_path = (
        self._segmentation_root_path
        / Path("baysor")
        / Path("3D")
        / Path("cell_boundaries_3d.parquet")
    )
    if not boundaries_path.exists():
        print("Baysor cell boundaries not found.")
        return None
    try:
        return self._load_from_parquet(boundaries_path)
    except (OSError, ValueError) as exc:
        print(exc)
        print("Error loading Baysor cell boundaries.")
        return None

`load_baysor_molecules_3d()`

Load Baysor 3D molecule assignments.

Returns:

Type	Description
`DataFrame or None`	Baysor molecule table, if present.

Source code in src/merfish3danalysis/qi2labDataStore.py

def load_baysor_molecules_3d(self) -> pd.DataFrame | None:
    """
    Load Baysor 3D molecule assignments.

    Returns
    -------
    pandas.DataFrame or None
        Baysor molecule table, if present.
    """
    molecules_path = (
        self._segmentation_root_path
        / Path("baysor")
        / Path("3D")
        / Path("molecules.parquet")
    )
    if not molecules_path.exists():
        print("Baysor molecules not found.")
        return None
    try:
        return self._load_from_parquet(molecules_path)
    except (OSError, ValueError) as exc:
        print(exc)
        print("Error loading Baysor molecules.")
        return None

`load_chromatic_affine_transform_zyx_um(channel_name=None, channel_index=None, wavelength_um=None)`

Load one chromatic affine transform with identity fallback.

Parameters:

Name	Type	Description	Default
`channel_name`	`str or None`	Channel name from the calibration metadata.	`None`
`channel_index`	`int or None`	Channel index from the calibration metadata.	`None`
`wavelength_um`	`float or None`	Channel wavelength in microns. Used only when channel name/index do not find a match.	`None`

Returns:

Type	Description
`ndarray`	4x4 affine matrix in physical Z, Y, X microns. Identity is returned if the calibration or requested channel is absent.

Source code in src/merfish3danalysis/qi2labDataStore.py

def load_chromatic_affine_transform_zyx_um(
    self,
    channel_name: str | None = None,
    channel_index: int | None = None,
    wavelength_um: float | None = None,
) -> np.ndarray:
    """
    Load one chromatic affine transform with identity fallback.

    Parameters
    ----------
    channel_name : str or None, default=None
        Channel name from the calibration metadata.
    channel_index : int or None, default=None
        Channel index from the calibration metadata.
    wavelength_um : float or None, default=None
        Channel wavelength in microns. Used only when channel name/index do
        not find a match.

    Returns
    -------
    numpy.ndarray
        4x4 affine matrix in physical Z, Y, X microns. Identity is returned
        if the calibration or requested channel is absent.
    """
    calibration = self.load_chromatic_affine_transforms_zyx_um()
    channels = calibration.get("channels", {})
    if not isinstance(channels, Mapping):
        return np.eye(4, dtype=np.float32)

    candidates = []
    if channel_name is not None:
        channel = channels.get(str(channel_name))
        if isinstance(channel, Mapping):
            candidates.append(channel)
    if channel_index is not None:
        for channel in channels.values():
            if isinstance(channel, Mapping) and int(
                channel.get("channel_index", -1)
            ) == int(channel_index):
                candidates.append(channel)
    if wavelength_um is not None:
        wavelength = float(wavelength_um)
        for channel in channels.values():
            if not isinstance(channel, Mapping):
                continue
            stored = channel.get("wavelength_um")
            if stored is not None and np.isclose(float(stored), wavelength):
                candidates.append(channel)

    for channel in candidates:
        affine = channel.get("affine_zyx_um")
        if affine is not None:
            return np.asarray(affine, dtype=np.float32)
    return np.eye(4, dtype=np.float32)

`load_chromatic_affine_transforms_zyx_um()`

Load chromatic affine calibration metadata.

Returns:

Type	Description
`dict[str, Any]`	Stored calibration metadata. Returns an empty dictionary when no chromatic calibration is present.

Source code in src/merfish3danalysis/qi2labDataStore.py

def load_chromatic_affine_transforms_zyx_um(self) -> dict[str, Any]:
    """
    Load chromatic affine calibration metadata.

    Returns
    -------
    dict[str, Any]
        Stored calibration metadata. Returns an empty dictionary when no
        chromatic calibration is present.
    """
    try:
        attributes = self._load_calibrations_attributes()
    except (FileNotFoundError, json.JSONDecodeError, ValueError):
        return {}
    calibration = attributes.get("chromatic_affine_transforms_zyx_um", {})
    if isinstance(calibration, dict):
        if "voxel_size_zyx_um" in calibration:
            calibration["voxel_size_zyx_um"] = round_spacing_um(
                calibration["voxel_size_zyx_um"]
            ).tolist()
        return calibration
    return {}

`load_codebook_parsed()`

Load and split codebook into gene_ids and codebook matrix.

Returns:

Name	Type	Description
`gene_ids`	`Collection[str]`	Gene IDs.
`codebook_matrix`	`ArrayLike`	Codebook matrix.

Source code in src/merfish3danalysis/qi2labDataStore.py

def load_codebook_parsed(
    self,
) -> tuple[Collection[str], ArrayLike] | None:
    """Load and split codebook into gene_ids and codebook matrix.

    Returns
    -------
    gene_ids : Collection[str]
        Gene IDs.
    codebook_matrix : ArrayLike
        Codebook matrix.
    """
    try:
        data = getattr(self, "_codebook", None)

        if data is None:
            return None
        num_columns = len(data[0]) if data else 0
        columns = ["gene_id"] + [f"bit{i:02d}" for i in range(1, num_columns)]
        codebook_df = pd.DataFrame(data, columns=columns)

        gene_ids = codebook_df.iloc[:, 0].tolist()
        codebook_matrix = codebook_df.iloc[:, 1:].to_numpy().astype(int)
        del data, codebook_df
        return gene_ids, codebook_matrix
    except (KeyError, ValueError, TypeError):
        print("Error parsing codebook.")
        return None

`load_coord_of_xform_px(tile, round, return_future=True)`

Local fiducial optical flow matrix for one round and tile.

Parameters:

Name	Type	Description	Default
`tile`	`int or str or None`	Tile index or tile id.	required
`round`	`int or str or None`	Round index or round id.	required
`return_future`	`bool or None`	True returns a read future, False returns a NumPy array, and None returns a sliceable TensorStore handle opened through yaozarrs.	`True`

Returns:

Name	Type	Description
`of_xform_px`	`ndarray or Future or TensorStore`	Local fiducial optical flow matrix for one round and tile.
`block_size`	`ndarray`	Block size used for the pixel warp.
`block_stride`	`ndarray`	Block stride used for the pixel warp.
	`Returns None when the image or required metadata is unavailable.`

Source code in src/merfish3danalysis/qi2labDataStore.py

def load_coord_of_xform_px(
    self,
    tile: int | str | None,
    round: int | str | None,
    return_future: bool | None = True,
) -> "tuple[np.ndarray | Future | TensorStore, np.ndarray, np.ndarray] | None":
    """Local fiducial optical flow matrix for one round and tile.

    Parameters
    ----------
    tile : int or str or None
        Tile index or tile id.
    round : int or str or None
        Round index or round id.
    return_future : bool or None
        True returns a read future, False returns a NumPy array, and None
        returns a sliceable TensorStore handle opened through yaozarrs.

    Returns
    -------
    of_xform_px : numpy.ndarray or tensorstore.Future or tensorstore.TensorStore
        Local fiducial optical flow matrix for one round and tile.
    block_size : numpy.ndarray
        Block size used for the pixel warp.
    block_stride : numpy.ndarray
        Block stride used for the pixel warp.

    Returns None when the image or required metadata is unavailable.
    """
    if isinstance(tile, int):
        if tile < 0 or tile >= self._num_tiles:
            print("Set tile index >=0 and <" + str(self._num_tiles))
            return None
        else:
            tile_id = self._tile_ids[tile]
    elif isinstance(tile, str):
        if tile not in self._tile_ids:
            print("set valid tiled id")
            return None
        else:
            tile_id = tile
    else:
        print("'tile' must be integer index or string identifier")
        return None

    if isinstance(round, int):
        if round < 0 or round >= len(self._round_ids):
            print("Set round index >=0 and <" + str(self._num_rounds))
            return None
        else:
            round_id = self._round_ids[round]
    elif isinstance(round, str):
        if round not in self._round_ids:
            print("Set valid round id")
            return None
        else:
            round_id = round
    else:
        print("'round' must be integer index or string identifier")
        return None

    entity_root = self._fiducial_root_path / Path(tile_id) / Path(round_id)
    current_local_zarr_path = entity_root / Path("opticalflow_xform_px")

    image_path = self._image_store_path(current_local_zarr_path)
    if not image_path.exists():
        print("Optical flow transform mapping back to first round not found.")
        return None

    try:
        of_xform_px = self._load_from_zarr_array(image_path, return_future)
        attributes = self._load_entity_attributes(
            entity_root, image_names=("opticalflow_xform_px",)
        )
        block_size = np.asarray(attributes["block_size"], dtype=np.float32)
        block_stride = np.asarray(attributes["block_stride"], dtype=np.float32)

        return (of_xform_px, block_size, block_stride)
    except (OSError, ValueError, KeyError) as e:
        print(e)
        print("Error loading optical flow transform.")
        return None

`load_decode_normalization_metadata(decode_run_key, kind)`

Load provenance for default or run-scoped normalization vectors.

Source code in src/merfish3danalysis/qi2labDataStore.py

def load_decode_normalization_metadata(
    self,
    decode_run_key: str | None,
    kind: str,
) -> dict[str, Any] | None:
    """Load provenance for default or run-scoped normalization vectors."""
    if kind not in {"global", "iterative"}:
        raise ValueError("kind must be one of 'global' or 'iterative'.")
    calib_attrs = self._load_calibrations_attributes()
    if decode_run_key is None:
        metadata = calib_attrs.get("decode_normalization_metadata", {}).get(kind)
    else:
        decode_run_key = self._validate_decode_run_key(decode_run_key)
        metadata = (
            calib_attrs.get("decode_normalization_runs", {})
            .get(decode_run_key, {})
            .get(f"{kind}_metadata")
        )
    return dict(metadata) if isinstance(metadata, Mapping) else None

`load_decode_normalization_vectors(decode_run_key, kind)`

Load run-scoped normalization and background vectors.

Parameters:

Name	Type	Description	Default
`decode_run_key`	`str or None`	Optional decoded-output run key. None reads the default vectors.	required
`kind`	`('global', iterative)`	Normalization vector kind.	`'global'`

Returns:

Type	Description
`tuple[ndarray or None, ndarray or None]`	Normalization and background vectors.

Source code in src/merfish3danalysis/qi2labDataStore.py

def load_decode_normalization_vectors(
    self,
    decode_run_key: str | None,
    kind: str,
) -> tuple[np.ndarray | None, np.ndarray | None]:
    """
    Load run-scoped normalization and background vectors.

    Parameters
    ----------
    decode_run_key : str or None
        Optional decoded-output run key. None reads the default vectors.
    kind : {'global', 'iterative'}
        Normalization vector kind.

    Returns
    -------
    tuple[numpy.ndarray or None, numpy.ndarray or None]
        Normalization and background vectors.
    """
    if kind == "global":
        if decode_run_key is None:
            return self.global_normalization_vector, self.global_background_vector
        norm_key = "global_normalization_vector"
        background_key = "global_background_vector"
    elif kind == "iterative":
        if decode_run_key is None:
            return (
                self.iterative_normalization_vector,
                self.iterative_background_vector,
            )
        norm_key = "iterative_normalization_vector"
        background_key = "iterative_background_vector"
    else:
        raise ValueError("kind must be one of 'global' or 'iterative'.")

    decode_run_key = self._validate_decode_run_key(decode_run_key)
    calib_attrs = self._load_calibrations_attributes()
    run_attrs = calib_attrs.get("decode_normalization_runs", {}).get(
        decode_run_key, {}
    )
    normalization_vector = run_attrs.get(norm_key)
    background_vector = run_attrs.get(background_key)
    if normalization_vector is None or background_vector is None:
        return None, None
    return (
        np.asarray(normalization_vector, dtype=np.float32),
        np.asarray(background_vector, dtype=np.float32),
    )

`load_global_cellpose_outlines()`

Load Cellpose max projection cell outlines.

Returns:

Name	Type	Description
`cellpose_outlines`	`dict or None`	Cellpose cell mask outlines.

Source code in src/merfish3danalysis/qi2labDataStore.py

def load_global_cellpose_outlines(
    self,
) -> dict | None:
    """Load Cellpose max projection cell outlines.

    Returns
    -------
    cellpose_outlines : dict or None
        Cellpose cell mask outlines.
    """
    current_cellpose_outlines_path = (
        self._segmentation_root_path / Path("cellpose") / Path("cell_outlines.json")
    )

    if not current_cellpose_outlines_path.exists():
        print("Cellpose cell mask outlines not found.")
        return None
    else:
        cellpose_outlines = self._load_from_microjson(
            current_cellpose_outlines_path
        )
        return cellpose_outlines

`load_global_cellpose_roi_zip()`

Load global Cellpose outlines from an ImageJ ROI zip.

Returns:

Name	Type	Description
`cellpose_outlines`	`dict[int, ArrayLike] or None`	Cellpose ROI outlines with global X, Y coordinates.

Source code in src/merfish3danalysis/qi2labDataStore.py

def load_global_cellpose_roi_zip(
    self,
) -> dict[int, ArrayLike] | None:
    """Load global Cellpose outlines from an ImageJ ROI zip.

    Returns
    -------
    cellpose_outlines : dict[int, ArrayLike] or None
        Cellpose ROI outlines with global X, Y coordinates.
    """
    roi_path = (
        self._segmentation_root_path
        / Path("cellpose")
        / Path("imagej_rois")
        / Path("global_coords_rois.zip")
    )
    if not roi_path.exists():
        print("Cellpose global ROI zip not found.")
        return None

    try:
        from roifile import roiread
    except ImportError:
        print("roifile is required to load Cellpose ROI zip.")
        return None

    outlines: dict[int, ArrayLike] = {}
    try:
        for idx, roi in enumerate(roiread(roi_path)):
            coordinates = getattr(roi, "subpixel_coordinates", None)
            if coordinates is None:
                coordinates = roi.coordinates()
            if coordinates is not None:
                outlines[idx + 1] = np.asarray(coordinates, dtype=float)
        return outlines
    except (OSError, ValueError) as exc:
        print(exc)
        print("Error loading Cellpose ROI zip.")
        return None

`load_global_cellpose_segmentation_image(return_future=True)`

Load Cellpose max projection, downsampled segmentation image.

Parameters:

Name	Type	Description	Default
`return_future`	`bool or None`	True returns a read future, False returns a NumPy array, and None returns a sliceable TensorStore handle opened through yaozarrs.	`True`

Returns:

Name	Type	Description
`fused_image`	`ndarray or Future or TensorStore or None`	Cellpose max projection, downsampled segmentation image.

Source code in src/merfish3danalysis/qi2labDataStore.py

def load_global_cellpose_segmentation_image(
    self,
    return_future: bool | None = True,
) -> "np.ndarray | Future | TensorStore | None":
    """Load Cellpose max projection, downsampled segmentation image.

    Parameters
    ----------
    return_future : bool or None
        True returns a read future, False returns a NumPy array, and None
        returns a sliceable TensorStore handle opened through yaozarrs.

    Returns
    -------
    fused_image : numpy.ndarray or tensorstore.Future or tensorstore.TensorStore or None
        Cellpose max projection, downsampled segmentation image.
    """
    current_local_zarr_path = (
        self._segmentation_root_path
        / Path("cellpose")
        / Path(f"masks_{self.fiducial_folder_name}_iso_zyx")
    )

    image_path = self._image_store_path(current_local_zarr_path)
    if not image_path.exists():
        print("Cellpose prediction on global fused image not found.")
        return None

    try:
        fused_image = self._load_from_zarr_array(image_path, return_future)
        return fused_image
    except (OSError, ValueError):
        print("Error loading Cellpose image.")
        return None

`load_global_coord_xforms_um(tile)`

Load global registration transform for one tile.

Parameters:

Name	Type	Description	Default
`tile`	`int or str`	Tile index or tile id.	required

Returns:

Name	Type	Description
`affine_zyx_um`	`ArrayLike or None`	Global affine registration transform for one tile.
`origin_zyx_um`	`ArrayLike or None`	Global origin registration transform for one tile.
`spacing_zyx_um`	`ArrayLike or None`	Global spacing registration transform for one tile.

Source code in src/merfish3danalysis/qi2labDataStore.py

def load_global_coord_xforms_um(
    self,
    tile: int | str,
) -> tuple[ArrayLike | None, ArrayLike | None, ArrayLike | None] | None:
    """Load global registration transform for one tile.

    Parameters
    ----------
    tile : int or str
        Tile index or tile id.

    Returns
    -------
    affine_zyx_um : ArrayLike or None
        Global affine registration transform for one tile.
    origin_zyx_um : ArrayLike or None
        Global origin registration transform for one tile.
    spacing_zyx_um : ArrayLike or None
        Global spacing registration transform for one tile.
    """
    if isinstance(tile, int):
        if tile < 0 or tile >= self._num_tiles:
            print("Set tile index >=0 and <" + str(self._num_tiles))
            return None, None, None
        else:
            tile_id = self._tile_ids[tile]
    elif isinstance(tile, str):
        if tile not in self._tile_ids:
            print("set valid tiled id")
            return None, None, None
        else:
            tile_id = tile
    else:
        print("'tile' must be integer index or string identifier")
        return None

    try:
        entity_root = (
            self._fiducial_root_path / Path(tile_id) / Path(self._round_ids[0])
        )
        attributes = self._load_entity_attributes(entity_root)
        affine_zyx_um = np.asarray(attributes["affine_zyx_um"], dtype=np.float32)
        origin_zyx_um = np.asarray(attributes["origin_zyx_um"], dtype=np.float32)
        spacing_zyx_um = round_spacing_um(attributes["spacing_zyx_um"])
        return (affine_zyx_um, origin_zyx_um, spacing_zyx_um)
    except (FileNotFoundError, json.JSONDecodeError, KeyError):
        print(tile_id, self._round_ids[0])
        print("Global coordinate transforms not found")
        return None, None, None

`load_global_fiducial_image(return_future=True)`

Load downsampled, fused fiducial image.

Parameters:

Name	Type	Description	Default
`return_future`	`bool or None`	True returns a read future, False returns a NumPy array, and None returns a sliceable TensorStore handle opened through yaozarrs.	`True`

Returns:

Name	Type	Description
`fused_image`	`ndarray or Future or TensorStore or None`	Downsampled, fused fiducial image.
`affine_zyx_um`	`ArrayLike or None`	Global affine registration transform for fused image.
`origin_zyx_um`	`ArrayLike or None`	Global origin registration transform for fused image.
`spacing_zyx_um`	`ArrayLike or None`	Global spacing registration transform for fused image.

Source code in src/merfish3danalysis/qi2labDataStore.py

def load_global_fiducial_image(
    self,
    return_future: bool | None = True,
) -> "tuple[np.ndarray | Future | TensorStore, ArrayLike, ArrayLike, ArrayLike] | None":
    """Load downsampled, fused fiducial image.

    Parameters
    ----------
    return_future : bool or None
        True returns a read future, False returns a NumPy array, and None
        returns a sliceable TensorStore handle opened through yaozarrs.

    Returns
    -------
    fused_image : numpy.ndarray or tensorstore.Future or tensorstore.TensorStore or None
        Downsampled, fused fiducial image.
    affine_zyx_um : ArrayLike or None
        Global affine registration transform for fused image.
    origin_zyx_um : ArrayLike or None
        Global origin registration transform for fused image.
    spacing_zyx_um : ArrayLike or None
        Global spacing registration transform for fused image.
    """
    current_local_zarr_path = self._fused_root_path / Path(
        f"fused_{self.fiducial_folder_name}_zyx"
    )

    image_path = self._image_store_path(current_local_zarr_path)
    if not image_path.exists():
        print("Globally registered, fused image not found.")
        return None

    try:
        fused_image = self._load_from_zarr_array(image_path, return_future)
        attributes = self.load_image_metadata(image_path)
        affine_zyx_um = np.asarray(attributes["affine_zyx_um"], dtype=np.float32)
        origin_zyx_um = np.asarray(attributes["origin_zyx_um"], dtype=np.float32)
        spacing_zyx_um = round_spacing_um(attributes["spacing_zyx_um"])
        return fused_image, affine_zyx_um, origin_zyx_um, spacing_zyx_um
    except (OSError, ValueError, KeyError):
        print("Error loading globally registered, fused image.")
        return None

`load_global_filtered_decoded_spots(decode_run_key=None, gene_ids=None, columns=None)`

Load all decoded and filtered spots.

Parameters:

Name	Type	Description	Default
`decode_run_key`	`str or None`	Optional decoded-output run key.	`None`
`gene_ids`	`Collection[str] or None`	Optional gene ids to load.	`None`
`columns`	`Collection[str] or None`	Optional columns to load.	`None`

Returns:

Name	Type	Description
`all_tiles_filtered`	`DataFrame or None`	All decoded and filtered spots.

Source code in src/merfish3danalysis/qi2labDataStore.py

def load_global_filtered_decoded_spots(
    self,
    decode_run_key: str | None = None,
    gene_ids: Collection[str] | None = None,
    columns: Collection[str] | None = None,
) -> pd.DataFrame | None:
    """Load all decoded and filtered spots.

    Parameters
    ----------
    decode_run_key : str or None, default None
        Optional decoded-output run key.
    gene_ids : Collection[str] or None, default None
        Optional gene ids to load.
    columns : Collection[str] or None, default None
        Optional columns to load.

    Returns
    -------
    all_tiles_filtered : pandas.DataFrame or None
        All decoded and filtered spots.
    """
    current_global_filtered_decoded_dir_path = self._global_filtered_decoded_root(
        decode_run_key
    )
    current_global_filtered_decoded_path = (
        current_global_filtered_decoded_dir_path / Path("decoded_features.parquet")
    )

    if not current_global_filtered_decoded_path.exists():
        print("Global, filtered, decoded spots not found.")
        return None
    elif gene_ids is not None or columns is not None:
        selected_gene_ids = (
            [str(gene_id) for gene_id in gene_ids] if gene_ids is not None else []
        )
        filters = (
            [("gene_id", "in", selected_gene_ids)] if gene_ids is not None else None
        )
        all_tiles_filtered = pd.read_parquet(
            current_global_filtered_decoded_path,
            columns=None if columns is None else list(columns),
            filters=filters,
        )
        if gene_ids is not None and "gene_id" in all_tiles_filtered.columns:
            all_tiles_filtered = all_tiles_filtered[
                all_tiles_filtered["gene_id"].astype(str).isin(selected_gene_ids)
            ]
        return all_tiles_filtered
    else:
        all_tiles_filtered = self._load_from_parquet(
            current_global_filtered_decoded_path
        )
        return all_tiles_filtered

`load_image_metadata(image_path)` `staticmethod`

Load extra attributes through yaozarrs.

Parameters:

Name	Type	Description	Default
`image_path`	`Path \| str`	Image store path.	required

Returns:

Type	Description
`dict[str, Any]`	Extra attributes stored on the image root.

Source code in src/merfish3danalysis/qi2labDataStore.py

@staticmethod
def load_image_metadata(image_path: Path | str) -> dict[str, Any]:
    """
    Load extra attributes through yaozarrs.

    Parameters
    ----------
    image_path : Path | str
        Image store path.

    Returns
    -------
    dict[str, Any]
        Extra attributes stored on the image root.
    """
    image_root = qi2labDataStore._image_store_path(image_path)
    attrs = dict(open_group(str(image_root)).attrs)
    attrs.pop("ome", None)
    for key in ("spacing_zyx_um", "voxel_size_zyx_um"):
        if key in attrs:
            attrs[key] = round_spacing_um(attrs[key]).tolist()
    return attrs

`load_local_bit_linker(tile, round)`

Load readout bits linked to fiducial round for one tile.

Parameters:

Name	Type	Description	Default
`tile`	`int or str`	Tile index or tile id.	required
`round`	`int or str`	Round index or round id.	required

Returns:

Name	Type	Description
`bit_linker`	`Sequence[int] or None`	Readout bits linked to fiducial round for one tile.

Source code in src/merfish3danalysis/qi2labDataStore.py

def load_local_bit_linker(
    self,
    tile: int | str,
    round: int | str,
) -> Sequence[int] | None:
    """Load readout bits linked to fiducial round for one tile.

    Parameters
    ----------
    tile : int or str
        Tile index or tile id.
    round : int or str
        Round index or round id.

    Returns
    -------
    bit_linker : Sequence[int] or None
        Readout bits linked to fiducial round for one tile.
    """
    if isinstance(tile, int):
        if tile < 0 or tile >= self._num_tiles:
            print("Set tile index >=0 and <" + str(self._num_tiles))
            return None
        else:
            tile_id = self._tile_ids[tile]
    elif isinstance(tile, str):
        if tile not in self._tile_ids:
            print("set valid tiled id.")
            return None
        else:
            tile_id = tile
    else:
        print("'tile' must be integer index or string identifier")
        return None

    if isinstance(round, int):
        if round < 0 or round >= len(self._round_ids):
            print("Set round index >=0 and <" + str(self._num_rounds))
            return None
        else:
            round_id = self._round_ids[round]
    elif isinstance(round, str):
        if round not in self._round_ids:
            print("Set valid round id.")
            return None
        else:
            round_id = round
    else:
        print("'round' must be integer index or string identifier")
        return None

    try:
        entity_root = self._fiducial_root_path / Path(tile_id) / Path(round_id)
        attributes = self._load_entity_attributes(entity_root)
        bit_linker = attributes.get("bit_linker")
        if bit_linker is None:
            print(tile_id, round_id)
            print("Bit linker attribute not found.")
            return None
        return [int(v) for v in list(bit_linker)]
    except (TypeError, ValueError):
        print(tile_id, round_id)
        print("Bit linker attribute not found.")
        return None

`load_local_corrected_image(tile, round=None, bit=None, return_future=True)`

Load gain and offset corrected image for fiducial OR readout bit for one tile.

Parameters:

Name	Type	Description	Default
`tile`	`int or str`	Tile index or tile id.	required
`round`	`int or str or None`	Round index or round id.	`None`
`bit`	`int or str or None`	Bit index or bit id.	`None`
`return_future`	`bool or None`	True returns a read future, False returns a NumPy array, and None returns a sliceable TensorStore handle opened through yaozarrs.	`True`

Returns:

Name	Type	Description
`corrected_image`	`ndarray or Future or TensorStore or None`	Gain and offset corrected image for fiducial OR readout bit for one tile.

Source code in src/merfish3danalysis/qi2labDataStore.py

def load_local_corrected_image(
    self,
    tile: int | str,
    round: int | str | None = None,
    bit: int | str | None = None,
    return_future: bool | None = True,
) -> "np.ndarray | Future | TensorStore | None":
    """Load gain and offset corrected image for fiducial OR readout bit for one tile.

    Parameters
    ----------
    tile : int or str
        Tile index or tile id.
    round : int or str or None
        Round index or round id.
    bit : int or str or None
        Bit index or bit id.
    return_future : bool or None
        True returns a read future, False returns a NumPy array, and None
        returns a sliceable TensorStore handle opened through yaozarrs.

    Returns
    -------
    corrected_image : numpy.ndarray or tensorstore.Future or tensorstore.TensorStore or None
        Gain and offset corrected image for fiducial OR readout bit for one tile.
    """
    if (round is None and bit is None) or (round is not None and bit is not None):
        print("Provide either 'round' or 'bit', but not both")
        return None

    if isinstance(tile, int):
        if tile < 0 or tile >= self._num_tiles:
            print("Set tile index >=0 and <" + str(self._num_tiles))
            return None
        else:
            tile_id = self._tile_ids[tile]
    elif isinstance(tile, str):
        if tile not in self._tile_ids:
            print("set valid tiled id")
            return None
        else:
            tile_id = tile
    else:
        print("'tile' must be integer index or string identifier")
        return None

    if bit is not None:
        if isinstance(bit, int):
            if bit < 0 or bit >= len(self._bit_ids):
                print("Set bit index >=0 and <" + str(len(self._bit_ids)))
                return None
            else:
                local_id = self._bit_ids[bit]
        elif isinstance(bit, str):
            if bit not in self._bit_ids:
                print("Set valid bit id")
                return None
            else:
                local_id = bit
        else:
            print("'bit' must be integer index or string identifier")
            return None
        current_local_zarr_path = str(
            self._readouts_root_path
            / Path(tile_id)
            / Path(local_id)
            / Path("corrected_data")
        )
    else:
        if isinstance(round, int):
            if round < 0 or round >= len(self._round_ids):
                print("Set round index >=0 and <" + str(self._num_rounds))
                return None
            else:
                local_id = self._round_ids[round]
        elif isinstance(round, str):
            if round not in self._round_ids:
                print("Set valid round id")
                return None
            else:
                local_id = round
        else:
            print("'round' must be integer index or string identifier")
            return None
        current_local_zarr_path = str(
            self._fiducial_root_path
            / Path(tile_id)
            / Path(local_id)
            / Path("corrected_data")
        )

    image_path = self._image_store_path(current_local_zarr_path)
    if not image_path.exists():
        print("Corrected image not found.")
        return None

    try:
        corrected_image = self._load_from_zarr_array(image_path, return_future)
        return corrected_image
    except (OSError, ValueError):
        print("Error loading corrected image.")
        return None

`load_local_decoded_spots(tile, decode_run_key=None)`

Load decoded spots and features for one tile.

Parameters:

Name	Type	Description	Default
`tile`	`int or str`	Tile index or tile id.	required
`decode_run_key`	`str or None`	Optional decoded-output run key.	`None`

Returns:

Name	Type	Description
`tile_features`	`DataFrame or None`	Decoded spots and features for one tile.

Source code in src/merfish3danalysis/qi2labDataStore.py

def load_local_decoded_spots(
    self,
    tile: int | str,
    decode_run_key: str | None = None,
) -> pd.DataFrame | None:
    """Load decoded spots and features for one tile.

    Parameters
    ----------
    tile : int or str
        Tile index or tile id.
    decode_run_key : str or None, default None
        Optional decoded-output run key.

    Returns
    -------
    tile_features : pandas.DataFrame or None
        Decoded spots and features for one tile.
    """
    if isinstance(tile, int):
        if tile < 0 or tile >= self._num_tiles:
            print("Set tile index >=0 and <" + str(self._num_tiles))
            return None
        else:
            tile_id = self._tile_ids[tile]
    elif isinstance(tile, str):
        if tile not in self._tile_ids:
            print("set valid tiled id")
            return None
        else:
            tile_id = tile
    else:
        print("'tile' must be integer index or string identifier")
        return None

    current_tile_features_path = self._decoded_run_root(decode_run_key) / Path(
        tile_id + "_decoded_features.parquet"
    )

    if not current_tile_features_path.exists():
        print("Decoded spots not found.")
        return None
    else:
        tile_features = self._load_from_parquet(current_tile_features_path)
        return tile_features

`load_local_deconvolved_fiducial_image(tile, round, return_future=True)`

Load a native-frame deconvolved fiducial image.

Deconvolved fiducials are loaded from decon_data in their native, unwarped tile frame. This image exists only when fiducial deconvolution was run during preprocessing.

Parameters:

Name	Type	Description	Default
`tile`	`int or str`	Tile index or tile id.	required
`round`	`int or str`	Round index or round id.	required
`return_future`	`bool or None`	True returns a read future, False returns a NumPy array, and None returns a sliceable TensorStore handle opened through yaozarrs.	`True`

Returns:

Type	Description
`ndarray or Future or TensorStore or None`	Native-frame deconvolved fiducial image.

Source code in src/merfish3danalysis/qi2labDataStore.py

def load_local_deconvolved_fiducial_image(
    self,
    tile: int | str,
    round: int | str,
    return_future: bool | None = True,
) -> "np.ndarray | Future | TensorStore | None":
    """Load a native-frame deconvolved fiducial image.

    Deconvolved fiducials are loaded from ``decon_data`` in their native,
    unwarped tile frame. This image exists only when fiducial deconvolution
    was run during preprocessing.

    Parameters
    ----------
    tile : int or str
        Tile index or tile id.
    round : int or str
        Round index or round id.
    return_future : bool or None
        True returns a read future, False returns a NumPy array, and None
        returns a sliceable TensorStore handle opened through yaozarrs.

    Returns
    -------
    numpy.ndarray or tensorstore.Future or tensorstore.TensorStore or None
        Native-frame deconvolved fiducial image.
    """
    if isinstance(tile, int):
        if tile < 0 or tile >= self._num_tiles:
            print("Set tile index >=0 and <" + str(self._num_tiles))
            return None
        tile_id = self._tile_ids[tile]
    elif isinstance(tile, str):
        if tile not in self._tile_ids:
            print("set valid tiled id")
            return None
        tile_id = tile
    else:
        print("'tile' must be integer index or string identifier")
        return None

    if isinstance(round, int):
        if round < 0 or round >= len(self._round_ids):
            print("Set round index >=0 and <" + str(self._num_rounds))
            return None
        round_id = self._round_ids[round]
    elif isinstance(round, str):
        if round not in self._round_ids:
            print("Set valid round id")
            return None
        round_id = round
    else:
        print("'round' must be integer index or string identifier")
        return None

    decon_path = self._fiducial_root_path / tile_id / round_id / Path("decon_data")
    image_path = self._image_store_path(decon_path)
    if not image_path.exists():
        return None

    try:
        return self._load_from_zarr_array(image_path, return_future)
    except (OSError, ValueError) as e:
        print(e)
        print("Error loading local deconvolved fiducial image.")
        return None

`load_local_deconvolved_readout_image(tile, bit, return_future=True)`

Load a native-frame deconvolved readout bit image.

Deconvolved readout bits are loaded from decon_data in their native, unwarped tile frame. This image exists only when readout deconvolution was run during preprocessing.

Parameters:

Name	Type	Description	Default
`tile`	`int or str`	Tile index or tile id.	required
`bit`	`int or str`	Bit index or bit id.	required
`return_future`	`bool or None`	True returns a read future, False returns a NumPy array, and None returns a sliceable TensorStore handle opened through yaozarrs.	`True`

Returns:

Type	Description
`ndarray or Future or TensorStore or None`	Native-frame deconvolved readout image.

Source code in src/merfish3danalysis/qi2labDataStore.py

def load_local_deconvolved_readout_image(
    self,
    tile: int | str,
    bit: int | str,
    return_future: bool | None = True,
) -> "np.ndarray | Future | TensorStore | None":
    """Load a native-frame deconvolved readout bit image.

    Deconvolved readout bits are loaded from ``decon_data`` in their
    native, unwarped tile frame. This image exists only when readout
    deconvolution was run during preprocessing.

    Parameters
    ----------
    tile : int or str
        Tile index or tile id.
    bit : int or str
        Bit index or bit id.
    return_future : bool or None
        True returns a read future, False returns a NumPy array, and None
        returns a sliceable TensorStore handle opened through yaozarrs.

    Returns
    -------
    numpy.ndarray or tensorstore.Future or tensorstore.TensorStore or None
        Native-frame deconvolved readout image.
    """
    if isinstance(tile, int):
        if tile < 0 or tile >= self._num_tiles:
            print("Set tile index >=0 and <" + str(self._num_tiles))
            return None
        tile_id = self._tile_ids[tile]
    elif isinstance(tile, str):
        if tile not in self._tile_ids:
            print("set valid tiled id")
            return None
        tile_id = tile
    else:
        print("'tile' must be integer index or string identifier")
        return None

    if isinstance(bit, int):
        if bit < 0 or bit >= len(self._bit_ids):
            print("Set bit index >=0 and <" + str(len(self._bit_ids)))
            return None
        bit_id = self._bit_ids[bit]
    elif isinstance(bit, str):
        if bit not in self._bit_ids:
            print("Set valid bit id")
            return None
        bit_id = bit
    else:
        print("'bit' must be integer index or string identifier")
        return None

    readout_path = (
        self._readouts_root_path / Path(tile_id) / Path(bit_id) / Path("decon_data")
    )
    image_path = self._image_store_path(readout_path)
    if not image_path.exists():
        return None

    try:
        return self._load_from_zarr_array(image_path, return_future)
    except (OSError, ValueError) as e:
        print(e)
        print("Error loading local deconvolved readout image.")
        return None

`load_local_feature_predictor_image(tile, bit, return_future=True)`

Load readout bit feature_predictor prediction image for one tile.

Parameters:

Name	Type	Description	Default
`tile`	`int or str`	Tile index or tile id.	required
`bit`	`int or str`	Bit index or bit id.	required
`return_future`	`bool or None`	True returns a read future, False returns a NumPy array, and None returns a sliceable TensorStore handle opened through yaozarrs.	`True`

Returns:

Name	Type	Description
`feature_predictor_image`	`ndarray or Future or TensorStore or None`	feature_predictor prediction image for one tile.

Source code in src/merfish3danalysis/qi2labDataStore.py

def load_local_feature_predictor_image(
    self,
    tile: int | str,
    bit: int | str,
    return_future: bool | None = True,
) -> "np.ndarray | Future | TensorStore | None":
    """Load readout bit feature_predictor prediction image for one tile.

    Parameters
    ----------
    tile : int or str
        Tile index or tile id.
    bit : int or str
        Bit index or bit id.
    return_future : bool or None
        True returns a read future, False returns a NumPy array, and None
        returns a sliceable TensorStore handle opened through yaozarrs.

    Returns
    -------
    feature_predictor_image : numpy.ndarray or tensorstore.Future or tensorstore.TensorStore or None
        feature_predictor prediction image for one tile.
    """
    if isinstance(tile, int):
        if tile < 0 or tile >= self._num_tiles:
            print("Set tile index >=0 and <" + str(self._num_tiles))
            return None
        else:
            tile_id = self._tile_ids[tile]
    elif isinstance(tile, str):
        if tile not in self._tile_ids:
            print("set valid tiled id")
            return None
        else:
            tile_id = tile
    else:
        print("'tile' must be integer index or string identifier")
        return None

    if isinstance(bit, int):
        if bit < 0 or bit >= len(self._bit_ids):
            print("Set bit index >=0 and <" + str(len(self._bit_ids)))
            return None
        else:
            bit_id = self._bit_ids[bit]
    elif isinstance(bit, str):
        if bit not in self._bit_ids:
            print("Set valid bit id")
            return None
        else:
            bit_id = bit
    else:
        print("'bit' must be integer index or string identifier")
        return None

    current_local_zarr_path = str(
        self._readouts_root_path
        / Path(tile_id)
        / Path(bit_id)
        / Path(f"{self.feature_predictor_folder_name}_data")
    )

    image_path = self._image_store_path(current_local_zarr_path)
    if not image_path.exists():
        print("feature_predictor prediction image not found.")
        return None

    try:
        feature_predictor_image = self._load_from_zarr_array(
            image_path, return_future
        )
        return feature_predictor_image
    except (OSError, ValueError) as e:
        print(e)
        print("Error loading feature_predictor image.")
        return None

`load_local_feature_predictor_spots(tile, bit)`

Load feature_predictor spot localizations and features for one tile.

Parameters:

Name	Type	Description	Default
`tile`	`int or str`	Tile index or tile id.	required
`bit`	`int or str`	Bit index or bit id.	required

Returns:

Name	Type	Description
`feature_predictor_localizations`	`DataFrame or None`	feature_predictor localizations and features for one tile.

Source code in src/merfish3danalysis/qi2labDataStore.py

def load_local_feature_predictor_spots(
    self,
    tile: int | str,
    bit: int | str,
) -> pd.DataFrame | None:
    """Load feature_predictor spot localizations and features for one tile.

    Parameters
    ----------
    tile : int or str
        Tile index or tile id.
    bit : int or str
        Bit index or bit id.

    Returns
    -------
    feature_predictor_localizations : pandas.DataFrame or None
        feature_predictor localizations and features for one tile.
    """
    if isinstance(tile, int):
        if tile < 0 or tile >= self._num_tiles:
            print("Set tile index >=0 and <" + str(self._num_tiles))
            return None
        else:
            tile_id = self._tile_ids[tile]
    elif isinstance(tile, str):
        if tile not in self._tile_ids:
            print("set valid tiled id")
            return None
        else:
            tile_id = tile
    else:
        print("'tile' must be integer index or string identifier")
        return None

    if isinstance(bit, int):
        if bit < 0 or bit >= len(self._bit_ids):
            print("Set bit index >=0 and <" + str(len(self._bit_ids)))
            return None
        else:
            bit_id = self._bit_ids[bit]
    elif isinstance(bit, str):
        if bit not in self._bit_ids:
            print("Set valid bit id")
            return None
        else:
            bit_id = bit
    else:
        print("'bit' must be integer index or string identifier")
        return None

    current_feature_predictor_localizations_path = (
        self._feature_predictor_localizations_root_path
        / Path(tile_id)
        / Path(bit_id + ".parquet")
    )

    if not current_feature_predictor_localizations_path.exists():
        print("feature_predictor localizations not found.")
        return None
    else:
        feature_predictor_localizations = self._load_from_parquet(
            current_feature_predictor_localizations_path
        )
        return feature_predictor_localizations

`load_local_fiducial_image(tile, round, return_future=True)`

Load the best available native-frame fiducial image.

Deconvolved fiducial data are returned when decon_data exists; otherwise corrected fiducial data are returned.

Parameters:

Name	Type	Description	Default
`tile`	`int or str`	Tile index or tile id.	required
`round`	`int or str`	Round index or round id.	required
`return_future`	`bool or None`	True returns a read future, False returns a NumPy array, and None returns a sliceable TensorStore handle opened through yaozarrs.	`True`

Returns:

Type	Description
`ndarray or Future or TensorStore or None`	Deconvolved fiducial image if available, otherwise corrected image.

Source code in src/merfish3danalysis/qi2labDataStore.py

def load_local_fiducial_image(
    self,
    tile: int | str,
    round: int | str,
    return_future: bool | None = True,
) -> "np.ndarray | Future | TensorStore | None":
    """Load the best available native-frame fiducial image.

    Deconvolved fiducial data are returned when ``decon_data`` exists;
    otherwise corrected fiducial data are returned.

    Parameters
    ----------
    tile : int or str
        Tile index or tile id.
    round : int or str
        Round index or round id.
    return_future : bool or None
        True returns a read future, False returns a NumPy array, and None
        returns a sliceable TensorStore handle opened through yaozarrs.

    Returns
    -------
    numpy.ndarray or tensorstore.Future or tensorstore.TensorStore or None
        Deconvolved fiducial image if available, otherwise corrected image.
    """
    image = self.load_local_deconvolved_fiducial_image(
        tile=tile,
        round=round,
        return_future=return_future,
    )
    if image is not None:
        return image
    return self.load_local_corrected_image(
        tile=tile,
        round=round,
        return_future=return_future,
    )

`load_local_image_metadata(tile, *, round=None, bit=None, image_names=None)`

Load image and sidecar metadata for one fiducial round or readout bit.

Parameters:

Name	Type	Description	Default
`tile`	`int or str`	Tile index or identifier.	required
`round`	`int or str or None`	Fiducial round index or identifier; excludes bit.	`None`
`bit`	`int or str or None`	Readout bit index or identifier; excludes round.	`None`
`image_names`	`Sequence[str] or None`	Image names to inspect, in metadata precedence order.	`None`

Returns:

Type	Description
`dict[str, Any]`	Merged image metadata, with sidecar values taking precedence.

Source code in src/merfish3danalysis/qi2labDataStore.py

def load_local_image_metadata(
    self,
    tile: int | str,
    *,
    round: int | str | None = None,
    bit: int | str | None = None,
    image_names: Sequence[str] | None = None,
) -> dict[str, Any]:
    """Load image and sidecar metadata for one fiducial round or readout bit.

    Parameters
    ----------
    tile : int or str
        Tile index or identifier.
    round : int or str or None
        Fiducial round index or identifier; excludes bit.
    bit : int or str or None
        Readout bit index or identifier; excludes round.

    image_names : Sequence[str] or None
        Image names to inspect, in metadata precedence order.

    Returns
    -------
    dict[str, Any]
        Merged image metadata, with sidecar values taking precedence.
    """
    path = self.local_image_path(tile, "corrected_data", round=round, bit=bit)
    return self._load_entity_attributes(path.parent, image_names=image_names)

`load_local_readout_image(tile, bit, return_future=True)`

Load the best available native-frame readout bit image.

Deconvolved readout data are returned when decon_data exists; otherwise corrected readout data are returned.

Parameters:

Name	Type	Description	Default
`tile`	`int or str`	Tile index or tile id.	required
`bit`	`int or str`	Bit index or bit id.	required
`return_future`	`bool or None`	True returns a read future, False returns a NumPy array, and None returns a sliceable TensorStore handle opened through yaozarrs.	`True`

Returns:

Type	Description
`ndarray or Future or TensorStore or None`	Deconvolved readout image if available, otherwise corrected image.

Source code in src/merfish3danalysis/qi2labDataStore.py

def load_local_readout_image(
    self,
    tile: int | str,
    bit: int | str,
    return_future: bool | None = True,
) -> "np.ndarray | Future | TensorStore | None":
    """Load the best available native-frame readout bit image.

    Deconvolved readout data are returned when ``decon_data`` exists;
    otherwise corrected readout data are returned.

    Parameters
    ----------
    tile : int or str
        Tile index or tile id.
    bit : int or str
        Bit index or bit id.
    return_future : bool or None
        True returns a read future, False returns a NumPy array, and None
        returns a sliceable TensorStore handle opened through yaozarrs.

    Returns
    -------
    numpy.ndarray or tensorstore.Future or tensorstore.TensorStore or None
        Deconvolved readout image if available, otherwise corrected image.
    """
    image = self.load_local_deconvolved_readout_image(
        tile=tile,
        bit=bit,
        return_future=return_future,
    )
    if image is not None:
        return image
    return self.load_local_corrected_image(
        tile=tile,
        bit=bit,
        return_future=return_future,
    )

`load_local_rigid_xform_xyz_px(tile, round)`

Load calculated rigid registration transform for one round and tile.

Parameters:

Name	Type	Description	Default
`tile`	`int or str`	Tile index or tile id.	required
`round`	`int or str`	Round index or round id.	required

Returns:

Name	Type	Description
`rigid_xform_xyz_px`	`ArrayLike or None`	Local rigid registration transform for one round and tile.

Source code in src/merfish3danalysis/qi2labDataStore.py

def load_local_rigid_xform_xyz_px(
    self,
    tile: int | str,
    round: int | str,
) -> ArrayLike | None:
    """Load calculated rigid registration transform for one round and tile.

    Parameters
    ----------
    tile : int or str
        Tile index or tile id.
    round : int or str
        Round index or round id.

    Returns
    -------
    rigid_xform_xyz_px : ArrayLike or None
        Local rigid registration transform for one round and tile.
    """
    if isinstance(tile, int):
        if tile < 0 or tile >= self._num_tiles:
            print("Set tile index >=0 and <" + str(self._num_tiles))
            return None
        else:
            tile_id = self._tile_ids[tile]
    elif isinstance(tile, str):
        if tile not in self._tile_ids:
            print("set valid tiled id")
            return None
        else:
            tile_id = tile
    else:
        print("'tile' must be integer index or string identifier")
        return None

    if isinstance(round, int):
        if round < 0 or round >= len(self._round_ids):
            print("Set round index >=0 and <" + str(self._num_rounds))
            return None
        else:
            round_id = self._round_ids[round]
    elif isinstance(round, str):
        if round not in self._round_ids:
            print("Set valid round id")
            return None
        else:
            round_id = round
    else:
        print("'round' must be integer index or string identifier")
        return None
    try:
        entity_root = self._fiducial_root_path / Path(tile_id) / Path(round_id)
        attributes = self._load_entity_attributes(entity_root)
        rigid_xform_xyz_px = np.asarray(
            attributes["rigid_xform_xyz_px"], dtype=np.float32
        )
        return rigid_xform_xyz_px
    except (FileNotFoundError, json.JSONDecodeError, KeyError):
        print(tile_id, round_id)
        print("Rigid transform mapping back to first round not found.")
        return None

`load_local_round_linker(tile, bit)`

Load fiducial round linked to readout bit for one tile.

Parameters:

Name	Type	Description	Default
`tile`	`int or str`	Tile index or tile id.	required
`bit`	`int or str`	Bit index or bit id.	required

Returns:

Name	Type	Description
`round_linker`	`Sequence[int] or None`	Fiducial round linked to readout bit for one tile.

Source code in src/merfish3danalysis/qi2labDataStore.py

def load_local_round_linker(
    self,
    tile: int | str,
    bit: int | str,
) -> Sequence[int] | None:
    """Load fiducial round linked to readout bit for one tile.

    Parameters
    ----------
    tile : int or str
        Tile index or tile id.
    bit : int or str
        Bit index or bit id.

    Returns
    -------
    round_linker : Sequence[int] or None
        Fiducial round linked to readout bit for one tile.
    """
    if isinstance(tile, int):
        if tile < 0 or tile >= self._num_tiles:
            print("Set tile index >=0 and <" + str(self._num_tiles))
            return None
        else:
            tile_id = self._tile_ids[tile]
    elif isinstance(tile, str):
        if tile not in self._tile_ids:
            print("set valid tiled id.")
            return None
        else:
            tile_id = tile
    else:
        print("'tile' must be integer index or string identifier")
        return None

    if isinstance(bit, int):
        if bit < 0 or bit >= len(self._bit_ids):
            print("Set bit index >=0 and <" + str(len(self._bit_ids)))
            return None
        else:
            bit_id = self._bit_ids[bit]
    elif isinstance(bit, str):
        if bit not in self._bit_ids:
            print("Set valid bit id.")
            return None
        else:
            bit_id = bit
    else:
        print("'bit' must be integer index or string identifier")
        return None

    try:
        entity_root = self._readouts_root_path / Path(tile_id) / Path(bit_id)
        attributes = self._load_entity_attributes(entity_root)
        round_linker = attributes.get("round_linker")
        if round_linker is None:
            print(tile_id, bit_id)
            print("Round linker attribute not found.")
            return None
        return int(round_linker)
    except (TypeError, ValueError):
        print(tile_id, bit_id)
        print("Round linker attribute not found.")
        return None

`load_local_round_transform_zyx_um(tile, round)`

Load the local fiducial round transform for one tile.

Parameters:

Name	Type	Description	Default
`tile`	`int \| str`	Tile index or tile identifier.	required
`round`	`int \| str`	Fiducial round index or round identifier.	required

Returns:

Type	Description
`ArrayLike or None`	Homogeneous 4x4 affine transform in physical Z, Y, X microns. The transform maps first-round reference coordinates to coordinates in the requested moving round. Returns None when the transform is not present.

Source code in src/merfish3danalysis/qi2labDataStore.py

def load_local_round_transform_zyx_um(
    self,
    tile: int | str,
    round: int | str,
) -> ArrayLike | None:
    """
    Load the local fiducial round transform for one tile.

    Parameters
    ----------
    tile : int | str
        Tile index or tile identifier.
    round : int | str
        Fiducial round index or round identifier.

    Returns
    -------
    ArrayLike or None
        Homogeneous 4x4 affine transform in physical Z, Y, X microns. The
        transform maps first-round reference coordinates to coordinates in
        the requested moving round. Returns None when the transform is not
        present.
    """
    if isinstance(tile, int):
        if tile < 0 or tile >= self._num_tiles:
            print("Set tile index >=0 and <" + str(self._num_tiles))
            return None
        tile_id = self._tile_ids[tile]
    elif isinstance(tile, str):
        if tile not in self._tile_ids:
            print("set valid tiled id")
            return None
        tile_id = tile
    else:
        print("'tile' must be integer index or string identifier")
        return None

    if isinstance(round, int):
        if round < 0 or round >= len(self._round_ids):
            print("Set round index >=0 and <" + str(self._num_rounds))
            return None
        round_id = self._round_ids[round]
    elif isinstance(round, str):
        if round not in self._round_ids:
            print("Set valid round id")
            return None
        round_id = round
    else:
        print("'round' must be integer index or string identifier")
        return None
    try:
        entity_root = self._fiducial_root_path / Path(tile_id) / Path(round_id)
        attributes = self._load_entity_attributes(entity_root)
        return np.asarray(
            attributes["local_round_transform_zyx_um"], dtype=np.float32
        )
    except (FileNotFoundError, json.JSONDecodeError, KeyError):
        print(tile_id, round_id)
        print("Local round transform mapping back to first round not found.")
        return None

`load_local_sofima_flow_field(*, tile, round, return_future=True)`

Load the SOFIMA flow field for one local fiducial round.

Parameters:

Name	Type	Description	Default
`tile`	`int or str`	Tile index or tile identifier.	required
`round`	`int or str`	Moving fiducial round index or identifier.	required
`return_future`	`bool or None`	True returns a read future, False returns a NumPy array, and None returns a sliceable TensorStore handle opened through yaozarrs.	`True`

Returns:

Type	Description
`tuple[ndarray or Future or TensorStore, dict] or None`	SOFIMA flow field and metadata attributes. The map channels are X, Y, Z and spatial axes are Z, Y, X. `map_stride_zyx_px` is stored in Z, Y, X order. `map_box_start_xyz_px` is stored in X, Y, Z order and gives the reference-grid coordinate of the first flow sample. For fields produced by SOFIMA this is the patch center coordinate, not the image corner.

Source code in src/merfish3danalysis/qi2labDataStore.py

def load_local_sofima_flow_field(
    self,
    *,
    tile: int | str,
    round: int | str,
    return_future: bool | None = True,
) -> "tuple[np.ndarray | Future | TensorStore, dict] | None":
    """
    Load the SOFIMA flow field for one local fiducial round.

    Parameters
    ----------
    tile : int or str
        Tile index or tile identifier.
    round : int or str
        Moving fiducial round index or identifier.
    return_future : bool or None, default=True
        True returns a read future, False returns a NumPy array, and None
        returns a sliceable TensorStore handle opened through yaozarrs.

    Returns
    -------
    tuple[numpy.ndarray or tensorstore.Future or tensorstore.TensorStore, dict] or None
        SOFIMA flow field and metadata attributes. The map channels are X,
        Y, Z and spatial axes are Z, Y, X. ``map_stride_zyx_px`` is stored
        in Z, Y, X order. ``map_box_start_xyz_px`` is stored in X, Y, Z
        order and gives the reference-grid coordinate of the first flow
        sample. For fields produced by SOFIMA this is the patch center
        coordinate, not the image corner.
    """
    if isinstance(tile, int):
        if tile < 0 or tile >= self._num_tiles:
            print("Set tile index >=0 and <" + str(self._num_tiles))
            return None
        tile_id = self._tile_ids[tile]
    elif isinstance(tile, str):
        if tile not in self._tile_ids:
            print("set valid tiled id")
            return None
        tile_id = tile
    else:
        print("'tile' must be integer index or string identifier")
        return None

    if isinstance(round, int):
        if round < 0 or round >= len(self._round_ids):
            print("Set round index >=0 and <" + str(self._num_rounds))
            return None
        round_id = self._round_ids[round]
    elif isinstance(round, str):
        if round not in self._round_ids:
            print("Set valid round id")
            return None
        round_id = round
    else:
        print("'round' must be integer index or string identifier")
        return None

    image_name = "local_sofima_flow_field"
    entity_root = self._fiducial_root_path / Path(tile_id) / Path(round_id)
    current_local_zarr_path = entity_root / Path(image_name)
    image_path = self._image_store_path(current_local_zarr_path)
    if not image_path.exists():
        print("SOFIMA flow field not found.")
        return None

    try:
        sofima_flow_field = self._load_from_zarr_array(image_path, return_future)
        attributes = self._load_entity_attributes(
            entity_root,
            image_names=(image_name,),
        )
        return sofima_flow_field, attributes
    except (OSError, ValueError, KeyError) as e:
        print(e)
        print("Error loading SOFIMA flow field.")
        return None

`load_local_stage_position_zyx_um(tile, round)`

Load tile stage position for one tile.

Parameters:

Name	Type	Description	Default
`tile`	`int or str`	Tile index or tile id.	required
`round`	`int or str`	Round index or round id.	required

Returns:

Name	Type	Description
`stage_zyx_um`	`ArrayLike or None`	Tile stage position in Z, Y, X microns. Legacy two-coordinate Y, X metadata is returned with Z=0 without modifying the stored data.
`affine_zyx_um`	`ArrayLike or None`	Affine transformation between stage and camera

Source code in src/merfish3danalysis/qi2labDataStore.py

def load_local_stage_position_zyx_um(
    self,
    tile: int | str,
    round: int | str,
) -> tuple[np.ndarray, np.ndarray] | None:
    """Load tile stage position for one tile.

    Parameters
    ----------
    tile : int or str
        Tile index or tile id.
    round : int or str
        Round index or round id.

    Returns
    -------
    stage_zyx_um : ArrayLike or None
        Tile stage position in Z, Y, X microns. Legacy two-coordinate Y, X
        metadata is returned with Z=0 without modifying the stored data.
    affine_zyx_um: ArrayLike or None
        Affine transformation between stage and camera
    """
    if isinstance(tile, int):
        if tile < 0 or tile >= self._num_tiles:
            print("Set tile index >=0 and <" + str(self._num_tiles))
            return None
        else:
            tile_id = self._tile_ids[tile]
    elif isinstance(tile, str):
        if tile not in self._tile_ids:
            print("set valid tiled id.")
            return None
        else:
            tile_id = tile
    else:
        print("'tile' must be integer index or string identifier")
        return None

    if isinstance(round, int):
        if round < 0 or round >= len(self._round_ids):
            print("Set round index >=0 and <" + str(self._num_rounds))
            return None
        else:
            round_id = self._round_ids[round]
    elif isinstance(round, str):
        if round not in self._round_ids:
            print("Set valid round id.")
            return None
        else:
            round_id = round
    else:
        print("'round' must be integer index or string identifier")
        return None

    try:
        entity_root = self._fiducial_root_path / Path(tile_id) / Path(round_id)
        attributes = self._load_entity_attributes(entity_root)
        stage_zyx_um = attributes.get("stage_zyx_um")
        affine_zyx_px = attributes.get("affine_zyx_px")
        if stage_zyx_um is None or affine_zyx_px is None:
            print(tile_id, round_id)
            print("Stage position attribute not found.")
            return None
        return self._normalize_stage_position_zyx_um(stage_zyx_um), np.asarray(
            affine_zyx_px, dtype=np.float32
        )
    except (TypeError, ValueError):
        print(tile_id, round_id)
        print("Stage position attribute not found.")
        return None

`load_local_wavelengths_um(tile, round=None, bit=None)`

Load wavelengths for fiducial OR readout bit for one tile.

Parameters:

Name	Type	Description	Default
`tile`	`int or str`	Tile index or tile id.	required
`round`	`int or str or None`	Round index or round id.	`None`
`bit`	`int or str or None`	Bit index or bit id.	`None`

Returns:

Name	Type	Description
`wavelengths_um`	`tuple[float, float] or None`	Wavelengths for fiducial OR readout bit for one tile.

Source code in src/merfish3danalysis/qi2labDataStore.py

def load_local_wavelengths_um(
    self,
    tile: int | str,
    round: int | str | None = None,
    bit: int | str | None = None,
) -> tuple[float, float] | None:
    """Load wavelengths for fiducial OR readout bit for one tile.

    Parameters
    ----------
    tile : int or str
        Tile index or tile id.
    round : int or str or None
        Round index or round id.
    bit : int or str or None
        Bit index or bit id.

    Returns
    -------
    wavelengths_um : tuple[float, float] or None
        Wavelengths for fiducial OR readout bit for one tile.
    """
    if (round is None and bit is None) or (round is not None and bit is not None):
        print("Provide either 'round' or 'bit', but not both")
        return None

    if isinstance(tile, int):
        if tile < 0 or tile >= self._num_tiles:
            print("Set tile index >=0 and <" + str(self._num_tiles))
            return None
        else:
            tile_id = self._tile_ids[tile]
    elif isinstance(tile, str):
        if tile not in self._tile_ids:
            print("set valid tiled id")
            return None
        else:
            tile_id = tile
    else:
        print("'tile' must be integer index or string identifier")
        return None

    if bit is not None:
        if isinstance(bit, int):
            if bit < 0 or bit >= len(self._bit_ids):
                print("Set bit index >=0 and <" + str(len(self._bit_ids)))
                return None
            else:
                local_id = self._bit_ids[bit]
        elif isinstance(bit, str):
            if bit not in self._bit_ids:
                print("Set valid bit id")
                return None
            else:
                local_id = bit
        else:
            print("'bit' must be integer index or string identifier")
            return None
        entity_root = self._readouts_root_path / Path(tile_id) / Path(local_id)
    else:
        if isinstance(round, int):
            if round < 0 or round >= len(self._round_ids):
                print("Set round index >=0 and <" + str(self._num_rounds))
                return None
            else:
                local_id = self._round_ids[round]
        elif isinstance(round, str):
            if round not in self._round_ids:
                print("Set valid round id")
                return None
            else:
                local_id = round
        else:
            print("'round' must be integer index or string identifier")
            return None
        entity_root = self._fiducial_root_path / Path(tile_id) / Path(local_id)

    try:
        attributes = self._load_entity_attributes(entity_root)
        ex_wavelength_um = attributes["excitation_um"]
        em_wavelength_um = attributes["emission_um"]
        return (ex_wavelength_um, em_wavelength_um)
    except KeyError:
        print("Wavelength attributes not found.")
        return None

`load_proseg_cell_polygons_3d(run_name=None)`

Load Proseg 3D refined cell polygons.

Parameters:

Name	Type	Description	Default
`run_name`	`str or None`	Proseg run name. `None` or `"default"` selects `proseg/3D`.	`None`

Returns:

Name	Type	Description
`polygons`	`dict[Any, ArrayLike] or None`	Cell identifiers mapped to polygon vertices in X, Y order.

Source code in src/merfish3danalysis/qi2labDataStore.py

def load_proseg_cell_polygons_3d(
    self,
    run_name: str | None = None,
) -> dict[Any, ArrayLike] | None:
    """Load Proseg 3D refined cell polygons.

    Parameters
    ----------
    run_name : str or None, default None
        Proseg run name. ``None`` or ``"default"`` selects ``proseg/3D``.

    Returns
    -------
    polygons : dict[Any, ArrayLike] or None
        Cell identifiers mapped to polygon vertices in X, Y order.
    """
    polygon_path = self._proseg_3d_run_root(run_name) / Path(
        "cell_polygons_3D.geojson.gz"
    )
    if not polygon_path.exists():
        print("Proseg cell polygons not found.")
        return None

    try:
        with gzip.open(polygon_path, "rt", encoding="utf-8") as file:
            geojson = json.load(file)
    except (OSError, json.JSONDecodeError) as exc:
        print(exc)
        print("Error loading Proseg cell polygons.")
        return None

    polygons: dict[Any, ArrayLike] = {}
    for idx, feature in enumerate(geojson.get("features", [])):
        properties = feature.get("properties", {})
        cell_id = properties.get("cell", idx)
        geometry = feature.get("geometry", {})
        coordinates = geometry.get("coordinates", [])
        rings: list[np.ndarray] = []
        if geometry.get("type") == "Polygon":
            rings.extend(np.asarray(ring, dtype=float) for ring in coordinates)
        elif geometry.get("type") == "MultiPolygon":
            for polygon in coordinates:
                rings.extend(np.asarray(ring, dtype=float) for ring in polygon)
        if rings:
            polygons[cell_id] = max(rings, key=len)

    return polygons

`load_proseg_transcripts_3d(run_name=None)`

Load Proseg 3D transcript metadata.

Parameters:

Name	Type	Description	Default
`run_name`	`str or None`	Proseg run name. `None` or `"default"` selects `proseg/3D`.	`None`

Returns:

Name	Type	Description
`transcripts`	`DataFrame or None`	Proseg transcript metadata.

Source code in src/merfish3danalysis/qi2labDataStore.py

def load_proseg_transcripts_3d(
    self,
    run_name: str | None = None,
) -> pd.DataFrame | None:
    """Load Proseg 3D transcript metadata.

    Parameters
    ----------
    run_name : str or None, default None
        Proseg run name. ``None`` or ``"default"`` selects ``proseg/3D``.

    Returns
    -------
    transcripts : pandas.DataFrame or None
        Proseg transcript metadata.
    """
    transcript_path = self._proseg_3d_run_root(run_name) / Path(
        "transcript_metadata_3D.csv.gz"
    )
    if not transcript_path.exists():
        print("Proseg transcript metadata not found.")
        return None
    try:
        return pd.read_csv(transcript_path, compression="gzip")
    except (OSError, ValueError) as exc:
        print(exc)
        print("Error loading Proseg transcript metadata.")
        return None

`local_feature_predictor_spots_path(tile, bit)`

Return the localization table path for a tile and readout identifier.

Source code in src/merfish3danalysis/qi2labDataStore.py

def local_feature_predictor_spots_path(self, tile: str, bit: str) -> Path:
    """Return the localization table path for a tile and readout identifier."""
    if tile not in self._tile_ids or bit not in self._bit_ids:
        raise ValueError(f"Invalid tile or bit: {tile}, {bit}")
    return (
        self._feature_predictor_localizations_root_path / tile / (bit + ".parquet")
    )

`local_image_path(tile, image_name, *, round=None, bit=None)`

Return a native fiducial or readout OME-Zarr image path.

Parameters:

Name	Type	Description	Default
`tile`	`int or str`	Zero-based tile index or stored tile identifier.	required
`image_name`	`str`	Logical image name such as corrected_data or decon_data.	required
`round`	`int or str or None`	Zero-based fiducial round index or identifier; excludes bit.	`None`
`bit`	`int or str or None`	Zero-based readout bit index or identifier; excludes round.	`None`

Returns:

Type	Description
`Path`	Image path without loading pixels or creating directories.

Source code in src/merfish3danalysis/qi2labDataStore.py

def local_image_path(
    self,
    tile: int | str,
    image_name: str,
    *,
    round: int | str | None = None,
    bit: int | str | None = None,
) -> Path:
    """Return a native fiducial or readout OME-Zarr image path.

    Parameters
    ----------
    tile : int or str
        Zero-based tile index or stored tile identifier.
    image_name : str
        Logical image name such as corrected_data or decon_data.
    round : int or str or None
        Zero-based fiducial round index or identifier; excludes bit.
    bit : int or str or None
        Zero-based readout bit index or identifier; excludes round.

    Returns
    -------
    Path
        Image path without loading pixels or creating directories.
    """
    if (round is None) == (bit is None):
        raise ValueError("Provide exactly one of round or bit.")
    if isinstance(tile, int) and not 0 <= tile < len(self._tile_ids):
        raise ValueError(f"Invalid tile: {tile}")
    tile_id = self._tile_ids[tile] if isinstance(tile, int) else tile
    if tile_id not in self._tile_ids:
        raise ValueError(f"Invalid tile: {tile}")
    ids = self._round_ids if round is not None else self._bit_ids
    selection = round if round is not None else bit
    if isinstance(selection, int) and not 0 <= selection < len(ids):
        raise ValueError(f"Invalid round or bit: {selection}")
    entity_id = ids[selection] if isinstance(selection, int) else selection
    if entity_id not in ids:
        raise ValueError(f"Invalid round or bit: {selection}")
    root = (
        self._fiducial_root_path if round is not None else self._readouts_root_path
    )
    return self._image_store_path(root / tile_id / entity_id / image_name)

`save_chromatic_affine_transforms_zyx_um(calibration)`

Save chromatic affine calibration metadata.

Parameters:

Name	Type	Description	Default
`calibration`	`Mapping[str, Any]`	Calibration metadata containing one 4x4 `affine_zyx_um` matrix per channel. Each affine maps that channel's physical Z, Y, X coordinates onto the lowest-wavelength reference channel.	required

Returns:

Type	Description
`None`	Metadata are written to `calibrations/attributes.json`.

Source code in src/merfish3danalysis/qi2labDataStore.py

def save_chromatic_affine_transforms_zyx_um(
    self,
    calibration: Mapping[str, Any],
) -> None:
    """
    Save chromatic affine calibration metadata.

    Parameters
    ----------
    calibration : Mapping[str, Any]
        Calibration metadata containing one 4x4 ``affine_zyx_um`` matrix
        per channel. Each affine maps that channel's physical Z, Y, X
        coordinates onto the lowest-wavelength reference channel.

    Returns
    -------
    None
        Metadata are written to ``calibrations/attributes.json``.
    """
    calibration = dict(calibration)
    if "voxel_size_zyx_um" in calibration:
        calibration["voxel_size_zyx_um"] = round_spacing_um(
            calibration["voxel_size_zyx_um"]
        ).tolist()
    self._set_calibration_attribute(
        "chromatic_affine_transforms_zyx_um",
        calibration,
    )

`save_coord_of_xform_px(of_xform_px, tile, block_size, block_stride, round, return_future=False)`

Save fiducial optical flow matrix for one round and tile.

Parameters:

Name	Type	Description	Default
`of_xform_px`	`ArrayLike`	Local fiducial optical flow matrix for one round and tile.	required
`tile`	`int or str`	Tile index or tile id.	required
`block_size`	`Sequence[float]`	Block size for pixel warp	required
`block_stride`	`Sequence[float]`	Block stride for pixel warp	required
`round`	`int or str`	Round index or round id.	required
`return_future`	`bool or None`	Return the completed TensorStore write handle when True. Writes finish before associated metadata is reported as saved.	`False`

Returns:

Type	Description
`WriteFutures or None`	Completed pixel-write handle when return_future is True; otherwise None. Invalid tile/round/bit selections also return None.

Source code in src/merfish3danalysis/qi2labDataStore.py

def save_coord_of_xform_px(
    self,
    of_xform_px: ArrayLike,
    tile: int | str,
    block_size: Sequence[float],
    block_stride: Sequence[float],
    round: int | str,
    return_future: bool | None = False,
) -> "WriteFutures | None":
    """Save fiducial optical flow matrix for one round and tile.

    Parameters
    ----------
    of_xform_px : ArrayLike
        Local fiducial optical flow matrix for one round and tile.
    tile : int or str
        Tile index or tile id.
    block_size : Sequence[float]
        Block size for pixel warp
    block_stride: Sequence[float]
        Block stride for pixel warp
    round : int or str
        Round index or round id.
    return_future : bool or None
        Return the completed TensorStore write handle when True. Writes
        finish before associated metadata is reported as saved.

    Returns
    -------
    tensorstore.WriteFutures or None
        Completed pixel-write handle when return_future is True; otherwise
        None. Invalid tile/round/bit selections also return None.
    """
    if isinstance(tile, int):
        if tile < 0 or tile >= self._num_tiles:
            print("Set tile index >=0 and <" + str(self._num_tiles))
            return None
        else:
            tile_id = self._tile_ids[tile]
    elif isinstance(tile, str):
        if tile not in self._tile_ids:
            print("set valid tiled id")
            return None
        else:
            tile_id = tile
    else:
        print("'tile' must be integer index or string identifier")
        return None

    if isinstance(round, int):
        if round < 0 or round >= len(self._round_ids):
            print("Set round index >=0 and <" + str(self._num_rounds))
            return None
        else:
            local_id = self._round_ids[round]
    elif isinstance(round, str):
        if round not in self._round_ids:
            print("Set valid round id")
            return None
        else:
            local_id = round
    else:
        print("'round' must be integer index or string identifier")
        return None
    entity_root = self._fiducial_root_path / Path(tile_id) / Path(local_id)
    current_local_zarr_path = entity_root / Path("opticalflow_xform_px")

    try:
        opticalflow_attrs = {
            "block_size": np.asarray(block_size, dtype=np.float32).tolist(),
            "block_stride": np.asarray(block_stride, dtype=np.float32).tolist(),
        }
        # Optical flow is a dense pixel-space field, so we do not encode
        # physical voxel scale or stage translation transforms here.
        write_future = self._save_to_zarr_array(
            of_xform_px,
            current_local_zarr_path,
            return_future,
            extra_attributes=opticalflow_attrs,
        )
        if write_future is not None:
            write_future.result()
        self._save_entity_attributes(
            entity_root_path=entity_root, updates=opticalflow_attrs
        )
        return write_future
    except (OSError, TimeoutError):
        print("Error saving optical flow transform.")
        raise

`save_decode_normalization_vectors(decode_run_key, kind, normalization_vector, background_vector, decode_mode=None, metadata=None)`

Save default or run-scoped normalization and background vectors.

Parameters:

Name	Type	Description	Default
`decode_run_key`	`str or None`	Optional decoded-output run key. None writes the default vectors.	required
`kind`	`('global', iterative)`	Normalization vector kind.	`'global'`
`normalization_vector`	`ArrayLike`	Foreground normalization vector.	required
`background_vector`	`ArrayLike`	Background vector.	required
`decode_mode`	`str or None`	Decode mode metadata.	`None`
`metadata`	`Mapping[str, Any] or None`	Additional provenance for these normalization vectors.	`None`

Source code in src/merfish3danalysis/qi2labDataStore.py

def save_decode_normalization_vectors(
    self,
    decode_run_key: str | None,
    kind: str,
    normalization_vector: ArrayLike,
    background_vector: ArrayLike,
    decode_mode: str | None = None,
    metadata: Mapping[str, Any] | None = None,
) -> None:
    """
    Save default or run-scoped normalization and background vectors.

    Parameters
    ----------
    decode_run_key : str or None
        Optional decoded-output run key. None writes the default vectors.
    kind : {'global', 'iterative'}
        Normalization vector kind.
    normalization_vector : ArrayLike
        Foreground normalization vector.
    background_vector : ArrayLike
        Background vector.
    decode_mode : str or None, default None
        Decode mode metadata.
    metadata : Mapping[str, Any] or None, default None
        Additional provenance for these normalization vectors.
    """
    if kind == "global":
        if decode_run_key is None:
            self.global_normalization_vector = normalization_vector
            self.global_background_vector = background_vector
            self._save_default_decode_normalization_metadata(kind, metadata)
            return
        norm_key = "global_normalization_vector"
        background_key = "global_background_vector"
    elif kind == "iterative":
        if decode_run_key is None:
            self.iterative_normalization_vector = normalization_vector
            self.iterative_background_vector = background_vector
            self._save_default_decode_normalization_metadata(kind, metadata)
            return
        norm_key = "iterative_normalization_vector"
        background_key = "iterative_background_vector"
    else:
        raise ValueError("kind must be one of 'global' or 'iterative'.")

    decode_run_key = self._validate_decode_run_key(decode_run_key)
    calib_attrs = self._load_calibrations_attributes()
    runs = dict(calib_attrs.get("decode_normalization_runs", {}))
    run_attrs = dict(runs.get(decode_run_key, {}))
    if decode_mode is not None:
        run_attrs["decode_mode"] = str(decode_mode)
    if metadata is not None:
        run_attrs[f"{kind}_metadata"] = dict(metadata)
    run_attrs[norm_key] = np.asarray(normalization_vector, dtype=np.float32)
    run_attrs[background_key] = np.asarray(background_vector, dtype=np.float32)
    runs[decode_run_key] = run_attrs
    calib_attrs["decode_normalization_runs"] = runs
    self._save_calibrations_attributes(calib_attrs)

`save_global_cellpose_segmentation_image(cellpose_image, downsampling, return_future=False)`

Save Cellpose max projection, downsampled segmentation image.

The caller runs segmentation and selects its image grid. This method stores the supplied labels unchanged and derives their physical scale from the native voxel calibration and supplied downsampling factors.

Parameters:

Name	Type	Description	Default
`cellpose_image`	`ArrayLike`	Cellpose max projection, downsampled segmentation image.	required
`downsampling`	`Sequence[float]`	Caller-selected Z, Y, X factors: segmentation spacing divided by native voxel spacing. Two-dimensional masks use the resulting YX physical scale while retaining all three factors in metadata.	required
`return_future`	`bool or None`	Return the completed TensorStore write handle when True. Writes finish before associated metadata is reported as saved.	`False`

Returns:

Type	Description
`WriteFutures or None`	Completed pixel-write handle when return_future is True; otherwise None.

Source code in src/merfish3danalysis/qi2labDataStore.py

def save_global_cellpose_segmentation_image(
    self,
    cellpose_image: ArrayLike,
    downsampling: Sequence[float],
    return_future: bool | None = False,
) -> "WriteFutures | None":
    """Save Cellpose max projection, downsampled segmentation image.

    The caller runs segmentation and selects its image grid. This method
    stores the supplied labels unchanged and derives their physical scale
    from the native voxel calibration and supplied downsampling factors.

    Parameters
    ----------
    cellpose_image : ArrayLike
        Cellpose max projection, downsampled segmentation image.
    downsampling : Sequence[float]
        Caller-selected Z, Y, X factors: segmentation spacing divided by
        native voxel spacing. Two-dimensional masks use the resulting YX
        physical scale while retaining all three factors in metadata.
    return_future : bool or None
        Return the completed TensorStore write handle when True. Writes
        finish before associated metadata is reported as saved.

    Returns
    -------
    tensorstore.WriteFutures or None
        Completed pixel-write handle when return_future is True; otherwise
        None.
    """
    current_local_zarr_path = (
        self._segmentation_root_path
        / Path("cellpose")
        / Path(f"masks_{self.fiducial_folder_name}_iso_zyx")
    )

    downsampling = np.asarray(downsampling, dtype=np.float64)
    if (
        downsampling.shape != (3,)
        or not np.all(np.isfinite(downsampling))
        or np.any(downsampling <= 0)
    ):
        raise ValueError(
            "Downsampling must contain three positive finite Z, Y, X factors."
        )
    spacing = round_spacing_um(self.voxel_size_zyx_um) * downsampling
    attributes = {"downsampling": downsampling.tolist()}

    try:
        write_future = self._save_to_zarr_array(
            cellpose_image,
            current_local_zarr_path,
            return_future,
            ome_scale=round_spacing_um(spacing).tolist(),
            extra_attributes=attributes,
        )
        if write_future is not None:
            write_future.result()
        return write_future
    except (OSError, TimeoutError):
        print("Error saving Cellpose image.")
        raise

`save_global_coord_xforms_um(affine_zyx_um, origin_zyx_um, spacing_zyx_um, tile)`

Save global registration transform for one tile.

Parameters:

Name	Type	Description	Default
`affine_zyx_um`	`ArrayLike`	Final 4x4 registration correction in physical Z, Y, X coordinates, applied after the separately stored camera-to-stage transform.	required
`origin_zyx_um`	`ArrayLike`	Native image origin in Z, Y, X micrometers, before camera mapping.	required
`spacing_zyx_um`	`ArrayLike`	Native Z, Y, X voxel spacing in micrometers.	required
`tile`	`int or str`	Tile index or tile id.	required

Source code in src/merfish3danalysis/qi2labDataStore.py

def save_global_coord_xforms_um(
    self,
    affine_zyx_um: ArrayLike,
    origin_zyx_um: ArrayLike,
    spacing_zyx_um: ArrayLike,
    tile: int | str,
) -> None:
    """Save global registration transform for one tile.

    Parameters
    ----------
    affine_zyx_um : ArrayLike
        Final 4x4 registration correction in physical Z, Y, X coordinates,
        applied after the separately stored camera-to-stage transform.
    origin_zyx_um : ArrayLike
        Native image origin in Z, Y, X micrometers, before camera mapping.
    spacing_zyx_um : ArrayLike
        Native Z, Y, X voxel spacing in micrometers.
    tile : int or str
        Tile index or tile id.
    """
    if isinstance(tile, int):
        if tile < 0 or tile >= self._num_tiles:
            print("Set tile index >=0 and <" + str(self._num_tiles))
            return None
        else:
            tile_id = self._tile_ids[tile]
    elif isinstance(tile, str):
        if tile not in self._tile_ids:
            print("set valid tiled id")
            return None
        else:
            tile_id = tile
    else:
        print("'tile' must be integer index or string identifier")
        return None

    try:
        entity_root = (
            self._fiducial_root_path / Path(tile_id) / Path(self._round_ids[0])
        )
        self._save_entity_attributes(
            entity_root_path=entity_root,
            updates={
                "affine_zyx_um": np.asarray(
                    affine_zyx_um, dtype=np.float32
                ).tolist(),
                "origin_zyx_um": np.asarray(
                    origin_zyx_um, dtype=np.float32
                ).tolist(),
                "spacing_zyx_um": round_spacing_um(spacing_zyx_um).tolist(),
            },
        )
    except (FileNotFoundError, json.JSONDecodeError, TypeError, ValueError) as e:
        print(e)
        print("Could not save global coordinate transforms.")

`save_global_fiducial_image(fused_image, affine_zyx_um, origin_zyx_um, spacing_zyx_um, fusion_type='fiducial', return_future=False)`

Save downsampled, fused fiducial image.

The caller selects the fusion grid. This method stores the supplied image and spacing without choosing a dataset-specific downsampling.

Parameters:

Name	Type	Description	Default
`fused_image`	`ArrayLike`	Downsampled, fused fiducial image.	required
`affine_zyx_um`	`ArrayLike`	Global affine registration transform for fused image.	required
`origin_zyx_um`	`ArrayLike`	Global origin registration transform for fused image.	required
`spacing_zyx_um`	`ArrayLike`	Caller-selected fused voxel spacing in Z, Y, X microns.	required
`fusion_type`	`str`	Type of fusion (fiducial or all_channels).	`'fiducial'`
`return_future`	`bool or None`	Return the completed TensorStore write handle when True. Writes finish before associated metadata is reported as saved.	`False`

Returns:

Type	Description
`WriteFutures or None`	Completed pixel-write handle when return_future is True; otherwise None.

Source code in src/merfish3danalysis/qi2labDataStore.py

def save_global_fiducial_image(
    self,
    fused_image: ArrayLike,
    affine_zyx_um: ArrayLike,
    origin_zyx_um: ArrayLike,
    spacing_zyx_um: ArrayLike,
    fusion_type: str = "fiducial",
    return_future: bool | None = False,
) -> "WriteFutures | None":
    """Save downsampled, fused fiducial image.

    The caller selects the fusion grid. This method stores the supplied
    image and spacing without choosing a dataset-specific downsampling.

    Parameters
    ----------
    fused_image : ArrayLike
        Downsampled, fused fiducial image.
    affine_zyx_um : ArrayLike
        Global affine registration transform for fused image.
    origin_zyx_um : ArrayLike
        Global origin registration transform for fused image.
    spacing_zyx_um : ArrayLike
        Caller-selected fused voxel spacing in Z, Y, X microns.
    fusion_type : str
        Type of fusion (fiducial or all_channels).
    return_future : bool or None
        Return the completed TensorStore write handle when True. Writes
        finish before associated metadata is reported as saved.

    Returns
    -------
    tensorstore.WriteFutures or None
        Completed pixel-write handle when return_future is True; otherwise
        None.
    """
    if fusion_type == "fiducial":
        filename = f"fused_{self.fiducial_folder_name}_zyx"
    else:
        filename = "fused_all_channels_zyx"
    current_local_zarr_path = self._fused_root_path / Path(filename)

    metadata_attrs = {
        "affine_zyx_um": np.asarray(affine_zyx_um, dtype=np.float32).tolist(),
        "origin_zyx_um": np.asarray(origin_zyx_um, dtype=np.float32).tolist(),
        "spacing_zyx_um": round_spacing_um(spacing_zyx_um).tolist(),
    }
    fused_array = np.asarray(fused_image)
    try:
        write_future = self._save_to_zarr_array(
            fused_array.astype(np.uint16),
            current_local_zarr_path,
            return_future,
            ome_scale=metadata_attrs["spacing_zyx_um"],
            extra_attributes=metadata_attrs,
            chunks=self._fused_image_chunks(fused_array),
        )
        if write_future is not None:
            write_future.result()
        return write_future
    except (OSError, TimeoutError):
        print("Error saving fused image.")
        raise

`save_global_filtered_decoded_spots(filtered_decoded_df, decode_run_key=None)`

Save all decoded and filtered spots.

Parameters:

Name	Type	Description	Default
`filtered_decoded_df`	`DataFrame`	All decoded and filtered spots.	required
`decode_run_key`	`str or None`	Optional decoded-output run key.	`None`

Source code in src/merfish3danalysis/qi2labDataStore.py

def save_global_filtered_decoded_spots(
    self,
    filtered_decoded_df: pd.DataFrame,
    decode_run_key: str | None = None,
) -> None:
    """Save all decoded and filtered spots.

    Parameters
    ----------
    filtered_decoded_df : pd.DataFrame
        All decoded and filtered spots.
    decode_run_key : str or None, default None
        Optional decoded-output run key.
    """
    current_global_filtered_decoded_dir_path = self._global_filtered_decoded_root(
        decode_run_key
    )

    if not current_global_filtered_decoded_dir_path.exists():
        current_global_filtered_decoded_dir_path.mkdir(parents=True)

    current_global_filtered_decoded_path = (
        current_global_filtered_decoded_dir_path / Path("decoded_features.parquet")
    )
    current_global_filtered_decoded_csv_gz_path = (
        current_global_filtered_decoded_dir_path / Path("decoded_features.csv.gz")
    )

    self._save_to_parquet(filtered_decoded_df, current_global_filtered_decoded_path)
    self._save_to_csv_gz(
        filtered_decoded_df, current_global_filtered_decoded_csv_gz_path
    )

`save_image_metadata(image_path, extra_attributes, merge=True)` `staticmethod`

Write image-level extra attributes for externally-created OME-Zarr stores.

Parameters:

Name	Type	Description	Default
`image_path`	`Path \| str`	Image group path. Both the directory path and the corresponding OME-Zarr store path are accepted.	required
`extra_attributes`	`Mapping[str, Any]`	Attribute updates to write at the image root.	required
`merge`	`bool`	If True, merge updates into existing attributes. If False, replace the existing image-level attributes with `extra_attributes`.	`True`

Returns:

Type	Description
`None`	Attributes are written to the Zarr v3 `zarr.json`. The OME metadata is preserved when replacing extra attributes.

Source code in src/merfish3danalysis/qi2labDataStore.py

@staticmethod
def save_image_metadata(
    image_path: Path | str,
    extra_attributes: Mapping[str, Any],
    merge: bool = True,
) -> None:
    """
    Write image-level extra attributes for externally-created OME-Zarr stores.

    Parameters
    ----------
    image_path : Path | str
        Image group path. Both the directory path and the corresponding
        OME-Zarr store path are accepted.
    extra_attributes : Mapping[str, Any]
        Attribute updates to write at the image root.
    merge : bool, default=True
        If True, merge updates into existing attributes. If False, replace
        the existing image-level attributes with ``extra_attributes``.

    Returns
    -------
    None
        Attributes are written to the Zarr v3 ``zarr.json``. The OME
        metadata is preserved when replacing extra attributes.
    """
    image_root = qi2labDataStore._image_store_path(image_path)
    payload = {
        str(k): qi2labDataStore._to_json_compatible(v)
        for k, v in dict(extra_attributes).items()
    }

    for key in ("spacing_zyx_um", "voxel_size_zyx_um"):
        if key in payload:
            payload[key] = round_spacing_um(payload[key]).tolist()

    group = open_group(image_root)
    metadata = group.metadata.model_dump(mode="json", exclude_none=True)
    if metadata["zarr_format"] != 3:
        raise ValueError("Datastore images must use OME-Zarr on Zarr v3.")
    existing = dict(group.attrs)
    attributes = existing if merge else {"ome": existing["ome"]}
    attributes.update(payload)
    round_ome_spatial_scales(attributes)
    metadata["attributes"] = attributes
    # yaozarrs exposes attributes read-only. Updating metadata for an
    # externally fused image requires replacing the local Zarr v3 JSON.
    qi2labDataStore._save_to_json(metadata, image_root / "zarr.json")

`save_local_bit_linker(bit_linker, tile, round)`

Save readout bits linked to fiducial round for one tile.

Parameters:

Name	Type	Description	Default
`bit_linker`	`Sequence[int]`	Readout bits linked to fiducial round for one tile.	required
`tile`	`int or str`	Tile index or tile id.	required
`round`	`int or str`	Round index or round id.	required

Source code in src/merfish3danalysis/qi2labDataStore.py

def save_local_bit_linker(
    self,
    bit_linker: Sequence[int],
    tile: int | str,
    round: int | str,
) -> None:
    """Save readout bits linked to fiducial round for one tile.

    Parameters
    ----------
    bit_linker : Sequence[int]
        Readout bits linked to fiducial round for one tile.
    tile : int or str
        Tile index or tile id.
    round : int or str
        Round index or round id.
    """
    if isinstance(tile, int):
        if tile < 0 or tile >= self._num_tiles:
            print("Set tile index >=0 and <" + str(self._num_tiles))
            return None
        else:
            tile_id = self._tile_ids[tile]
    elif isinstance(tile, str):
        if tile not in self._tile_ids:
            print("set valid tiled id.")
            return None
        else:
            tile_id = tile
    else:
        print("'tile' must be integer index or string identifier")
        return None

    if isinstance(round, int):
        if round < 0 or round >= len(self._round_ids):
            print("Set round index >=0 and <" + str(self._num_rounds))
            return None
        else:
            round_id = self._round_ids[round]
    elif isinstance(round, str):
        if round not in self._round_ids:
            print("Set valid round id.")
            return None
        else:
            round_id = round
    else:
        print("'round' must be integer index or string identifier")
        return None

    try:
        entity_root = self._fiducial_root_path / Path(tile_id) / Path(round_id)
        values = [int(v) for v in list(bit_linker)]
        self._save_entity_attributes(
            entity_root_path=entity_root, updates={"bit_linker": values}
        )
    except (TypeError, ValueError):
        print(tile_id, round_id)
        print("Error writing bit linker attribute.")
        return None

`save_local_corrected_image(image, tile, gain_correction=True, hotpixel_correction=True, shading_correction=False, psf_idx=0, round=None, bit=None, return_future=False)`

Save gain and offset corrected image.

Parameters:

Name	Type	Description	Default
`image`	`ArrayLike`	Local corrected image.	required
`tile`	`int or str`	Tile index or tile id.	required
`gain_correction`	`bool`	Gain correction applied (True) or not (False).	`True`
`hotpixel_correction`	`bool`	Hotpixel correction applied (True) or not (False).	`True`
`shading_correction`	`bool`	Shading correction applied (True) or not (False).	`False`
`psf_idx`	`int`	PSF index.	`0`
`round`	`int or str or None`	Round index or round id.	`None`
`bit`	`int or str or None`	Bit index or bit id.	`None`
`return_future`	`bool or None`	Return the completed TensorStore write handle when True. Writes finish before associated metadata is reported as saved.	`False`

Returns:

Type	Description
`WriteFutures or None`	Completed pixel-write handle when return_future is True; otherwise None. Invalid tile/round/bit selections also return None.

Source code in src/merfish3danalysis/qi2labDataStore.py

def save_local_corrected_image(
    self,
    image: ArrayLike,
    tile: int | str,
    gain_correction: bool = True,
    hotpixel_correction: bool = True,
    shading_correction: bool = False,
    psf_idx: int = 0,
    round: int | str | None = None,
    bit: int | str | None = None,
    return_future: bool | None = False,
) -> "WriteFutures | None":
    """Save gain and offset corrected image.

    Parameters
    ----------
    image : ArrayLike
        Local corrected image.
    tile : int or str
        Tile index or tile id.
    gain_correction : bool
        Gain correction applied (True) or not (False).
    hotpixel_correction : bool
        Hotpixel correction applied (True) or not (False).
    shading_correction : bool
        Shading correction applied (True) or not (False).
    psf_idx : int
        PSF index.
    round : int or str or None
        Round index or round id.
    bit : int or str or None
        Bit index or bit id.
    return_future : bool or None
        Return the completed TensorStore write handle when True. Writes
        finish before associated metadata is reported as saved.

    Returns
    -------
    tensorstore.WriteFutures or None
        Completed pixel-write handle when return_future is True; otherwise
        None. Invalid tile/round/bit selections also return None.
    """
    if (round is None and bit is None) or (round is not None and bit is not None):
        print("Provide either 'round' or 'bit', but not both")
        return None

    if isinstance(tile, int):
        if tile < 0 or tile >= self._num_tiles:
            print("Set tile index >=0 and <" + str(self._num_tiles))
            return None
        else:
            tile_id = self._tile_ids[tile]
    elif isinstance(tile, str):
        if tile not in self._tile_ids:
            print("set valid tiled id")
            return None
        else:
            tile_id = tile
    else:
        print("'tile' must be integer index or string identifier")
        return None

    if bit is not None:
        if isinstance(bit, int):
            if bit < 0 or bit >= len(self._bit_ids):
                print("Set bit index >=0 and <" + str(len(self._bit_ids)))
                return None
            else:
                local_id = self._bit_ids[bit]
        elif isinstance(bit, str):
            if bit not in self._bit_ids:
                print("Set valid bit id")
                return None
            else:
                local_id = bit
        else:
            print("'bit' must be integer index or string identifier")
            return None
        entity_root = self._readouts_root_path / Path(tile_id) / Path(local_id)
        current_local_zarr_path = entity_root / Path("corrected_data")
        stage_position = self._resolve_original_tile_position_zyx_um(
            tile_id=tile_id, bit_id=local_id
        )
    else:
        if isinstance(round, int):
            if round < 0 or round >= len(self._round_ids):
                print("Set round index >=0 and <" + str(self._num_rounds))
                return None
            else:
                local_id = self._round_ids[round]
        elif isinstance(round, str):
            if round not in self._round_ids:
                print("Set valid round id")
                return None
            else:
                local_id = round
        else:
            print("'round' must be integer index or string identifier")
            return None
        entity_root = self._fiducial_root_path / Path(tile_id) / Path(local_id)
        current_local_zarr_path = entity_root / Path("corrected_data")
        stage_position = self._resolve_original_tile_position_zyx_um(
            tile_id=tile_id, round_id=local_id
        )

    try:
        self._validate_core_image_shape(
            entity_root_path=entity_root, image_name="corrected_data", image=image
        )
        attributes = self._load_entity_attributes(entity_root)
        attributes.update(
            {
                "gain_correction": bool(gain_correction),
                "hotpixel_correction": bool(hotpixel_correction),
                "shading_correction": bool(shading_correction),
                "psf_idx": int(psf_idx),
            }
        )
        write_future = self._save_to_zarr_array(
            image,
            current_local_zarr_path,
            return_future,
            ome_scale=self.voxel_size_zyx_um,
            ome_translation=stage_position,
            extra_attributes=attributes,
        )
        if write_future is not None:
            write_future.result()
        self._save_entity_attributes(
            entity_root_path=entity_root, updates=attributes
        )
        return write_future
    except (OSError, TimeoutError, ValueError) as e:
        print(e)
        print("Error saving corrected image.")
        raise

`save_local_decoded_spots(features_df, tile, decode_run_key=None)`

Save decoded spots and features for one tile.

Parameters:

Name	Type	Description	Default
`features_df`	`DataFrame`	Decoded spots and features for one tile.	required
`tile`	`int or str`	Tile index or tile id.	required
`decode_run_key`	`str or None`	Optional decoded-output run key.	`None`

Source code in src/merfish3danalysis/qi2labDataStore.py

def save_local_decoded_spots(
    self,
    features_df: pd.DataFrame,
    tile: int | str,
    decode_run_key: str | None = None,
) -> None:
    """Save decoded spots and features for one tile.

    Parameters
    ----------
    features_df : pd.DataFrame
        Decoded spots and features for one tile.
    tile : int or str
        Tile index or tile id.
    decode_run_key : str or None, default None
        Optional decoded-output run key.
    """
    if isinstance(tile, int):
        if tile < 0 or tile >= self._num_tiles:
            print("Set tile index >=0 and <" + str(self._num_tiles))
            return None
        else:
            tile_id = self._tile_ids[tile]
    elif isinstance(tile, str):
        if tile not in self._tile_ids:
            print("set valid tiled id")
            return None
        else:
            tile_id = tile
    else:
        print("'tile' must be integer index or string identifier")
        return None

    decoded_root_path = self._decoded_run_root(decode_run_key)
    decoded_root_path.mkdir(parents=True, exist_ok=True)
    current_tile_features_path = decoded_root_path / Path(
        tile_id + "_decoded_features.parquet"
    )

    self._save_to_parquet(features_df, current_tile_features_path)

`save_local_deconvolved_fiducial_image(image, tile, round, return_future=False)`

Save a native-frame deconvolved fiducial image.

Deconvolved fiducials are saved under decon_data in their native, unwarped tile frame.

Parameters:

Name	Type	Description	Default
`image`	`ArrayLike`	Image to save.	required
`tile`	`int or str`	Tile index or tile id.	required
`round`	`int or str`	Round index or round id.	required
`return_future`	`bool or None`	Return the completed TensorStore write handle when True. Writes finish before associated metadata is reported as saved.	`False`

Returns:

Type	Description
`WriteFutures or None`	Completed pixel-write handle when return_future is True; otherwise None. Invalid tile/round/bit selections also return None.

Source code in src/merfish3danalysis/qi2labDataStore.py

def save_local_deconvolved_fiducial_image(
    self,
    image: ArrayLike,
    tile: int | str,
    round: int | str,
    return_future: bool | None = False,
) -> "WriteFutures | None":
    """
    Save a native-frame deconvolved fiducial image.

    Deconvolved fiducials are saved under ``decon_data`` in their native,
    unwarped tile frame.

    Parameters
    ----------
    image : ArrayLike
        Image to save.
    tile : int or str
        Tile index or tile id.
    round : int or str
        Round index or round id.
    return_future : bool or None
        Return the completed TensorStore write handle when True. Writes
        finish before associated metadata is reported as saved.

    Returns
    -------
    tensorstore.WriteFutures or None
        Completed pixel-write handle when return_future is True; otherwise
        None. Invalid tile/round/bit selections also return None.
    """
    if isinstance(tile, int):
        if tile < 0 or tile >= self._num_tiles:
            print("Set tile index >=0 and <" + str(self._num_tiles))
            return None
        tile_id = self._tile_ids[tile]
    elif isinstance(tile, str):
        if tile not in self._tile_ids:
            print("set valid tiled id")
            return None
        tile_id = tile
    else:
        print("'tile' must be integer index or string identifier")
        return None

    if isinstance(round, int):
        if round < 0 or round >= len(self._round_ids):
            print("Set round index >=0 and <" + str(self._num_rounds))
            return None
        round_id = self._round_ids[round]
    elif isinstance(round, str):
        if round not in self._round_ids:
            print("Set valid round id")
            return None
        round_id = round
    else:
        print("'round' must be integer index or string identifier")
        return None

    entity_root = self._fiducial_root_path / tile_id / round_id
    decon_path = entity_root / Path("decon_data")
    stage_position = self._resolve_reference_tile_position_zyx_um(tile_id)

    try:
        self._validate_core_image_shape(
            entity_root_path=entity_root,
            image_name="decon_data",
            image=image,
        )
        attributes = self._load_entity_attributes(entity_root)
        attributes["deconvolution"] = True
        write_future = self._save_to_zarr_array(
            image,
            decon_path,
            return_future,
            ome_scale=self.voxel_size_zyx_um,
            ome_translation=stage_position,
            extra_attributes=attributes,
        )
        if write_future is not None:
            write_future.result()
        self._save_entity_attributes(
            entity_root_path=entity_root, updates=attributes
        )
        return write_future
    except (OSError, TimeoutError, ValueError):
        print("Error saving local deconvolved fiducial image.")
        raise

`save_local_deconvolved_readout_image(image, tile, bit, return_future=False)`

Save a native-frame deconvolved readout bit image.

Deconvolved readout bits are saved under decon_data in their native, unwarped tile frame.

Parameters:

Name	Type	Description	Default
`image`	`ArrayLike`	Image to save.	required
`tile`	`int or str`	Tile index or tile id.	required
`bit`	`int or str`	Bit index or bit id.	required
`return_future`	`bool or None`	Return the completed TensorStore write handle when True. Writes finish before associated metadata is reported as saved.	`False`

Returns:

Type	Description
`WriteFutures or None`	Completed pixel-write handle when return_future is True; otherwise None. Invalid tile/round/bit selections also return None.

Source code in src/merfish3danalysis/qi2labDataStore.py

def save_local_deconvolved_readout_image(
    self,
    image: ArrayLike,
    tile: int | str,
    bit: int | str,
    return_future: bool | None = False,
) -> "WriteFutures | None":
    """
    Save a native-frame deconvolved readout bit image.

    Deconvolved readout bits are saved under ``decon_data`` in their
    native, unwarped tile frame.

    Parameters
    ----------
    image : ArrayLike
        Image to save.
    tile : int or str
        Tile index or tile id.
    bit : int or str
        Bit index or bit id.
    return_future : bool or None
        Return the completed TensorStore write handle when True. Writes
        finish before associated metadata is reported as saved.

    Returns
    -------
    tensorstore.WriteFutures or None
        Completed pixel-write handle when return_future is True; otherwise
        None. Invalid tile/round/bit selections also return None.
    """
    if isinstance(tile, int):
        if tile < 0 or tile >= self._num_tiles:
            print("Set tile index >=0 and <" + str(self._num_tiles))
            return None
        tile_id = self._tile_ids[tile]
    elif isinstance(tile, str):
        if tile not in self._tile_ids:
            print("set valid tiled id")
            return None
        tile_id = tile
    else:
        print("'tile' must be integer index or string identifier")
        return None

    if isinstance(bit, int):
        if bit < 0 or bit >= len(self._bit_ids):
            print("Set bit index >=0 and <" + str(len(self._bit_ids)))
            return None
        bit_id = self._bit_ids[bit]
    elif isinstance(bit, str):
        if bit not in self._bit_ids:
            print("Set valid bit id")
            return None
        bit_id = bit
    else:
        print("'bit' must be integer index or string identifier")
        return None

    entity_root = self._readouts_root_path / Path(tile_id) / Path(bit_id)
    readout_path = entity_root / Path("decon_data")
    stage_position = self._resolve_original_tile_position_zyx_um(
        tile_id=tile_id,
        bit_id=bit_id,
    )

    try:
        self._validate_core_image_shape(
            entity_root_path=entity_root,
            image_name="decon_data",
            image=image,
        )
        attributes = self._load_entity_attributes(entity_root)
        attributes["deconvolution"] = True
        write_future = self._save_to_zarr_array(
            image,
            readout_path,
            return_future,
            ome_scale=self.voxel_size_zyx_um,
            ome_translation=stage_position,
            extra_attributes=attributes,
        )
        if write_future is not None:
            write_future.result()
        self._save_entity_attributes(
            entity_root_path=entity_root, updates=attributes
        )
        return write_future
    except (OSError, TimeoutError, ValueError):
        print("Error saving local deconvolved readout image.")
        raise

`save_local_feature_predictor_image(feature_predictor_image, tile, bit, return_future=False)`

Save feature_predictor prediction image.

Parameters:

Name	Type	Description	Default
`feature_predictor_image`	`ArrayLike`	feature_predictor prediction image.	required
`tile`	`int or str`	Tile index or tile id.	required
`bit`	`int or str`	Bit index or bit id.	required
`return_future`	`bool or None`	Return the completed TensorStore write handle when True. Writes finish before associated metadata is reported as saved.	`False`

Returns:

Type	Description
`WriteFutures or None`	Completed pixel-write handle when return_future is True; otherwise None. Invalid tile/round/bit selections also return None.

Source code in src/merfish3danalysis/qi2labDataStore.py

def save_local_feature_predictor_image(
    self,
    feature_predictor_image: ArrayLike,
    tile: int | str,
    bit: int | str,
    return_future: bool | None = False,
) -> "WriteFutures | None":
    """Save feature_predictor prediction image.

    Parameters
    ----------
    feature_predictor_image : ArrayLike
        feature_predictor prediction image.
    tile : int or str
        Tile index or tile id.
    bit : int or str
        Bit index or bit id.
    return_future : bool or None
        Return the completed TensorStore write handle when True. Writes
        finish before associated metadata is reported as saved.

    Returns
    -------
    tensorstore.WriteFutures or None
        Completed pixel-write handle when return_future is True; otherwise
        None. Invalid tile/round/bit selections also return None.
    """
    if isinstance(tile, int):
        if tile < 0 or tile >= self._num_tiles:
            print("Set tile index >=0 and <" + str(self._num_tiles))
            return None
        else:
            tile_id = self._tile_ids[tile]
    elif isinstance(tile, str):
        if tile not in self._tile_ids:
            print("set valid tiled id")
            return None
        else:
            tile_id = tile
    else:
        print("'tile' must be integer index or string identifier")
        return None

    if isinstance(bit, int):
        if bit < 0 or bit >= len(self._bit_ids):
            print("Set bit index >=0 and <" + str(len(self._bit_ids)))
            return None
        else:
            local_id = self._bit_ids[bit]
    elif isinstance(bit, str):
        if bit not in self._bit_ids:
            print("Set valid bit id")
            return None
        else:
            local_id = bit
    else:
        print("'bit' must be integer index or string identifier")
        return None
    entity_root = self._readouts_root_path / Path(tile_id) / Path(local_id)
    current_local_zarr_path = entity_root / Path(
        f"{self.feature_predictor_folder_name}_data"
    )

    try:
        self._validate_core_image_shape(
            entity_root_path=entity_root,
            image_name=f"{self.feature_predictor_folder_name}_data",
            image=feature_predictor_image,
        )
        stage_position = self._resolve_original_tile_position_zyx_um(
            tile_id=tile_id, bit_id=local_id
        )
        attributes = self._load_entity_attributes(entity_root)
        write_future = self._save_to_zarr_array(
            feature_predictor_image,
            current_local_zarr_path,
            return_future,
            ome_scale=self.voxel_size_zyx_um,
            ome_translation=stage_position,
            extra_attributes=attributes,
        )
        if write_future is not None:
            write_future.result()
        self._save_entity_attributes(
            entity_root_path=entity_root, updates=attributes
        )
        return write_future
    except (OSError, ValueError) as e:
        print(e)
        print("Error saving feature_predictor image.")
        raise

`save_local_feature_predictor_spots(spot_df, tile, bit)`

Save feature_predictor localizations and features.

Parameters:

Name	Type	Description	Default
`spot_df`	`DataFrame`	feature_predictor localizations and features.	required
`tile`	`int or str`	Tile index or tile id.	required
`bit`	`int or str`	Bit index or bit id.	required

Source code in src/merfish3danalysis/qi2labDataStore.py

def save_local_feature_predictor_spots(
    self,
    spot_df: pd.DataFrame,
    tile: int | str,
    bit: int | str,
) -> None:
    """Save feature_predictor localizations and features.

    Parameters
    ----------
    spot_df : pd.DataFrame
        feature_predictor localizations and features.
    tile : int or str
        Tile index or tile id.
    bit : int or str
        Bit index or bit id.
    """
    if isinstance(tile, int):
        if tile < 0 or tile >= self._num_tiles:
            print("Set tile index >=0 and <" + str(self._num_tiles))
            return None
        else:
            tile_id = self._tile_ids[tile]
    elif isinstance(tile, str):
        if tile not in self._tile_ids:
            print("set valid tiled id")
            return None
        else:
            tile_id = tile
    else:
        print("'tile' must be integer index or string identifier")
        return None

    if isinstance(bit, int):
        if bit < 0 or bit >= len(self._bit_ids):
            print("Set bit index >=0 and <" + str(len(self._bit_ids)))
            return None
        else:
            bit_id = self._bit_ids[bit]
    elif isinstance(bit, str):
        if bit not in self._bit_ids:
            print("Set valid bit id")
            return None
        else:
            bit_id = bit
    else:
        print("'bit' must be integer index or string identifier")
        return None

    tile_localizations_path = (
        self._feature_predictor_localizations_root_path / Path(tile_id)
    )
    tile_localizations_path.mkdir(parents=True, exist_ok=True)

    current_feature_predictor_localizations_path = tile_localizations_path / Path(
        bit_id + ".parquet"
    )

    try:
        self._save_to_parquet(spot_df, current_feature_predictor_localizations_path)
    except OSError as e:
        print(e)
        print("Error saving feature_predictor localizations.")
        return None

`save_local_rigid_xform_xyz_px(rigid_xform_xyz_px, tile, round)`

Save calculated rigid registration transform for one round and tile.

Parameters:

Name	Type	Description	Default
`rigid_xform_xyz_px`	`ArrayLike`	Local rigid registration transform for one round and tile.	required
`tile`	`int or str`	Tile index or tile id.	required
`round`	`int or str`	Round index or round id.	required

Returns:

Name	Type	Description
`rigid_xform_xyz_px`	`ArrayLike or None`	Local rigid registration transform for one round and tile.

Source code in src/merfish3danalysis/qi2labDataStore.py

def save_local_rigid_xform_xyz_px(
    self,
    rigid_xform_xyz_px: ArrayLike,
    tile: int | str,
    round: int | str,
) -> ArrayLike | None:
    """Save calculated rigid registration transform for one round and tile.

    Parameters
    ----------
    rigid_xform_xyz_px : ArrayLike
        Local rigid registration transform for one round and tile.
    tile : int or str
        Tile index or tile id.
    round : int or str
        Round index or round id.

    Returns
    -------
    rigid_xform_xyz_px : ArrayLike or None
        Local rigid registration transform for one round and tile.
    """
    if isinstance(tile, int):
        if tile < 0 or tile >= self._num_tiles:
            print("Set tile index >=0 and <" + str(self._num_tiles))
            return None
        else:
            tile_id = self._tile_ids[tile]
    elif isinstance(tile, str):
        if tile not in self._tile_ids:
            print("set valid tiled id")
            return None
        else:
            tile_id = tile
    else:
        print("'tile' must be integer index or string identifier")
        return None

    if isinstance(round, int):
        if round < 0 or round >= len(self._round_ids):
            print("Set round index >=0 and <" + str(self._num_rounds))
            return None
        else:
            round_id = self._round_ids[round]
    elif isinstance(round, str):
        if round not in self._round_ids:
            print("Set valid round id")
            return None
        else:
            round_id = round
    else:
        print("'round' must be integer index or string identifier")
        return None
    try:
        entity_root = self._fiducial_root_path / Path(tile_id) / Path(round_id)
        self._save_entity_attributes(
            entity_root_path=entity_root,
            updates={
                "rigid_xform_xyz_px": np.asarray(
                    rigid_xform_xyz_px, dtype=np.float32
                ).tolist()
            },
        )
    except (FileNotFoundError, json.JSONDecodeError, TypeError, ValueError):
        print("Error writing rigid transform attribute.")
        return None

`save_local_round_linker(round_linker, tile, bit)`

Save fiducial round linker attribute to readout bit for one tile.

Parameters:

Name	Type	Description	Default
`round_linker`	`int`	Fiducial round linked to readout bit for one tile.	required
`tile`	`int or str`	Tile index or tile id.	required
`bit`	`int or str`	Bit index or bit id.	required

Source code in src/merfish3danalysis/qi2labDataStore.py

def save_local_round_linker(
    self,
    round_linker: int,
    tile: int | str,
    bit: int | str,
) -> None:
    """Save fiducial round linker attribute to readout bit for one tile.

    Parameters
    ----------
    round_linker : int
        Fiducial round linked to readout bit for one tile.
    tile : int or str
        Tile index or tile id.
    bit : int or str
        Bit index or bit id.
    """
    if isinstance(tile, int):
        if tile < 0 or tile >= self._num_tiles:
            print("Set tile index >=0 and <" + str(self._num_tiles))
            return None
        else:
            tile_id = self._tile_ids[tile]
    elif isinstance(tile, str):
        if tile not in self._tile_ids:
            print("set valid tiled id.")
            return None
        else:
            tile_id = tile
    else:
        print("'tile' must be integer index or string identifier")
        return None

    if isinstance(bit, int):
        if bit < 0 or bit >= len(self._bit_ids):
            print("Set bit index >=0 and <" + str(len(self._bit_ids)))
            return None
        else:
            bit_id = self._bit_ids[bit]
    elif isinstance(bit, str):
        if bit not in self._bit_ids:
            print("Set valid bit id.")
            return None
        else:
            bit_id = bit
    else:
        print("'bit' must be integer index or string identifier")
        return None

    try:
        entity_root = self._readouts_root_path / Path(tile_id) / Path(bit_id)
        self._save_entity_attributes(
            entity_root_path=entity_root,
            updates={"round_linker": int(round_linker)},
        )
    except (TypeError, ValueError):
        print(tile_id, bit_id)
        print("Error writing round linker attribute.")
        return None

`save_local_round_transform_zyx_um(transform_zyx_um, tile, round)`

Save the local fiducial round transform for one tile.

Parameters:

Name	Type	Description	Default
`transform_zyx_um`	`ArrayLike`	Homogeneous 4x4 affine transform in physical Z, Y, X microns. The transform maps first-round reference coordinates to coordinates in the requested moving round.	required
`tile`	`int \| str`	Tile index or tile identifier.	required
`round`	`int \| str`	Fiducial round index or round identifier.	required

Returns:

Type	Description
`None`	The transform is stored in the entity attributes for the requested fiducial tile and round.

Source code in src/merfish3danalysis/qi2labDataStore.py

def save_local_round_transform_zyx_um(
    self,
    transform_zyx_um: ArrayLike,
    tile: int | str,
    round: int | str,
) -> None:
    """
    Save the local fiducial round transform for one tile.

    Parameters
    ----------
    transform_zyx_um : ArrayLike
        Homogeneous 4x4 affine transform in physical Z, Y, X microns. The
        transform maps first-round reference coordinates to coordinates in
        the requested moving round.
    tile : int | str
        Tile index or tile identifier.
    round : int | str
        Fiducial round index or round identifier.

    Returns
    -------
    None
        The transform is stored in the entity attributes for the requested
        fiducial tile and round.
    """
    if isinstance(tile, int):
        if tile < 0 or tile >= self._num_tiles:
            print("Set tile index >=0 and <" + str(self._num_tiles))
            return None
        tile_id = self._tile_ids[tile]
    elif isinstance(tile, str):
        if tile not in self._tile_ids:
            print("set valid tiled id")
            return None
        tile_id = tile
    else:
        print("'tile' must be integer index or string identifier")
        return None

    if isinstance(round, int):
        if round < 0 or round >= len(self._round_ids):
            print("Set round index >=0 and <" + str(self._num_rounds))
            return None
        round_id = self._round_ids[round]
    elif isinstance(round, str):
        if round not in self._round_ids:
            print("Set valid round id")
            return None
        round_id = round
    else:
        print("'round' must be integer index or string identifier")
        return None
    try:
        entity_root = self._fiducial_root_path / Path(tile_id) / Path(round_id)
        self._save_entity_attributes(
            entity_root_path=entity_root,
            updates={
                "local_round_transform_zyx_um": np.asarray(
                    transform_zyx_um, dtype=np.float32
                ).tolist()
            },
        )
    except (FileNotFoundError, json.JSONDecodeError, TypeError, ValueError):
        print("Error writing local round transform attribute.")
        return None

`save_local_sofima_flow_field(sofima_flow_field_xyz_px, *, tile, round, reference_round, map_stride_zyx_px, map_box_start_xyz_px, map_box_size_xyz_px, reference_shape_zyx_px, moving_shape_zyx_px, sofima_status='ok', valid_flow_vectors=None, return_future=False)`

Save the SOFIMA flow field for one local fiducial round.

The saved OME-Zarr image stores the raw float32 SOFIMA map exactly as used in memory. The package convention is channel-first (3, z, y, x) with channels X, Y, Z and spatial axes Z, Y, X. Flow values are relative displacements in reference-image pixels from a reference coordinate to the affine-initialized moving coordinate. map_box_start_xyz_px is the reference coordinate of the first flow sample in X, Y, Z order. SOFIMA patch-correlation vectors are patch-centered, so this is normally half the patch size.

Parameters:

Name	Type	Description	Default
`sofima_flow_field_xyz_px`	`ArrayLike`	Relative SOFIMA flow field with channels X, Y, Z and spatial axes Z, Y, X.	required
`tile`	`int or str`	Tile index or tile identifier.	required
`round`	`int or str`	Moving fiducial round index or identifier.	required
`reference_round`	`int or str`	Reference fiducial round index or identifier.	required
`map_stride_zyx_px`	`Sequence[float]`	Flow-field stride in reference pixels in Z, Y, X order.	required
`map_box_start_xyz_px`	`Sequence[float]`	Reference pixel coordinate of the first flow sample in X, Y, Z order.	required
`map_box_size_xyz_px`	`Sequence[float]`	Flow-field sample-lattice extent in X, Y, Z order, measured from `map_box_start_xyz_px` through the last stored map sample.	required
`reference_shape_zyx_px`	`Sequence[int]`	Reference image shape in Z, Y, X order.	required
`moving_shape_zyx_px`	`Sequence[int]`	Moving native image shape in Z, Y, X order.	required
`sofima_status`	`str`	Status reported by the SOFIMA estimator.	`"ok"`
`valid_flow_vectors`	`int or None`	Number of valid local vectors before missing-vector fill.	`None`
`return_future`	`bool or None`	Return the completed TensorStore write handle when True. Writes finish before associated metadata is reported as saved.	`False`

Returns:

Type	Description
`WriteFutures or None`	Completed pixel-write handle when return_future is True; otherwise None. Invalid tile or round selections also return None.

Source code in src/merfish3danalysis/qi2labDataStore.py

def save_local_sofima_flow_field(
    self,
    sofima_flow_field_xyz_px: ArrayLike,
    *,
    tile: int | str,
    round: int | str,
    reference_round: int | str,
    map_stride_zyx_px: Sequence[float],
    map_box_start_xyz_px: Sequence[float],
    map_box_size_xyz_px: Sequence[float],
    reference_shape_zyx_px: Sequence[int],
    moving_shape_zyx_px: Sequence[int],
    sofima_status: str = "ok",
    valid_flow_vectors: int | None = None,
    return_future: bool | None = False,
) -> "WriteFutures | None":
    """
    Save the SOFIMA flow field for one local fiducial round.

    The saved OME-Zarr image stores the raw float32 SOFIMA map exactly as
    used in memory. The package convention is channel-first ``(3, z, y,
    x)`` with channels ``X, Y, Z`` and spatial axes ``Z, Y, X``. Flow
    values are relative displacements in reference-image pixels from a
    reference coordinate to the affine-initialized moving coordinate.
    ``map_box_start_xyz_px`` is the reference coordinate of the first flow
    sample in ``X, Y, Z`` order. SOFIMA patch-correlation vectors are
    patch-centered, so this is normally half the patch size.

    Parameters
    ----------
    sofima_flow_field_xyz_px : ArrayLike
        Relative SOFIMA flow field with channels X, Y, Z and spatial axes
        Z, Y, X.
    tile : int or str
        Tile index or tile identifier.
    round : int or str
        Moving fiducial round index or identifier.
    reference_round : int or str
        Reference fiducial round index or identifier.
    map_stride_zyx_px : Sequence[float]
        Flow-field stride in reference pixels in Z, Y, X order.
    map_box_start_xyz_px : Sequence[float]
        Reference pixel coordinate of the first flow sample in X, Y, Z
        order.
    map_box_size_xyz_px : Sequence[float]
        Flow-field sample-lattice extent in X, Y, Z order, measured from
        ``map_box_start_xyz_px`` through the last stored map sample.
    reference_shape_zyx_px : Sequence[int]
        Reference image shape in Z, Y, X order.
    moving_shape_zyx_px : Sequence[int]
        Moving native image shape in Z, Y, X order.
    sofima_status : str, default="ok"
        Status reported by the SOFIMA estimator.
    valid_flow_vectors : int or None, default=None
        Number of valid local vectors before missing-vector fill.
    return_future : bool or None, default=False
        Return the completed TensorStore write handle when True. Writes
        finish before associated metadata is reported as saved.

    Returns
    -------
    tensorstore.WriteFutures or None
        Completed pixel-write handle when return_future is True; otherwise
        None. Invalid tile or round selections also return None.
    """
    if isinstance(tile, int):
        if tile < 0 or tile >= self._num_tiles:
            print("Set tile index >=0 and <" + str(self._num_tiles))
            return None
        tile_id = self._tile_ids[tile]
    elif isinstance(tile, str):
        if tile not in self._tile_ids:
            print("set valid tiled id")
            return None
        tile_id = tile
    else:
        print("'tile' must be integer index or string identifier")
        return None

    if isinstance(round, int):
        if round < 0 or round >= len(self._round_ids):
            print("Set round index >=0 and <" + str(self._num_rounds))
            return None
        round_id = self._round_ids[round]
    elif isinstance(round, str):
        if round not in self._round_ids:
            print("Set valid round id")
            return None
        round_id = round
    else:
        print("'round' must be integer index or string identifier")
        return None

    if isinstance(reference_round, int):
        if reference_round < 0 or reference_round >= len(self._round_ids):
            print("Set reference round index >=0 and <" + str(len(self._round_ids)))
            return None
        reference_round_id = self._round_ids[reference_round]
    elif isinstance(reference_round, str):
        if reference_round not in self._round_ids:
            print("Set valid reference round id")
            return None
        reference_round_id = reference_round
    else:
        print("'reference_round' must be integer index or string identifier")
        return None

    image_name = "local_sofima_flow_field"
    entity_root = self._fiducial_root_path / Path(tile_id) / Path(round_id)
    current_local_zarr_path = entity_root / Path(image_name)
    attributes = {
        "registration_backend": "sofima",
        "initial_registration_source": "stored_local_affine_transform",
        "flow_field_name": image_name,
        "flow_direction": (
            f"{reference_round_id}_reference_xyz_px_to_affine_initialized_"
            f"{round_id}_xyz_px"
        ),
        "final_render_direction": (
            f"{reference_round_id}_reference_xyz_px_to_moving_native_xyz_px"
        ),
        "flow_representation": "sofima_relative_coordinate_map",
        "flow_channel_order": "xyz",
        "flow_spatial_order": "zyx",
        "map_stride_zyx_px": np.asarray(
            map_stride_zyx_px, dtype=np.float32
        ).tolist(),
        "map_box_start_xyz_px": np.asarray(
            map_box_start_xyz_px, dtype=np.float32
        ).tolist(),
        "map_box_size_xyz_px": np.asarray(
            map_box_size_xyz_px, dtype=np.float32
        ).tolist(),
        "reference_shape_zyx_px": np.asarray(
            reference_shape_zyx_px, dtype=np.int64
        ).tolist(),
        "moving_shape_zyx_px": np.asarray(
            moving_shape_zyx_px, dtype=np.int64
        ).tolist(),
        "sofima_status": str(sofima_status),
        "interpolation_count_final_image": 1,
    }
    if valid_flow_vectors is not None:
        attributes["valid_flow_vectors"] = int(valid_flow_vectors)

    try:
        write_future = self._save_to_zarr_array(
            np.asarray(sofima_flow_field_xyz_px, dtype=np.float32),
            current_local_zarr_path,
            return_future,
            ome_scale=self.voxel_size_zyx_um,
            extra_attributes=attributes,
        )
        if write_future is not None:
            write_future.result()
        self._save_entity_attributes(
            entity_root_path=entity_root, updates=attributes
        )
        return write_future
    except (OSError, TimeoutError):
        print("Error saving SOFIMA flow field.")
        raise

`save_local_stage_position_zyx_um(stage_zyx_um, affine_zyx_px, tile, round)`

Save tile stage position for one tile.

Parameters:

Name	Type	Description	Default
`stage_zyx_um`	`ArrayLike`	Tile stage position in Z, Y, X microns. Two-coordinate Y, X input is accepted and stored as Z, Y, X with Z=0.	required
`affine_zyx_px`	`ArrayLike`	4x4 homogeneous affine matrix for stage transformation	required
`tile`	`int or str`	Tile index or tile id.	required
`round`	`int or str`	Round index or round id.	required

Source code in src/merfish3danalysis/qi2labDataStore.py

def save_local_stage_position_zyx_um(
    self,
    stage_zyx_um: ArrayLike,
    affine_zyx_px: ArrayLike,
    tile: int | str,
    round: int | str,
) -> None:
    """Save tile stage position for one tile.

    Parameters
    ----------
    stage_zyx_um : ArrayLike
        Tile stage position in Z, Y, X microns. Two-coordinate Y, X input
        is accepted and stored as Z, Y, X with Z=0.
    affine_zyx_px: ArrayLike
        4x4 homogeneous affine matrix for stage transformation
    tile : int or str
        Tile index or tile id.
    round : int or str
        Round index or round id.
    """
    if isinstance(tile, int):
        if tile < 0 or tile >= self._num_tiles:
            print("Set tile index >=0 and <" + str(self._num_tiles))
            return None
        else:
            tile_id = self._tile_ids[tile]
    elif isinstance(tile, str):
        if tile not in self._tile_ids:
            print("set valid tiled id.")
            return None
        else:
            tile_id = tile
    else:
        print("'tile' must be integer index or string identifier")
        return None

    if isinstance(round, int):
        if round < 0 or round >= len(self._round_ids):
            print("Set round index >=0 and <" + str(self._num_rounds))
            return None
        else:
            round_id = self._round_ids[round]
    elif isinstance(round, str):
        if round not in self._round_ids:
            print("Set valid round id.")
            return None
        else:
            round_id = round
    else:
        print("'round' must be integer index or string identifier")
        return None

    try:
        entity_root = self._fiducial_root_path / Path(tile_id) / Path(round_id)
        stage_zyx_um = self._normalize_stage_position_zyx_um(stage_zyx_um)
        self._save_entity_attributes(
            entity_root_path=entity_root,
            updates={
                "stage_zyx_um": stage_zyx_um.tolist(),
                "affine_zyx_px": np.asarray(
                    affine_zyx_px, dtype=np.float32
                ).tolist(),
            },
        )
        self._update_image_translation_transform(
            entity_root / Path("corrected_data"), stage_zyx_um
        )
    except (TypeError, ValueError):
        print(tile_id, round_id)
        print("Error writing stage position attribute.")
        return None

`save_local_wavelengths_um(wavelengths_um, tile, round=None, bit=None)`

Save wavelengths for fiducial OR readout bit for one tile.

Parameters:

Name	Type	Description	Default
`wavelengths_um`	`tuple[float, float]`	Wavelengths for fiducial OR readout bit for one tile.	required
`tile`	`int or str`	Tile index or tile id.	required
`round`	`int or str or None`	Round index or round id.	`None`
`bit`	`int or str or None`	Bit index or bit id.	`None`

Returns:

Name	Type	Description
`wavelengths_um`	`tuple[float, float] or None`	Wavelengths for fiducial OR readout bit for one tile.

Source code in src/merfish3danalysis/qi2labDataStore.py

def save_local_wavelengths_um(
    self,
    wavelengths_um: tuple[float, float],
    tile: int | str,
    round: int | str | None = None,
    bit: int | str | None = None,
) -> tuple[float, float] | None:
    """Save wavelengths for fiducial OR readout bit for one tile.

    Parameters
    ----------
    wavelengths_um : tuple[float, float]
        Wavelengths for fiducial OR readout bit for one tile.
    tile : int or str
        Tile index or tile id.
    round : int or str or None
        Round index or round id.
    bit : int or str or None
        Bit index or bit id.

    Returns
    -------
    wavelengths_um : tuple[float, float] or None
        Wavelengths for fiducial OR readout bit for one tile.
    """
    if (round is None and bit is None) or (round is not None and bit is not None):
        print("Provide either 'round' or 'bit', but not both")
        return None

    if isinstance(tile, int):
        if tile < 0 or tile >= self._num_tiles:
            print("Set tile index >=0 and <" + str(self._num_tiles))
            return None
        else:
            tile_id = self._tile_ids[tile]
    elif isinstance(tile, str):
        if tile not in self._tile_ids:
            print("set valid tiled id")
            return None
        else:
            tile_id = tile
    else:
        print("'tile' must be integer index or string identifier")
        return None

    if bit is not None:
        if isinstance(bit, int):
            if bit < 0 or bit >= len(self._bit_ids):
                print("Set bit index >=0 and <" + str(len(self._bit_ids)))
                return None
            else:
                local_id = self._bit_ids[bit]
        elif isinstance(bit, str):
            if bit not in self._bit_ids:
                print("Set valid bit id")
                return None
            else:
                local_id = bit
        else:
            print("'bit' must be integer index or string identifier")
            return None
        entity_root = self._readouts_root_path / Path(tile_id) / Path(local_id)
    else:
        if isinstance(round, int):
            if round < 0 or round >= len(self._round_ids):
                print("Set round index >=0 and <" + str(self._num_rounds))
                return None
            else:
                local_id = self._round_ids[round]
        elif isinstance(round, str):
            if round not in self._round_ids:
                print("Set valid round id")
                return None
            else:
                local_id = round
        else:
            print("'round' must be integer index or string identifier")
            return None
        entity_root = self._fiducial_root_path / Path(tile_id) / Path(local_id)

    try:
        self._save_entity_attributes(
            entity_root_path=entity_root,
            updates={
                "excitation_um": float(wavelengths_um[0]),
                "emission_um": float(wavelengths_um[1]),
            },
        )
    except (FileNotFoundError, json.JSONDecodeError, TypeError, ValueError):
        print("Error writing wavelength attributes.")
        return None

DataStore Class

qi2labDataStore

binning property writable

bit_ids property

camera_model property writable

channel_psfs property writable

channel_shading_maps property writable

channels_in_data property writable

codebook property writable

datastore_path property

datastore_state property writable

e_per_ADU property writable

experiment_order property writable

global_background_vector property writable

global_normalization_vector property writable

iterative_background_vector property writable

iterative_normalization_vector property writable

microscope_type property writable

na property writable

noise_map property writable

num_bits property writable

num_rounds property writable

num_tiles property writable

ri property writable

round_ids property

tile_ids property

tile_overlap property writable

voxel_size_zyx_um property writable

__init__(datastore_path, validate=True)

_build_axes(v05, ndim) staticmethod

_calibrations_attributes_path()

_check_for_zarr_array(image_path) staticmethod

_coerce_experiment_order_dataframe(value)

_collect_strict_ids(parent, prefix, width) classmethod

_create_array_tensorstore_qi2lab(path, shape, dtype, chunks, *, shards, dimension_names, overwrite, compression) staticmethod

_decoded_run_root(decode_run_key=None)

_default_chunks(array, spatial_chunk_zyx=(16, 512, 512)) staticmethod

_entity_attributes_path(entity_root_path) staticmethod

_fused_image_chunks(array) staticmethod

_global_filtered_decoded_root(decode_run_key=None)

_image_store_path(image_path) staticmethod

_init_datastore()

_load_calibrations_attributes()

_load_entity_attributes(entity_root_path, image_names=None)

_load_from_json(dictionary_path) staticmethod

_load_from_microjson(dictionary_path) staticmethod

_load_from_parquet(parquet_path) staticmethod

_load_from_zarr_array(image_path, return_future=True) staticmethod

_normalize_stage_position_zyx_um(stage_zyx_um) staticmethod

_normalize_transform(values, ndim, fill) staticmethod

_normalize_voxel_size_zyx_um(value) staticmethod

_parse_datastore(validate=True)

_proseg_3d_root()

_proseg_3d_run_root(run_name=None)

_resolve_original_tile_position_zyx_um(tile_id, round_id=None, bit_id=None)

_resolve_reference_tile_position_zyx_um(tile_id)

_save_calibrations_attributes(attributes)

_save_default_decode_normalization_metadata(kind, metadata)

_save_entity_attributes(entity_root_path, updates)

_save_to_csv_gz(df, csv_gz_path) staticmethod

_save_to_json(dictionary, dictionary_path) staticmethod

_save_to_parquet(df, parquet_path) staticmethod

_save_to_zarr_array(array, image_path, return_future=False, *, chunks=None, ome_scale=None, ome_translation=None, extra_attributes=None) staticmethod

_set_calibration_attribute(key, value)

_strict_id_sort_key(name, prefix, width) staticmethod

_to_json_compatible(value) staticmethod

_update_image_translation_transform(image_root, stage_zyx_um)

_validate_core_image_shape(entity_root_path, image_name, image)

_validate_decode_run_key(decode_run_key) staticmethod

baysor_3d_available()

decoded_temporary_dir(decode_run_key=None, iteration=None)

fused_image_path(image_name=None)

image_shape(image_path) staticmethod

initialize_tile(tile)

list_proseg_3d_runs()

load_baysor_cell_boundaries_3d()

load_baysor_molecules_3d()

load_chromatic_affine_transform_zyx_um(channel_name=None, channel_index=None, wavelength_um=None)

load_chromatic_affine_transforms_zyx_um()

load_codebook_parsed()

`qi2labDataStore`

`binning` `property` `writable`

`bit_ids` `property`

`camera_model` `property` `writable`

`channel_psfs` `property` `writable`

`channel_shading_maps` `property` `writable`

`channels_in_data` `property` `writable`

`codebook` `property` `writable`

`datastore_path` `property`

`datastore_state` `property` `writable`

`e_per_ADU` `property` `writable`

`experiment_order` `property` `writable`

`global_background_vector` `property` `writable`

`global_normalization_vector` `property` `writable`

`iterative_background_vector` `property` `writable`

`iterative_normalization_vector` `property` `writable`

`microscope_type` `property` `writable`

`na` `property` `writable`

`noise_map` `property` `writable`

`num_bits` `property` `writable`

`num_rounds` `property` `writable`

`num_tiles` `property` `writable`

`ri` `property` `writable`

`round_ids` `property`

`tile_ids` `property`

`tile_overlap` `property` `writable`

`voxel_size_zyx_um` `property` `writable`

`init(datastore_path, validate=True)`

`_build_axes(v05, ndim)` `staticmethod`

`_calibrations_attributes_path()`

`_check_for_zarr_array(image_path)` `staticmethod`

`_coerce_experiment_order_dataframe(value)`

`_collect_strict_ids(parent, prefix, width)` `classmethod`

`_create_array_tensorstore_qi2lab(path, shape, dtype, chunks, *, shards, dimension_names, overwrite, compression)` `staticmethod`

`_decoded_run_root(decode_run_key=None)`

`_default_chunks(array, spatial_chunk_zyx=(16, 512, 512))` `staticmethod`

`_entity_attributes_path(entity_root_path)` `staticmethod`

`_fused_image_chunks(array)` `staticmethod`

`_global_filtered_decoded_root(decode_run_key=None)`

`_image_store_path(image_path)` `staticmethod`

`_init_datastore()`

`_load_calibrations_attributes()`

`_load_entity_attributes(entity_root_path, image_names=None)`

`_load_from_json(dictionary_path)` `staticmethod`

`_load_from_microjson(dictionary_path)` `staticmethod`

`_load_from_parquet(parquet_path)` `staticmethod`

`_load_from_zarr_array(image_path, return_future=True)` `staticmethod`

`_normalize_stage_position_zyx_um(stage_zyx_um)` `staticmethod`

`_normalize_transform(values, ndim, fill)` `staticmethod`

`_normalize_voxel_size_zyx_um(value)` `staticmethod`

`_parse_datastore(validate=True)`

`_proseg_3d_root()`

`_proseg_3d_run_root(run_name=None)`

`_resolve_original_tile_position_zyx_um(tile_id, round_id=None, bit_id=None)`

`_resolve_reference_tile_position_zyx_um(tile_id)`

`_save_calibrations_attributes(attributes)`

`_save_default_decode_normalization_metadata(kind, metadata)`

`_save_entity_attributes(entity_root_path, updates)`

`_save_to_csv_gz(df, csv_gz_path)` `staticmethod`

`_save_to_json(dictionary, dictionary_path)` `staticmethod`

`_save_to_parquet(df, parquet_path)` `staticmethod`

`_save_to_zarr_array(array, image_path, return_future=False, *, chunks=None, ome_scale=None, ome_translation=None, extra_attributes=None)` `staticmethod`

`_set_calibration_attribute(key, value)`

`_strict_id_sort_key(name, prefix, width)` `staticmethod`

`_to_json_compatible(value)` `staticmethod`

`_update_image_translation_transform(image_root, stage_zyx_um)`

`_validate_core_image_shape(entity_root_path, image_name, image)`

`_validate_decode_run_key(decode_run_key)` `staticmethod`

`baysor_3d_available()`

`decoded_temporary_dir(decode_run_key=None, iteration=None)`

`fused_image_path(image_name=None)`

`image_shape(image_path)` `staticmethod`

`initialize_tile(tile)`

`list_proseg_3d_runs()`

`load_baysor_cell_boundaries_3d()`

`load_baysor_molecules_3d()`

`load_chromatic_affine_transform_zyx_um(channel_name=None, channel_index=None, wavelength_um=None)`

`load_chromatic_affine_transforms_zyx_um()`

`load_codebook_parsed()`

`load_coord_of_xform_px(tile, round, return_future=True)`