isosegdenoise ============= .. py:module:: isosegdenoise .. autoapi-nested-parse:: This sister package to PalmettoBUG handles Segmentation and Denoising. This is because Deepcell (and possibly Cellpose) have non-commercial licenses that might conflict with the necessary GPL'ing of the PalmettoBUG program (although as the packages are only dynamically linked by the interpreter on an individual basis by users when initialize the program, this is a legal grey area). PalmettoBUG uses many GPL libraries both in the standard way and by translation, so it MUST be GPL-licensed. Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/isosegdenoise/Executable/index /autoapi/isosegdenoise/processing_class/index Classes ------- .. autoapisummary:: isosegdenoise.ImageProcessing Functions --------- .. autoapisummary:: isosegdenoise.run_GUI isosegdenoise.imc_entrypoint isosegdenoise.mask_expand Package Contents ---------------- .. py:function:: run_GUI(directory: str = directory_in, resolutions: tuple[float, float] = resolutions_in) -> None This is the function that launches the GUI. It can receive a directory and resolutions (list of two floats, for X / Y resolutions in micrometers / pixel) in order to directly load a folder, instead of needing to load the folder inside the GUI itself. .. 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 .. 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.