sarcasm.training_data_generation

Classes

TrainingDataGenerator

Class for training data generation:

Module Contents

class sarcasm.training_data_generation.TrainingDataGenerator(image_path: str, output_dirs: dict, pixelsize: float = None)

Class for training data generation: - Z-band mask - M-band mask - Sarcomere orientation field - Sarcomere mask

image_path

image = None

basename

output_dirs

shape

wavelet_dict = None

__getattr__(attr)

__dir__()

Include dynamic attributes in autocompletion

predict_zbands(model_path: str, network: str = 'Unet_v0', patch_size: tuple[int, int] = (1024, 1024))

Predict sarcomere Z-bands using pre-trained U-Net model. This is optional, alternatively manually annotated Z-band masks in ‘zbands’ directory can be used.

Parameters:

• model_path (str) – Path of U-Net model for sarcomere Z-band detection.

• network (str) – Model type, choose from models in bio-image-unet package. Defaults to ‘UNet_v0’.

• patch_size (Tuple[int, int]) – Patch size for prediction. Sizes should be multiples of 16.

wavelet_analysis(kernel: str = 'half_gaussian', size: float = 3.0, minor: float = 0.33, major: float = 1.0, len_lims: tuple[float, float] = (1.45, 2.7), len_step: float = 0.05, orient_lims: tuple[float, float] = (-90, 90), orient_step: float = 10, add_negative_center_kernel: bool = False, patch_size: int = 1024, score_threshold: float = 0.25, abs_threshold: bool = True, gating: bool = True, load_mbands: bool = False, dtype: torch.dtype | str = 'auto', save_memory: bool = False, device: torch.device = torch.device('cpu'))

AND-gated double wavelet analysis of sarcomere length and orientation.

Parameters:

• kernel (str, optional) – Filter kernel - ‘gaussian’ for bivariate Gaussian kernel - ‘half_gaussian’ for univariate Gaussian in minor axis direction and step function in major axis direction - ‘binary’ for binary step function in both directions Defaults to ‘half_gaussian’.

• size (float, optional) – Size of wavelet filters (in µm), needs to be larger than the upper limit of len_lims. Defaults to 3.0.

• minor (float, optional) – Minor axis width in µm, quantified by full width at half-maximum (FWHM, 2.33 * sigma in our paper), should match the thickness of Z-bands, for kernel=’gaussian’ and kernel=’half_gaussian’. Defaults to 0.33.

• major (float, optional) – Major axis width (parameter ‘w’ in our paper) in µm, should match the width of Z-bands. Full width at half-maximum (FWHM) for kernel=’gaussian’ and full width for kernel=’half_gaussian’. Defaults to 1.0.

• len_lims (tuple(float, float), optional) – Limits of lengths / wavelet distances in µm, range of sarcomere lengths. Defaults to (1.3, 2.6).

• len_step (float, optional) – Step size of sarcomere lengths in µm. Defaults to 0.05.

• orient_lims (tuple(float, float), optional) – Limits of sarcomere orientation angles in degrees. Defaults to (-90, 90).

• orient_step (float, optional) – Step size of orientation angles in degrees. Defaults to 10.

• add_negative_center_kernel (bool, optional) – Whether to add a negative kernel in the middle of the two wavelets, to avoid detection of two Z-bands two sarcomeres apart as sarcomere, only for kernel=’gaussian’. Defaults to False.

• patch_size (int, optional) – Patch size for wavelet analysis, default is 1024 pixels. Adapt to GPU storage. Defaults to 1024.

• score_threshold (float, optional) – Threshold score for clipping of length and orientation map (if abs_threshold=False, score_threshold is percentile (e.g., 90) for adaptive thresholding). Defaults to 0.25.

• abs_threshold (bool, optional) – If True, absolute threshold value is applied; if False, adaptive threshold based on percentile. Defaults to True.

• gating (bool, optional) – If True, AND-gated wavelet filtering is used. If False, both wavelet filters are applied jointly. Defaults to True.

