Co-Expression Analysis

Module Documentation

This module performs evaluation of spatial co-expression of two or three antigens based on their staining intensities within tumor-tissue areas. It calculates combined tumor coverage as well as overlapping and complementary expression of the evaluated antigens.

Primary Functions

cubats.slide_collection.tile_colocalization.evaluate_antigen_pair_tile(iterable)[source]

This function analyzes antigen co-expression of the same tile from two different antigen slides and returns the results as dictionary.

The function performs pixel-wise comparison across two images to evaluate combined total coverage, antigen overlap, and complementary expression. The intensity levels are divided into five categories based on their intensity values. Intensity values are defined for each tile by the passed antigen profile which can be defined when initializing the SlideCollection. If not antigen profiles are defined, intensity values will fall back to default thresholds: high positive (0-60), medium positive (61-120), low positive (121-180), negative (181-234), and background (235-255). The results are saved in a dictionary and returned. Optionally, an image containing the colored results can be saved in the specified directory. Masking mode can be determined to mirror the mode applied during quantification: tile-level or pixel-level.

Parameters:

iterable (iterable) –

An iterable containing the following elements:

  • tile1: the first tile to be compared and analyzed for antigen coverage.

  • tile2: the second tile to be compared and analyzed for antigen coverage.

  • Antigen-specific profiles: ‘profile1’, ‘profile2’, and ‘profile3’ containing antigen-specific thresholds for tile1, tile2, and tile 3respectively.

  • output path: the directory where the output image should be saved.

  • save_img: a flag indicating whether to save the output image.

  • masking_mode: Applied masking mode as for quantification: tile-level or pixel-level.

Returns:

A dictionary containing the results of the analysis:

  • Tilename: Name of the tile

  • Flag: Flag indicating if the tile was processed or not. (1: processed; -1: not processed due to both tiles not being processable; -2: one of the tiles was not processable due to wrong shape)

  • Total Coverage: Percentage of positive pixels (intensity values < 181), covered by both tiles combined, with respect to the tumor mask in the images (!=255). (Only if Flag == 1)

  • Total Overlap: Percentage of positive pixels that are positive in both images combined, with respect to the tumor mask in the images (!=255). (Only if Flag == 1)

  • Total Complement: Percentage of positive pixels that are only covered by one of the two images, with respect to the tumor mask in the images (!=255). (Only if Flag == 1)

  • High Positive Overlap: Percentage of highly positive pixels covered by both tiles combined, with respect to the tumor mask in the images (!=255). (Only if Flag == 1)

  • High Positive Complement: Percentage of highly positive pixels covered by only one of the two tiles, with respect to the tumor mask in the images (!=255). (Only if Flag == 1)

  • Medium Positive Overlap: Percentage of medium positive pixels covered by both tiles combined, with respect to the tumor mask in the images (!=255). (Only if Flag == 1)

  • Medium Positive Complement: Percentage of medium positive pixels covered by only one of the two tiles, with respect to the tumor mask in the images (!=255). (Only if Flag == 1)

  • Low Positive Overlap: Percentage of low positive pixels covered by both tiles combined, with respect to the tumor mask in the images (!=255). (Only if Flag == 1)

  • Low Positive Complement: Percentage of low positive pixels covered by only one of the two tiles, with respect to the tumor mask in the images (!=255). (Only if Flag == 1)

  • Negative: Percentage of negative pixels not covered by either of the two tiles, with respect to the tumor mask in the images (!=255). (Only if Flag == 1)

  • Tissue: Percentage of actual tissue across the tiles, with respect to the tumor mask in the images (!=255). (Only if Flag == 1)

  • Background / No Tissue: Percentage of the tile that is not covered by tissue across the tiles with respect to the total pixel count of the tile. (Only if Flag == 1)

  • Mask Area: Percentage of the tile that is covered by the tumor mask.

  • Non-mask Area: Percentage of the tile that is not covered by the mask as tumor tissue (=255), with respect to total pixels in the image (1024 x 1024 = 1048576).

Return type:

dict

