ark.segmentation.ez_seg

ark.segmentation.ez_seg.composites

ark.segmentation.ez_seg.composites.add_to_composite(data: xarray.DataArray, composite_array: numpy.ndarray, images_to_add: List[str], image_type: str, composite_method: str) → numpy.ndarray

Adds tiffs together to form a composite array.

Parameters:

• data (xr.DataArray) – The data array containing the set of all images which get filtered out with images_to_add.

• composite_array (np.ndarray) – The array to add channels to.

• images_to_add (List[str]) – A list of channels or pixel cluster names to add together.

• image_type (str) – Either “signal” or “pixel_cluster” data.

• composite_method (str) – Binarized mask returns (“binary”) or intensity, gray-scale tiffs returned (“total”).

Returns:

The composite array, either as a binary mask, or as a scaled intensity array.

Return type:

np.ndarray

ark.segmentation.ez_seg.composites.composite_builder(image_data_dir: Union[str, Path], img_sub_folder: str, fov_list: list[str], images_to_add: list[str], images_to_subtract: list[str], image_type: str, composite_method: str, composite_directory: Union[str, Path] = None, composite_name: str = None, log_dir: Union[str, Path] = None) → None

Adds tiffs together, either pixel clusters or base signal tiffs and returns a composite channel or mask.

Parameters:

• image_data_dir (Union[str, pathlib.Path]) – The path to dir containing the set of all images which get filtered out with images_to_add and images_to_subtract.

• img_sub_folder (str) – A name for sub-folders within each fov in the image_data location.

• fov_list – A list of fov’s to create composite channels through.

• images_to_add (List[str]) – A list of channels or pixel cluster names to add together.

• images_to_subtract (List[str]) – A list of channels or pixel cluster names to subtract from the composite.

• image_type (str) – Either “signal” or “pixel_cluster” data.

• composite_method (str) – Binarized mask returns (“binary”) or intensity, gray-scale tiffs returned (“total”).

• composite_directory (Union[str, pathlib.Path]) – The directory to save the composite array.

• composite_name (str) – The name of the composite array to save.

• log_dir – The directory to save log information to.

Returns:

Saves the composite array, either as a binary mask, or as a scaled intensity array. If composite_directory is None, return a dictionary with keys being FOV names and values are np.ndarray of the composite image.

Return type:

np.ndarray

ark.segmentation.ez_seg.composites.subtract_from_composite(data: xarray.DataArray, composite_array: numpy.ndarray, images_to_subtract: List[str], image_type: str, composite_method: str) → numpy.ndarray

Subtracts tiffs from a composite array.

Parameters:

• data (xr.DataArray) – The data array containing the set of all images which get filtered out with images_to_subtract.

• composite_array (np.ndarray) – An array to subtract channels from.

• images_to_subtract (List[str]) – A list of channels or pixel cluster names to subtract from the composite.

• image_type (str) – Either “signal” or “pixel_cluster” data.

• composite_method (str) – Binarized mask returns (‘binary’) or intensity, gray-scale tiffs returned (‘total’).

Returns:

The composite array, either as a binary mask, or as a scaled intensity array.

Return type:

np.ndarray

ark.segmentation.ez_seg.ez_object_segmentation

ark.segmentation.ez_seg.ez_object_segmentation.create_object_masks(image_data_dir: Union[str, Path], img_sub_folder: Optional[str], fov_list: list[str], mask_name: str, channel_to_segment: str, masks_dir: Union[str, Path], log_dir: Union[str, Path], object_shape_type: str = 'blob', sigma: int = 1, thresh: Optional[numpy.float32] = None, hole_size: Optional[int] = None, fov_dim: int = 400, min_object_area: int = 100, max_object_area: int = 100000) → None

Calculates a mask for each channel in the FOV for circular or ‘blob’-like objects such as: single large cells or amyloid plaques. It will blur the input image, then threshold the blurred image on either a given fixed value, or an adaptive thresholding method. In addition, it removes small holes using that same thresholding input and filters out objects which are either too small or too large.

Parameters:

• image_data_dir (Union[str, pathlib.Path]) – The directory to pull images from to perform segmentation on.

• img_sub_folder (str) – A name for sub-folders within each fov in the image_data location.

• fov_list – A list of fov names to segment on.

• mask_name (str) – The name of the masks you are creating.

• channel_to_segment – The channel on which to perform segmentation.

• masks_dir (Union[str, pathlib.Path]) – The directory to save segmented images to.

• object_shape_type (str, optional) – Specify whether the object is either “blob” or

• “blob”. (“projection” shaped. Defaults to) –

• sigma (int) – The standard deviation for Gaussian kernel, used for blurring the

• 1. (image. Defaults to) –

• thresh (np.float32, optional) – The global threshold value for image thresholding if

• None. (Defaults to) –

• hole_size (int, optional) – A specific area to close small holes over in object masks.

