Interaction Analysis

The interaction module quantifies spatial relationships between different organelle types through distance-based and contact-based analyses. iPA supports 14 predefined organelle interaction types, covering combinations of spherical, tubular, cylindrical, and network organelles.

Overview

Organelle interactions are fundamental to cellular function. For example:

  • Actin-vesicle: Regulates vesicle transport and docking

  • Mito-ER: Mitochondria-associated membranes (MAMs) for calcium signaling

  • Microtubule-organelle: Long-range transport tracks

iPA calculates minimal Euclidean distances between organelle pairs and identifies contact sites (distance < threshold), enabling quantitative analysis of inter-organelle spatial relationships.

Supported Interaction Types

iPA provides analysis functions for the following organelle pairs:

Actin-based Interactions: - Actin ↔ Vesicle - Actin ↔ Microtubule - Actin ↔ Mitochondria - Actin ↔ Endoplasmic Reticulum (ER)

Microtubule-based Interactions: - Microtubule ↔ Actin - Microtubule ↔ Vesicle - Microtubule ↔ Mitochondria - Microtubule ↔ ER

Organelle-Organelle Interactions: - Vesicle ↔ Mitochondria - Vesicle ↔ ER - Mitochondria ↔ ER

Each function follows a unified template:

  1. Load organelle masks or coordinates

  2. Apply coordinate shift correction (if needed)

  3. Calculate pairwise distance matrix using scipy.spatial.distance.cdist

  4. Extract minimum distances and corresponding point pairs

  5. Compute statistics (mean, std, percentiles)

  6. Identify contact sites (distance < threshold)

  7. Generate visualizations and save results

Core Functions

All interaction analysis functions share a common signature and return structure.

Common Parameters

  • data_id (str): Dataset identifier for output files

  • *_file (str): File paths for organelle masks (.mrc) or coordinates (.json)

  • config (dict): Configuration dictionary with keys: - voxel_size_xyz (list): Voxel dimensions [nm] - shift_bias (list): Coordinate offset correction [nm] - contact_threshold_nm (float, optional): Distance threshold for contacts. Default: 20.0 - visualization (bool): Enable visualization. Default: True - save_intermediate (bool): Save intermediate results. Default: False - output_dir (str): Output directory. Default: “./results”

Common Returns

  • results (dict): Dictionary containing: - distance_stats (dict): Distance statistics (mean, std, min, max, percentiles) - contact_sites_count (int): Number of contact sites - contact_coords (list): Contact point coordinates (if enabled) - visualization_path (str): Path to saved figure (if enabled)

Actin Interaction Functions

actin_to_vesicle_analysis

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

Calculate distance analysis from actin filaments to vesicle membranes

This function analyzes shortest distances from actin filaments to vesicle membrane surfaces, providing quantitative analysis of cytoskeleton-membrane structure interactions.

Parameters:

  • data_id (str) – Dataset identifier

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

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

  • config (Dict) – Configuration parameters dictionary, same as actin_to_actin_analysis

Returns:

Analysis result dictionary containing actin-to-vesicle membrane distance statistics

Return type:

Dict

Examples

>>> result = actin_to_vesicle_analysis(
...     data_id="sample_01",
...     mask_file="vesicle_mask.mrc",
...     json_file="actin_coords.json",
...     config=config
... )
>>> print(f"Average distance: {result['distance_stats']['mean']:.2f}")

Analyzes shortest distances from actin filaments to vesicle membranes.

Biological Context: Actin cortex regulates vesicle docking and secretion at the plasma membrane.

actin_to_vesicle_dist_angle_pair_analysis

ipa.analysis.actin_to_vesicle_dist_angle_pair_analysis(data_id: str, mask_file: str, json_file: str, angle_file: str, config: Dict) → Dict[source]

Calculate distance-angle pair analysis from actin filaments to vesicle membranes

This function simultaneously analyzes distance and angle relationships between actin filaments and vesicle membranes, providing comprehensive spatial interaction information.

Parameters:

  • data_id (str) – Dataset identifier

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

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

  • angle_file (str) – Actin angle data file path (.json format)

  • config (Dict) – Configuration parameters dictionary

Returns:

Analysis result dictionary containing distance and angle statistics

  • distance_stats (Dict): Distance statistics

  • angle_stats (Dict): Angle statistics (in degrees)

