spatiomic.process¶

Pre-/post-processing classes for image data.

spatiomic provides classes that facilitate common pre-/post-processing tasks for image data. However, this selection is not exhaustive. Many tools for transforming image data exist and users are encouraged to use the spatiomic classes togther with other tools, such as scikit-image.

Classes¶

`clip`	Initialise the Clip class and set the clipping parameters.
`log1p`	Initialise the Log1p class and set the numpy/cupy backend.
`normalize`	Set the parameters for the Normalize class to normalize data channel-wise to a given range.
`register`	Expose registration methods.
`zscore`	Initialise the ZScore class and set mean and standard deviation to None.

Package Contents¶

class spatiomic.process.clip(method='percentile', percentile_min=1.0, percentile_max=99.9, min_value=None, max_value=None, fill_value=None, use_gpu=True)¶

Bases: spatiomic.process._base.Processer

Initialise the Clip class and set the clipping parameters.

There are two methods of operation, either using percentiles or a specified range. If percentiles are used, the channel-wise minimum and maximum values are calculated based on the provided percentile values. If a range is used, the provided minimum and maximum values are used to clip the data. If a fill value is provided, values outside of the range are replaced with the fill value.

Parameters:

method (Literal["percentile", "minmax"], optional) – Whether to use percentiles or min and max values. Defaults to “percentile”.
percentile_min (float, optional) – The percentile to calculate the channel-wise minimum clipping value. Defaults to 1.0.
percentile_max (float, optional) – The percentile to calculate the channel-wise maximum clipping value. Defaults to 99.9.
min_value (Optional[Union[float, NDArray]], optional) – The minimum clipping value. Defaults to None.
max_value (Optional[Union[float, NDArray]], optional) – The maximum clipping value. Defaults to None.
fill_value (Optional[Union[float, NDArray]], optional) – The value to replace values outside of the range with. Defaults to None.
use_gpu (bool, optional) – Whether to use cupy on the GPU or numpy on the CPU. Defaults to True.

fill_value: numpy.typing.NDArray | None = None¶

fit(data, fraction=1.0)¶

Calculate the channel-wise minimum and maximum clipping value based on provided percentiles.

Parameters:

data (NDArray) – An array with channels being the last dimension.
fraction (float, optional) – Fraction of data to randomly use for min and max value calculation. Defaults to 1.0.

Return type:

None

fit_transform(data, fraction=1.0)¶

Fit the min and max value and transform provided data.

Parameters:

data (NDArray) – An array with channels being the last dimension.
fraction (float, optional) – Fraction of data to randomly use for min and max value calculation. Defaults to 1.0.

Returns:

The channel-wise clipped data.

Return type:

NDArray

fitted¶

classmethod load(save_path)¶

Load a Clip object from a file.

Parameters:: save_path (str) – The path to load the Clip object from.
Returns:: The loaded Clip object.
Return type:: Clip

max_value: numpy.typing.NDArray | None = None¶

method = 'percentile'¶

min_value: numpy.typing.NDArray | None = None¶

percentile_max = 99.9¶

percentile_max_absolute: numpy.typing.NDArray | None = None¶

percentile_min = 1.0¶

percentile_min_absolute: numpy.typing.NDArray | None = None¶

save(save_path)¶

Save the Clip object to a file.

Parameters:: save_path (str) – The path to save the Clip object to.
Return type:: None

transform(data)¶

Calculate the clipped data based on previously fit min and max clipping values.

Parameters:: data (NDArray) – The data, at least two-dimensional, last dimension being channels.
Returns:: The channel-wise clipped data.
Return type:: NDArray

class spatiomic.process.log1p(use_gpu=True)¶

Bases: spatiomic.process._base.Processer

Initialise the Log1p class and set the numpy/cupy backend.

Usage:

data = my_xyc_image

log1p = so.process.log1p()
data_log1p = log1p.fit_transform(data)

data_recovered = log1p.inverse_transform(data_log1p)

Warning

Critically evaluate whether the log1p transform is appropriate for your data. While often used for variance stabilization, it may distort the data in ways that are not desirable and is often not necessary.

Parameters:: use_gpu (bool, optional) – Whether to force numpy usage or use cupy or numpy depending on availability. Defaults to True.

fit_transform(data)¶

Fit and transform the data channel-wise.

Parameters:: data (NDArray) – Data to fit and transform, channels being the last dimension.
Returns:: The log1p transformed data.
Return type:: NDArray

inverse_transform(data)¶

Inverse log1p transform the data channel-wise.