Optional Image Saving:

If save_img is True, an image containing the colored results will be saved in the specified directory. The coloring scheme is as follows:

  • Overlapping pixels (positive in both tiles):

    • Highly positive: Red ([255, 0, 0])

    • Medium positive: Red ([255, 0, 0])

    • Low positive: Red ([255, 0, 0])

  • Complementary pixels (positive in only one tile):

    • Tile1 highly positive: Green ([0, 255, 0])

    • Tile1 medium positive: Light Green ([153, 238, 153])

    • Tile1 low positive: Very Light Green ([204, 255, 204])

    • Tile2 highly positive: Blue ([0, 0, 204])

    • Tile2 medium positive: Light Blue ([102, 204, 255])

    • Tile2 low positive: Very Light Blue ([153, 204, 255])

  • Negative pixels (both tiles negative): White ([255, 255, 255])

  • Background pixels (no tissue): Gray ([192, 192, 192])

  • Non-mask pixels: Dark Gray ([128, 128, 128])

cubats.slide_collection.tile_colocalization.evaluate_antigen_triplet_tile(iterable)[source]

This function analyzes antigen co-expression of the same tile from 3 different antigen slides and returns the results as dictionary.

The function performs pixel-wise comparison across three images to evaluate combined total coverage, antigen overlap, and complementary expression. The intensity levels are divided into five categories based on their intensity values. Intensity values are defined for each tile by the passed antigen profile which can be defined when initializing the SlideCollection. If not antigen profiles are defined, intensity values will fall back to default thresholds: high positive (0-60), medium positive (61-120), low positive (121-180), negative (181-234), and background (235-255). The results are saved in a dictionary and returned. Optionally, an image containing the colored results can be saved in the specified directory. Masking mode can be determined to mirror the mode applied during quantification: tile-level or pixel-level.

Parameters:

iterable (iterable) –

An iterable containing the following elements:

  • tile1: the first tile to be compared and analyzed for antigen coverage.

  • tile2: the second tile to be compared and analyzed for antigen coverage.

  • tile3: the third tile to be compared and analyzed for antigen coverage.

  • Antigen-specific profiles: ‘profile1’, ‘profile2’, and ‘profile3’ containing antigen-specific thresholds for tile1, tile2, and tile 3respectively.

  • output path: the directory where the output image should be saved.

  • save_img: a flag indicating whether to save the output image.

  • masking_mode: Applied masking mode as for quantification: tile-level or pixel-level.

Returns:

A dictionary containing the results of the analysis:

  • Tilename: Name of the tile

  • Flag: Flag indicating if the tile was processed or not. (1: processed; 0: not processed due both tiles not being processable; -1: all tiles not containing tissue)

  • Total Coverage: Percentage of positive pixels (intensity values < 181), covered by all three tiles combined, with respect to the tumor mask in the images (!=255). (Only if Flag == 1)

  • Total Overlap: Percentage of positive pixels that are positive in at least two or all three images combined, with respect to the tumor mask in the images (!=255). (Only if Flag == 1)

  • Total Complement: Percentage of positive pixels that are only covered by one of the three images, with respect to the tumor mask in the images (!=255). (Only if Flag == 1)

  • High Positive Overlap: Percentage of highly positive pixels covered by all three tiles combined, with respect to the tumor mask in the images (!=255). (Only if Flag == 1)

  • High Positive Complement: Percentage of highly positive pixels covered by only one of the three tiles, with respect to the tumor mask in the images (!=255). (Only if Flag == 1)

  • Medium Positive Overlap: Percentage of medium positive pixels covered by all three tiles combined, with respect to the tumor mask in the images (!=255). (Only if Flag == 1)

  • Medium Positive Complement: Percentage of medium positive pixels covered by only one of the three tiles. (Only if Flag == 1)

  • Low Positive Overlap: Percentage of low positive pixels covered by all three tiles combined, with respect to the tumor mask in the images (!=255). (Only if Flag == 1)

  • Low Positive Complement: Percentage of low positive pixels covered by only one of the three tiles, with respect to the tumor mask in the images (!=255). (Only if Flag == 1)

  • Negative: Percentage of negative pixels not covered by any of the three tiles, with respect to actual tissue in the images.(Only if Flag == 1)

  • Tissue: Percentage of actual tissue across the tiles, with respect to the tumor mask in the images (!=255). (Only if Flag == 1)

  • Background / No Tissue: Percentage of the tile that is not covered by tissue across the tiles with respect to the total pixel count of the tile. (Only if Flag == 1)

  • Mask Area: Percentage of the tile that is covered by the tumor mask.

  • Non-mask Area: Percentage of the tile that is not covered by the mask as tumor tissue (=255), with respect to total pixels in the image (1024 x 1024 = 1048576).