Return type:

Dict

Note

Angle calculation based on angle between actin filament direction vectors and vesicle membrane normal vectors

Combined distance-angle analysis for actin-vesicle interactions, providing both spatial proximity and angular orientation metrics.

actin_to_microtube_analysis

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

Calculate distance analysis from actin filaments to microtubules

Analyzes spatial relationships between actin filaments and microtubules in the cytoskeleton, calculating shortest distances between two types of filamentous structures.

Parameters:

  • data_id (str) – Dataset identifier

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

  • microtube_file (str) – Microtubule data file path (.json format)

  • config (Dict) – Configuration parameters dictionary

Returns:

Analysis result dictionary containing actin-to-microtubule distance analysis results

  • total_distance_vectors (int): Total number of distance vectors

  • total_shortest_distances (int): Total number of shortest distances

Return type:

Dict

Examples

>>> result = actin_to_microtube_analysis(
...     data_id="cytoskeleton_01",
...     actin_file="actin.json",
...     microtube_file="microtube.json",
...     config=config
... )

Analyzes spatial relationships between actin filaments and microtubules, revealing cytoskeletal network organization.

actin_to_mito_analysis

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

Calculate distance analysis from actin filaments to mitochondria

Analyzes spatial relationships between actin filaments and mitochondria, studying interaction patterns between cytoskeleton and organelles.

Parameters:

  • data_id (str) – Dataset identifier

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

  • mito_file (str) – Mitochondria mask file path (.mrc format)

  • config (Dict) – Configuration parameters dictionary

Returns:

Analysis result dictionary containing actin-to-mitochondria distance statistics

Return type:

Dict

Quantifies interactions between actin filaments and mitochondria, important for mitochondrial positioning and dynamics.

actin_to_endoreticulum_analysis

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

Calculate distance analysis from actin filaments to endoplasmic reticulum membranes, using original distances_generator and outplot functions.

Parameters:

  • data_id (str) – Dataset identifier

  • actin_file (str) – Actin filament coordinates file (.json)

  • er_file (str) – ER mask file (.mrc)

  • config (Dict) – Configuration dictionary - voxel_size_xyz (List[float]) - shift_bias (List[float]) - visualization (bool) - save_intermediate (bool) - output_dir (str, optional)

Returns:

Analysis result dictionary with distance stats, saved files, and visualizations

Return type:

Dict

Analyzes actin-endoplasmic reticulum spatial interactions, relevant for ER shaping and trafficking.

Microtubule Interaction Functions

microtube_to_actin_analysis

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

Calculate distance analysis from microtubules to actin filaments (reverse analysis)

Analyzes distance relationships from microtubules to actin filaments, providing another perspective on cytoskeletal network interactions.

Parameters:

  • data_id (str) – Dataset identifier

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

  • microtube_file (str) – Microtubule data file path (.json format)

  • config (Dict) – Configuration parameters dictionary

Returns:

Analysis result dictionary containing microtubule-to-actin distance and vector analysis results

Return type:

Dict

Analyzes microtubule-actin filament interactions from microtubule perspective (complementary to actin_to_microtube_analysis).

microtube_to_vesicle_analysis

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

Calculate distance analysis from microtubules to vesicle membranes, using original distances_generator and outplot functions.

Parameters:

  • data_id (str) – Dataset identifier

  • microtube_file (str) – Microtubule point coordinates file path (.json format)

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

  • config (Dict) – Configuration dictionary - voxel_size_xyz (List[float]) - shift_bias (List[float]) - visualization (bool) - save_intermediate (bool) - output_dir (str, optional)

Returns:

Analysis result with distance statistics, saved files, and plot results

Return type:

Dict

Quantifies spatial relationships between microtubules and vesicles, critical for long-range vesicle transport.

microtube_to_mito_analysis

ipa.analysis.microtube_to_mito_analysis(data_id: str, microtube_file: str, mito_file: str, config: Dict) → Dict[source]

Calculate distance analysis from microtubules to mitochondria membranes, using original distances_generator and outplot functions.

