bmtool 0.6.8.2__py3-none-any.whl → 0.6.8.4__py3-none-any.whl

bmtool/analysis/lfp.py

@@ -292,7 +292,7 @@ def butter_bandpass_filter(data: np.ndarray, lowcut: float, highcut: float, fs:
     return x_a
 
 
-def calculate_plv(x1: np.ndarray, x2: np.ndarray, fs: float, freq_of_interest: float = None, 
+def calculate_signal_signal_plv(x1: np.ndarray, x2: np.ndarray, fs: float, freq_of_interest: float = None, 
                   method: str = 'wavelet', lowcut: float = None, highcut: float = None, 
                   bandwidth: float = 2.0) -> np.ndarray:
     """
@@ -345,115 +345,252 @@ def calculate_plv(x1: np.ndarray, x2: np.ndarray, fs: float, freq_of_interest: f
     return plv
 
 
-def calculate_plv_over_time(x1: np.ndarray, x2: np.ndarray, fs: float, 
-                            window_size: float, step_size: float, 
-                            method: str = 'wavelet', freq_of_interest: float = None, 
-                            lowcut: float = None, highcut: float = None, 
-                            bandwidth: float = 2.0):
+def calculate_spike_lfp_plv(spike_times: np.ndarray = None, lfp_signal: np.ndarray = None, spike_fs : float = None,
+                   lfp_fs: float = None, method: str = 'hilbert', freq_of_interest: float = None,
+                   lowcut: float = None, highcut: float = None,
+                   bandwidth: float = 2.0) -> tuple:
     """
-    Calculate the time-resolved Phase Locking Value (PLV) between two signals using a sliding window approach.
+    Calculate spike-lfp phase locking value Based on https://www.sciencedirect.com/science/article/pii/S1053811910000959
     
     Parameters:
-    ----------
-    x1, x2 : array-like
-        Input signals (1D arrays, same length).
-    fs : float
-        Sampling frequency of the input signals.
-    window_size : float
-        Length of the window in seconds for PLV calculation.
-    step_size : float
-        Step size in seconds to slide the window across the signals.
-    method : str, optional
-        Method to calculate PLV ('wavelet' or 'hilbert'). Defaults to 'wavelet'.
-    freq_of_interest : float, optional
-        Frequency of interest for the wavelet method. Required if method is 'wavelet'.
-    lowcut, highcut : float, optional
-        Cutoff frequencies for the Hilbert method. Required if method is 'hilbert'.
-    bandwidth : float, optional
-        Bandwidth parameter for the wavelet. Defaults to 2.0.
-        
+    - spike_times: Array of spike times 
+    - lfp_signal: Local field potential time series
+    - spike_fs: Sampling frequency in Hz of the spike times only needed if spikes times and lfp has different fs
+    - lfp_fs : Sampling frequency in Hz of the LFP
+    - method: 'wavelet' or 'hilbert' to choose the phase extraction method
+    - freq_of_interest: Desired frequency for wavelet phase extraction
+    - lowcut, highcut: Cutoff frequencies for bandpass filtering (Hilbert method)
+    - bandwidth: Bandwidth parameter for the wavelet
+    
     Returns:
-    -------
-    plv_over_time : 1D array
-        Array of PLV values calculated over each window.
-    times : 1D array
-        The center times of each window where the PLV was calculated.
+    - ppc1: Phase-Phase Coupling value
+    - spike_phases: Phases at spike times
     """
-    # Convert window and step size from seconds to samples
-    window_samples = int(window_size * fs)
-    step_samples = int(step_size * fs)
-    
-    # Initialize results
-    plv_over_time = []
-    times = []
-    
-    # Iterate over the signal with a sliding window
-    for start in range(0, len(x1) - window_samples + 1, step_samples):
-        end = start + window_samples
-        window_x1 = x1[start:end]
-        window_x2 = x2[start:end]
+    
+    if spike_fs == None:
+        spike_fs = lfp_fs
+    # Convert spike times to sample indices
+    spike_times_seconds = spike_times / spike_fs
+
+    # Then convert from seconds to samples at the new sampling rate
+    spike_indices = np.round(spike_times_seconds * lfp_fs).astype(int)
+    
+    # Filter indices to ensure they're within bounds of the LFP signal
+    valid_indices = [idx for idx in spike_indices if 0 <= idx < len(lfp_signal)]
+    if len(valid_indices) <= 1:
+        return 0, np.array([])
+    
+    # Extract phase using the specified method
+    if method == 'wavelet':
+        if freq_of_interest is None:
+            raise ValueError("freq_of_interest must be provided for the wavelet method.")
+        
+        # Apply CWT to extract phase at the frequency of interest
+        lfp_complex = wavelet_filter(x=lfp_signal, freq=freq_of_interest, fs=lfp_fs, bandwidth=bandwidth)
+        instantaneous_phase = np.angle(lfp_complex)
         
-        # Use the updated calculate_plv function within each window
-        plv = calculate_plv(x1=window_x1, x2=window_x2, fs=fs, 
-                            method=method, freq_of_interest=freq_of_interest, 
-                            lowcut=lowcut, highcut=highcut, bandwidth=bandwidth)
-        plv_over_time.append(plv)
+    elif method == 'hilbert':
+        if lowcut is None or highcut is None:
+            print("Lowcut and/or highcut were not defined, signal will not be filtered and will just take Hilbert transform for PPC1 calculation")
+            filtered_lfp = lfp_signal
+        else:
+            # Bandpass filter the signal
+            filtered_lfp = butter_bandpass_filter(lfp_signal, lowcut, highcut, lfp_fs)
         
-        # Store the time at the center of the window
-        center_time = (start + end) / 2 / fs
-        times.append(center_time)
+        # Get phase using the Hilbert transform
+        analytic_signal = signal.hilbert(filtered_lfp)
+        instantaneous_phase = np.angle(analytic_signal)
+        
+    else:
+        raise ValueError("Invalid method. Choose 'wavelet' or 'hilbert'.")
+    
+    # Get phases at spike times
+    spike_phases = instantaneous_phase[valid_indices]
     
-    return np.array(plv_over_time), np.array(times)
+    # Calculate PPC1
+    n = len(spike_phases)
+    
+    # Convert phases to unit vectors in the complex plane
+    unit_vectors = np.exp(1j * spike_phases)
+    
+    # Calculate the resultant vector
+    resultant_vector = np.sum(unit_vectors)
+    
+    # Plv is the squared length of the resultant vector divided by n²
+    plv = (np.abs(resultant_vector) ** 2) / (n ** 2)
+    
+    return plv
 
 
-def calculate_ppc1(spike_times, lfp_signal, fs, freq_range, window_size=0.5):
+def calculate_ppc(spike_times: np.ndarray = None, lfp_signal: np.ndarray = None, spike_fs: float = None,
+                  lfp_fs: float = None, method: str = 'hilbert', freq_of_interest: float = None,
+                  lowcut: float = None, highcut: float = None,
+                  bandwidth: float = 2.0) -> tuple:
     """
-    Calculate PPC1 metric between spike times and LFP signal using the vector dot product method.
+    Calculate Pairwise Phase Consistency (PPC) between spike times and LFP signal.
+    Based on https://www.sciencedirect.com/science/article/pii/S1053811910000959
     
     Parameters:
-    -----------
-    spike_times : array_like
-        Array of spike times in seconds
-    lfp_signal : array_like
-        Local field potential time series
-    fs : float
-        Sampling frequency of the LFP signal in Hz
-    freq_range : tuple
-        Frequency range (low, high) to filter the LFP signal in Hz
-    window_size : float, optional
-        Size of the window around each spike in seconds, default is 0.5s
+    - spike_times: Array of spike times 
+    - lfp_signal: Local field potential time series
+    - spike_fs: Sampling frequency in Hz of the spike times only needed if spikes times and lfp has different fs
+    - lfp_fs: Sampling frequency in Hz of the LFP
+    - method: 'wavelet' or 'hilbert' to choose the phase extraction method
+    - freq_of_interest: Desired frequency for wavelet phase extraction
+    - lowcut, highcut: Cutoff frequencies for bandpass filtering (Hilbert method)
+    - bandwidth: Bandwidth parameter for the wavelet
     
     Returns:
-    --------
-    ppc1 : float
-        PPC1 value
-    phases : array
-        Phases at spike times
+    - ppc: Pairwise Phase Consistency value
+    - spike_phases: Phases at spike times
     """
+    print("Note this method will a very long time if there are a lot of spikes. If there are a lot of spikes consider using the PPC2 method if speed is an issue")
+    if spike_fs is None:
+        spike_fs = lfp_fs
     # Convert spike times to sample indices
-    spike_indices = np.round(spike_times * fs).astype(int)
-    
-    # Filter LFP in the frequency band of interest
-    nyquist = fs / 2
-    b, a = signal.butter(3, [freq_range[0] / nyquist, freq_range[1] / nyquist], btype='band')
-    filtered_lfp = signal.filtfilt(b, a, lfp_signal)
+    spike_times_seconds = spike_times / spike_fs
+
+    # Then convert from seconds to samples at the new sampling rate
+    spike_indices = np.round(spike_times_seconds * lfp_fs).astype(int)
     
-    # Get analytic signal through Hilbert transform
-    analytic_signal = signal.hilbert(filtered_lfp)
+    # Filter indices to ensure they're within bounds of the LFP signal
+    valid_indices = [idx for idx in spike_indices if 0 <= idx < len(lfp_signal)]
+    if len(valid_indices) <= 1:
+        return 0, np.array([])
     
-    # Extract instantaneous phase
-    instantaneous_phase = np.angle(analytic_signal)
+    # Extract phase using the specified method
+    if method == 'wavelet':
+        if freq_of_interest is None:
+            raise ValueError("freq_of_interest must be provided for the wavelet method.")
+        
+        # Apply CWT to extract phase at the frequency of interest
+        lfp_complex = wavelet_filter(x=lfp_signal, freq=freq_of_interest, fs=lfp_fs, bandwidth=bandwidth)
+        instantaneous_phase = np.angle(lfp_complex)
+        
+    elif method == 'hilbert':
+        if lowcut is None or highcut is None:
+            print("Lowcut and/or highcut were not defined, signal will not be filtered and will just take Hilbert transform for PPC calculation")
+            filtered_lfp = lfp_signal
+        else:
+            # Bandpass filter the signal
+            filtered_lfp = butter_bandpass_filter(lfp_signal, lowcut, highcut, lfp_fs)
+        
+        # Get phase using the Hilbert transform
+        analytic_signal = signal.hilbert(filtered_lfp)
+        instantaneous_phase = np.angle(analytic_signal)
+        
+    else:
+        raise ValueError("Invalid method. Choose 'wavelet' or 'hilbert'.")
     
     # Get phases at spike times
-    spike_phases = []
-    for spike_idx in spike_indices:
-        if 0 <= spike_idx < len(instantaneous_phase):
-            spike_phases.append(instantaneous_phase[spike_idx])
+    spike_phases = instantaneous_phase[valid_indices]
+    
+    n_spikes = len(spike_phases)
+
+    # Calculate PPC (Pairwise Phase Consistency)
+    if n_spikes <= 1:
+        return 0, spike_phases
     
-    spike_phases = np.array(spike_phases)
+    # Explicit calculation of pairwise phase consistency
+    sum_cos_diff = 0.0
     
-    # Calculate PPC1
+    # # Σᵢ Σⱼ₍ᵢ₊₁₎ f(θᵢ, θⱼ)
+    # for i in range(n_spikes - 1):  # For each spike i
+    #     for j in range(i + 1, n_spikes):  # For each spike j > i
+    #         # Calculate the phase difference between spikes i and j
+    #         phase_diff = spike_phases[i] - spike_phases[j]
+            
+    #         #f(θᵢ, θⱼ) = cos(θᵢ)cos(θⱼ) + sin(θᵢ)sin(θⱼ) can become #f(θᵢ, θⱼ) = cos(θᵢ - θⱼ)
+    #         cos_diff = np.cos(phase_diff)
+            
+    #         # Add to the sum
+    #         sum_cos_diff += cos_diff
+    
+    # # Calculate PPC according to the equation
+    # # PPC = (2 / (N(N-1))) * Σᵢ Σⱼ₍ᵢ₊₁₎ f(θᵢ, θⱼ)
+    # ppc = ((2 / (n_spikes * (n_spikes - 1))) * sum_cos_diff)
+    
+    # same as above (i think) but with vectorized computation and memory fixes so it wont take forever to run.
+    i, j = np.triu_indices(n_spikes, k=1)
+    phase_diff = spike_phases[i] - spike_phases[j]
+    sum_cos_diff = np.sum(np.cos(phase_diff))
+    ppc = ((2 / (n_spikes * (n_spikes - 1))) * sum_cos_diff)
+    
+    return ppc
+
+    
+def calculate_ppc2(spike_times: np.ndarray = None, lfp_signal: np.ndarray = None, spike_fs: float = None,
+                  lfp_fs: float = None, method: str = 'hilbert', freq_of_interest: float = None,
+                  lowcut: float = None, highcut: float = None,
+                  bandwidth: float = 2.0) -> tuple:
+    """
+    # -----------------------------------------------------------------------------
+    # PPC2 Calculation (Vinck et al., 2010) 
+    # -----------------------------------------------------------------------------
+    # Equation(Original):
+    #   PPC = (2 / (n * (n - 1))) * sum(cos(φ_i - φ_j) for all i < j)
+    # Optimized Formula (Algebraically Equivalent):
+    #   PPC = (|sum(e^(i*φ_j))|^2 - n) / (n * (n - 1))
+    # -----------------------------------------------------------------------------
+        
+    Parameters:
+    - spike_times: Array of spike times 
+    - lfp_signal: Local field potential time series
+    - spike_fs: Sampling frequency in Hz of the spike times only needed if spikes times and lfp has different fs
+    - lfp_fs: Sampling frequency in Hz of the LFP
+    - method: 'wavelet' or 'hilbert' to choose the phase extraction method
+    - freq_of_interest: Desired frequency for wavelet phase extraction
+    - lowcut, highcut: Cutoff frequencies for bandpass filtering (Hilbert method)
+    - bandwidth: Bandwidth parameter for the wavelet
+    
+    Returns:
+    - ppc2: Pairwise Phase Consistency 2 value
+    - spike_phases: Phases at spike times
+    """
+    
+    if spike_fs is None:
+        spike_fs = lfp_fs
+    # Convert spike times to sample indices
+    spike_times_seconds = spike_times / spike_fs
+
+    # Then convert from seconds to samples at the new sampling rate
+    spike_indices = np.round(spike_times_seconds * lfp_fs).astype(int)
+    
+    # Filter indices to ensure they're within bounds of the LFP signal
+    valid_indices = [idx for idx in spike_indices if 0 <= idx < len(lfp_signal)]
+    if len(valid_indices) <= 1:
+        return 0, np.array([])
+    
+    # Extract phase using the specified method
+    if method == 'wavelet':
+        if freq_of_interest is None:
+            raise ValueError("freq_of_interest must be provided for the wavelet method.")
+        
+        # Apply CWT to extract phase at the frequency of interest
+        lfp_complex = wavelet_filter(x=lfp_signal, freq=freq_of_interest, fs=lfp_fs, bandwidth=bandwidth)
+        instantaneous_phase = np.angle(lfp_complex)
+        
+    elif method == 'hilbert':
+        if lowcut is None or highcut is None:
+            print("Lowcut and/or highcut were not defined, signal will not be filtered and will just take Hilbert transform for PPC2 calculation")
+            filtered_lfp = lfp_signal
+        else:
+            # Bandpass filter the signal
+            filtered_lfp = butter_bandpass_filter(lfp_signal, lowcut, highcut, lfp_fs)
+        
+        # Get phase using the Hilbert transform
+        analytic_signal = signal.hilbert(filtered_lfp)
+        instantaneous_phase = np.angle(analytic_signal)
+        
+    else:
+        raise ValueError("Invalid method. Choose 'wavelet' or 'hilbert'.")
+    
+    # Get phases at spike times
+    spike_phases = instantaneous_phase[valid_indices]
+    
+    # Calculate PPC2 according to Vinck et al. (2010), Equation 6
     n = len(spike_phases)
+    
     if n <= 1:
         return 0, spike_phases
     
@@ -463,7 +600,11 @@ def calculate_ppc1(spike_times, lfp_signal, fs, freq_range, window_size=0.5):
     # Calculate the resultant vector
     resultant_vector = np.sum(unit_vectors)
     
-    # PPC1 is the squared length of the resultant vector divided by n²
-    ppc1 = (np.abs(resultant_vector) ** 2) / (n ** 2)
+    # PPC2 = (|∑(e^(i*φ_j))|² - n) / (n * (n - 1))
+    ppc2 = (np.abs(resultant_vector)**2 - n) / (n * (n - 1))
+    
+    return ppc2
+
     
-    return ppc1, spike_phases
+
+

bmtool/bmplot.py

@@ -1012,6 +1012,8 @@ def plot_firing_rate_distribution(individual_stats: pd.DataFrame, groupby: Union
 
     return ax
   
+def plot_entrainment():
+    pass
     
 def plot_3d_positions(config=None, populations_list=None, group_by=None, title=None, save_file=None, subset=None):
     """

{bmtool-0.6.8.2.dist-info → bmtool-0.6.8.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bmtool
-Version: 0.6.8.2
+Version: 0.6.8.4
 Summary: BMTool
 Home-page: https://github.com/cyneuro/bmtool
 Download-URL: 

{bmtool-0.6.8.2.dist-info → bmtool-0.6.8.4.dist-info}/RECORD

@@ -1,7 +1,7 @@
 bmtool/SLURM.py,sha256=umHYGUX2HDlZr6Zo89wQekGrK9mZdAi0rBdCA7a--hE,19904
 bmtool/__init__.py,sha256=ZStTNkAJHJxG7Pwiy5UgCzC4KlhMS5pUNPtUJZVwL_Y,136
 bmtool/__main__.py,sha256=TmFkmDxjZ6250nYD4cgGhn-tbJeEm0u-EMz2ajAN9vE,650
-bmtool/bmplot.py,sha256=YoI7StM9qeZqyRfFX4M7oUGFz50tXTDOMIUqjYozj9s,54066
+bmtool/bmplot.py,sha256=ymyrNBctZoglsNA28733mXzM_l4b_3JIchXkQa2V2XE,54099
 bmtool/connectors.py,sha256=hWkUUcJ4tmas8NDOFPPjQT-TgTlPcpjuZsYyAW2WkPA,72242
 bmtool/graphs.py,sha256=K8BiughRUeXFVvAgo8UzrwpSClIVg7UfmIcvtEsEsk0,6020
 bmtool/manage.py,sha256=_lCU0qBQZ4jSxjzAJUd09JEetb--cud7KZgxQFbLGSY,657
@@ -9,7 +9,7 @@ bmtool/plot_commands.py,sha256=Tqujyf0c0u8olhiHOMwgUSJXIIE1hgjv6otb25G9cA0,12298
 bmtool/singlecell.py,sha256=XZAT_2n44EhwqVLnk3qur9aO7oJ-10axJZfwPBslM88,27219
 bmtool/synapses.py,sha256=gIkfLhKDG2dHHCVJJoKuQrFn_Qut843bfk_-s97wu6c,54553
 bmtool/analysis/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-bmtool/analysis/lfp.py,sha256=DXZvxYMVjFiCJS_IySQIUrpBQjdNuHVL8A7rxrHB7xo,16900
+bmtool/analysis/lfp.py,sha256=Ei-l9aA13IOsdOEjmkqmdthKgPkEPnbiHdJ_-TB2twQ,23771
 bmtool/analysis/spikes.py,sha256=qqJ4zD8xfvSwltlWm_Bhicdngzl6uBqH6Kn5wOMKRc8,11507
 bmtool/debug/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 bmtool/debug/commands.py,sha256=AwtcR7BUUheM0NxvU1Nu234zCdpobhJv5noX8x5K2vY,583
@@ -19,9 +19,9 @@ bmtool/util/commands.py,sha256=zJF-fiLk0b8LyzHDfvewUyS7iumOxVnj33IkJDzux4M,64396
 bmtool/util/util.py,sha256=00vOAwTVIifCqouBoFoT0lBashl4fCalrk8fhg_Uq4c,56654
 bmtool/util/neuron/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 bmtool/util/neuron/celltuner.py,sha256=xSRpRN6DhPFz4q5buq_W8UmsD7BbUrkzYBEbKVloYss,87194
-bmtool-0.6.8.2.dist-info/licenses/LICENSE,sha256=qrXg2jj6kz5d0EnN11hllcQt2fcWVNumx0xNbV05nyM,1068
-bmtool-0.6.8.2.dist-info/METADATA,sha256=pE_Li9uoVYndKge-Gcm7gawxW71VbGfFhEL1lT0-kB8,20431
-bmtool-0.6.8.2.dist-info/WHEEL,sha256=1tXe9gY0PYatrMPMDd6jXqjfpz_B-Wqm32CPfRC58XU,91
-bmtool-0.6.8.2.dist-info/entry_points.txt,sha256=0-BHZ6nUnh0twWw9SXNTiRmKjDnb1VO2DfG_-oprhAc,45
-bmtool-0.6.8.2.dist-info/top_level.txt,sha256=gpd2Sj-L9tWbuJEd5E8C8S8XkNm5yUE76klUYcM-eWM,7
-bmtool-0.6.8.2.dist-info/RECORD,,
+bmtool-0.6.8.4.dist-info/licenses/LICENSE,sha256=qrXg2jj6kz5d0EnN11hllcQt2fcWVNumx0xNbV05nyM,1068
+bmtool-0.6.8.4.dist-info/METADATA,sha256=J--vvrEONRRsOc3YTxEmdKd9AAjJDi_zErm6QtlR6W0,20431
+bmtool-0.6.8.4.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
+bmtool-0.6.8.4.dist-info/entry_points.txt,sha256=0-BHZ6nUnh0twWw9SXNTiRmKjDnb1VO2DfG_-oprhAc,45
+bmtool-0.6.8.4.dist-info/top_level.txt,sha256=gpd2Sj-L9tWbuJEd5E8C8S8XkNm5yUE76klUYcM-eWM,7
+bmtool-0.6.8.4.dist-info/RECORD,,

{bmtool-0.6.8.2.dist-info → bmtool-0.6.8.4.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (77.0.3)
+Generator: setuptools (78.1.0)
 Root-Is-Purelib: true
 Tag: py3-none-any