bactoscoop.image¶

Classes and public operations¶

Image¶

class bactoscoop.image.Image(image, image_name, frame, mask=None, processed_mesh_dataframe=None, px=0.065)¶

Represent one microscopy field, its calibrated cell population, and channel caches.

Cell geometry and detections are attached during the collection workflow. Array geometry uses row/column pixel coordinates.

Parameters:

image – Input image consumed by this implementation; its exact use is visible in the linked source below. No maintained parameter description is present in the original docstring.
image_name – Input image_name consumed by this implementation; its exact use is visible in the linked source below. No maintained parameter description is present in the original docstring.
frame – Input frame consumed by this implementation; its exact use is visible in the linked source below. No maintained parameter description is present in the original docstring.
mask – Input mask consumed by this implementation; its exact use is visible in the linked source below. No maintained parameter description is present in the original docstring.
processed_mesh_dataframe – Input processed_mesh_dataframe consumed by this implementation; its exact use is visible in the linked source below. No maintained parameter description is present in the original docstring.
px – Micrometres per pixel. Geometry arrays remain in pixel coordinates.

Returns:

None (no explicit return statement).

Assigned state: self.mask, self.cells, self.px, self.image_name, self.frame, self.image, self.channels, self.joined_mask, self.processing_mask, self.prefilter_summary, self.mesh_dataframe, self.processed_mesh_dataframe, self.im_interp2d, self.chann_interp2d, self.bg_channels, self.inverted_image, self.feature_errors, self.object_detection_errors, self.shift_errors.

View current source, line 20.

Image.calculate_features¶

Image.calculate_features(method, channel, all_data, use_shifted_contours, shift_signal, max_mesh_size, retain_contour_on_object_mesh_failure_channels=None)¶

Calculate features for cells based on the specified method and channel.

Parameters:

method – The method used to calculate features for cells. The methods are: ‘morphological’, ‘profiling’, ‘svm’, ‘objects’, ‘phase’. (To be expanded)
channel – Channel identifier for the selected signal, or None for phase/morphology where supported.
all_data – Feature-method-specific option; objects includes detailed per-object arrays when true.
use_shifted_contours – Select stored shifted contour, midline, and mesh geometry; the correction must already exist.
shift_signal – Enable the method-specific optional signal cropping/shift path; this is not a universal object-coordinate shift.
max_mesh_size – Maximum accepted mesh row count; cells above this limit are removed from the image cell population.
retain_contour_on_object_mesh_failure_channels – Channels whose object rows keep contour measurements and NaN mesh aggregates when object geometry fails.

Return expressions in source:

result_df

Assigned state: self.feature_errors, self.cells, cell.discard.

Explicitly raised exceptions: TypeError. Errors from called functions can also propagate or be recorded.

View current source, line 76.

Original docstring (legacy wording may differ from the current signature)

Calculate features for cells based on the specified method and channel.

This method calculates features for individual cells in the image based on the provided method
and channel. It also allows for adding profiling data if required.

Parameters
----------
method : str
    The method used to calculate features for cells.
    The methods are: 'morphological', 'profiling', 'svm', 'objects', 'phase'. (To be expanded)
channel : str
    The channel for which features are calculated.
add_profiling_data : bool
    Whether to include profiling data in the feature calculations.

Returns
-------
pd.DataFrame
    A DataFrame containing the calculated features for the cells.

Image.features_to_dataframe¶

Image.features_to_dataframe(method)¶

Convert cell features stored in a dictionary to a pandas DataFrame.

Parameters:: method – The name of the method used for feature calculation.

Return expressions in source:

features_df

View current source, line 182.

Original docstring (legacy wording may differ from the current signature)

Convert cell features stored in a dictionary to a pandas DataFrame.

This method takes a dictionary of cell features, specified by the method name, and converts it into a pandas DataFrame.
Additionally, it adds information features to the DataFrame.

Parameters
----------
method : str
    The name of the method used for feature calculation.

Returns
-------
pd.DataFrame
    A DataFrame containing cell features.

Image.dataframe_from_dict¶

