isosegdenoise.processing_class

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

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.

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

ImageProcessing

This class coordinates the segmentation / denoising functions

Functions

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

Module Contents

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

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