• None. –

• fov_dim (int) – The dimension in μm of the FOV.

• min_object_area (int) – The minimum size (area) of an object to capture in

• 100. (pixels. Defaults to) –

• max_object_area (int) – The maximum size (area) of an object to capture in

• 100000. (pixels. Defaults to) –

• log_dir (Union[str, pathlib.Path]) – The directory to save log information to.

ark.segmentation.ez_seg.ez_object_segmentation.get_block_size(block_type: str, fov_dim: int, img_shape: int) → int

Computes the approximate local otsu threshold based on fov size (in μm) and pixel resolution.

Parameters:

• block_type (str) – Either “small_holes” or “local_thresh”

• fov_dim (int, optional) – The size in μm for the FOV.

• img_shape (int, optional) – The shape of the image.

Returns:

Returns the approximate block area

Return type:

int

ark.segmentation.ez_seg.ez_seg_display

ark.segmentation.ez_seg.ez_seg_display.create_overlap_and_merge_visual(fov: str, mask_name: str, object_mask_dir: Path, cell_mask_dir: Path, cell_mask_suffix: str, merged_mask_dir: Path) → numpy.ndarray

Generate the NumPy Array representing the overlap between two masks

Parameters:

• fov (str) – Name of the fov to view

• mask_name (str) – Name of mask to view

• object_mask_dir (pathlib.Path) – Directory where the object masks are stored.

• cell_mask_dir (pathlib.Path) – Directory where the cell masks are stored.

• cell_mask_suffix (str) – Suffix name of the cell mask files.

• merged_mask_dir (pathlib.Path) – Directory where the merged masks are stored.

Returns:

Contains an overlap image of the two masks

Return type:

np.ndarray

ark.segmentation.ez_seg.ez_seg_display.display_channel_image(base_image_path: Union[str, Path], sub_folder_name: str, test_fov_name: str, channel_name: str, composite: bool = False) → None

Displays a channel or a composite image.

Parameters:

• base_image_path (Union[str, pathlib.Path]) – The path to the image.

• sub_folder_name (str) – If a subfolder name for the channel data exists.

• test_fov_name (str) – The name of the fov you wish to display.

• channel_name (str) – The name of the channel you wish to display.

• composite (bool) – Whether the image to be viewed is a composite image.

ark.segmentation.ez_seg.ez_seg_display.multiple_mask_display(fov: str, mask_name: str, object_mask_dir: Union[str, PathLike], cell_mask_dir: Union[str, PathLike], cell_mask_suffix: str, merged_mask_dir: Union[str, PathLike]) → None

Create a grid to display the object, cell, and merged masks for a given fov.

Parameters:

• fov (str) – Name of the fov to view

• mask_name (str) – Name of mask to view

• object_mask_dir (Union[str, os.PathLike]) – Directory where the object masks are stored.

• cell_mask_dir (Union[str, os.PathLike]) – Directory where the cell masks are stored.

• cell_mask_suffix (str) – Suffix name of the cell mask files.

• merged_mask_dir (Union[str, os.PathLike]) – Directory where the merged masks are stored.

ark.segmentation.ez_seg.ez_seg_display.overlay_mask_outlines(fov: str, channel: str, image_dir: Union[str, PathLike], sub_folder_name: str, mask_name: str, mask_dir: Union[str, PathLike]) → None

Displays a segmentation mask overlaid on a base image (channel or composite).

Parameters:

• fov (str) – name of fov to be viewed

• channel (str) – name of channel to view

• image_dir (Union[str, os.PathLike]) – The Path to channel for viewing.

• sub_folder_name (str) – If a subfolder name for the channel data exists.

• mask_name (str) – The name of mask to view

• mask_dir (Union[str, os.PathLike]) – The path to the directory containing the mask.

ark.segmentation.ez_seg.ez_seg_utils

ark.segmentation.ez_seg.ez_seg_utils.create_mantis_project(fovs: Union[str, List[str]], image_data_dir: Union[str, Path], segmentation_dir: Union[str, Path], mantis_dir: Union[str, Path]) → None

Creates a folder for viewing FOVs in Mantis.

Parameters:

• fovs (Union[str, List[str]]) – A list of FOVs to use for creating the mantis project

• image_data_dir (Union[str, pathlib.Path]) – The path to the directory containing the raw image data.

• segmentation_dir (Union[str, pathlib.Path]) – The path to the directory containing masks.

• mantis_dir – The path to the directory containing housing the ez_seg specific mantis project.

ark.segmentation.ez_seg.ez_seg_utils.filter_csvs_by_mask(csv_path_name: Union[str, Path], csv_substr_replace: str, column_to_filter: str = 'mask_type') → None

Function to take in and separate a single cell table into multiple based on the mask_type parameter.

Parameters:

• csv_path_name (Union[str, pathlib.Path]) – The path to the directory containing the cell table CSVs.

