Morphology Analysis

The morphology module extracts structural features from segmented organelles, including volume, surface area, length, and shape descriptors. These features are fundamental for characterizing subcellular structures across imaging modalities.

Overview

Morphological analysis quantifies the physical properties of organelles based on their 3D masks or coordinate representations. iPA categorizes organelles into three morphological classes:

  • Spherical organelles: ISGs, vesicles, lipid droplets - characterized by volume and sphericity

  • Cylindrical organelles: Mitochondria - characterized by volume and aspect ratio

  • Tubular organelles: F-actin, microtubules - characterized by total length and network topology

The extracted features enable quantitative comparisons of organelle morphology under different conditions (e.g., low vs. high glucose) and across imaging modalities.

Core Functions

extract_isg_features

ipa.analysis.extract_isg_features(isg_mask, min_distance=5, min_size=20, save_csv=False, output_path=None)[source]

Use watershed algorithm to perform 3D segmentation on ISG mask, generating data in the same format as 3D analysis results.

Parameters: - isg_mask: numpy ndarray, 3D ISG binary mask - min_distance: int, minimum distance for peak detection - min_size: int, minimum connected region size - save_csv: bool, whether to save CSV file - output_path: str, output CSV file path

Returns: - pandas.DataFrame: DataFrame containing segmentation results - numpy.ndarray: 3D segmented label image

Extracts comprehensive morphological features from insulin secretory granule (ISG) masks using watershed-based instance segmentation.

Features Extracted:

  • Volume (μm³)

  • Surface area (μm²)

  • Sphericity (0-1, where 1 = perfect sphere)

  • Major/minor axis lengths (nm)

  • Eccentricity

  • Solidity (area / convex area)

  • Equivalent diameter

Algorithm:

  1. Apply distance transform to ISG mask

  2. Detect local maxima as seed points

  3. Perform watershed segmentation to separate touching ISGs

  4. Calculate morphological features for each instance

  5. Optionally save results to CSV

Parameters:

  • img_isg (np.ndarray): 3D binary ISG mask

  • min_distance (int, optional): Minimum distance between peaks for seed detection. Default: 5

  • min_size (int, optional): Minimum connected component size (voxels). Default: 20

  • save_csv (bool, optional): Whether to save results to CSV. Default: False

  • output_path (str, optional): Output CSV file path. Required if save_csv=True

Returns:

  • df (pd.DataFrame): DataFrame containing morphological features for each ISG instance

  • labels (np.ndarray): 3D labeled mask with unique instance IDs

Example:

from ipa.analysis import extract_isg_features
from ipa.data_loader import UniversalDataLoader

# Load ISG mask from SXT data
isg_mask = UniversalDataLoader.load_data("isg_segmentation.mrc")

# Extract features
features_df, labels = extract_isg_features(
    isg_mask,
    min_distance=5,
    min_size=20,
    save_csv=True,
    output_path="results/isg_morphology.csv"
)

print(f"Found {len(features_df)} ISGs")
print(f"Mean volume: {features_df['Vol (unit)'].mean():.3f} μm³")
print(f"Mean sphericity: {features_df['Sphericity'].mean():.3f}")

calculate_tubular_length

ipa.analysis.calculate_tubular_length(skeleton_mask, voxel_size=(1.0, 1.0, 1.0), return_individual=False)[source]

Calculate the total length of tubular organelles by summing the distances between adjacent skeleton voxels.

Parameters:

  • skeleton_mask (np.ndarray) – 3D binary mask representing the skeleton of the tubular structure.

  • voxel_size (tuple) – Physical size of each voxel (z, y, x) in nm or um.

  • return_individual (bool) – If True, also returns a list of lengths for each individual connected component. NOTE: This is computationally expensive for large masks as it performs BFS on coordinates.

Returns:

Total length if return_individual is False. (Total length, List of individual lengths) if return_individual is True.

Return type:

float or tuple

Calculates the total length of tubular organelles (e.g., F-actin, microtubules) from skeleton masks by summing distances between adjacent skeleton voxels.