Parameters:

  • data_id (str) – Dataset identifier

  • microtube_file (str) – Microtubule coordinates file (.json)

  • mito_file (str) – Mitochondria mask file (.mrc)

  • config (Dict) – Configuration dictionary - voxel_size_xyz (List[float]) - shift_bias (List[float]) - visualization (bool) - save_intermediate (bool) - output_dir (str, optional)

Returns:

Analysis result with distance stats, saved result files, and plots

Return type:

Dict

Analyzes microtubule-mitochondria interactions, essential for mitochondrial distribution and motility.

microtube_to_endoreticulum_analysis

ipa.analysis.microtube_to_endoreticulum_analysis(data_id: str, microtube_file: str, er_file: str, config: Dict) → Dict[source]

Calculate distance analysis from microtubules to endoplasmic reticulum membranes, using original distances_generator and outplot functions.

Parameters:

  • data_id (str) – Dataset identifier

  • microtube_file (str) – Microtubule coordinates file (.json)

  • er_file (str) – ER mask file (.mrc)

  • config (Dict) – Configuration dictionary - voxel_size_xyz (List[float]) - shift_bias (List[float]) - visualization (bool) - save_intermediate (bool) - output_dir (str, optional)

Returns:

Analysis result with distance stats, saved result files, and plots

Return type:

Dict

Studies microtubule-ER spatial relationships, important for ER network organization.

Organelle-Organelle Interaction Functions

vesicle_to_mito_analysis

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

Calculate distance analysis from vesicle membranes to mitochondria membranes using image processing, compatible with original batch-wise calculation and outplot functions.

Parameters:

  • data_id (str) – Dataset identifier

  • vesicle_file (str) – Vesicle mask file (.mrc)

  • mito_file (str) – Mitochondria mask file (.mrc)

  • config (Dict) – Configuration dictionary - voxel_size_xyz (List[float]) - visualization (bool) - save_intermediate (bool) - output_dir (str, optional) - zoom_degree (float, optional, default 0.10) - batch_size (int, optional, default 1024)

Returns:

Analysis result dictionary with distance stats, saved files, and plots

Return type:

Dict

Analyzes direct vesicle-mitochondria spatial interactions, relevant for metabolic coupling.

vesicle_to_endoreticulum_analysis

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

Calculate distance analysis from vesicle membranes to endoplasmic reticulum membranes using image processing, compatible with original batch-wise calculation and outplot functions.

Parameters:

  • data_id (str) – Dataset identifier

  • vesicle_file (str) – Vesicle mask file (.mrc)

  • er_file (str) – ER mask file (.mrc)

  • config (Dict) – Configuration dictionary - voxel_size_xyz (List[float]) - visualization (bool) - save_intermediate (bool) - output_dir (str, optional) - zoom_degree (float, optional, default 0.10) - batch_size (int, optional, default 1024)

Returns:

Analysis result dictionary with distance stats, saved files, and plots

Return type:

Dict

Quantifies vesicle-ER spatial relationships, important for protein trafficking.

mito_to_endoreticulum_analysis

ipa.analysis.mito_to_endoreticulum_analysis(data_id: str, mito_file: str, er_file: str, config: Dict) → Dict[source]

Calculate distance analysis from mitochondria to endoplasmic reticulum (using image processing)

Uses image processing methods to analyze spatial relationships between mitochondria and endoplasmic reticulum, studying interaction patterns between two important organelles.

Parameters:

  • data_id (str) – Dataset identifier

  • mito_file (str) – Mitochondria mask file path (.mrc format)

  • er_file (str) – Endoplasmic reticulum mask file path (.mrc format)

  • config (Dict) – Configuration parameters dictionary

Returns:

Analysis result dictionary containing mitochondria-to-ER distance statistics

Return type:

Dict

Analyzes mitochondria-endoplasmic reticulum interactions, critical for calcium signaling and lipid transfer at MAMs (Mitochondria-Associated Membranes).

Usage Examples

Basic Actin-Vesicle Analysis

from ipa.analysis import actin_to_vesicle_analysis

# Configuration for cryo-ET data
config = {
    'voxel_size_xyz': [1.34, 1.34, 1.34],  # nm
    'shift_bias': [0.0, 0.0, 0.0],
    'contact_threshold_nm': 20.0,
    'visualization': True,
    'save_intermediate': False,
    'output_dir': "results/interactions/"
}

