Synchronization

Phase Synchronization analysis for paired signals.

This module implements the Synchronization feature, which measures the phase locking between two or more time series using the Phase Locking Value (PLV).

Synchronization

Bases: DynamicFeature

Real-time phase synchronization analyzer for paired signals.

Note

Computes the Phase Locking Value (PLV) between multiple signals after optional bandpass filtering and Hilbert transform.

Read more in the User Guide.

Parameters:

Examples:

>>> sync = Synchronization(filter_params={'low': 1.0, 'high': 10.0})
Source code in pyeyesweb/analysis_primitives/synchronization.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
class Synchronization(DynamicFeature):
    """Real-time phase synchronization analyzer for paired signals.

    !!! note
        Computes the Phase Locking Value (PLV) between multiple signals after
        optional bandpass filtering and Hilbert transform.

    Read more in the [User Guide](../../user_guide/theoretical_framework/analysis_primitives/synchronization.md).

    Parameters
    ----------
    filter_params : dict, optional
        Parameters for the bandpass filter applied before phase estimation.
        See [validate_and_normalize_filter_params](../utils/signal_processing.md#validate_and_normalize_filter_params)
        for details.

    Examples
    --------
    >>> sync = Synchronization(filter_params={'low': 1.0, 'high': 10.0})
    """

    def __init__(self, filter_params=None):
        super().__init__()
        self.filter_params = filter_params

    @property
    def filter_params(self):
        """Parameters for the bandpass pre-filter."""
        return self._filter_params

    @filter_params.setter
    def filter_params(self, value):
        self._filter_params = validate_and_normalize_filter_params(value)

    def compute(self, window_data: np.ndarray) -> SynchronizationResult:
        """Compute the Phase Locking Value (PLV) for the window.

        Parameters
        ----------
        window_data : numpy.ndarray of shape (Time, N_signals, N_dims)
            Input motion data.

        Returns
        -------
        SynchronizationResult
            Result containing the PLV.  Returns
            `SynchronizationResult(is_valid=False)` if fewer than 2 signals
            are present.
        """
        # Flatten to (Time, Signals)
        data = window_data.reshape(window_data.shape[0], -1)

        if data.shape[1] < 2:
            return SynchronizationResult(is_valid=False)

        # Assumes compute_phase_synchronization expects a 2D array of (Time, N_Signals)
        plv = compute_phase_synchronization(data, self.filter_params)
        return SynchronizationResult(plv=float(plv))

filter_params property writable

Parameters for the bandpass pre-filter.

compute(window_data)

Compute the Phase Locking Value (PLV) for the window.

Parameters:
  • window_data (numpy.ndarray of shape (Time, N_signals, N_dims)) –

    Input motion data.
Returns:
  • SynchronizationResult –

    Result containing the PLV. Returns SynchronizationResult(is_valid=False) if fewer than 2 signals are present.
Source code in pyeyesweb/analysis_primitives/synchronization.py 
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
def compute(self, window_data: np.ndarray) -> SynchronizationResult:
    """Compute the Phase Locking Value (PLV) for the window.

    Parameters
    ----------
    window_data : numpy.ndarray of shape (Time, N_signals, N_dims)
        Input motion data.

    Returns
    -------
    SynchronizationResult
        Result containing the PLV.  Returns
        `SynchronizationResult(is_valid=False)` if fewer than 2 signals
        are present.
    """
    # Flatten to (Time, Signals)
    data = window_data.reshape(window_data.shape[0], -1)

    if data.shape[1] < 2:
        return SynchronizationResult(is_valid=False)

    # Assumes compute_phase_synchronization expects a 2D array of (Time, N_Signals)
    plv = compute_phase_synchronization(data, self.filter_params)
    return SynchronizationResult(plv=float(plv))

SynchronizationResult dataclass

Bases: FeatureResult

Output contract for Phase Synchronization.

Attributes:
  • plv (float) –

    The Phase Locking Value in [0, 1]. A value of 1.0 indicates perfect phase synchronization; 0.0 indicates no synchronization.
Source code in pyeyesweb/analysis_primitives/synchronization.py 
16
17
18
19
20
21
22
23
24
25
26
@dataclass(slots=True)
class SynchronizationResult(FeatureResult):
    """Output contract for Phase Synchronization.

    Attributes
    ----------
    plv : float
        The Phase Locking Value in `[0, 1]`. A value of `1.0` indicates
        perfect phase synchronization; `0.0` indicates no synchronization.
    """
    plv: float = 0.0