isosegdenoise.processing_class ============================== .. py:module:: isosegdenoise.processing_class .. autoapi-nested-parse:: This module contains the back-end / image processing classes and functions that handle image segmentation and denoising. Particularly the ImageProcessing class and its subclasses handles most of these functions. This is also the only important module for the non-GUI API of isoSegDenoise, and the only module that call to the _steinbock.py module. Portions of this file are derivative / partially copy&paste with modification from the steinbock package: Steinbock License ----------------- MIT License Copyright (c) 2021 University of Zurich Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ----------------- functions of relevance derived from steinbock marked with a comment like: # ****stein_derived (notes) Additionally, the assumed directory structure and panel file are derived from those structures/files from steinbock The simple denoise method here is a self-made algorithm, although it was made with the assistance of the skimage documentation. (probably not genuinely / legally considered "derivative" of those doc files, but the skimage doc files are: Copyright: 2009-2022 the scikit-image team ) LICENSE text (BSD-3): Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the University nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. . THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Classes ------- .. autoapisummary:: isosegdenoise.processing_class.ImageProcessing Functions --------- .. autoapisummary:: isosegdenoise.processing_class.imc_entrypoint isosegdenoise.processing_class.mask_expand Module Contents --------------- .. py:function:: imc_entrypoint(directory: Union[None, str] = None, resolutions: tuple[float, float] = [1.0, 1.0], from_mcds: bool = True) -> ImageProcessing This function is the entrypoint for a project using MCDs or TIFFs. It initializes and return an ImageAnalysis object using the arguments passed in by the user. :param directory: This is the path to a folder containing a subfolder /raw with either .tiff or .mcd files inside it :type directory: Path or string :param resolutions (iterable of length two: float, float): This is the [X, Y] resolutions of the images in micrometers / pixel. The default is 1.0 microns / pixels for both dimensions, as has been usual for IMC. :param from_mcds: whether the /raw subfolder contains .mcd files (= True) or .tiff files (= False) :type from_mcds: boolean .. py:function:: mask_expand(distance: int, image_source: str, output_directory: str) -> None Function that expands the size of cell masks: :param distance: the number of pixels to expand the masks by :type distance: integer :param image_source: the file path to a folder containing the cell masks (as tiff files) to expand :type image_source: string or Path :param output_directory: the file path to a folder where you want to write the expanded masks. Must already exist or be creatable by os.mkdir() :type output_directory: string or Path Inputs / Outputs: Inputs: reads every file in image_source folder (expecting .tiff format for all) Outputs: writes a (.ome).tiff into the output_directory folder for each file read-in from image_source The filenames in the image_source folder as preserved in the output_directory, so if image_source == output_directory then the original masks will be overwritten. .. py:class:: ImageProcessing(directory: Union[pathlib.Path, str, None], resolutions: tuple[float, float] = [1.0, 1.0]) This class coordinates the segmentation / denoising functions Key Attributes: directory (str): the path to a folder contianing a directory/raw/ subfolder where the MCD or TIFF files are directory_object (DirSetup): this attribute is a sub-class from Utils/SharedClasses.py module. it coordinates directories of the typical PalmettoBUG project. sub-Attributes: - directory_object.main = self.directory - directory_object.raw_dir = {self.directory}/raw, the folder where the original mcds / tiffs are located. Not interacted with by isoSegDenoise - directory_object.img_dir = {self.directory}/images, the folder where sub-folders of images are located. The /img subfolder contains the .tiffs converted from raw_dir. In the GUI, many steps looks inside img_dir for sub-folders of images to use, and denoisings automatically export there as well. - directory_object.masks_dir = {self.directory}/masks, the folder where sub-folders of cell masks are located. deepcell and cellpose segmentation automatically export to the subfolders masks_dir/deepcell_masks and masks_dir/cellpose_masks, respectively. Mask expansion reads/writes from subfolders of masks_dir. - directory_object.logs = {self.directory}/Logs, the folder where log files are written by the GUI. resolutions (list[float, float]): the X and Y resolutions of the images, in micrometers / pixel panel (pandas dataframe): this is a pandas dataframe read-in & written to directory/panel.csv. This is a steinbock-style panel (with changes), with four columns = "name","antigen","keep","segmentation" .. py:attribute:: resolutions :value: [1.0, 1.0] .. py:method:: _panel_setup() -> None Setups the Panel file. Unlike PalmettoBUG version of this function, this always assumes a panel file is available in the provided directory (it does not attempt to construct a preliminary verison of the panel if a panel is not available in the directory) .. py:method:: panel_write() -> None .. py:method:: deepcell_segment(image_folder: str, output_folder: Union[str, None] = None, image_choice: str = 'ALL', re_do: bool = False, is_torch: Union[bool, None] = None) -> None Runs deepcell / mesmer segmentation, and writes masks to output_folder :param image_folder: The directory to a folder of .tiff files to be denoised. If attempting to run all the images in this folder (img = "") then this folder MUST ONLY contain .tiff files and nothing else (including no subfolders). :type image_folder: string / Pathlike :param output_folder: The directory of the folder where the denoised images are to be written. :type output_folder: string / Pathlike :param image_choice: If "All" --> attempts to segment every file in image_folder. Otherwise, the value in the list should be one of the image's filenames (discoverable by os.listdir(image_folder)). :type image_choice: string :param re_do: whether to skip or to redo images that already have mask files in output_folder. If == False, then images in image_folder that already have a matching file in output_folder will be skipped and not segmented again. If True, will segment every imgae in image_folder, overwriting any previously done masks with matching filenames to the filenames in image_folder. Use case: if new .mcd's / .tiff's have been added to the project, and you only need those to be segmented, redo = False will save time by not redoing the segmentation of the project's original images. :type re_do: boolean :param is_torch: whether to use the original tensorflow backend for mesmer segmentation (False), use the new PyTorch / ONNX converted backend (True), or allow iSD to automatically decide which to try to use (None). If None, iSD will prefer tensorflow if it can be imported -- and failing import of tensorflow will instead use PyTorch. :type is_torch: boolean, or None Inputs / Outputs: Inputs: reads .tiff file(s) from image_folder Outputs: writes .tiff file(s) to output_folder .. py:method:: cellpose_segment(image_folder: str, output_folder: str, img: str = '', re_do: bool = False, gpu: bool = False, flow_threshold: float = 0.4, cellprob_threshold: float = 0.0, min_size: int = 15, model_type: Union[None, str] = None, diam_mean: float = 30.0) -> None This executes cellpose segmentation on one or all of the images (.tiff) in a supplied folder :param image_folder: The directory to a folder of .tiff files to be denoised. If attempting to run all the images in this folder (img = "") then this folder MUST ONLY contain .tiff files and nothing else (including no subfolders). :type image_folder: string / Pathlike :param output_folder: The directory of the fodler where the denoised images are to be written. :type output_folder: string / Pathlike :param img: default is the empty string, which leads to denoising of all images in the supplied directory. Otherwise this string should be the filename of one of the images in the directory. Only that image will be denoised. The strings that can be used for this argument can obtained by os.listdir(img_directory) :type img: string :param re_do: whether to skip or to redo images that already have mask files in output_folder. If == False, then images in image_folder that already have a matching file in output_folder will be skipped and not segmented again. If True, will segment every imgae in image_folder, overwriting any previously done masks with matching filenames to the filenames in image_folder. Use case: if new .mcd's / .tiff's have been added to the project, and you only need those to be segmented, redo = False will save time by not redoing the segmentation of the project's original images. :type re_do: boolean :param gpu: whether to attempt to run the dneoising using an installed GPU (True) or to simply use the CPU (False) Cellpose uses PyTorch (unlike DeepCell which uses tensorflow, and automatically attempts to detect a GPU). :type gpu: boolean :param flow_threshold: hyperparameter of cellpose model. Cells with flow error rates above this threshold will be excluded. Higher values should increase the number of cell masks, and lower values decrease the number of cell masks. :type flow_threshold: float :param cellprob_threshold: Hyperparameter of cellpose model. Pixels above this threshold included in cell masks, Higher value shrink cell masks and lower values expand cell mask sizes. :type cellprob_threshold: float :param min_size: hyperparameter of cellpose model, minimum size (in pixels) for cell regions :type min_size: int :param model_type: which cellpose model to use to modify the images options : "cyto3", "nuclei", "cyto2_cp3", "tissuenet_cp3", "livecell_cp3", "yeast_PhC_cp3", "yeast_BF_cp3", "bact_phase_cp3", "bact_fluor_cp3", "deepbacs_cp3", "cyto2", "cyto", "transformer_cp3", "neurips_cellpose_default", "neurips_cellpose_transformer", "neurips_grayscale_cyto2" :type model_type: string :param diam_mean: the average size of the objects in the image (in microns) -- used by cellpose to up/downscale the image to match what cellpose was trained on before proceeding with denoising. :type diam_mean: float Inputs / Outputs: Inputs: reads .tiff file(s) from image_folder Outputs: writes .tiff file(s) to output_folder .. py:method:: cellpose_denoise(channel_list: list[int], image_folder: Union[str, pathlib.Path], output_folder: Union[str, pathlib.Path], img: str = '', gpu: bool = False, model_type: Union[None, str] = None, diam_mean: float = 30.0) -> None Executes cellpose based denoising on one or all of the image (.tiff) files in a directory, operating on the selected channels :param channel_list: The channels in the images to denoise. The channels are represented as integers, as in, once the images are converted to numpy arrays, then each channel can be accessed by simple numpy subsetting:: channel = image_array[channel_number,:,:] This means that this method assumes the images in the supplied folder all have the same order of channels. :type channel_list: list of integers :param image_folder: The directory to a folder of .tiff files to be denoised. If attempting to run all the images in this folder (img = "") then this folder MUST ONLY contain .tiff files and nothing else (including no subfolders). :type image_folder: string / Pathlike :param output_folder: The directory of the fodler where the denoised images are to be written. :type output_folder: string / Pathlike :param img: default is the empty string, which leads to denoising of all images in the supplied directory. Otherwise this string should be the fileanme of one of the images in the directory. Only that image will be denoised. The strings that can be used for this argument can obtained by os.listdir(image_folder) :type img: string :param gpu: whether to attempt to run the dneoising using an installed GPU (True) or to simply use the CPU (False) Cellpose uses PyTorch (unlike DeepCell which uses tensorflow, and automatically attempts to detect a GPU). :type gpu: boolean :param model_type: which cellpose model to use to modify the images options : 'denoise_cyto3', 'deblur_cyto3', 'upsample_cyto3', 'denoise_nuclei', 'deblur_nuclei', 'upsample_nuclei' :type model_type: string :param diam_mean: the average size of the objects in the image (in microns) -- used by cellpose to up/downscale the image to match what cellpose was trained on before proceeding with denoising. :type diam_mean: float Inputs / Outputs: Inputs: reads .tiff file(s) from image_folder Outputs: writes .tiff file(s) to output_folder .. py:method:: simple_denoise(image_folder: str, output_folder: str, channel_list: list[int], image: str = '', sigma_range: Union[None, list[float]] = None, pre_cal: bool = False, cal_img: int = 0) -> None Executes "simple" denoising on one or all of the image (.tiff) files in a directory, operating on the selected channels :param channel_list: The channels in the images to denoise. The channels are represented as integers, as in, once the images are converted to numpy arrays, then each channel can be accessed by simple numpy subsetting:: channel = image_array[channel_number,:,:] This means that this method assumes the images in the supplied folder all have the same order of channels. :type channel_list: list of integers :param image_folder: The directory to a folder of .tiff files to be denoised. If attempting to run all the images in this folder (img = "") then this folder MUST ONLY contain .tiff files and nothing else (including no subfolders). :type image_folder: string / Pathlike :param output_folder: The directory of the fodler where the denoised images are to be written. :type output_folder: string / Pathlike :param img: default is the empty string, which leads to denoising of all images in the supplied directory. Otherwise this string should be the filename of one of the images in the directory. Only that image will be denoised. The strings that can be used for this argument can obtained by os.listdir(image_folder) :type img: string :param sigma_range: the range of sigmas to perform coarse calibration of the j-invariant nl means algorithm on. Once coarse calibration is performed on one image, fine calibration is performed on each image before denoising, looking at a smaller range of sigmas above & below the optimum sigma determined during coarse calibration. :type sigma_range: list of integers, or None :param pre_cal: whether coarse calibration of sigma has already been performed (True), or not (False, default). :type pre_cal: boolean :param cal_img: which image in os.listdir(image_folder) will be used for coarse calibratio nof sigma. By default the first image in that list is used (cal_img = 0) :type cal_img: integer Inputs / Outputs: Inputs: reads .tiff file(s) from image_folder Outputs: writes .tiff file(s) to output_folder