# Analyze actin-vesicle interactions
results = actin_to_vesicle_analysis(
    data_id="sample_01",
    mask_file="vesicle_mask.mrc",
    json_file="actin_coords.json",
    config=config
)

print(f"Mean distance: {results['distance_stats']['mean']:.2f} nm")
print(f"Contact sites: {results['contact_sites_count']}")

Multi-Organelle Interaction Pipeline

This example demonstrates analyzing multiple interaction pairs in a single workflow:

from ipa.analysis import (
    actin_to_microtube_analysis,
    actin_to_mito_analysis,
    vesicle_to_mito_analysis,
    mito_to_endoreticulum_analysis
)

# Common configuration
config = {
    'voxel_size_xyz': [1.34, 1.34, 1.34],
    'shift_bias': [0.0, 0.0, 0.0],
    'contact_threshold_nm': 20.0,
    'visualization': True,
    'output_dir': "results/interactions/"
}

# Analyze multiple interaction pairs
interactions = {}

# Cytoskeletal interactions
interactions['actin_microtubule'] = actin_to_microtube_analysis(
    data_id="sample_01",
    actin_file="actin_coords.json",
    microtube_file="microtubule_coords.json",
    config=config
)

interactions['actin_mito'] = actin_to_mito_analysis(
    data_id="sample_01",
    actin_file="actin_coords.json",
    mito_file="mito_mask.mrc",
    config=config
)

# Organelle-organelle interactions
interactions['vesicle_mito'] = vesicle_to_mito_analysis(
    data_id="sample_01",
    vesicle_file="vesicle_mask.mrc",
    mito_file="mito_mask.mrc",
    config=config
)

interactions['mito_er'] = mito_to_endoreticulum_analysis(
    data_id="sample_01",
    mito_file="mito_mask.mrc",
    er_file="er_mask.mrc",
    config=config
)

# Summarize results
print("\n=== Interaction Summary ===")
for pair, results in interactions.items():
    mean_dist = results['distance_stats']['mean']
    contacts = results['contact_sites_count']
    print(f"{pair}: mean distance = {mean_dist:.2f} nm, contacts = {contacts}")

Configuration Parameters

All interaction analysis functions accept a configuration dictionary. Here’s a complete reference:

Required Parameters:

  • voxel_size_xyz (list): Voxel dimensions in xyz [nm]. Example: [1.34, 1.34, 1.34] for cryo-ET

  • shift_bias (list): Coordinate offset correction [nm]. Use [0.0, 0.0, 0.0] if no correction needed

Optional Parameters:

  • contact_threshold_nm (float): Distance threshold for defining contacts. Default: 20.0 nm

  • visualization (bool): Enable result visualization. Default: True

  • save_intermediate (bool): Save intermediate processing results. Default: False

  • output_dir (str): Directory for output files. Default: “./results”

  • zoom_degree (float): Visualization zoom factor. Default: 1.0

  • batch_size (int): Processing batch size for memory management. Default: 10000

Example Configuration:

# For cryo-ET data
config_cryoet = {
    'voxel_size_xyz': [1.34, 1.34, 1.34],
    'shift_bias': [0.0, 0.0, 0.0],
    'contact_threshold_nm': 20.0,
    'visualization': True,
    'output_dir': "results/cryoet_interactions/"
}

# For SIM data
config_sim = {
    'voxel_size_xyz': [31.3, 31.3, 90.9],
    'shift_bias': [0.0, 0.0, 0.0],
    'contact_threshold_nm': 100.0,  # Larger threshold for lower resolution
    'visualization': True,
    'output_dir': "results/sim_interactions/"
}

Contact Analysis Functions

Beyond pairwise distances, iPA provides specialized functions for analyzing organelle contacts using radial distribution and probability metrics.

calculate_contact_rdf

ipa.analysis.calculate_contact_rdf(contact_coords, partition_mask, n_shells=8)[source]

Calculate the Radial Distribution Function (RDF) of organelle contacts.

Parameters:

  • contact_coords (list of tuples) – List of (z, y, x) coordinates for contact points.

  • partition_mask (np.ndarray) – 3D mask where values 1-n_shells represent radial shells.

  • n_shells (int) – Number of radial shells.

Returns:

Dictionary containing contact counts per shell and normalized RDF.

Return type:

dict