Image.dataframe_from_dict(feature_dictionary)¶

Convert a feature dictionary to a pandas DataFrame.

Parameters:: feature_dictionary – The name of the feature dictionary to convert.

Return expressions in source:

df

View current source, line 205.

Original docstring (legacy wording may differ from the current signature)

Convert a feature dictionary to a pandas DataFrame.

This method takes a feature dictionary, which maps cell IDs to feature values, and converts it into a pandas DataFrame.

Parameters
----------
feature_dictionary : str
    The name of the feature dictionary to convert.

Returns
-------
pd.DataFrame
    A DataFrame containing cell features.

Image.add_info_feature_df¶

Image.add_info_feature_df(dataframe)¶

Add information columns to a feature DataFrame.

Parameters:: dataframe – The DataFrame to which information columns will be added.
Returns:: None (no explicit return statement).

View current source, line 231.

Original docstring (legacy wording may differ from the current signature)

Add information columns to a feature DataFrame.

This method adds information columns, including 'image_name', 'cell_id', and 'frame',
to an existing DataFrame.

Parameters
----------
dataframe : pd.DataFrame
    The DataFrame to which information columns will be added.

Image.apply_neighbor_prefilter¶

Image.apply_neighbor_prefilter(max_neighbors=None, connectivity=1)¶

Apply neighbor prefilter.

Parameters:

max_neighbors – Remove labels whose distinct touching-label count is greater than this limit.
connectivity – Touching-label neighborhood: 1/4 for edges, 2/8 including diagonals.

Return expressions in source:

stats
None

Assigned state: self.processing_mask, self.prefilter_summary.

Explicitly raised exceptions: ValueError. Errors from called functions can also propagate or be recorded.

View current source, line 253.

Image.join_split_pipeline¶

Image.join_split_pipeline(join_thresh=4, split_thresh=0.3, CD_width=False, smoothing=0.1, neighbor_filter_max_neighbors=None, neighbor_filter_connectivity=1, max_daughter_cell_mesh_rows=800)¶

Perform a pipeline for joining and splitting cells.

Parameters:

join_thresh – Maximum pole-to-pole joining distance in pixels.
split_thresh – Relative constriction threshold used by the splitting pipeline.
CD_width – Use the width-based constriction path when true; otherwise use the pipeline phase-signal path.
smoothing – Smoothing passed to the contour/mesh fitting path.
neighbor_filter_max_neighbors – Maximum number of touching distinct labels allowed before meshing; None disables the prefilter.
neighbor_filter_connectivity – 1 or 4 for edge contact; 2 or 8 for edge and diagonal contact.
max_daughter_cell_mesh_rows – Maximum rebuilt mesh rows per daughter during cell splitting (default 800; integer >= 4). Rejects oversized predicted counts before reconstruction; both final daughters must have 4..limit rows. Does not limit unsplit parents and is separate from feature extraction max_mesh_size.

Returns:

None (no explicit return statement).

View current source, line 283.

Original docstring (legacy wording may differ from the current signature)

Perform a pipeline for joining and splitting cells.

This method is used within the batch_mesh_process() method of ImageCollection. It involves joining cells based on
a specified threshold, converting masks to mesh data, splitting cells based on a specified threshold,
and creating cell objects.

Parameters
----------
join_thresh : int, optional
    The threshold for joining cells in pixels. (default is 4)
split_thresh : float, optional
    The threshold for splitting cells. (default is 0.3)
max_daughter_cell_mesh_rows : int, optional
    Maximum rebuilt daughter mesh rows (default 800, minimum 4).
    Oversized resampling is rejected before its dense allocations.

Returns
-------
None

Image.create_cell_object¶

Image.create_cell_object(verbose=True)¶

Create Cell objects from mesh data.

Parameters:: verbose – Whether to print a message indicating the source of the Cell objects (processed or unprocessed meshes). (default is True)

Return expressions in source:

None

Assigned state: self.cells.

View current source, line 329.

Original docstring (legacy wording may differ from the current signature)

Create Cell objects from mesh data.