Return type:

dict

Optional Image Saving:

If save_img is True, an image containing the colored results will be saved in the specified directory. The coloring scheme is as follows:

  • Overlapping pixels (positive in both tiles):

    • Highly positive: Red ([255, 0, 0])

    • Medium Positive: Red ([255, 0, 0])

    • Low positive: Red ([255, 0, 0])

  • Complementary pixels (positive in only one tile):

    • Tile1 highly positive: Green ([0, 255, 0])

    • Tile1 medium positive: Light Green ([153, 238, 153])

    • Tile1 low positive: Very Light Green ([204, 255, 204])

    • Tile2 highly positive: Blue ([0, 0, 204])

    • Tile2 medium positive: Light Blue ([102, 204, 255])

    • Tile2 low positive: Very Light Blue ([153, 204, 255])

    • Tile3 highly positive: Orange ([255, 165, 0])

    • Tile3 medium positive: Light Orange ([255, 200, 102])

    • Tile3 low positive: Very Light Orange ([255, 225, 153])

  • Negative pixels (both tiles negative): White ([255, 255, 255])

  • Background pixels (no tissue): Gray ([192, 192, 192])

  • Non-mask pixels: Dark Gray ([128, 128, 128])

Internal Functions

cubats.slide_collection.tile_colocalization._process_single_tile(tile, dir, save_img, color, antigen_profile)[source]

Processes antigen expression for a single tile.

Processes a single image tile using vectorization and automatic backend detection for GPU acceleration. It categorizes pixels into different complement levels, negative tissue, and background based on the passed antigen profile. Optionally creates and saves a colored image of the analysis into the directory if save_img is True.

Parameters:

  • tile (dict) – A dictionary containing the image under the key Image Array and masks under the key Masks.

  • save_img (bool) – A flag indicating whether to create a colored image and save it.

  • dir (str) – The directory where the image should be saved if save_img is True.

  • color (list) – A list of RGB color values to be used for different complement levels.

  • antigen_profile (dict) – Antigen profile for the tile, specifying the thresholds applied during processing.

Returns:

A tuple containing counts of pixels in the following order:

  • high_complement (int): Sum of pixels with values below high_positive_threshold of antigen profile.

  • med_complement (int): Sum of pixels with values between high_positive_threshold and ‘medium_positive_threshold` of antigen_profile.

  • low_complement (int): Sum of pixels with values between medium_positive_threshold and low_positive_threshold of antigen_profile.

  • negative (int): Sum of pixels with values between low_positive_threshold and 234 of antigen_profile.

  • background (int): Sum of pixels above 235 and below 255.

Return type:

tuple

Optional Image Saving:

If save_img is True, an image containing the colored results will be saved in the specified directory. The coloring scheme depends on the color parameter and is specified by the calling function.

cubats.slide_collection.tile_colocalization._process_two_tiles(tile1, tile2, dir, save_img, colors, antigen_profiles)[source]

Processes antigen co-expression for two single tiles.

Processes two image tiles using vectorization and automatic backend detection for GPU acceleration. It categorizes pixels into overlap, different complement levels, negative tissue, and background based on the passed antigen profiles. Optionally creates and saves a colored image of the analysis into the directory if save_img is True. This function is typically called by evaluate_antigen_pair_tile or evaluate_antigen_triplet_tile when two of the three tiles contain tissue.

Parameters:

  • tile1 (dict) – A dictionary containing tile1’s data. The image can be accessed using the key Image Array.

  • tile2 (dict) – A dictionary containing tile2’s data. The image can be accessed using the key Image Array.

  • dir (str) – The directory where the output image should be saved if save_img is True.

  • save_img (bool) – A flag indicating whether to save the output image.

  • colors (list) – A list of RGB color values to be used for different complement levels.

  • antigen_profiles (list) – List of two dicts specifying antigen thresholds for each tile respectively.

Returns:

A tuple containing the counts of:

  • high_overlap (int): Sum of pixels where both tiles are highly positive, according to antigen_profiles.

  • med_overlap (int): Sum of pixels where both tiles are medium positive, according to antigen_profiles.

  • low_overlap (int): Sum of pixels where both tiles are low positive, according to antigen_profiles.

  • high_complement (int): Sum of pixels with only one tile is below high_positive_threshold of antigen profiles.

  • med_complement (int): Sum of pixels with only one tile is between high_positive_threshold and medium_positive_threshold of antigen_profiles.

  • low_complement (int): Sum of pixels with only one tile is between medium_positive_threshold and low_positive_threshold of antigen_profiles.

  • negative (int): Sum of pixels with values between low_positive_threshold and 235 of antigen_profiles.

  • background (int): Sum of pixels above 235 and below 255.

Return type:

tuple

Optional Image Saving:

If save_img is True, an image containing the colored results will be saved in the specified directory. The coloring scheme depends on the color parameter and is specified by the calling function. For more information, refer to the evaluate_antigen_pair_tile or evaluate_antigen_triplet_tile functions.

cubats.slide_collection.tile_colocalization._process_three_tiles(tile1, tile2, tile3, dir, save_img, antigen_profiles)[source]

Processes antigen expression for three tiles.

Processes three image tiles using vectorization and automatic backend detection for GPU acceleration. It categorizes pixels into overlap, different complement levels, negative tissue, and background based on the passed antigen profiles. Optionally creates and saves a colored image of the analysis into the directory if save_img is True. This function is typically called by evaluate_antigen_pair_tile or evaluate_antigen_triplet_tile when two of the three tiles contain tissue.

Parameters:

  • tile1 (dict) – A dictionary containing tile1’s data. The image can be accessed using the key Image Array.

  • tile2 (dict) – A dictionary containing tile2’s data. The image can be accessed using the key Image Array.

  • tile3 (dict) – A dictionary containing tile3’s data. The image can be accessed using the key Image Array.

  • dir (str) – The directory where the output image should be saved if save_img is True.

  • save_img (bool) – A flag indicating whether to save the output image.

  • colors (list) – A list of RGB color values to be used for different complement levels.

  • antigen_profiles (list) – List of two dicts specifying antigen thresholds for each tile respectively.

Returns:

A tuple containing the counts of:

  • high_overlap (int): Sum of pixels where both tiles are highly positive, according to antigen_profiles.

  • med_overlap (int): Sum of pixels where both tiles are medium positive, according to antigen_profiles.

  • low_overlap (int): Sum of pixels where both tiles are low positive, according to antigen_profiles.

  • high_complement (int): Sum of pixels with only one tile is below high_positive_threshold of antigen profiles.

  • med_complement (int): Sum of pixels with only one tile is between high_positive_threshold and medium_positive_threshold of antigen_profiles.

  • low_complement (int): Sum of pixels with only one tile is between medium_positive_threshold and low_positive_threshold of antigen_profiles.

  • negative (int): Sum of pixels with values between low_positive_threshold and 235 of antigen_profiles.

  • background (int): Sum of pixels above 235 and below 255.

Return type:

tuple

Optional Image Saving:

If save_img is True, an image containing the colored results will be saved in the specified directory. The coloring scheme depends on the color parameter and is specified by the calling function. For more information, refer to the evaluate_antigen_pair_tile or evaluate_antigen_triplet_tile functions.