• load_mbands (bool, optional) – If True, manually curated M-band mask is loaded.

• dtype (torch.dtype or str, optional) – Specify torch data type (torch.float32 or torch.float16), ‘auto’ chooses float16 for cuda and mps, and float32 for cpu. Defaults to ‘auto’.

• device (torch.device) – Device for 2D convolutions (torch.device(‘cuda’) for GPU, torch.device(‘mps’) for Apple Silicon, torch.device(‘cpu’) for CPU)

create_sarcomere_mask(dilation_radius)

Create binary sarcomere mask from sarcomere vectors.

Parameters:

dilation_radius (float) – Dilation radius to dilate sarcomere mask and close small gaps, in µm.

create_orientation_map()

Creates 2D sarcomere orientation map from sarcomere vectors. The 2D shows shows the directions of unit vectors pointing from M-bands to Z-bands. Undefined regions have np.nan values.

Returns:

orientation_map – A 2D array with values reflecting the local sarcomere orientation angle.

Return type:

numpy.ndarray

smooth_orientation_map(window_size: int = 3)

Smooth orientation angle map using a nanmedian filter. To handle the angle discontinuity from 2 pi -> 0, the orientation angle map is converted to a 2D orientation field, both components are smoothed, and then converted back

Parameters:

window_size (int) – Size of smoothing kernel, must be odd integer.

plot_results(save_path=None, xlim=None, ylim=None)

static binary_kernel(d: float, sigma: float, width: float, orient: float, size: float, pixelsize: float, mode: str = 'both') → numpy.ndarray | tuple[numpy.ndarray, numpy.ndarray]

Returns binary kernel pair for AND-gated double wavelet analysis.

Parameters:

• d (float) – Distance between two wavelets.

• sigma (float) – Minor axis width of single wavelets.

• width (float) – Major axis width of single wavelets.

• orient (float) – Rotation orientation in degrees.

• size (Tuple[float, float]) – Size of kernel in µm.

• pixelsize (float) – Pixelsize in µm.

• mode (str, optional) – ‘separate’ returns two separate kernels, ‘both’ returns a single kernel. Defaults to ‘both’.

Returns:

The generated binary kernel(s).

Return type:

Union[np.ndarray, Tuple[np.ndarray, np.ndarray]]

static gaussian_kernel(dist: float, minor: float, major: float, orient: float, size: float, pixelsize: float, mode: str = 'both', add_negative_center_kernel: bool = False) → tuple[numpy.ndarray, numpy.ndarray] | numpy.ndarray

Returns gaussian kernel pair for AND-gated double wavelet analysis

Parameters:

• dist (float) – Distance between two wavelets

• minor (float) – Minor axis width of single wavelets in µm

• major (float) – Major axis width of single wavelets in µm

• orient (float) – Rotation orientation in degree

• size (float) – Size of kernel in µm

• pixelsize (float) – Pixelsize in µm

• mode (str, optional) – ‘separate’ returns two separate kernels, ‘both’ returns single kernel

• add_negative_center_kernel (bool, optional) – Whether to add a negative kernel in the middle of the two wavelets, to avoid detection of two Z-bands two sarcomeres apart as sarcomere

Returns:

Gaussian kernel pair

Return type:

tuple[np.ndarray, np.ndarray]

static half_gaussian_kernel(dist: float, minor: float, major: float, orient: float, size: float, pixelsize: float, mode: str = 'both', add_negative_center_kernel: bool = False) → tuple[numpy.ndarray, numpy.ndarray] | numpy.ndarray

Returns kernel pair for AND-gated double wavelet analysis with univariate Gaussian profile in longitudinal minor axis direction and step function in lateral major axis direction

Parameters:

• dist (float) – Distance between two wavelets

• minor (float) – Minor axis width, in full width at half maximum (FWHM), of single wavelets in µm

• major (float) – Major axis width of single wavelets in µm.

• orient (float) – Rotation orientation in degree

• size (float) – Size of kernel in µm