This method creates Cell objects based on mesh data contained in a DataFrame. The Cell objects are
initialized with contour, mesh, and midline data, and they are added to the list of cells in the Image object.

Parameters
----------
verbose : bool, optional
    Whether to print a message indicating the source of the Cell objects (processed or unprocessed meshes). (default is True)

Returns
-------
None

Image.add_cell¶

Image.add_cell(cell)¶

Add a Cell object to the list of cells in the Image object.

Parameters:: cell – Cell instance containing geometry and measurements.
Returns:: None (no explicit return statement).

View current source, line 377.

Original docstring (legacy wording may differ from the current signature)

Add a Cell object to the list of cells in the Image object.

Image.get_inverted_image¶

Image.get_inverted_image()¶

Calculate the inverted image for phase contrast.

Returns:: None (no explicit return statement).

Assigned state: self.inverted_image, self.im_interp2d.

View current source, line 383.

Original docstring (legacy wording may differ from the current signature)

Calculate the inverted image for phase contrast.

This method computes the inverted image for phase contrast imaging. It subtracts the maximum pixel value
from the original image and does a background subtraction (bgr = mean(background intensity)) to obtain the inverted image.

Image.get_bg_channel¶

Image.get_bg_channel(channel)¶

Get bg channel.

Parameters:: channel – Channel identifier for the selected signal, or None for phase/morphology where supported.
Returns:: None (no explicit return statement).

Assigned state: self.bg_channels.

View current source, line 396.

Image.get_inverted_interp2d¶

Image.get_inverted_interp2d()¶

Get inverted interp2d.

Return expressions in source:

self.im_interp2d

Assigned state: self.im_interp2d.

View current source, line 403.

Image.get_channel_interp2d¶

Image.get_channel_interp2d(channel)¶

Get channel interp2d.

Parameters:: channel – Channel identifier for the selected signal, or None for phase/morphology where supported.

Return expressions in source:

self.chann_interp2d[channel]

Assigned state: self.chann_interp2d.

View current source, line 410.

Image.channel_interp2d¶

Image.channel_interp2d()¶

Interpolate channel images using 2D spline interpolation.

Returns:: None (no explicit return statement).

View current source, line 417.

Original docstring (legacy wording may differ from the current signature)

Interpolate channel images using 2D spline interpolation.

This method interpolates the channel images using 2D spline interpolation and stores the interpolated images
in the 'chann_interp2d' dictionary.

Image.join_cells¶

Image.join_cells(thresh=None, smoothing=0.1)¶

Join cells based on pole-to-pole distance.

Parameters:

thresh – The distance threshold for joining cells. Cells with pole-to-pole distances below this value will be merged. If None, no threshold is applied, and all cells will be considered for joining. (default is None)
smoothing – Smoothing passed to the contour/mesh fitting path.

Returns:

None (no explicit return statement).

Assigned state: self.joined_mask.

Explicitly raised exceptions: ValueError. Errors from called functions can also propagate or be recorded.

View current source, line 427.

Original docstring (legacy wording may differ from the current signature)

Join cells based on pole-to-pole distance.

This method attempts to join adjacent cells within the image based on the distance between their poles. It identifies cell pairs
with pole-to-pole distances below a specified threshold and merges them into a single cell. The joined cell IDs are updated in the
'joined_mask' array.

Parameters
----------
thresh : float, optional
    The distance threshold for joining cells. Cells with pole-to-pole distances below this value will be merged. If None, no
    threshold is applied, and all cells will be considered for joining. (default is None)

Image.mask2mesh¶

Image.mask2mesh(smoothing=0.1)¶

Create meshes from cell masks.

Parameters:: smoothing – Smoothing passed to the contour/mesh fitting path.
Returns:: None (no explicit return statement).

Assigned state: self.mesh_dataframe.

View current source, line 520.

Original docstring (legacy wording may differ from the current signature)

Create meshes from cell masks.

This method processes cell masks to create corresponding meshes. It generates contours and skeletons for each cell in the mask,
extends the skeleton, and calculates additional geometric properties, such as length and width. Based on these properties, it
straightens the cell contour and creates a mesh representation. The resulting mesh data, including contour, mesh, and midline,
is stored in a DataFrame and associated with the image frame.