Calculates the Radial Distribution Function (RDF) of organelle contacts. This function quantifies how contact sites are distributed across different radial shells from the nucleus to the plasma membrane.

Algorithm:

  1. Count contact points in each radial shell

  2. Calculate shell volumes (total voxels per shell)

  3. Compute contact density: density = count / volume

  4. Normalize by average density across all shells: RDF = density / mean_density

Parameters:

  • contact_coords (list of tuples): List of (z, y, x) coordinates for contact points

  • partition_mask (np.ndarray): 3D mask where values 1-n_shells represent radial shells

  • n_shells (int): Number of radial shells. Default: 8

Returns:

  • dict: Dictionary containing: - contact_counts (np.ndarray): Contact counts per shell - shell_volumes (np.ndarray): Volume of each shell - rdf (np.ndarray): Normalized RDF values

Biological Significance:

Contact RDF reveals spatial patterns of organelle interactions. For example: - Enrichment near PM (RDF > 1 in outer shells): Contacts cluster at cell periphery - Uniform distribution (RDF ≈ 1): Contacts evenly distributed - Depletion near PM (RDF < 1 in outer shells): Contacts avoid cell periphery

Example:

from ipa.analysis import calculate_contact_rdf
from ipa.processing.partitioning import Partitioning
import numpy as np

# Assume you have contact coordinates from interaction analysis
contact_coords = [
    (50, 100, 150),  # (z, y, x)
    (52, 105, 155),
    (48, 98, 148)
]

# Create partition mask
partitioner = Partitioning(root_dir="results/", n_slices=8)
center, ne_edge, pm_edge = partitioner.extract_ne_pm_edges(pm_mask, ne_mask)
partition_mask = partitioner.create_nepm_radial_partitions(
    ne_edge, pm_edge,
    shape=volume.shape,
    n_slices=8,
    pm_mask=pm_mask,
    ne_mask=ne_mask
)

# Calculate contact RDF
results = calculate_contact_rdf(
    contact_coords,
    partition_mask,
    n_shells=8
)

print(f"Contact counts per shell: {results['contact_counts']}")
print(f"Contact RDF: {results['rdf']}")

calculate_contact_probability

ipa.analysis.calculate_contact_probability(contact_counts, total_organelles_per_shell)[source]

Calculate the probability that an organelle participates in a contact within each shell.

Parameters:

  • contact_counts (np.ndarray) – Number of contacts in each shell.

  • total_organelles_per_shell (np.ndarray) – Total number of organelles in each shell.

Returns:

Probability of contact per shell.

Return type:

np.ndarray

Calculates the probability that an organelle participates in a contact within each radial shell.

Formula:

\[P_{contact}(r) = \frac{N_{contacts}(r)}{N_{organelles}(r)}\]

where \(N_{contacts}(r)\) is the number of contacts in shell r, and \(N_{organelles}(r)\) is the total number of organelles in shell r.

Parameters:

  • contact_counts (np.ndarray): Number of contacts in each shell

  • total_organelles_per_shell (np.ndarray): Total number of organelles in each shell

Returns:

  • np.ndarray: Probability of contact per shell (values between 0 and 1)

Interpretation:

  • High probability (> 0.5): Most organelles in this region participate in contacts

  • Low probability (< 0.1): Few organelles form contacts

  • Spatial variation: Different probabilities across shells reveal regional specialization

Example:

from ipa.analysis import calculate_contact_probability
import numpy as np

# Contact counts from previous analysis
contact_counts = np.array([5, 8, 12, 15, 18, 20, 16, 10])

# Total organelles per shell (e.g., ISG counts)
total_isgs_per_shell = np.array([50, 60, 70, 80, 90, 100, 85, 65])

# Calculate contact probability
probs = calculate_contact_probability(contact_counts, total_isgs_per_shell)

print("Contact probability per shell:")
for shell_idx, prob in enumerate(probs):
    print(f"  Shell {shell_idx + 1}: {prob:.2%}")

# Visualization
import matplotlib.pyplot as plt
plt.bar(range(1, 9), probs)
plt.xlabel('Radial Shell (1=NE, 8=PM)')
plt.ylabel('Contact Probability')
plt.title('ISG Contact Probability Across Radial Shells')
plt.savefig('contact_probability.png', dpi=300)