• pixelsize (float) – Pixelsize in µm

• mode (str, optional) – ‘separate’ returns two separate kernels, ‘both’ returns single kernel

• add_negative_center_kernel (bool, optional) – Whether to add a negative kernel in the middle of the two wavelets, to avoid detection of two Z-bands two sarcomeres apart as sarcomere

Returns:

Gaussian kernel pair

Return type:

tuple[np.ndarray, np.ndarray]

static round_up_to_odd(f: float) → int

Rounds float up to the next odd integer.

Parameters:

f (float) – The input float number.

Returns:

The next odd integer.

Return type:

int

static create_wavelet_bank(pixelsize: float, kernel: str = 'half_gaussian', size: float = 3, minor: float = 0.15, major: float = 0.5, len_lims: tuple[float, float] = (1.3, 2.5), len_step: float = 0.025, orient_lims: tuple[float, float] = (-90, 90), orient_step: float = 5, add_negative_center_kernel: bool = False) → list[numpy.ndarray]

Returns bank of double wavelets.

Parameters:

• pixelsize (float) – Pixel size in µm.

• kernel (str, optional) – Filter kernel (‘gaussian’ for double Gaussian kernel, ‘binary’ for binary double-line, ‘half_gaussian’ for half Gaussian kernel). Defaults to ‘half_gaussian’.

• size (float, optional) – Size of kernel in µm. Defaults to 3.

• minor (float, optional) – Minor axis width of single wavelets. Defaults to 0.15.

• major (float, optional) – Major axis width of single wavelets. Defaults to 0.5.

• len_lims (Tuple[float, float], optional) – Limits of lengths / wavelet distances in µm. Defaults to (1.3, 2.5).

• len_step (float, optional) – Step size in µm. Defaults to 0.025.

• orient_lims (Tuple[float, float], optional) – Limits of orientation angle in degrees. Defaults to (-90, 90).

• orient_step (float, optional) – Step size in degrees. Defaults to 5.

• add_negative_center_kernel (bool, optional) – Whether to add a negative kernel in the middle of the two wavelets, to avoid detection of two Z-bands two sarcomeres apart as sarcomere, only for kernel==’gaussian’ or ‘half_gaussian. Defaults to False.

Returns:

Bank of double wavelets.

Return type:

List[np.ndarray]

static convolve_image_with_bank(image: numpy.ndarray, bank: numpy.ndarray, device: torch.device, gating: bool = True, dtype: torch.dtype = torch.float16, save_memory: bool = False, patch_size: int = 512) → torch.Tensor

AND-gated double-wavelet convolution of image using kernels from filter bank, with merged functionality. Processes the image in smaller overlapping patches to manage GPU memory usage and avoid edge effects.

Parameters:

• image (np.ndarray) – Input image to be convolved.

• bank (np.ndarray) – Filter bank containing the wavelet kernels.

• device (torch.device) – Device on which to perform the computation (e.g., ‘cuda’, ‘mps’ or ‘cpu’).

• gating (bool, optional) – Whether to use AND-gated double-wavelet convolution. Default is True.

• dtype (torch.dtype, optional) – Data type for the tensors. Default is torch.float16.

• save_memory (bool, optional) – Whether to save memory by moving intermediate results to CPU. Default is False.

• patch_size (int, optional) – Size of the patches to process the image in. Default is 512.

Returns:

The result of the convolution, reshaped to match the input image dimensions.

Return type:

torch.Tensor

static argmax_wavelets(result: torch.Tensor, len_range: torch.Tensor, orient_range: torch.Tensor) → tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]

Compute the argmax of wavelet convolution results to extract length, orientation, and maximum score map.

This function processes the result of a wavelet convolution operation to determine the optimal length and orientation for each position in the input image. It leverages GPU acceleration for efficient computation and returns the results as NumPy arrays.

Parameters:

• result (torch.Tensor) – The result tensor from a wavelet convolution operation, expected to be on a GPU device. Shape is expected to be (num_orientations, num_lengths, height, width).