This method is based on the cell profile creation of the MOMIA package (doi: 10.1016/j.celrep.2021.110154)

Image.split_cells¶

Image.split_cells(thresh=0.3, CD_width=False, max_daughter_cell_mesh_rows=800)¶

Split cells based on a constriction degree threshold.

Parameters:

thresh – The constriction degree threshold for splitting cells. Cells with a constriction degree greater than this threshold will be split. The default is 0.3.
CD_width – Use the width-based constriction path when true; otherwise use the pipeline phase-signal path.
max_daughter_cell_mesh_rows – Maximum rebuilt mesh rows per daughter during cell splitting (default 800; integer >= 4). Rejects oversized predicted counts before reconstruction; both final daughters must have 4..limit rows. Does not limit unsplit parents and is separate from feature extraction max_mesh_size.

Returns:

None (no explicit return statement).

Assigned state: self.processed_mesh_dataframe.

View current source, line 543.

Original docstring (legacy wording may differ from the current signature)

Split cells based on a constriction degree threshold.

This method separates cells within the image based on a given constriction degree threshold. It calculates the constriction degree
for each cell and, if it exceeds the threshold, splits the cell into two separate cells. The new mesh data, including contour, mesh,
and midline, is stored in a DataFrame and associated with the image frame.

This method is based on the splitting algorithm in the Oufti software package (doi: 10.1111/mmi.13264).

Parameters
----------
thresh : float, optional
    The constriction degree threshold for splitting cells. Cells with a constriction degree greater than this threshold will be split.
    The default is 0.3.

max_daughter_cell_mesh_rows : int, optional
    Maximum final mesh rows per daughter (default 800, minimum 4).
    Reject oversized predicted row counts before reconstruction, then
    require both final daughters to have 4..limit rows. If either fails,
    neither daughter nor the parent enters the processed dataframe.

Image.object_detection¶

Image.object_detection(channels=None, smoothing=0.1, align=False, log_sigma=3, kernel_width=4, min_overlap_ratio=0.01, max_external_ratio=0.1)¶

Detect subcellular objects within cell contours in specified channels.

Parameters:

channels – Requested channel identifiers; for correlation, channel pairs are generated from this sequence.
smoothing – Smoothing passed to the contour/mesh fitting path.
align – Use the object-detection alignment path for the selected signal.
log_sigma – Laplacian-of-Gaussian sigma for signal-object detection.
kernel_width – Width of the square dilation kernel used for candidate object masks.
min_overlap_ratio – Minimum accepted overlap ratio under the utility implementation; inspect its denominator in source.
max_external_ratio – Maximum accepted outside-cell ratio under the utility implementation.

Return expressions in source:

detections_df

Assigned state: self.object_detection_errors, cell.object_meshdata.

View current source, line 657.

Original docstring (legacy wording may differ from the current signature)

Detect subcellular objects within cell contours in specified channels.

This method performs object detection within the contours of cells for the specified channels. It uses a Laplacian of Gaussian (LoG)
filter to detect subcellular objects and returns their contours. The detected objects are stored in a DataFrame, including the frame,
cell ID, channel name, and object contours.

Parameters
----------
channels : List of str, optional
    The list of channel names for which to perform object detection.

log_sigma : int, optional
    The sigma parameter of the LoG filter used in object detection. Increasing this parameter may detect larger objects.
    The default is 3.

kernel_width : int, optional
    The kernel width used for dilating object masks. Increasing this value results in larger masks.
    The default is 4.

min_overlap_ratio : float, optional
    The minimum overlap ratio between detected objects and cell contours to keep the object. Objects with lower overlap are discarded.
    The default is 0.01.

max_external_ratio : float, optional
    The maximum ratio an object is allowed to lie outside the cell contour. Objects exceeding this ratio are discarded.
    The default is 0.1.

Returns
-------
pd.DataFrame
    A DataFrame containing information about the detected objects, including frame, cell ID, channel name, and object contours.

Image.shift_correction¶