Algorithm:

  1. Extract skeleton voxel coordinates from binary mask

  2. Build KDTree for efficient nearest neighbor search

  3. Find nearest neighbors for each voxel within a radius threshold

  4. Sum unique connections (divided by 2 to avoid double counting)

  5. Convert to physical units using voxel size

Parameters:

  • skeleton_mask (np.ndarray): 3D binary skeleton mask

  • voxel_size (tuple, optional): Physical voxel size (Z, Y, X) in nm. Default: (1.0, 1.0, 1.0)

  • return_individual (bool, optional): Whether to return individual filament lengths. Default: False

Returns:

  • If return_individual=False: Total length (float, in nm)

  • If return_individual=True: Tuple of (total_length, list_of_individual_lengths)

Biological Significance:

Tubular length is a key metric for cytoskeletal networks. Changes in F-actin or microtubule length reflect cellular remodeling during processes like glucose-stimulated insulin secretion (GSIS).

Example:

from ipa.analysis import calculate_tubular_length
import json
import numpy as np

# Load actin coordinates from JSON (cryo-ET data)
with open("actin_filled_points.json", 'r') as f:
    actin_data = json.load(f)

# Reconstruct skeleton mask from coordinates
coords = np.array([pt for filament in actin_data.values() for pt in filament])
skeleton_mask = np.zeros(volume_shape, dtype=np.uint8)
for z, y, x in coords.astype(int):
    skeleton_mask[z, y, x] = 1

# Calculate length (cryo-ET voxel size: 1.34 nm)
total_length, individual_lengths = calculate_tubular_length(
    skeleton_mask,
    voxel_size=(1.34, 1.34, 1.34),
    return_individual=True
)

print(f"Total F-actin length: {total_length:.2f} nm")
print(f"Number of filaments: {len(individual_lengths)}")
print(f"Mean filament length: {np.mean(individual_lengths):.2f} nm")

actin_to_actin_analysis

ipa.analysis.actin_to_actin_analysis(data_id: str, mask_file: str, actin_file: str, config: Dict) → Dict[source]

Calculate distance analysis between actin filaments

This function analyzes spatial relationships between actin filaments, calculates shortest distances between filamentous structures, and generates corresponding statistical information and visualization results.

Parameters:

  • data_id (str) – Dataset identifier for naming output files

  • mask_file (str) – Vesicle mask file path (.mrc format)

  • actin_file (str) – Actin point coordinates file path (.json format)

  • config (Dict) – Configuration parameters dictionary containing: - voxel_size_xyz (List[float]): Voxel size [x, y, z] in Angstroms - shift_bias (List[float]): Coordinate offset [x, y, z] - visualization (bool): Whether to generate visualization charts - save_intermediate (bool): Whether to save intermediate result files - output_dir (str, optional): Output directory path

Returns:

Analysis result dictionary containing:

  • data_id (str): Dataset identifier

  • total_actin_filaments (int): Total number of actin filaments

  • total_distances (int): Total number of calculated distances

  • distance_stats (Dict): Distance statistics (mean, std, min/max, etc.)

  • status (str): Analysis status (‘success’ or ‘error’)

  • output_directory (str): Output directory path

  • vector_file (str, optional): Vector data file path

  • distance_file (str, optional): Distance data file path

  • plot_file (str, optional): Visualization chart file path

Return type:

Dict

Raises:

  • FileNotFoundError – Raised when input files do not exist

  • ImportError – Raised when required modules are not available

Analyzes spatial relationships within actin filament networks, calculating shortest distances between filaments and generating statistical summaries.

Parameters:

  • data_id (str): Dataset identifier for output files

  • mask_file (str): Vesicle mask file path (.mrc)

  • actin_file (str): Actin coordinates file (.json)

  • config (dict): Configuration dictionary with keys: - voxel_size_xyz (list): Voxel dimensions [nm] - shift_bias (list): Coordinate offset correction [nm] - visualization (bool): Enable visualization - output_dir (str): Output directory

Returns:

  • results (dict): Dictionary containing: - distance_stats: Distance statistics (mean, std, percentiles) - contact_sites: List of contact point coordinates - visualization_path: Path to saved figure (if enabled)

