isosegdenoise

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

Classes

ImageProcessing

This class coordinates the segmentation / denoising functions

Functions

`run_GUI`(→ 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
`imc_entrypoint`(→ ImageProcessing)	This function is the entrypoint for a project using MCDs or TIFFs. It initializes and return an ImageAnalysis object using the
`mask_expand`(→ None)	Function that expands the size of cell masks:

Package Contents

isosegdenoise.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.

class isosegdenoise.ImageProcessing(directory: 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”

resolutions = [1.0, 1.0]

_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)

panel_write() → None

deepcell_segment(image_folder: str, output_folder: str | None = None, image_choice: str = 'ALL', re_do: bool = False, is_torch: bool | None = None) → None

Runs deepcell / mesmer segmentation, and writes masks to output_folder

Parameters:

image_folder (string / Pathlike) – 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).
output_folder (string / Pathlike) – The directory of the folder where the denoised images are to be written.
image_choice (string) – 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)).
re_do (boolean) – 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.
is_torch (boolean, or None) – 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.

Inputs / Outputs:

Inputs:: reads .tiff file(s) from image_folder
Outputs:: writes .tiff file(s) to output_folder

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: 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

Parameters:

image_folder (string / Pathlike) – 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).
output_folder (string / Pathlike) – The directory of the fodler where the denoised images are to be written.
img (string) – 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)
re_do (boolean) – 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.
gpu (boolean) – 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).
flow_threshold (float) – 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.
cellprob_threshold (float) – Hyperparameter of cellpose model. Pixels above this threshold included in cell masks, Higher value shrink cell masks and lower values expand cell mask sizes.
min_size (int) – hyperparameter of cellpose model, minimum size (in pixels) for cell regions
model_type (string) – 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”
diam_mean (float) – 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.

Inputs / Outputs:

Inputs:: reads .tiff file(s) from image_folder
Outputs:: writes .tiff file(s) to output_folder

cellpose_denoise(channel_list: list[int], image_folder: str | pathlib.Path, output_folder: str | pathlib.Path, img: str = '', gpu: bool = False, model_type: 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

Parameters:

channel_list (list of integers) –
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.
image_folder (string / Pathlike) – 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).
output_folder (string / Pathlike) – The directory of the fodler where the denoised images are to be written.
img (string) – 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)
gpu (boolean) – 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).
model_type (string) – which cellpose model to use to modify the images options : ‘denoise_cyto3’, ‘deblur_cyto3’, ‘upsample_cyto3’, ‘denoise_nuclei’, ‘deblur_nuclei’, ‘upsample_nuclei’
diam_mean (float) – 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.

Inputs / Outputs:

Inputs:: reads .tiff file(s) from image_folder
Outputs:: writes .tiff file(s) to output_folder

simple_denoise(image_folder: str, output_folder: str, channel_list: list[int], image: str = '', sigma_range: 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

Parameters:

channel_list (list of integers) –
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.
image_folder (string / Pathlike) – 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).
output_folder (string / Pathlike) – The directory of the fodler where the denoised images are to be written.
img (string) – 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)
sigma_range (list of integers, or None) – 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.
pre_cal (boolean) – whether coarse calibration of sigma has already been performed (True), or not (False, default).
cal_img (integer) – 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)

Inputs / Outputs:

Inputs:: reads .tiff file(s) from image_folder
Outputs:: writes .tiff file(s) to output_folder

isosegdenoise.imc_entrypoint(directory: 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.

Parameters:

directory (Path or string) – This is the path to a folder containing a subfolder /raw with either .tiff or .mcd files inside it
two (resolutions (iterable of length) – 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.
from_mcds (boolean) – whether the /raw subfolder contains .mcd files (= True) or .tiff files (= False)

isosegdenoise.mask_expand(distance: int, image_source: str, output_directory: str) → None

Function that expands the size of cell masks:

Parameters:

distance (integer) – the number of pixels to expand the masks by
image_source (string or Path) – the file path to a folder containing the cell masks (as tiff files) to expand
output_directory (string or Path) – the file path to a folder where you want to write the expanded masks. Must already exist or be creatable by os.mkdir()

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.