Image.shift_correction(shifted_channel, log_sigma, kernel_width, min_overlap_ratio, max_external_ratio, phase_log_sigma, phase_closing_level, signal_closing_level, max_shift_correction)¶

Shift correction.

Parameters:

shifted_channel – Input shifted_channel consumed by this implementation; its exact use is visible in the linked source below. No maintained parameter description is present in the original docstring.
log_sigma – Laplacian-of-Gaussian sigma for signal-object detection.
kernel_width – Width of the square dilation kernel used for candidate object masks.
min_overlap_ratio – Minimum accepted overlap ratio under the utility implementation; inspect its denominator in source.
max_external_ratio – Maximum accepted outside-cell ratio under the utility implementation.
phase_log_sigma – Input phase_log_sigma consumed by this implementation; its exact use is visible in the linked source below. No maintained parameter description is present in the original docstring.
phase_closing_level – Input phase_closing_level consumed by this implementation; its exact use is visible in the linked source below. No maintained parameter description is present in the original docstring.
signal_closing_level – Input signal_closing_level consumed by this implementation; its exact use is visible in the linked source below. No maintained parameter description is present in the original docstring.
max_shift_correction – Input max_shift_correction consumed by this implementation; its exact use is visible in the linked source below. No maintained parameter description is present in the original docstring.

Return expressions in source:

(len(self.cells) - failed_attempts) / len(self.cells)
0.0

Assigned state: self.shift_errors, cell.shifted_contour, cell.shifted_mesh, cell.shifted_midline.

Explicitly raised exceptions: ValueError. Errors from called functions can also propagate or be recorded.

View current source, line 778.

Cell¶

class bactoscoop.image.Cell(contour, mesh, midline, shape, cell_id)¶

Store one cell contour, paired mesh, midline, identity, and feature dictionaries.

The cell_id is local to a field; geometry arrays remain in pixel units.

Parameters:

contour – Boundary points in (row, column) pixel coordinates.
mesh – Paired-boundary geometry with four columns in pixel coordinates.
midline – Central-axis points in (row, column) pixel coordinates.
shape – Input shape consumed by this implementation; its exact use is visible in the linked source below. No maintained parameter description is present in the original docstring.
cell_id – Cell identifier local to the selected image; check that it remains after curation/filtering.

Returns:

None (no explicit return statement).

Assigned state: self.discard, self.contour, self.mesh, self.midline, self.cell_id, self.shifted_contour, self.shifted_mesh, self.shifted_midline, self.x1, self.y1, self.x2, self.y2, self.profile_mesh, self.object_meshdata, self.morphological_features, self.phase_features, self.objects_features, self.svm_features, self.profiling_features, self.signal_correlation_features, self.profiling_data.

View current source, line 839.

Original docstring (legacy wording may differ from the current signature)

Class representing a single cell in an image.

This class represents a single cell within an image, characterized by its contour, mesh, and midline data. It is identified by a unique cell ID.

Attributes
----------
discard : bool
    A flag to indicate whether the cell should be discarded during analysis.

contour : ndarray
    The contour data of the cell.

mesh : ndarray
    The mesh data (4xN).

midline : ndarray
    The midline data describing the cell's central axis (2xN).

cell_id : int
    A unique identifier for the cell.

x1, y1, x2, y2 : ndarray
    Arrays representing the coordinates of the cell's mesh.

profile_mesh : None
    Placeholder for profile mesh data.

object_contours : dict
    A dictionary to store detected subcellular object contours in different channels.

morphological_features : dict
    Dictionary to store morphological features of the cell.

phase_features : dict
    Dictionary to store phase contrast features of the cell.

objects_features : dict
    Dictionary to store features related to subcellular objects within the cell.

svm_features : dict
    Dictionary to store support vector machine (SVM) features.

profiling_features : dict
    Dictionary to store profiling features.

profiling_data : dict
    Dictionary to store data related to the profiling of the cell.

Internal helpers¶

Image._active_mask¶

Image._active_mask()¶

active mask.

Return expressions in source:

self.processing_mask if self.processing_mask is not None else self.mask

View current source, line 250.