How to write a custom measurement

This guide shows you how to create your own single-cell measurement in Python, ready-to-be-used in the software.

Reference keys: ROI, Mask, Features

Prerequisite

You need access to the source code of Celldetective or at least the celldetective/extra_properties.py file.

Introduction

Celldetective allows you to extend its measurement capabilities by adding custom Python functions. These functions are automatically discovered and applied to every cell during the measurement process. This is useful for specific needs like:

  • Measuring the area of dark regions within a cell.

  • Computing specific intensity percentiles.

  • Calculating shape descriptors not included in the standard library.

Step 1: Locate the definitions file

  1. Navigate to your Celldetective installation folder.

  2. Open the file celldetective/extra_properties.py in a text editor or IDE.

Step 2: Define your function

Add a new function to the file. It must follow this specific signature:

def my_custom_measurement(regionmask, intensity_image, target_channel='adhesion_channel', **kwargs):
    # ... your calculation ...
    return scalar_value

Arguments:

  • regionmask (ndarray): A binary mask of the cell within its bounding box.

  • intensity_image (ndarray): The intensity image crop corresponding to the bounding box.

  • target_channel (str): The name of the channel being analyzed.

  • **kwargs: Required to handle additional arguments passed by the system.

Return Value:

  • Must return a single scalar (float or int).

  • Returning NaN is allowed.

Example: Measuring the max intensity

import numpy as np

def max_intensity(regionmask, intensity_image, **kwargs):
    # Select pixels within the cell mask
    masked_pixels = intensity_image[regionmask]
    # Return the maximum value
    return np.max(masked_pixels)

Step 3: Naming your function

The name of your function determines the column name in the output table.

  • Automatic Renaming: If your function name contains intensity, it will be replaced by the actual channel name. * Example: max_intensity becomes red_channel_max (if measuring the red channel).

  • Avoid Conflicts: Do not use simple numbers (e.g., measure_1) to avoid confusion with channel indices.

Step 4: Use it in Celldetective

  1. Save the extra_properties.py file.

  2. Restart Celldetective.

  3. Go to the Measurements module settings.

  4. Your new function will appear in the Extra features list. Checks the box to enable it.