Parameters:: data (NDArray) – Data to inverse log1p transform, channels being the last dimension.
Returns:: The inverse log1p transformed data.
Return type:: NDArray

transform(data)¶

Log1p transform the data channel-wise.

Parameters:: data (NDArray) – Data to log1p transform, channels being the last dimension.
Returns:: The log1p transformed data.
Return type:: NDArray

class spatiomic.process.normalize(min_value=0, max_value=1, use_gpu=True)¶

Bases: spatiomic.process._base.Processer

Set the parameters for the Normalize class to normalize data channel-wise to a given range.

Parameters:

min_value (int, optional) – The lower bound of the range the data should be normalised to. Defaults to 0.0.
max_value (int, optional) – The upper bound of the range the data should be normalised to. Defaults to 1.0.
use_gpu (bool, optional) – Whether to use cuml and cupy on the GPU or sklearn and numpy on the CPU. Defaults to True.

estimator¶

fit(data, fraction=1.0)¶

Fit the MinMaxScaler estimator of the class channel-wise to the data.

Parameters:

data (NDArray) – The data of at least two dimensions, the last one being the channels.
fraction (float, optional) – The random subsampling fraction to use to fit the estimator. Defaults to 1.0.

Return type:

None

fit_transform(data, fraction=1.0, clip=True)¶

Fit the MinMaxScaler and transform the data to the range.

Parameters:

data (NDArray) – The data of at least two dimensions, the last one being the channels.
fraction (float, optional) – The random subsampling fraction to use to fit the estimator. Defaults to 1.0.
clip (bool, optional) – Whether to restrict the data strictly to the minimum and maximum of the range the estimator was fitted to. This only has consequences if the data to be transformed differs from the data used for fitting. Defaults to True.

Returns:

The normalized data.

Return type:

NDArray

fitted = False¶

classmethod load(load_path)¶

Load a Normalize object from a file.

Parameters:: load_path (str) – The path to load the Normalize object from.
Returns:: The loaded Normalize object.
Return type:: Normalize

max_value = 1¶

min_value = 0¶

save(save_path)¶

Save the Clip object to a file.

Parameters:: save_path (str) – The path to save the Clip object to.
Return type:: None

transform(data, clip=True)¶

Normalize the data with the previously fit normalization estimator of the class.

Parameters:

data (NDArray) – The data of at least two dimensions, the last one being the channels.
clip (bool, optional) – Whether to restrict the data strictly to the minimum and maximum of the range the estimator was fitted to. This only has consequences if the data to be transformed differs from the data used for fitting. Defaults to True.

Returns:

The normalized data.

Return type:

NDArray

use_gpu = True¶

class spatiomic.process.register¶

Expose registration methods.

static apply_homography(pixels, homography)¶

Apply the homography to the pixels.

Parameters:

pixels (NDArray) – The pixels to be warped.
homography (numpy.typing.NDArray)

Returns:

The warped pixels.

Return type:

NDArray

static apply_optical_flow(pixels, flow)¶

Apply the optical flow to the pixels.

Parameters:

pixels (NDArray) – The pixels to be warped.
flow (numpy.typing.NDArray)

Returns:

The warped pixels.

Return type:

NDArray

static apply_shift(pixels, shift, precision='float32', use_gpu=True)¶

Shift the pixels of an image by a given offset.

Parameters:

pixels (NDArray) – The 2D image to be shifted.
shift (Union[Tuple[float, float], NDArray[Float, Float]]) – The y- and the x-offset to translate the image by.
precision (Literal["float32", "float64"], optional) – The precision of the pixels. Defaults to “float32”.
use_gpu (bool, optional) – Whether to use cupyx for translation on the GPU. Defaults to True.

Returns:

The shifted image.

Return type:

NDArray

Raises:

ValueError – If the pixels do not have 2 or 3 dimensions.

static get_homography(pixels, reference_pixels, keypoint_distance_multiplier=0.7, knn_matcher='flann', ransac_threshold=5.0)¶

Calculate the homography between two images.

Parameters:

pixels (NDArray) – The pixels for which a shift is to be detected.
reference_pixels (NDArray) – The reference pixels to calculate the shift with.
keypoint_distance_multiplier (float, optional) – The multiplier for the keypoint distance used in Lowe’s ratio test. Defaults to 0.7.
knn_matcher (Literal["bf", "flann"], optional) – The keypoint matcher to use. Defaults to “flann”.
ransac_threshold (float, optional) – The threshold for the RANSAC algorithm. Defaults to 5.0.

Returns:

The homography.

Return type:

NDArray

static get_optical_flow(pixels, reference_pixels, normalize=True)¶

