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

ipa.analysis.calculate_3d_velocity(positions_t1, positions_t2, time_interval_s)[source]

Calculate 3D velocity from consecutive frame positions.

The 3D velocity is calculated as the Euclidean distance of positions at two consecutive time steps, divided by the time interval between the steps.

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:

Array of 3D velocities [N] in μm/s

Return type:

np.ndarray

Example

>>> import numpy as np
>>> from ipa.analysis import calculate_3d_velocity
>>> pos1 = np.array([[10, 20, 30], [15, 25, 35]])  # μm
>>> pos2 = np.array([[10.5, 20.3, 30.2], [15.4, 25.2, 35.1]])  # μm
>>> dt = 8.0  # seconds
>>> velocities = calculate_3d_velocity(pos1, pos2, dt)
>>> print(velocities)  # [0.064, 0.051] μm/s

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:

Calculate Euclidean displacement: displacement = ||pos_t2 - pos_t1||
Divide by time interval: velocity = displacement / Δt
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:

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

ipa.analysis.calculate_radial_velocity(positions, velocities, pm_mask)[source]

Calculate radial velocity of organelles projected along the direction to the nearest PM voxel.

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:

Array of radial velocity values.

Return type:

np.ndarray

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:

Find the nearest plasma membrane (PM) voxel for each organelle position using KD-tree
Calculate the unit vector from organelle to PM: vec_to_pm / ||vec_to_pm||
Project the 3D velocity onto this radial direction: v_radial = dot(velocity, unit_vector)
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:

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

ipa.analysis.create_velocity_violin_plot(speed_data, max_speed=30, y_limit=0.35, figure_size=(1.5, 1.2))[source]

Create a violin plot for velocity data comparison between categories

Parameters:

speed_datalist: List of tuples (speed, category)
max_speedfloat, optional: Maximum speed threshold for filtering outliers
y_limitfloat, optional: Y-axis upper limit for the plot
figure_sizetuple, optional: Figure size as (width, height) in inches

Returns:

matplotlib.figure.Figure : The created figure object

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:

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:

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.