• csv_substr_replace (str) – The substring in the CSV file name to replace in favor of the mask name

• column_to_filter (str) – The name of the column to split on, defaults to "mask_type"

ark.segmentation.ez_seg.ez_seg_utils.find_and_copy_files(mask_names: List[str], source_folder: Union[str, Path], destination_folder: Union[str, Path])

Creates a new directory of masks for relabeling and cell table generation. Useful if more than one mask type is needed for cell table generation. E.g. merged cells and proteopathy objects.

Parameters:

• mask_names (List[str]) – List of mask names to be merged. Can be partial names.

• source_folder (Union[str, pathlib.Path]) – The parent segmentation folder all masks are found in.

• destination_folder (Union[str, pathlib.Path]) – New dir where final masks will be copied to.

ark.segmentation.ez_seg.ez_seg_utils.log_creator(variables_to_log: dict, base_dir: str, log_name: str = 'config_values.txt')

Logs the variables in variables_to_log to the file at base_dir/log_name

Parameters:

• variables_to_log (dict) – The name of each variable along with their associated value

• base_dir (str) – Where the log will be written to

• log_name (str) – The name of the log file to write the variables to

ark.segmentation.ez_seg.ez_seg_utils.renumber_masks(mask_dir: Union[Path, str])

Relabels all masks in mask tiffs so each label is unique across all mask images in entire dataset.

Parameters:

mask_dir (Union[pathlib.Path, str]) – Directory that points to parent directory of all segmentation masks to be relabeled.

ark.segmentation.ez_seg.merge_masks

ark.segmentation.ez_seg.merge_masks.filter_labels_in_bbox(bounding_box: List, cell_props: pandas.DataFrame, expansion_factor: int)

Gets the cell labels that fall within the expanded bounding box of a given object.

Parameters:

• bounding_box (List) – The bounding box values for the input obj_label

• cell_props (pd.DataFrame) – The cell label regionprops DataFrame.

• expansion_factor – how many pixels from the bounding box you want to expand the search for compatible cells.

Returns:

The cell labels that fall within the expanded bounding box.

Return type:

List

ark.segmentation.ez_seg.merge_masks.get_bounding_boxes(object_labels: numpy.ndarray)

Gets the bounding boxes of labeled images based on object major axis length.

Parameters:

object_labels (np.ndarray) – label array

Returns:

Dictionary containing labels as keys and bounding box as values

Return type:

dict

ark.segmentation.ez_seg.merge_masks.merge_masks_seq(fov_list: List[str], object_list: List[str], object_mask_dir: Union[Path, str], cell_mask_dir: Union[Path, str], cell_mask_suffix: str, overlap_percent_threshold: int, expansion_factor: int, save_path: Union[Path, str], log_dir: Union[Path, str]) → None

Sequentially merge object masks with cell masks. Object list is ordered enforced, e.g. object_list[i] will merge overlapping object masks with cell masks from the initial cell segmentation. Remaining, un-merged cell masks will then be used to merge with object_list[i+1], etc.

Parameters:

• fov_list (List[str]) – A list of fov names to merge masks over.

• object_list (List[str]) – A list of names representing previously generated object masks. Note, order matters.

• object_mask_dir (Union[pathlib.Path, str]) – Directory where object (ez) segmented masks are located

• cell_mask_dir (Union[str, pathlib.Path]) – Path to where the original cell masks are located.

• cell_mask_suffix (str) – Name of the cell type you are merging. Usually “whole_cell”.

• overlap_percent_threshold (int) – Percent overlap of total pixel area needed fo object to be merged to a cell.

• expansion_factor (int) – How many pixels out from an objects bbox a cell should be looked for.

• save_path (Union[str, pathlib.Path]) – The directory where merged masks and remaining cell mask will be saved.

• log_dir (Union[str, pathlib.Path]) – The directory to save log information to.

ark.segmentation.ez_seg.merge_masks.merge_masks_single(object_mask: numpy.ndarray, cell_mask: numpy.ndarray, overlap_thresh: int, object_name: str, mask_save_path: str, expansion_factor: int) → numpy.ndarray

Combines overlapping object and cell masks. For any combination which represents has at least overlap percentage of overlap, the combined mask is kept and incorporated into the original object masks to generate a new set of masks.

Parameters:

• object_mask (np.ndarray) – The object mask numpy array.

• cell_mask (np.ndarray) – The cell mask numpy array.

• overlap_thresh (int) – The percentage overlap required for a cell to be merged.

• object_name (str) – The name of the object.

• mask_save_path (str) – The path to save the mask.

• expansion_factor (int) – How many pixels out from an objects bbox a cell should be looked for.

Returns:

The cells remaining mask, which will be used for the next cycle in merging while there are objects. When no more cells and objects are left to merge, the final, non-merged cells are returned.

Return type:

np.ndarray