sarcasm.structure_modules.domain_motion

Domain motion analysis module.

This module provides functions for analyzing sarcomere contraction dynamics within sarcomere domains over time, computing per-domain summary statistics and contraction parameters.

Attributes

logger

Functions

compute_domain_timeseries(→ Dict[str, numpy.ndarray])

Compute per-domain sarcomere length statistics over time.

detect_domain_contractions(→ Dict[str, numpy.ndarray])

Detect contraction cycles from domain-averaged sarcomere length time-series using ContractionNet.

analyze_domain_contraction_parameters() → Dict[str, ...)

Analyze contraction parameters for domain-averaged sarcomere length trajectories.

_interpolate_nans(→ numpy.ndarray)

Interpolate NaN values in a 1D array using linear interpolation.

Module Contents

sarcasm.structure_modules.domain_motion.logger
sarcasm.structure_modules.domain_motion.compute_domain_timeseries(pos_vectors_all: List[numpy.ndarray], sarcomere_length_vectors_all: List[numpy.ndarray], domain_mask: numpy.ndarray, pixelsize: float, n_domains: int) → Dict[str, numpy.ndarray][source]

Compute per-domain sarcomere length statistics over time.

For each frame, assigns sarcomere vectors to domains based on their position and computes summary statistics (mean, std, quartiles) of sarcomere lengths within each domain.

Parameters:

  • pos_vectors_all (List[np.ndarray]) – List of position vectors for each frame. Each element is shape (n_vectors, 2) in µm.

  • sarcomere_length_vectors_all (List[np.ndarray]) – List of sarcomere length vectors for each frame. Each element is shape (n_vectors,) in µm.

  • domain_mask (np.ndarray) – Integer-labeled domain mask from the reference frame. Domain IDs are 1, 2, 3, etc. Background pixels have value 0.

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

  • n_domains (int) – Number of domains in the mask (excluding background).

Returns:

Dictionary containing per-domain time-series: - ‘domain_slen_timeseries’: np.ndarray, shape (n_domains, n_frames), mean sarcomere length - ‘domain_slen_median_timeseries’: np.ndarray, shape (n_domains, n_frames), median sarcomere length - ‘domain_slen_std_timeseries’: np.ndarray, shape (n_domains, n_frames), std of sarcomere length - ‘domain_slen_q25_timeseries’: np.ndarray, shape (n_domains, n_frames), 25th percentile - ‘domain_slen_q75_timeseries’: np.ndarray, shape (n_domains, n_frames), 75th percentile - ‘domain_n_vectors_timeseries’: np.ndarray, shape (n_domains, n_frames), number of vectors

Return type:

dict

sarcasm.structure_modules.domain_motion.detect_domain_contractions(domain_slen_timeseries: numpy.ndarray, frametime: float, model_path: str, threshold: float = 0.3, contr_time_min: float = 0.2, merge_time_max: float = 0.05, buffer_frames: int = 3, min_valid_frames: float = 0.5) → Dict[str, numpy.ndarray][source]

Detect contraction cycles from domain-averaged sarcomere length time-series using ContractionNet.

Uses the ContractionNet neural network to predict contraction states from the mean sarcomere length signal of each domain, then applies morphological operations to clean up the predictions.

Parameters:

  • domain_slen_timeseries (np.ndarray) – Per-domain mean sarcomere length time-series. Shape (n_domains, n_frames).

  • frametime (float) – Time between frames in seconds.

  • model_path (str) – Path to the ContractionNet model weights (.pt file).

  • threshold (float, optional) – Binary threshold for contraction state prediction. Default 0.3.

  • contr_time_min (float, optional) – Minimal time of contraction in seconds. Shorter contractions are removed. Default 0.2.

  • merge_time_max (float, optional) – Maximal time between two contractions. Closer contractions are merged. Default 0.05.

  • buffer_frames (int, optional) – Remove contraction cycles within this many frames of start/end of time-series. Default 3.

  • min_valid_frames (float, optional) – Minimum fraction of valid (non-NaN) frames required for a domain to be analyzed. Default 0.5.

Returns:

Dictionary containing per-domain contraction detection results: - ‘domain_contr’: np.ndarray, shape (n_domains, n_frames), binary contraction state - ‘domain_n_contr’: np.ndarray, shape (n_domains,), number of contractions per domain - ‘domain_labels_contr’: np.ndarray, shape (n_domains, n_frames), contraction cycle labels - ‘domain_beating_rate’: np.ndarray, shape (n_domains,), beating rate in Hz - ‘domain_beating_rate_variability’: np.ndarray, shape (n_domains,), std of inter-beat interval

Return type:

dict

sarcasm.structure_modules.domain_motion.analyze_domain_contraction_parameters(domain_slen_timeseries: numpy.ndarray, domain_labels_contr: numpy.ndarray, domain_n_contr: numpy.ndarray, frametime: float, filter_params: Tuple[int, int] = (13, 5)) → Dict[str, numpy.ndarray][source]

Analyze contraction parameters for domain-averaged sarcomere length trajectories.

Computes per-domain, per-contraction-cycle parameters including maximum contraction, maximum elongation, velocities, and timing parameters.

Parameters:

  • domain_slen_timeseries (np.ndarray) – Per-domain mean sarcomere length time-series. Shape (n_domains, n_frames).

  • domain_labels_contr (np.ndarray) – Per-domain contraction cycle labels. Shape (n_domains, n_frames).

  • domain_n_contr (np.ndarray) – Number of contractions per domain. Shape (n_domains,).

  • frametime (float) – Time between frames in seconds.

  • filter_params (Tuple[int, int], optional) – Savitzky-Golay filter parameters (window_length, polyorder) for velocity smoothing. Default (13, 5).

Returns:

Dictionary containing per-domain contraction parameters: - ‘domain_equ’: np.ndarray, shape (n_domains,), equilibrium/resting sarcomere length - ‘domain_contr_max’: np.ndarray, shape (n_domains, max_n_contr), max contraction per cycle - ‘domain_elong_max’: np.ndarray, shape (n_domains, max_n_contr), max elongation per cycle - ‘domain_vel_contr_max’: np.ndarray, shape (n_domains, max_n_contr), max shortening velocity - ‘domain_vel_elong_max’: np.ndarray, shape (n_domains, max_n_contr), max elongation velocity - ‘domain_time_to_peak’: np.ndarray, shape (n_domains, max_n_contr), time to maximal contraction - ‘domain_time_to_relax’: np.ndarray, shape (n_domains, max_n_contr), time from peak to relaxation - ‘domain_time_contr’: np.ndarray, shape (n_domains, max_n_contr), contraction duration

Return type:

dict

sarcasm.structure_modules.domain_motion._interpolate_nans(arr: numpy.ndarray) → numpy.ndarray[source]

Interpolate NaN values in a 1D array using linear interpolation.

Parameters:

arr (np.ndarray) – 1D array potentially containing NaN values.

Returns:

Array with NaN values interpolated.

Return type:

np.ndarray