spatiomic.process ================= .. py:module:: spatiomic.process .. autoapi-nested-parse:: 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 ------- .. autoapisummary:: spatiomic.process.clip spatiomic.process.log1p spatiomic.process.normalize spatiomic.process.register spatiomic.process.zscore Package Contents ---------------- .. py:class:: clip(method = 'percentile', percentile_min = 1.0, percentile_max = 99.9, min_value = None, max_value = None, fill_value = None, use_gpu = True) Bases: :py:obj:`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. :param method: Whether to use percentiles or min and max values. Defaults to "percentile". :type method: Literal["percentile", "minmax"], optional :param percentile_min: The percentile to calculate the channel-wise minimum clipping value. Defaults to 1.0. :type percentile_min: float, optional :param percentile_max: The percentile to calculate the channel-wise maximum clipping value. Defaults to 99.9. :type percentile_max: float, optional :param min_value: The minimum clipping value. Defaults to None. :type min_value: Optional[Union[float, NDArray]], optional :param max_value: The maximum clipping value. Defaults to None. :type max_value: Optional[Union[float, NDArray]], optional :param fill_value: The value to replace values outside of the range with. Defaults to None. :type fill_value: Optional[Union[float, NDArray]], optional :param use_gpu: Whether to use cupy on the GPU or numpy on the CPU. Defaults to True. :type use_gpu: bool, optional .. py:attribute:: fill_value :type: Optional[numpy.typing.NDArray] :value: None .. py:method:: fit(data, fraction = 1.0) Calculate the channel-wise minimum and maximum clipping value based on provided percentiles. :param data: An array with channels being the last dimension. :type data: NDArray :param fraction: Fraction of data to randomly use for min and max value calculation. Defaults to 1.0. :type fraction: float, optional .. py:method:: fit_transform(data, fraction = 1.0) Fit the min and max value and transform provided data. :param data: An array with channels being the last dimension. :type data: NDArray :param fraction: Fraction of data to randomly use for min and max value calculation. Defaults to 1.0. :type fraction: float, optional :returns: The channel-wise clipped data. :rtype: NDArray .. py:attribute:: fitted .. py:method:: load(save_path) :classmethod: Load a Clip object from a file. :param save_path: The path to load the Clip object from. :type save_path: str :returns: The loaded Clip object. :rtype: Clip .. py:attribute:: max_value :type: Optional[numpy.typing.NDArray] :value: None .. py:attribute:: method :value: 'percentile' .. py:attribute:: min_value :type: Optional[numpy.typing.NDArray] :value: None .. py:attribute:: percentile_max :value: 99.9 .. py:attribute:: percentile_max_absolute :type: Optional[numpy.typing.NDArray] :value: None .. py:attribute:: percentile_min :value: 1.0 .. py:attribute:: percentile_min_absolute :type: Optional[numpy.typing.NDArray] :value: None .. py:method:: save(save_path) Save the Clip object to a file. :param save_path: The path to save the Clip object to. :type save_path: str .. py:method:: transform(data) Calculate the clipped data based on previously fit min and max clipping values. :param data: The data, at least two-dimensional, last dimension being channels. :type data: NDArray :returns: The channel-wise clipped data. :rtype: NDArray .. py:class:: log1p(use_gpu = True) Bases: :py:obj:`spatiomic.process._base.Processer` Initialise the Log1p class and set the numpy/cupy backend. Usage: .. code-block:: python 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. :param use_gpu: Whether to force numpy usage or use cupy or numpy depending on availability. Defaults to True. :type use_gpu: bool, optional .. py:method:: fit_transform(data) Fit and transform the data channel-wise. :param data: Data to fit and transform, channels being the last dimension. :type data: NDArray :returns: The log1p transformed data. :rtype: NDArray .. py:method:: inverse_transform(data) Inverse log1p transform the data channel-wise. :param data: Data to inverse log1p transform, channels being the last dimension. :type data: NDArray :returns: The inverse log1p transformed data. :rtype: NDArray .. py:method:: transform(data) Log1p transform the data channel-wise. :param data: Data to log1p transform, channels being the last dimension. :type data: NDArray :returns: The log1p transformed data. :rtype: NDArray .. py:class:: normalize(min_value = 0, max_value = 1, use_gpu = True) Bases: :py:obj:`spatiomic.process._base.Processer` Set the parameters for the Normalize class to normalize data channel-wise to a given range. :param min_value: The lower bound of the range the data should be normalised to. Defaults to 0.0. :type min_value: int, optional :param max_value: The upper bound of the range the data should be normalised to. Defaults to 1.0. :type max_value: int, optional :param use_gpu: Whether to use cuml and cupy on the GPU or sklearn and numpy on the CPU. Defaults to True. :type use_gpu: bool, optional .. py:attribute:: estimator .. py:method:: fit(data, fraction = 1.0) Fit the MinMaxScaler estimator of the class channel-wise to the data. :param data: The data of at least two dimensions, the last one being the channels. :type data: NDArray :param fraction: The random subsampling fraction to use to fit the estimator. Defaults to 1.0. :type fraction: float, optional .. py:method:: fit_transform(data, fraction = 1.0, clip = True) Fit the MinMaxScaler and transform the data to the range. :param data: The data of at least two dimensions, the last one being the channels. :type data: NDArray :param fraction: The random subsampling fraction to use to fit the estimator. Defaults to 1.0. :type fraction: float, optional :param clip: 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. :type clip: bool, optional :returns: The normalized data. :rtype: NDArray .. py:attribute:: fitted :value: False .. py:method:: load(load_path) :classmethod: Load a Normalize object from a file. :param load_path: The path to load the Normalize object from. :type load_path: str :returns: The loaded Normalize object. :rtype: Normalize .. py:attribute:: max_value :value: 1 .. py:attribute:: min_value :value: 0 .. py:method:: save(save_path) Save the Clip object to a file. :param save_path: The path to save the Clip object to. :type save_path: str .. py:method:: transform(data, clip = True) Normalize the data with the previously fit normalization estimator of the class. :param data: The data of at least two dimensions, the last one being the channels. :type data: NDArray :param clip: 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. :type clip: bool, optional :returns: The normalized data. :rtype: NDArray .. py:attribute:: use_gpu :value: True .. py:class:: register Expose registration methods. .. py:method:: apply_homography(pixels, homography) :staticmethod: Apply the homography to the pixels. :param pixels: The pixels to be warped. :type pixels: NDArray :returns: The warped pixels. :rtype: NDArray .. py:method:: apply_optical_flow(pixels, flow) :staticmethod: Apply the optical flow to the pixels. :param pixels: The pixels to be warped. :type pixels: NDArray :returns: The warped pixels. :rtype: NDArray .. py:method:: apply_shift(pixels, shift, precision = 'float32', use_gpu = True) :staticmethod: Shift the pixels of an image by a given offset. :param pixels: The 2D image to be shifted. :type pixels: NDArray :param shift: The y- and the x-offset to translate the image by. :type shift: Union[Tuple[float, float], NDArray[Float, Float]] :param precision: The precision of the pixels. Defaults to "float32". :type precision: Literal["float32", "float64"], optional :param use_gpu: Whether to use cupyx for translation on the GPU. Defaults to True. :type use_gpu: bool, optional :returns: The shifted image. :rtype: NDArray :raises ValueError: If the pixels do not have 2 or 3 dimensions. .. py:method:: get_homography(pixels, reference_pixels, keypoint_distance_multiplier = 0.7, knn_matcher = 'flann', ransac_threshold = 5.0) :staticmethod: Calculate the homography between two images. :param pixels: The pixels for which a shift is to be detected. :type pixels: NDArray :param reference_pixels: The reference pixels to calculate the shift with. :type reference_pixels: NDArray :param keypoint_distance_multiplier: The multiplier for the keypoint distance used in Lowe's ratio test. Defaults to 0.7. :type keypoint_distance_multiplier: float, optional :param knn_matcher: The keypoint matcher to use. Defaults to "flann". :type knn_matcher: Literal["bf", "flann"], optional :param ransac_threshold: The threshold for the RANSAC algorithm. Defaults to 5.0. :type ransac_threshold: float, optional :returns: The homography. :rtype: NDArray .. py:method:: get_optical_flow(pixels, reference_pixels, normalize = True) :staticmethod: Calculate the optical flow between two images. :param pixels: The pixels for which a shift is to be detected. :type pixels: NDArray :param reference_pixels: The reference pixels to calculate the shift with. :type reference_pixels: NDArray :param normalize: Whether to normalize the optical flow. Defaults to True. :type normalize: bool, optional :returns: The optical flow. :rtype: NDArray .. py:method:: get_phase_shift(pixels, reference_pixels, blur = False, match_histogram = False, threshold = False, upsample_factor = 1, use_gpu = True) :staticmethod: Calculate the y- and the x-offset between two images. :param pixels: The pixels for which a shift is to be detected. :type pixels: NDArray :param reference_pixels: The reference pixels to calculate the shift with. :type reference_pixels: NDArray :param blur: Whether to blur the reference and the pixels before calculating the shift. Defaults to False. :type blur: bool, optional :param match_histogram: Whether to match the histograms between the reference and the pixels. Defaults to False. :type match_histogram: bool, optional :param threshold: Whether to threshold the reference and the pixels to everything >= the 70th percentile of the reference. Defaults to False. :type threshold: bool, optional :param upsample_factor: The upsample factor to use for the phase correlation method. Defaults to 1. :type upsample_factor: int, optional :param use_gpu: Whether to use the cucim phase_correlation gpu implementation instead of chi2 shift. Defaults to True. :type use_gpu: bool, optional :returns: The offset on the y- and the x-axis. :rtype: Tuple[float, float] .. py:method:: get_shift(pixels, reference_pixels, blur = False, match_histogram = False, threshold = False, threshold_percentile = 70, method = 'phase_correlation', upsample_factor = 1, use_gpu = True) :classmethod: Calculate the y- and the x-offset between two images. :param pixels: The pixels for which a shift is to be detected. :type pixels: NDArray :param reference_pixels: The reference pixels to calculate the shift with. :type reference_pixels: NDArray :param blur: Whether to blur the reference and the pixels before calculating the shift. Defaults to False. :type blur: bool, optional :param match_histogram: Whether to match the histograms between the reference and the pixels. Defaults to False. :type match_histogram: bool, optional :param threshold: Whether to threshold the reference and the pixels to everything >= the 70th percentile of the reference. Defaults to False. :type threshold: bool, optional :param threshold_percentile: The percentile to use for thresholding. :type threshold_percentile: Union[int, float], optional :param method: The method to use for shift detection. Defaults to "phase_correlation". :type method: Literal["chi2_shift", "phase_correlation"], optional :param upsample_factor: The upsample factor to use for the phase correlation method. Defaults to 1. :type upsample_factor: int, optional :param use_gpu: Whether to use the cucim phase_correlation gpu implementation. Defaults to True. :type use_gpu: bool, optional :returns: The offset on the y- and the x-axis. :rtype: Tuple[float, float] .. py:method:: get_ssim(pixels, reference_pixels) :staticmethod: Calculate the structural similarity index measure. :param pixels: A 2D array of pixels. :type pixels: NDArray :param reference_pixels: The 2D reference array for calculation of the structural similarity. :type reference_pixels: NDArray :returns: The structural similarity index measure. :rtype: float .. py:class:: zscore(use_gpu = True) Bases: :py:obj:`spatiomic.process._base.Processer` Initialise the ZScore class and set mean and standard deviation to None. :param use_gpu: Whether to force numpy usage or use cupy or numpy depending on availability. Defaults to True. :type use_gpu: bool, optional .. py:method:: fit(data, fraction = 1.0) Calculate the channel-wise mean and standard deviation, optionally only on a random subset. :param data: Data for mean and standard deviation calculations, channels being the last dimension. :type data: NDArray :param fraction: Fraction of data to randomly use for mean and standard deviation calculation. Defaults to 1.0. :type fraction: float, optional .. py:method:: fit_transform(data, fraction = 1.0) Fit the mean and standard deviation and calculate z-scores on provided data. :param data: Data for z-scoring, channels being the last dimension. :type data: NDArray :param fraction: Fraction of data to randomly use for mean and standard deviation calculation. Defaults to 1.0. :type fraction: float, optional :returns: The channel-wise z-scored data. :rtype: NDArray .. py:method:: load(save_path) :classmethod: Load a ZScore object from a file. :param save_path: The path to load the ZScore object from. :type save_path: str :returns: The loaded ZScore object. :rtype: ZScore .. py:attribute:: mean :type: Optional[numpy.typing.NDArray] :value: None .. py:method:: save(save_path) Save the ZScore object to a file. :param save_path: The path to save the ZScore object to. :type save_path: str .. py:attribute:: std :type: Optional[numpy.typing.NDArray] :value: None .. py:method:: transform(data) Calculate z-scores based on previously fit mean and standard deviation. :param data: Data for z-scoring, channels being the last dimension. :type data: NDArray :returns: The channel-wise z-scored data. :rtype: NDArray .. py:attribute:: use_gpu :type: bool :value: True