cellmap_flow.io.multiscale
==========================

.. py:module:: cellmap_flow.io.multiscale

.. autoapi-nested-parse::

   Choosing a level of a multiscale pyramid for a voxel size.

   The levels come from ``io.metadata.list_levels``, in the order the group's
   ``datasets`` list them (finest first, by convention); a precomputed
   volume's levels are its scales, in the order its info lists them. Voxel
   sizes are compared as nanometer floats on the spatial axes, so 10.48 nm is
   not 10 nm.



Attributes
----------

.. autoapisummary::

   cellmap_flow.io.multiscale.logger
   cellmap_flow.io.multiscale.Level
   cellmap_flow.io.multiscale.Mode


Functions
---------

.. autoapisummary::

   cellmap_flow.io.multiscale.same_voxel_size
   cellmap_flow.io.multiscale.coarser_anywhere
   cellmap_flow.io.multiscale.select_level
   cellmap_flow.io.multiscale.select_dataset
   cellmap_flow.io.multiscale.closest_raw_scale


Module Contents
---------------

.. py:data:: logger

.. py:data:: Level

.. py:function:: same_voxel_size(a, b) -> bool

   Equal as nanometer floats. Coordinate() truncated both sides, so a
   target of (10, 8, 8) matched an actual (10.48, 8, 8).


.. py:function:: coarser_anywhere(resolution, target) -> bool

   ``resolution`` is coarser than ``target`` along some axis.


.. py:data:: Mode

.. py:function:: select_level(levels: Sequence[Level], voxel_size=None, mode: Mode = 'floor') -> Level

   The ``(path, ArrayMeta)`` of ``levels`` to read at ``voxel_size``.

   With no ``voxel_size``, the first (finest) level. Otherwise, by ``mode``:

   - "floor": the level at ``voxel_size`` if there is one, else the last
     level before the first one that is coarser than ``voxel_size`` along
     some axis -- the finest level that is not too coarse, and the first
     level when even that is. This is how cellmap-flow has always chosen.
   - "exact": the level at ``voxel_size``; ValueError when there is none.
   - "nearest": the level whose voxel size is closest on a log scale
     (summed over the axes), the finer one on a tie.
   - "resample": the level to resample to ``voxel_size`` from
     (``io.resample``): the level at ``voxel_size`` if there is one (then
     nothing is resampled); else the coarsest level that is no coarser
     than ``voxel_size`` on any axis, so every axis is downsampled from as
     close as the pyramid allows; else, when every level is coarser on
     some axis, the finest level, which loses the least. Coarsest and
     finest are by voxel volume, the earlier level on a tie. Unlike
     "floor", this does not depend on the order the levels are listed in.


.. py:function:: select_dataset(dataset_path: str, voxel_size=None, mode: Mode = 'floor') -> Tuple[str, Optional[str]]

   ``(path of the array to read, level chosen)`` for a dataset path.

   A multiscale group resolves to its level for ``voxel_size`` (see
   ``select_level``); an array is read as it is, with level None. Raises
   when a group has no multiscales it can read.

   A precomputed volume is a group whose levels are its scales: it
   resolves to ``…/s<N>`` for ``voxel_size`` the same way, and the path of
   one scale is read as it is. Without a voxel size a volume is read at
   scale 0, the level select_level would give, without opening every scale
   to list them (a gs:// volume can have a dozen). It is never opened as
   zarr.


.. py:function:: closest_raw_scale(dataset_path: str, target_voxel_size) -> Optional[tuple]

   The voxel size (nm, z/y/x) of the level of ``dataset_path``'s pyramid
   that ``select_level`` picks for ``target_voxel_size``, or None if it
   can't be determined.

   ``dataset_path`` may be the multiscale group or one of its levels (a
   precomputed volume or one of its scales).