• len_range (torch.Tensor) – A tensor containing the different lengths used in the wavelet bank. Shape: (num_lengths,).

• orient_range (torch.Tensor) – A tensor containing the different orientation angles used in the wavelet bank, in degrees. Shape: (num_orientations,).

Returns:

• length_np (np.ndarray) – A 2D array of the optimal length for each position in the input image. Shape: (height, width).

• orient_np (np.ndarray) – A 2D array of the optimal orientation (in radians) for each position in the input image. Shape: (height, width).

• max_score_np (np.ndarray) – A 2D array of the maximum convolution score for each position in the input image. Shape: (height, width).

static get_sarcomere_vectors_wavelet(length: numpy.ndarray, orientation: numpy.ndarray, max_score: numpy.ndarray, len_range: numpy.ndarray, mbands: numpy.ndarray | None = None, score_threshold: float = 0.2, abs_threshold: bool = True) → tuple

Extracts vector positions on sarcomere mbands and calculates sarcomere length and orientation.

This function performs the following steps: 1. Thresholding: Applies a threshold to the length, orientation, and max_score arrays to refine sarcomere detection. 2. Binarization: Creates a binary mask to isolate mband regions. 3. Skeletonization: Thins the mband regions for easier analysis. 4. Labeling: Assigns unique labels to each connected mband component. 5. Midline Point Extraction: Identifies the coordinates of vectors along each mband. 6. Value Calculation: Calculates sarcomere length, orientation, and maximal score at each mband point.

Parameters:

• length (np.ndarray) – Sarcomere length map obtained from wavelet analysis.

• orientation (np.ndarray) – Sarcomere orientation angle map obtained from wavelet analysis.

• max_score (np.ndarray) – Map of maximal wavelet scores.

• len_range (torch.Tensor) – An array containing the different lengths used in the wavelet bank.

• mbands (np.ndarray or None, optional) – If not None, manually curated / corrected M-band mask is loaded.

• score_threshold (float, optional) – Threshold for filtering detected sarcomeres. Can be either an absolute value (if abs_threshold=True) or a percentile value for adaptive thresholding (if abs_threshold=False). Default is 90.

• abs_threshold (bool, optional) – Flag to determine the thresholding method. If True, ‘score_threshold’ is used as an absolute value. If False, ‘score_threshold’ is interpreted as a percentile for adaptive thresholding. Default is False.

Returns:

• pos_vectors_px (list): List of (x, y) coordinates for each mband point. In pixels.

• mband_id_vectors (list): List of corresponding mband labels for each point.

• mband_length_vectors (list): List of approximate mband lengths associated with each point. In pixels.

• sarcomere_length_vectors (list): List of sarcomere lengths at each mband point. In µm.

• sarcomere_orientation_vectors (list): List of sarcomere orientation angles at each mband point.

• max_score_vectors (list): List of maximal wavelet scores at each mband point.

• mband (np.ndarray): The binarized mband mask.

• score_threshold (float): The final threshold value used.

Return type:

tuple

static interpolate_distance_map(image, N=50, method='linear')

Interpolates NaN regions in a 2D image, filling only those regions whose size is less than or equal to a specified threshold.

Parameters:

• image (numpy.ndarray) – A 2D array representing the input image. NaN values represent gaps to be filled.

• N (int) – The maximum size (in pixels) of connected NaN regions to interpolate. Regions larger than this threshold will remain unaltered.

• method (str, optional) – The interpolation method to use. Options are ‘linear’, ‘nearest’, and ‘cubic’. Default is ‘linear’.

Returns:

A 2D array with the same shape as the input image, where small NaN regions (size <= N) have been interpolated. Larger NaN regions are left unchanged.

Return type:

numpy.ndarray

static get_pixel_size(file_path)

Retrieves pixel size (x, y) in micrometers from a TIFF file. Prioritizes ImageJ metadata, then falls back to TIFF resolution tags. Raises ValueError if pixel size cannot be determined.