Dynamics Analysis
=================

The dynamics module analyzes temporal features from time-lapse imaging data, including velocity and motion patterns of organelles.

Overview
--------

Dynamic analysis is crucial for understanding organelle transport and cellular processes. iPA currently provides tools for:

* **3D Velocity**: Displacement between consecutive frames divided by time interval
* **Radial Velocity**: Projection of 3D velocity onto the radial direction (toward/away from PM)
* **Velocity Distribution Visualization**: Violin plots for comparing conditions

These analyses are particularly important for studying processes like glucose-stimulated insulin secretion (GSIS), where ISG transport dynamics change significantly under different glucose conditions.

Core Functions
--------------

calculate_3d_velocity
~~~~~~~~~~~~~~~~~~~~~

.. autofunction:: ipa.analysis.calculate_3d_velocity

Calculates the 3D velocity of organelles from consecutive frame positions. The velocity is computed as the Euclidean distance between positions at two time steps, divided by the time interval.

**Algorithm**:

1. Calculate Euclidean displacement: ``displacement = ||pos_t2 - pos_t1||``
2. Divide by time interval: ``velocity = displacement / Δt``
3. Return velocity in μm/s (assuming positions are in μm)

**Parameters**:

- ``positions_t1`` (np.ndarray): Organelle positions at time t1 [N, 3] (in micrometers)
- ``positions_t2`` (np.ndarray): Organelle positions at time t2 [N, 3] (in micrometers)
- ``time_interval_s`` (float): Time interval between frames (seconds)

**Returns**: np.ndarray - Array of 3D velocities [N] in μm/s

**Example**:

.. code-block:: python

    import numpy as np
    from ipa.analysis import calculate_3d_velocity
    
    # Positions at two consecutive frames (μm)
    pos_t1 = np.array([[10, 20, 30], [15, 25, 35]])
    pos_t2 = np.array([[10.5, 20.3, 30.2], [15.4, 25.2, 35.1]])
    
    # Time interval (8 seconds for WFM)
    dt = 8.0
    
    # Calculate velocities
    velocities = calculate_3d_velocity(pos_t1, pos_t2, dt)
    print(f"Velocities: {velocities} μm/s")
    # Output: [0.064, 0.051] μm/s


calculate_radial_velocity
~~~~~~~~~~~~~~~~~~~~~~~~~

.. autofunction:: ipa.analysis.calculate_radial_velocity

Calculates the radial velocity of organelles by projecting their 3D velocity vectors onto the direction toward the nearest plasma membrane voxel. This metric reveals whether organelles are moving toward or away from the cell periphery.

**Algorithm**:

1. Find the nearest plasma membrane (PM) voxel for each organelle position using KD-tree
2. Calculate the unit vector from organelle to PM: ``vec_to_pm / ||vec_to_pm||``
3. Project the 3D velocity onto this radial direction: ``v_radial = dot(velocity, unit_vector)``
4. Positive values indicate movement toward PM; negative values indicate movement away

**Parameters**:

- ``positions`` (np.ndarray): Array of organelle positions [N, 3]
- ``velocities`` (np.ndarray): Array of 3D velocity vectors [N, 3]
- ``pm_mask`` (np.ndarray): 3D binary mask of the plasma membrane

**Returns**: np.ndarray - Array of radial velocity values

**Example**:

.. code-block:: python

    import numpy as np
    from ipa.analysis import calculate_radial_velocity
    
    # Load time-lapse data
    positions = np.array([[10, 20, 30], [15, 25, 35]])  # [N, 3]
    velocities = np.array([[0.5, 0.3, 0.2], [0.4, 0.2, 0.1]])  # [N, 3]
    pm_mask = load_plasma_membrane_mask()  # 3D binary mask
    
    # Calculate radial velocities
    radial_vels = calculate_radial_velocity(positions, velocities, pm_mask)
    print(f"Radial velocities: {radial_vels}")
    # Positive values: moving toward PM
    # Negative values: moving away from PM


create_velocity_violin_plot
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. autofunction:: ipa.analysis.create_velocity_violin_plot

Generates violin plots comparing velocity distributions across different conditions or time points.

**Parameters**:

- ``velocity_data`` (dict or list): Velocity measurements for different conditions. Can be:
  - Dictionary: {condition_name: array_of_velocities}
  - List: [array1, array2, ...]
- ``labels`` (list): Labels for different datasets (e.g., ['Control', 'Treatment'])
- ``title`` (str): Plot title
- ``ylabel`` (str, optional): Y-axis label. Default: "Velocity"
- ``save_path`` (str, optional): Path to save the figure. If None, displays interactively

**Returns**:

- ``fig`` (matplotlib.figure.Figure): Matplotlib figure object with violin plot

**Biological Context**:

In pancreatic β-cells, ISG velocities increase under high glucose conditions, reflecting enhanced MT-mediated transport toward the plasma membrane for secretion.

**Example**:

.. code-block:: python

    from ipa.analysis import create_velocity_violin_plot
    import numpy as np
    
    # Example: Compare velocities under different glucose conditions
    velocity_data = {
        'Low Glucose': np.random.normal(5.0, 1.5, 100),  # μm/s
        'High Glucose': np.random.normal(7.2, 2.0, 100)
    }
    
    # Create violin plot
    fig = create_velocity_violin_plot(
        velocity_data,
        labels=['Low Glucose', 'High Glucose'],
        title='ISG Velocity Distribution',
        ylabel='Velocity (μm/s)',
        save_path='results/velocity_comparison.png'
    )

Time-Series Analysis
~~~~~~~~~~~~~~~~~~~~

For analyzing velocity changes over time:

.. code-block:: python

    from ipa.analysis import create_velocity_violin_plot
    
    # Time-series velocity data
    timepoints = ['0 min', '5 min', '10 min', '15 min', '20 min']
    velocity_by_time = {
        '0 min': load_velocity_data('data_0min.csv'),
        '5 min': load_velocity_data('data_5min.csv'),
        '10 min': load_velocity_data('data_10min.csv'),
        '15 min': load_velocity_data('data_15min.csv'),
        '20 min': load_velocity_data('data_20min.csv')
    }
    
    # Visualize temporal changes
    fig = create_velocity_violin_plot(
        velocity_by_time,
        labels=timepoints,
        title='ISG Velocity Changes Over Time',
        ylabel='Velocity (μm/s)',
        save_path='results/velocity_timeseries.png'
    )

Future Extensions
-----------------

Planned features for future releases:

* **Trajectory Reconstruction**: Full path tracking and visualization
* **Mean Square Displacement (MSD)**: Quantifying diffusion characteristics
* **Diffusion Coefficient Estimation**: D values for different organelle types
* **Motion Pattern Classification**: Directed vs. random vs. confined motion
* **Kymograph Generation**: Space-time plots for visualizing transport

These extensions will further enhance iPA's capabilities for dynamic analysis of cellular processes.