Example:

from ipa.analysis import actin_to_actin_analysis

config = {
    'voxel_size_xyz': [1.34, 1.34, 1.34],  # Cryo-ET
    'shift_bias': [0.0, 0.0, 0.0],
    'visualization': True,
    'output_dir': 'results/'
}

results = actin_to_actin_analysis(
    data_id="sample_01",
    mask_file="vesicle_mask.mrc",
    actin_file="actin_coords.json",
    config=config
)

print(f"Mean inter-filament distance: {results['distance_stats']['mean']:.2f} nm")

actin_angle_distance_pair_enhanced_analysis

ipa.analysis.actin_angle_distance_pair_enhanced_analysis(data_id: str, actin_file: str, vesicle_file: str, config: Dict) → Dict[source]

Enhanced Actin angle-distance pair analysis function with custom actinangle2dist implementation

Parameters:

  • data_id – Data ID for the analysis

  • actin_file – Path to actin points file (.json)

  • vesicle_file – Path to vesicle mask file (.mrc)

  • config – Configuration parameters dictionary

Returns:

Dictionary containing analysis results

Return type:

Dict

Enhanced analysis of actin angle-distance pair relationships with advanced statistical measures. This function calculates both the distance from actin filaments to reference structures and the angular orientation relative to those structures.

Parameters:

  • data_id (str): Dataset identifier

  • actin_file (str): Path to actin coordinates file (.json)

  • vesicle_file (str): Path to vesicle mask file (.mrc)

  • config (dict): Configuration dictionary

Returns:

  • results (dict): Dictionary with enhanced analysis metrics including angle-distance correlations

Example:

from ipa.analysis import actin_angle_distance_pair_enhanced_analysis

config = {
    'voxel_size_xyz': [1.34, 1.34, 1.34],
    'shift_bias': [0.0, 0.0, 0.0],
    'visualization': True,
    'output_dir': 'results/'
}

results = actin_angle_distance_pair_enhanced_analysis(
    data_id="sample_01",
    actin_file="actin_coords.json",
    vesicle_file="vesicle_mask.mrc",
    config=config
)

Usage Examples

Complete Morphology Workflow

This example demonstrates extracting multiple morphological features from different organelle types:

from ipa.analysis import extract_isg_features, calculate_tubular_length
from ipa.data_loader import UniversalDataLoader
import tifffile
import json
import numpy as np

# 1. ISG Morphology (from SXT)
print("=== ISG Morphology ===")
isg_mask = UniversalDataLoader.load_data("isg_mask.mrc")
isg_features, isg_labels = extract_isg_features(
    isg_mask,
    min_distance=5,
    min_size=20,
    save_csv=True,
    output_path="results/isg_features.csv"
)
print(f"Total ISGs: {len(isg_features)}")
print(f"Volume distribution: mean={isg_features['Vol (unit)'].mean():.3f}, "
      f"std={isg_features['Vol (unit)'].std():.3f}")

# 2. F-actin Length (from cryo-ET)
print("\n=== F-actin Length ===")
with open("actin_points.json", 'r') as f:
    actin_data = json.load(f)

# Reconstruct mask
volume_shape = (100, 200, 200)
coords = np.array([pt for filament in actin_data.values() for pt in filament])
actin_mask = np.zeros(volume_shape, dtype=np.uint8)
for z, y, x in coords.astype(int):
    actin_mask[z, y, x] = 1

total_length, individual_lengths = calculate_tubular_length(
    actin_mask,
    voxel_size=(1.34, 1.34, 1.34),
    return_individual=True
)
print(f"Total length: {total_length:.2f} nm")
print(f"Filament count: {len(individual_lengths)}")

# 3. Compare across conditions
print("\n=== Condition Comparison ===")
# Low glucose
lg_features, _ = extract_isg_features(lg_isg_mask)
# High glucose
hg_features, _ = extract_isg_features(hg_isg_mask)

print(f"LG mean volume: {lg_features['Vol (unit)'].mean():.3f} μm³")
print(f"HG mean volume: {hg_features['Vol (unit)'].mean():.3f} μm³")