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
^^^^^^^^^^^^^^^^^^^^^^^^^

.. autofunction:: ipa.analysis.actin_to_vesicle_analysis

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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autofunction:: ipa.analysis.actin_to_vesicle_dist_angle_pair_analysis

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

actin_to_microtube_analysis
^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autofunction:: ipa.analysis.actin_to_microtube_analysis

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

actin_to_mito_analysis
^^^^^^^^^^^^^^^^^^^^^^

.. autofunction:: ipa.analysis.actin_to_mito_analysis

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

actin_to_endoreticulum_analysis
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autofunction:: ipa.analysis.actin_to_endoreticulum_analysis

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

Microtubule Interaction Functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

microtube_to_actin_analysis
^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autofunction:: ipa.analysis.microtube_to_actin_analysis

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

microtube_to_vesicle_analysis
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autofunction:: ipa.analysis.microtube_to_vesicle_analysis

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

microtube_to_mito_analysis
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autofunction:: ipa.analysis.microtube_to_mito_analysis

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

microtube_to_endoreticulum_analysis
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autofunction:: ipa.analysis.microtube_to_endoreticulum_analysis

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

Organelle-Organelle Interaction Functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

vesicle_to_mito_analysis
^^^^^^^^^^^^^^^^^^^^^^^^

.. autofunction:: ipa.analysis.vesicle_to_mito_analysis

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

vesicle_to_endoreticulum_analysis
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autofunction:: ipa.analysis.vesicle_to_endoreticulum_analysis

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

mito_to_endoreticulum_analysis
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autofunction:: ipa.analysis.mito_to_endoreticulum_analysis

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

Usage Examples
--------------

Basic Actin-Vesicle Analysis
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

    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:

.. code-block:: python

    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**:

.. code-block:: python

    # 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
^^^^^^^^^^^^^^^^^^^^^

.. autofunction:: ipa.analysis.calculate_contact_rdf

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**:

.. code-block:: python

    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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autofunction:: ipa.analysis.calculate_contact_probability

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

**Formula**:

.. math::

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

where :math:`N_{contacts}(r)` is the number of contacts in shell r, and :math:`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**:

.. code-block:: python

    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)