harpy.im.map_image

Contents

harpy.im.map_image#

harpy.im.map_image(sdata, image_name, output_image_name, func, fn_kwargs=mappingproxy({}), chunks=None, depth=None, blockwise=True, crd=None, to_coordinate_system='global', scale_factors=None, overwrite=False, **kwargs)#

Apply a specified function to an image element of a SpatialData object.

Function will be applied to each channel and z stack separately. Input and output dimension of func should be (1,1,y,x).

Parameters:

  • sdata (SpatialData) – Spatial data object containing the image to be processed.

  • image_name (str) – The image element in sdata to process.

  • output_image_name (str) – The name of the output element where results will be stored.

  • func (Callable[..., ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]] | Array] | Mapping[str, Any]) – The Callable to apply to the image. Can also be a Mapping if different Callable should be applied to different z_slices and/or channels e.g. { ‘channel1’: function, ‘channel2’: function2 … } or { ‘channel’: { ‘z_slice’: function … } … }. If a Mapping is specified, and fn_kwargs is specified then the Mapping should match the Mapping specified in fn_kwargs.

  • fn_kwargs (Mapping[str, Any] (default: mappingproxy({}))) – Keyword arguments to pass to func. If different fn_kwargs should be passed to different z_slices and or channels, one can specify e.g. {‘channel1’: fn_kwargs1, ‘channel2’: fn_kwargs2 … } or { ‘channel’: { ‘z_slice’: fn_kwargs … } … }.

  • chunks (str | int | tuple[int, ...] | None (default: None)) – Specification for rechunking the data before applying the function.

  • depth (tuple[int, int] | dict[int, int] | int | None (default: None)) – The overlapping depth used in dask.array.map_overlap. If not None, dask.array.map_overlap will be used, else dask.array.map_blocks. If specified as a tuple or dict, it contains the depth used in ‘y’ and ‘x’ dimension.

  • blockwise (bool (default: True)) – If True, func will be distributed with dask.array.map_overlap or dask.array.map_blocks, otherwise func is applied to the full data. If False, depth is ignored.

  • crd (tuple[int, int, int, int] | None (default: None)) – The coordinates specifying the region of the image to be processed. Defines the bounds (x_min, x_max, y_min, y_max).

  • to_coordinate_system (str (default: 'global')) – The coordinate system to which the crd is specified. Ignored if crd is None.

  • scale_factors (Sequence[dict[str, int] | int] | None (default: None)) – Scale factors to apply for multiscale.

  • overwrite (bool (default: False)) – If True, overwrites the output element if it already exists in sdata.

  • kwargs (Any) – Additional keyword arguments to pass to dask.array.map_overlap() or dask.array.map_blocks(). Ignored if blockwise is set to False.

Return type:

SpatialData

Returns:

: The sdata object with the processed image added to the specified output element.

Raises:

ValueError – If depth is a Tuple, and does not match (y,x).

Notes

This function is designed for processing images stored in a SpatialData object using Dask for potential parallelism and out-of-core computation. Depending on the chunks parameter and other settings, it can leverage dask’s map_overlap or map_blocks functions to apply the desired image processing function.

Examples

Apply a custom function my_function to all channels of an image element using different parameters for each channel (we assume sdata[ “raw_image” ] has 2 channels, 0 and 1, and has dimensions c,y,x ):

>>> def my_function( image, parameter ):
...    return image*parameter
>>> fn_kwargs={ 0: { "parameter": 2 }, 1: { "parameter": 3 } }
>>> sdata = apply(sdata, image_name="raw_image", output_image_name="processed_image", func=my_function, fn_kwargs=fn_kwargs,)

Apply the same function to all channels of the image with the same parameters:

>>> fn_kwargs={ "parameter": 2 }
>>> sdata = apply(sdata, image_name="raw_image", output_image_name="processed_image", func=my_function, fn_kwargs=fn_kwargs,)

Apply a custom function my_function to all z slices of an image element using different parameters for each z slice (we assume sdata[ “raw_image” ] has 2 z slices at 0.5 and 1.5, and has dimensions c,z,y,x ):

>>> def my_function( image, parameter ):
...    return image*parameter
>>> fn_kwargs={ 0.5: { "parameter": 2 }, 1.5: { "parameter": 3 } }
>>> sdata = apply(sdata, image_name="raw_image", output_image_name="processed_image", func=my_function, fn_kwargs=fn_kwargs,)

Apply a custom function my_function to all z slices and channels of an image element using different parameters for each z slice and channel. (we assume sdata[ “raw_image” ] has 2 channels 0 and 1, and 2 z slices at 0.5 and 1.5, and has dimensions c,z,y,x ):

>>> def my_function( image, parameter ):
...    return image*parameter
>>> fn_kwargs={ 0: {  0.5: { "parameter": 2 }, 1.5: { "parameter": 3 } }, 1: {  0.5: { "parameter": 4 }, 1.5: { "parameter": 5 } }  }
>>> sdata = apply(sdata, image_name="raw_image", output_image_name="processed_image", func=my_function, fn_kwargs=fn_kwargs,)
Contents