Calculate the optical flow between two images.

Parameters:

pixels (NDArray) – The pixels for which a shift is to be detected.
reference_pixels (NDArray) – The reference pixels to calculate the shift with.
normalize (bool, optional) – Whether to normalize the optical flow. Defaults to True.

Returns:

The optical flow.

Return type:

NDArray

static get_phase_shift(pixels, reference_pixels, blur=False, match_histogram=False, threshold=False, upsample_factor=1, use_gpu=True)¶

Calculate the y- and the x-offset between two images.

Parameters:

pixels (NDArray) – The pixels for which a shift is to be detected.
reference_pixels (NDArray) – The reference pixels to calculate the shift with.
blur (bool, optional) – Whether to blur the reference and the pixels before calculating the shift. Defaults to False.
match_histogram (bool, optional) – Whether to match the histograms between the reference and the pixels. Defaults to False.
threshold (bool, optional) – Whether to threshold the reference and the pixels to everything >= the 70th percentile of the reference. Defaults to False.
upsample_factor (int, optional) – The upsample factor to use for the phase correlation method. Defaults to 1.
use_gpu (bool, optional) – Whether to use the cucim phase_correlation gpu implementation instead of chi2 shift. Defaults to True.

Returns:

The offset on the y- and the x-axis.

Return type:

Tuple[float, float]

classmethod get_shift(pixels, reference_pixels, blur=False, match_histogram=False, threshold=False, threshold_percentile=70, method='phase_correlation', upsample_factor=1, use_gpu=True)¶

Calculate the y- and the x-offset between two images.

Parameters:

pixels (NDArray) – The pixels for which a shift is to be detected.
reference_pixels (NDArray) – The reference pixels to calculate the shift with.
blur (bool, optional) – Whether to blur the reference and the pixels before calculating the shift. Defaults to False.
match_histogram (bool, optional) – Whether to match the histograms between the reference and the pixels. Defaults to False.
threshold (bool, optional) – Whether to threshold the reference and the pixels to everything >= the 70th percentile of the reference. Defaults to False.
threshold_percentile (Union[int, float], optional) – The percentile to use for thresholding.
method (Literal["chi2_shift", "phase_correlation"], optional) – The method to use for shift detection. Defaults to “phase_correlation”.
upsample_factor (int, optional) – The upsample factor to use for the phase correlation method. Defaults to 1.
use_gpu (bool, optional) – Whether to use the cucim phase_correlation gpu implementation. Defaults to True.

Returns:

The offset on the y- and the x-axis.

Return type:

Tuple[float, float]

static get_ssim(pixels, reference_pixels)¶

Calculate the structural similarity index measure.

Parameters:

pixels (NDArray) – A 2D array of pixels.
reference_pixels (NDArray) – The 2D reference array for calculation of the structural similarity.

Returns:

The structural similarity index measure.

Return type:

float

class spatiomic.process.zscore(use_gpu=True)¶

Bases: spatiomic.process._base.Processer

Initialise the ZScore class and set mean and standard deviation to None.

Parameters:: use_gpu (bool, optional) – Whether to force numpy usage or use cupy or numpy depending on availability. Defaults to True.

fit(data, fraction=1.0)¶

Calculate the channel-wise mean and standard deviation, optionally only on a random subset.

Parameters:

data (NDArray) – Data for mean and standard deviation calculations, channels being the last dimension.
fraction (float, optional) – Fraction of data to randomly use for mean and standard deviation calculation. Defaults to 1.0.

Return type:

None

fit_transform(data, fraction=1.0)¶

Fit the mean and standard deviation and calculate z-scores on provided data.

Parameters:

data (NDArray) – Data for z-scoring, channels being the last dimension.
fraction (float, optional) – Fraction of data to randomly use for mean and standard deviation calculation. Defaults to 1.0.

Returns:

The channel-wise z-scored data.

Return type:

NDArray

classmethod load(save_path)¶

Load a ZScore object from a file.

Parameters:: save_path (str) – The path to load the ZScore object from.
Returns:: The loaded ZScore object.
Return type:: ZScore

mean: numpy.typing.NDArray | None = None¶

save(save_path)¶

Save the ZScore object to a file.

Parameters:: save_path (str) – The path to save the ZScore object to.
Return type:: None

std: numpy.typing.NDArray | None = None¶

transform(data)¶

Calculate z-scores based on previously fit mean and standard deviation.

Parameters:: data (NDArray) – Data for z-scoring, channels being the last dimension.
Returns:: The channel-wise z-scored data.
Return type:: NDArray

use_gpu: bool = True¶