fmatoolbox 0.1.0__tar.gz → 0.1.2__tar.gz

{fmatoolbox-0.1.0/src/fmatoolbox.egg-info → fmatoolbox-0.1.2}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: fmatoolbox
-Version: 0.1.0
+Version: 0.1.2
 Summary: Python port of FMAToolbox
 Author: Pietro Bozzo
 License-Expression: GPL-3.0-or-later
 Project-URL: Homepage, https://github.com/pietro-bozzo/FMAToolboxPython
 Project-URL: Repository, https://github.com/pietro-bozzo/FMAToolboxPython
 Project-URL: Issues, https://github.com/pietro-bozzo/FMAToolboxPython/issues
-Requires-Python: >=3.9
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy

{fmatoolbox-0.1.0 → fmatoolbox-0.1.2}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fmatoolbox"
-version = "0.1.0"
+version = "0.1.2"
 description = "Python port of FMAToolbox"
 authors = [{name = "Pietro Bozzo"}]
 readme = "README.md"
 license = "GPL-3.0-or-later"
 
-requires-python = ">=3.9"
+requires-python = ">=3.11"
 dependencies = [
     "numpy",
     "scipy",

{fmatoolbox-0.1.0 → fmatoolbox-0.1.2}/src/fmatoolbox/analysis.py

@@ -7,9 +7,86 @@ import sklearn.decomposition as skdc
 import skimage.filters as skif
 import joblib
 import statsmodels.stats.multitest
+import warnings
 from typing import Callable
 
 
+def istantaneousRate(samples, start:float=None, stop:float=None, bin:float=None, step:int=None, smooth:float=None, g_range:tuple[int,int]=None):
+    '''
+    estimate the istantaneous rate of a point process from a realization of its time stamps, e.g., the firing rate from spike times
+
+    arguments:
+        samples     (n,:) float, every row is either [sample time (s)] or [sample time (s), process id]; if 1d, interpreted as (n,1)
+        start       float = min(samples[:,0]) s, time to start count at
+        stop        float = max(samples[:,0]) s, time to stop count at
+        bin         float = 0.05 s, time bin to count samples
+        step        int = 1, rate is computed in windows of length 'bin' and overlap 'bin' / 'step', default is no overlap
+        smooth      float = None, gaussian kernel std to smooth rate over time
+        g_range     (2) int, range of groups (process ids) to consider, default is [min(samples[:,1]), max(samples[:,1])]
+                    (boundaries included, only for 2-columns 'samples')
+
+    output:
+        rate        (:,g+1) float, every row is [time stamp, rates for g processes], g is 1 if 'samples' has just one column
+    '''
+
+    # validate input
+    samples = np.asarray(samples)
+    if bin is None: bin = 0.05
+    if step is None: step = 1
+    if step % 1 or step == 0:
+        raise ValueError("'step' must be a non-zero integer")
+
+    groups = []
+    if samples.ndim == 1:
+        times = samples
+    elif samples.shape[1] == 1:
+        times = samples.reshape(-1)
+    else:
+        times = samples[:,0]
+        groups = samples[:,1]
+        if g_range is None:
+            g_range = np.unique(groups).astype(int)[[0,-1]]
+        else:
+            g_range = np.array(g_range,dtype=int)
+    if start is None: start = times.min()
+    if stop is None: stop = times.max()
+
+    def histogramVectorized(x,nbins):
+        a, b = x.shape
+        # assign bin indeces
+        bin_idx = (x / bin).astype(int) # bin_idx = 0, bin_idx = n_bins + 1 after 'stop'
+        bin_idx = np.clip(bin_idx,0,nbins-1)
+        offset = np.arange(b)[None,:] * nbins
+        hist = np.bincount((bin_idx+offset).ravel(), minlength=nbins*b).reshape(b,nbins).T
+        return hist
+
+    # repeat 'times' by 'step' times
+    times = np.tile(times[:,None],(1,step)) # (times, step)
+    # shift by: 'start', 'bin' to add bin before 'start', overlap for each repetition
+    times = times - start + bin - np.arange(step)*(bin/step)
+    # parameters
+    n_bins = int((stop + bin - start) // bin)
+    n_bins2 = n_bins + 2 # add two bins: first for 'samples' before 'start', last for 'samples' after 'stop'
+    if len(groups) == 0:
+        hist = histogramVectorized(times,n_bins2)
+        rate = (hist[1:-1] / bin).ravel() # remove data outside [start, stop], convert to rate (Hz), flatten
+    else:
+        rate = []
+        for g in range(g_range[0],g_range[-1] + 1):
+            hist = histogramVectorized(times[groups==g],n_bins2)
+            rate.append((hist[1:-1]).ravel())
+        rate = np.array(rate).T / bin
+
+    # make time axis
+    t = bin/step/2 + np.linspace(0,(n_bins-1)*bin,n_bins*step)
+
+    # apply smoothing
+    if smooth is not None:
+        firing_rate = sp.ndimage.gaussian_filter(firing_rate,smooth,axes=0)
+
+    return np.column_stack((t,rate))
+
+
 def firingRate(spikes, start:float=None, stop:float=None, bin_size:float=None, step:int=None, smooth:float=None, u_range:tuple[int,int]=None):
     # estimate istantaneous firing rate from spike times
     #
@@ -26,6 +103,8 @@ def firingRate(spikes, start:float=None, stop:float=None, bin_size:float=None, s
     # output:
     #     firing_rate    (:,m+1) float, every row is [time stamp, firing rates for m units], m is 1 if spikes has just one column
 
+    warnings.warn("firingRate is deprecated, use istantaneousRate instead!", DeprecationWarning)
+
     # validate input
     spikes = np.asarray(spikes)
     if bin_size is None: bin_size = 0.05
@@ -343,41 +422,35 @@ def reactivationStrength(raster, templates, threshold:float=5):
 
 # --- statistics functions ---
 
-def MCpValue(surrogate,real,alternative='two-sided'):
-    """
-    Compute Monte Carlo p-values comparing real statistics to surrogate distributions
-
-    Parameters
-    ----------
-    surrogate : array_like, shape (n_surrogates, n_features)
-        surrogate statistics
-    real : array_like, shape (n_features,)
-        observed statistics
-    alternative : {"two-sided", "greater", "less"}
-        direction of the test
-
-    Returns
-    -------
-    pvals : ndarray, shape (n_features,)
-        Monte Carlo p-values
-    """
+def MCpValue(surrogate,observed,alternative='two-sided'):
+    '''
+    compute Monte Carlo p-values comparing observed statistics to surrogate distributions
+
+    arguments:
+        surrogate      (s,f) float, surrogate statistics; s: # surrogates, f: # features
+        observed       (f,) float, observed statistics
+        alternative    str = {"two-sided", "greater", "less"}, test direction
+
+    output:
+        pvals          (f,) float, Monte Carlo p-values
+    '''
 
     surrogate = np.asarray(surrogate)
-    real = np.asarray(real).ravel()
+    observed = np.asarray(observed).ravel()
     if surrogate.ndim == 1:
         surrogate = surrogate.reshape((-1,1))
-    if surrogate.shape[1] != real.shape[0]:
-        raise ValueError("real must have one element for every column of surrogates")
+    if surrogate.shape[1] != observed.shape[0]:
+        raise ValueError("'observed' must have one element for every column of 'surrogates'")
     
     if alternative == "greater":
-        count = np.sum(surrogate >= real, axis=0)
+        count = np.sum(surrogate >= observed, axis=0)
 
     elif alternative == "less":
-        count = np.sum(surrogate <= real, axis=0)
+        count = np.sum(surrogate <= observed, axis=0)
 
     elif alternative == "two-sided":
-        greater = np.sum(surrogate >= real, axis=0)
-        less = np.sum(surrogate <= real, axis=0)
+        greater = np.sum(surrogate >= observed, axis=0)
+        less = np.sum(surrogate <= observed, axis=0)
         count = 2 * np.minimum(greater, less)
 
     else:
@@ -388,26 +461,19 @@ def MCpValue(surrogate,real,alternative='two-sided'):
     return np.minimum(pvals, 1.0)
 
 
-def holmBonferroni(pvals,alpha=0.05,return_reject=False):
-    """
+def holmBonferroni(pvals, alpha:float=0.05, return_reject:bool=False):
+    '''
     Holm-Bonferroni correction for multiple tests
 
-    Parameters
-    ----------
-    pvals : array-like 
-        array of p-values, NaNs are ignored in the correction procedure and propagated in output
-    alpha : float = 0.05
-        significance level
-    return_reject : bool = False
-        whether to also return rejection decisions
-
-    Returns
-    -------
-    corrected : ndarray
-        adjusted p-values, preserves input shape
-    reject : ndarray of bool, optional
-        true for hypothesis that can be rejected for given alpha, preserves input shape
-    """
+    arguments:
+        pvals            (n,) float, p values, NaNs are ignored in the correction procedure and propagated in output
+        alpha            float = 0.05, significance level, must be in [0,1]
+        return_reject    bool = False, return also rejection decisions
+
+    output:
+        corrected        (n,) float, adjusted p values
+        reject           (n,) bool, optional, true for hypothesis that can be rejected
+    '''
 
     pvals = np.asarray(pvals)
     original_shape = pvals.shape
@@ -430,45 +496,53 @@ def holmBonferroni(pvals,alpha=0.05,return_reject=False):
     return corrected
 
 
-def maxStatisticTest(data, surrogate, statistic=None, alpha:float=0.05, alternative:str='two-sided'):
-    # conduct a max statistic test over time
-    #
-    # arguments:
-    #     data (n sessions, n times)
-    #     surrogate (n session, n times, n surrogates)
-    
+def maxStatisticTest(data, surrogate, statistic=None, group=None, alpha:float=0.05, alternative:str='two-sided'):
+    '''
+    conduct a max statistic test over time, assessing in which time points the null hypothesis about a statistic across sessions can be rejected
+
+    arguments:
+        data           (sessions, times) float
+        surrogate      (sessions, times, surrogates) float
+        group          (sessions,) int, grouping variable used to aggregate sessions, the statistic is computed per group and then again over groups
+        alpha          float = 0.05, significance level, must be in [0,1]
+        alternative    str = {'two-sided','grater','less'}, test direction, defines the null hypothesis
+    '''
+
     data = np.array(data,ndmin=2)
-    surrogate = np.array(surrogate,ndmin=2)
+    surrogate = np.array(surrogate,ndmin=3)
     if data.shape[:2] != surrogate.shape[:2]:
-        raise ValueError("'data' and 'surrogate' must have the same first two dimensions")
-    if surrogate.ndim != 3:
-        raise ValueError("'surrogate' must have dimensions (sessions, times, surrogates)")
+        raise ValueError("'data' and 'surrogate' must have the same first two dimensions (sessions, times)")
     if statistic is None:
         statistic = lambda x : np.nanmean(x,axis=0)
     n_times = data.shape[1]
     n_surrogates = surrogate.shape[2]
 
     # statistic for real and surrogate data
-    s_real = statistic(data) # (n_times,)
-    s_surrogate = np.zeros((n_times,n_surrogates)) # (n_times,n_surrogates)
-    for i in range(n_surrogates):
-        s_surrogate[:,i] = statistic(surrogate[:,:,i])
+    if group is None:
+        s_real = statistic(data) # (times,)
+        s_surrogate = statistic(surrogate) # (times, surrogates)
+    else:
+        unique_groups = np.unique(group)
+        s_real = [statistic(data[group==g]) for g in unique_groups]
+        s_real = statistic(s_real)
+        s_surrogate = [statistic(surrogate[group==g]) for g in unique_groups]
+        s_surrogate = statistic(s_surrogate)
 
     # p-values per time point
     if alternative == 'greater':
-        s_surrogate = np.min(s_surrogate,axis=0) # (n_surrogates,)
-        p = MCpValue(np.tile(s_surrogate,(n_times,1)).T,s_real,alternative) # (n_times,)
+        s_surrogate = np.min(s_surrogate,axis=0) # (surrogates,)
+        p = MCpValue(np.tile(s_surrogate,(n_times,1)).T,s_real,alternative) # (times,)
     elif alternative == 'less':
         s_surrogate = np.max(s_surrogate,axis=0)
         p = MCpValue(np.tile(s_surrogate,(n_times,1)).T,s_real,alternative)
     elif alternative == 'two-sided':
         # standardize statistic to ensure proper two-tailed test
-        mu = np.mean(s_surrogate,axis=1) # (n_times,)
+        mu = np.mean(s_surrogate,axis=1) # (times,)
         sigma = np.std(s_surrogate,axis=1,ddof=1)
         s_real = np.abs((s_real - mu) / sigma) # abs(z-score( ))
         s_surrogate = (s_surrogate - mu.reshape(-1,1)) / sigma.reshape(-1,1)
-        s_surrogate = np.max(np.abs(s_surrogate),axis=0) # max_t(abs(z-score( ))), i.e., (n_surrogates,)
-        p = MCpValue(np.tile(s_surrogate,(n_times,1)).T,s_real,"greater")
+        s_surrogate = np.max(np.abs(s_surrogate),axis=0) # max_t(abs(z-score( ))), i.e., (surrogates,)
+        p = MCpValue(np.tile(s_surrogate,(n_times,1)).T,s_real,'greater')
     else:
         raise ValueError("'alternative' must be 'two-sided', 'greater' or 'less'")
 

{fmatoolbox-0.1.0 → fmatoolbox-0.1.2}/src/fmatoolbox/general.py

@@ -16,10 +16,7 @@ def consolidateIntervals(intervals, epsilon:float=0, duration:float=0):
     # output:
     #     intervals    (:,2) float, consolidated intervals (s)
 
-    try:
-        intervals = np.array(intervals,dtype=float,ndmin=2)
-    except Exception as e:
-        raise TypeError("'intervals' must be convertible to a NumPy array") from e
+    intervals = np.array(intervals,dtype=float,ndmin=2)
     if intervals.shape[1] != 2:
         raise ValueError("'intervals' must be a (n,2) array")
     if (intervals[:,0] > intervals[:,1]).any():
@@ -143,7 +140,7 @@ def intersectIntervals(intervals):
     return intersection
 
 
-def restrict(samples,intervals,shift=False,s_ind=False,i_ind=False):
+def restrict(samples, intervals, shift:bool=False, s_ind:bool=False, i_ind:bool=False):
     # keep only samples falling in a set of intervals
     #
     # arguments:
@@ -172,9 +169,9 @@ def restrict(samples,intervals,shift=False,s_ind=False,i_ind=False):
 
     # assign and index to each sample time, only odd indeces belong to intervals
     ind = np.digitize(samples[:,0],intervals.flatten())
-    is_ok = (ind % 2).astype(bool) # is_ok[i] is 1 iff samples[i] must be kept
-    samples = samples[is_ok]
-    Ii = (ind[is_ok] - 1) // 2 # Ii[j] indexes interval that contains samples[is_ok][j]
+    Is = (ind % 2).astype(bool) # Is[i] is 1 iff samples[i] must be kept
+    samples = samples[Is]
+    Ii = (ind[Is] - 1) // 2 # Ii[j] indexes interval that contains samples[Is][j]
 
     if shift:
         # cumulative shifts: distances between intervals
@@ -188,16 +185,16 @@ def restrict(samples,intervals,shift=False,s_ind=False,i_ind=False):
         samples = samples.reshape(-1)
 
     if not s_ind and not i_ind:
-        return samples   
-    out = (samples, is_ok, Ii) # prepare tuple to return requested outputs
+        return samples
+    out = (samples, Is, Ii) # prepare tuple to return requested outputs
     return out[:2+i_ind:2-s_ind]
 
 
-def unshift(samples,intervals):
+def unshift(samples, intervals):
     # perform the opposite operation of option 'shift' in restrict
     #
     # arguments:
-    #     samples      (:,:,) float, rows are [time stamp, value1, value2, ...]; if 1d, reshaped to (:,1)
+    #     samples      (:,:) float, rows are [time stamp, value1, value2, ...]; if 1d, reshaped to (:,1)
     #     intervals    (:,2) float, rows are [start, stop] times (s) for an interval, previously used to shift `samples`
 
     samples = np.asarray(samples,dtype=float)
@@ -219,56 +216,106 @@ def unshift(samples,intervals):
     return samples
 
 
-def shuffleEvents(events,offset=0,intervals=None):
-    # shuffle events preserving their inter-event interval
-    #
-    # arguments:
-    #     events       (n,) or (:,n) float, every row is either [event time] or [event time, event id]; if 1d, interpreted as (:,1)
-    #     offset       float = 0 s, reference time, necessary when events start at a time != 0, e.g., for a portion of a recording
-    #                  in [1000 s, 3000 s]; must be smaller than first event time, ignored if 'intervals' are provided
-    #     intervals    (:,2) float = None, rows are [start, stop] times of intervals; if 1d, reshaped to (1,2)
-    #
-    # output:
-    #     shuffled     (n,) or (:,n) float, shuffled events
-
+def shuffleEvents(events, offset:float=None, n:int=None, group=None, fast:bool=None, intervals=None):
+    '''
+    shuffle point-process events (i.e., time stamps) preserving their inter-event interval
+
+    arguments:
+        events       (s,) | (s,f) float, samples to shuffle; m: # samples, f: # features, if 2d, first column contains time stamps
+        offset       float = 0 s, reference time, necessary when events start at a time != 0, e.g., for a portion of a recording
+                     in [1000 s, 3000 s]; must be smaller than first event time, ignored if 'intervals' are provided
+        n            int = 1, number of independent repetitions of the shuffling procedure, changes output shape
+        group        (s,) int, grouping variable to shuffle events separately per group, adds output 'group'
+        fast         bool = False, if True, 'events' must be time sorted (to save computation time)
+        intervals    (:,2) float = None, rows are [start, stop] times of intervals to restrict shuffle into; if 1d, reshaped to (1,2)
+
+    output:
+        shuffled     (:,:,) float, shuffled events, shape depends on 'n':
+                     - same as 'events' if 'n' = 1
+                     - (s,f,n), i.e., with an extra dimension for 'n' shuffling repetitions, otherwise
+        group        (:,) int, optional, grouping variable for shuffled events, only returned if 'group' is not None, shape depends on 'n':
+                     - (s,) if 'n' = 1
+                     - (s,n), otherwise
+    '''
+
+    # default values
     events = np.asarray(events)
+    n_dim = events.ndim
+    if offset is None: offset = 0
+    if n is None: n = 1
+    if group is not None: group = np.asarray(group,dtype=int)
     if intervals is not None:
-        intervals = np.array(intervals,ndmin=2)
-        n_dim = events.ndim
-        events = restrict(events,intervals,shift=True)
+        events, valid = restrict(events,intervals,shift=True,s_ind=True)
         offset = 0
-    
-    # 1. single-column input (only timestamps)
-    if events.ndim == 1 or events.shape[1] == 1:
-
-        # compute and shuffle inter-event intervals
-        inter_event_intervals = np.diff(events,prepend=offset,axis=0)
-        rng = np.random.default_rng()
-        inter_event_intervals = rng.permutation(inter_event_intervals)
-        shuffled = offset + np.cumsum(inter_event_intervals,axis=0)
-
-    # 2: multiple columns (also grouping ids)
+        if group is not None:
+            group = group[valid]
+
+    # zero-repetitions case
+    if n == 0:
+        if group is not None:
+            return np.zeros(events.shape+(0,)), np.zeros((events.shape[0],0))
+        return np.zeros(events.shape+(0,))
+
+    # make 'events' 3d by appending singleton dimensions
+    events = events.reshape(*events.shape, *(1,) * (3 - n_dim)) # (events, features, 1)
+
+    # sort by time
+    if not fast:
+        order = events[:,0,0].argsort(axis=0)
+        events = events[order]
+        if group is not None:
+            group = group[order]
+
+    # repeat events 'n' times
+    events = np.tile(events,(1,1,n)) # (events, features, shuffle repetitions)
+
+    # core f to shuffle events of a group
+    rng = np.random.default_rng()
+    def shuffleGroup(e):
+        # shuffle inter-event intervals (IEI)
+        iei = np.diff(e[:,0,:],prepend=offset,axis=0)
+        iei_shape = iei.shape
+        permutation_idx = np.argsort(rng.random(iei_shape),axis=0)
+        iei = iei[permutation_idx,np.arange(iei_shape[1])]
+        # reconstruct shuffled samples
+        shuffled = offset + np.cumsum(iei,axis=0) # shuffled times (events, shuffle repetitions)
+        features = e[permutation_idx[:,None,:], np.arange(1,e.shape[1])[None,:,None], np.arange(iei_shape[1])[None,None,:]]
+        shuffled = np.concatenate((shuffled[:,None],features),axis=1) # append shuffled features
+        return shuffled
+
+    # perform shuffling
+    if group is None:
+        shuffled = shuffleGroup(events)
     else:
-
-        times = events[:,0].reshape((-1,1))
-        ids = events[:,1:]
-        unique_ids = np.unique(ids,axis=0)
-
         shuffled = []
-        for i in unique_ids:
-            # compute and shuffle inter-event intervals per group
-            inter_event_intervals = np.diff(times[(ids==i).all(1)],axis=0,prepend=offset)
-            inter_event_intervals = np.random.permutation(inter_event_intervals)
-            shuffled.append(np.concatenate((offset+np.cumsum(inter_event_intervals,axis=0),np.repeat(i.reshape((1,-1)),len(inter_event_intervals),axis=0)),axis=1))
-
+        unique_groups, g_count = np.unique(group,return_counts=True)
+        for g in unique_groups:
+            shuffled.append(shuffleGroup(events[group==g]))
         # sort by time
-        shuffled = np.concatenate(shuffled)
-        shuffled = shuffled[shuffled[:,0].argsort()]
-
+        shuffled = np.concatenate(shuffled,axis=0)
+        order = shuffled[:,0,:].argsort(axis=0)
+        shuffled = shuffled[order[:,None,:], np.arange(shuffled.shape[1])[None,:,None], np.arange(shuffled.shape[2])[None,None,:]]
+        # build 'group' for output
+        group = np.repeat(unique_groups,g_count) # use unique output to sort
+        group = group[order] # sort as 'shuffled'
+
+    # unshift events back into intervals
     if intervals is not None:
-        shuffled = unshift(shuffled,intervals)
-        if n_dim == 1:
-            shuffled = shuffled.ravel()
+        for i in range(n):
+            shuffled[:,:,i] = unshift(shuffled[:,:,i],intervals)
+
+    # restore shape
+    if n_dim == 1 and n == 1:
+        shuffled = shuffled.ravel()
+    elif n == 1:
+        shuffled = shuffled[:,:,0]
+
+    if group is not None:
+        if n_dim == 1 and n == 1:
+            group = group.ravel()
+        elif n == 1:
+            group = group[:,0]
+        return shuffled, group
 
     return shuffled
 
@@ -315,5 +362,7 @@ def subtractIntervals(a,b):
     c[new_even_ind] = a[even_ind]
     # return as interval set
     c = c.reshape((c.shape[0]//2,2))
+    # remove remaining empty intervals
+    c = c[(np.diff(c)!=0).ravel(),:]
 
     return c

{fmatoolbox-0.1.0 → fmatoolbox-0.1.2}/src/fmatoolbox/plotting.py

@@ -12,7 +12,7 @@ from collections.abc import Iterable
 from typing import Literal, Callable
 
 
-def adjustAxes(axs:Iterable[mpla.Axes], format:Literal['paper','poster']='paper'):
+def adjustAxes(axs:mpla.Axes|Iterable[mpla.Axes], format:Literal['paper','poster']='paper'):
     # adjust axes properties to emprove figure appearance
     #
     # arguments:
@@ -31,11 +31,11 @@ def adjustAxes(axs:Iterable[mpla.Axes], format:Literal['paper','poster']='paper'
 
     for ax in axs:
         
-        # remove upper and right borders
-        ax.spines[['right','top']].set_visible(False)
+        # remove upper and right borders in catesian axis
+        [ax.spines[spine].set_visible(False) for spine in ['right','top'] if spine in ax.spines]
 
         # adjust thickness and font size
-        ax.spines[['bottom','left']].set_linewidth(lw)
+        [ax.spines[spine].set_linewidth(lw) for spine in ['bottom','left','polar'] if spine in ax.spines]
         ax.tick_params(width=axw,labelsize=axtick)
         ax.xaxis.label.set_fontsize(axfont)
         ax.yaxis.label.set_fontsize(axfont)
@@ -43,7 +43,7 @@ def adjustAxes(axs:Iterable[mpla.Axes], format:Literal['paper','poster']='paper'
     return
 
 
-def makeFigure(title:str=None, n:tuple[int,int]=[1,1], size:tuple[float,float]=[20,10], projection=None, format:Literal['paper','poster']='paper'):
+def makeFigure(title:str=None, n:tuple[int,int]=[1,1], size:tuple[float,float]=[20,10], projection:str=None, format:Literal['paper','poster']='paper'):
     # make a figure
     #
     # arguments:
@@ -72,7 +72,7 @@ def makeFigure(title:str=None, n:tuple[int,int]=[1,1], size:tuple[float,float]=[
     return fig, axs
 
 
-def setProp(axs:Iterable[mpla.Axes], xlabelcolor:dict[int,mplt.ColorType]=None, xtickvisible:dict[int,bool]=None, **kwargs):
+def setProp(axs:mpla.Axes|Iterable[mpla.Axes], xlabelcolor:dict[int,mplt.ColorType]=None, xtickvisible:dict[int,bool]=None, **kwargs):
     # set multiple axes properties at once
     #
     # arguments:
@@ -104,7 +104,7 @@ def setProp(axs:Iterable[mpla.Axes], xlabelcolor:dict[int,mplt.ColorType]=None,
     return
 
 
-def saveFigure(fig,fname,format):
+def saveFigure(fig, fname:str, format:str):
 
     # promote single format to iterable
     if isinstance(format,str):
@@ -115,7 +115,7 @@ def saveFigure(fig,fname,format):
     return
 
 
-def plotXY(data,start=None,stop=None,color=None,label=None,ax=None):
+def plotXY(data, start=None, stop=None, color:mplt.ColorType=None, label=None, ax:mpla.Axes=None):
     # plot columns of 'data', interpreting the first as the x axis and all others as y values
 
     data = np.array(data, ndmin=2)
@@ -141,23 +141,26 @@ def plotXY(data,start=None,stop=None,color=None,label=None,ax=None):
     return
 
 
-def plotColorMap(data: npt.NDArray[np.floating], vmin: float = None, vmax: float = None, zscore = None, sortby = None, sortax: int = 0,
-                 xzoom: float = None, yzoom: float = None, x = None, y = None, aspect: float = 3/4, ax = None):
-    # plot a 2D array as a colormap with optional normalization, sorting, and resampling
-    #
-    # arguments:
-    #     data            (n,m) float, data to visualize, rows correspond to first dimension
-    #     vmin, vmax      float = None, lower / upper bound of the colormap, if None uses autoscale
-    #     zscore          int | 'all' = None, if int, specifies axis along which to z-score `data`; if 'all', compute z-score over whole array,
-    #                     if None, no normalization is applied
-    #     sortby          callable | 'peak' = None, optional method used to sort `data` along `sortax` (after optional z-scoring), either:
-    #                     - 'peak', sort rows or columns by the index of their maximum value along the opposite axis.
-    #                     - callable, must have signature ``f(data) -> array_like`` and return a 1D array used to sort data along `sortax`
-    #     sortax          int = 0, axis along which sorting is performed
-    #     xzoom, yzoom    float = None, optional horizontal / vertical resampling factor passed to ``scipy.ndimage.zoom`` (after sorting)
-    #     x, y            (:,) float, coordinates corresponding to columns and rows of `data`, defaults are range(m) and range(n)
-    #     aspect          float = 3/4, image aspect ratio
-    #     ax              matplotlib.axes.Axes = matplotlib.pyplot.gca(), axes to plot in
+def plotColorMap(data:npt.NDArray[np.floating], vmin:float=None, vmax:float=None, zscore=None, sortby:npt.NDArray[np.floating]|Callable|str=None, sortax:int=0,
+                 xzoom:float=None, yzoom:float=None, x=None, y=None, aspect:float=3/4, ax:mpla.Axes=None):
+    '''
+    plot a 2D array as a colormap with optional normalization, sorting, and resampling
+
+    arguments:
+        data            (n,m) float, data to visualize, rows correspond to first dimension
+        vmin, vmax      float = None, lower / upper bound of the colormap, if None uses autoscale
+        zscore          int | 'all' = None, if int, specifies axis along which to z-score `data`; if 'all', compute z-score over whole array,
+                        if None, no normalization is applied
+        sortby          (:,) int | callable | 'peak' = None, optional method used to sort `data` along `sortax` (after optional z-scoring), either:
+                        - 'peak', sort rows or columns by the index of their maximum value along the opposite axis
+                        - (:,) int, array of indeces to sort data along `sortax`
+                        - callable, must have signature ``f(data) -> array_like`` and return a 1D array used to sort data along `sortax`
+        sortax          int = 0, axis along which sorting is performed
+        xzoom, yzoom    float = None, optional horizontal / vertical resampling factor passed to ``scipy.ndimage.zoom`` (after sorting)
+        x, y            (:,) float, coordinates corresponding to columns and rows of `data`, defaults are range(m) and range(n)
+        aspect          float = 3/4, image aspect ratio
+        ax              matplotlib.axes.Axes = matplotlib.pyplot.gca(), axes to plot in
+    '''
 
     # store original shape in case data neds to be zoomed
     n_y, n_x = data.shape
@@ -165,12 +168,15 @@ def plotColorMap(data: npt.NDArray[np.floating], vmin: float = None, vmax: float
     if zscore is not None:
         if zscore == 'all':
             zscore = None
-        data = spst.zscore(data,axis=zscore)
+        data = spst.zscore(data,axis=zscore,nan_policy='omit')
 
     if sortby is not None:
-        if sortby == 'peak':
+        if isinstance(sortby,str) and sortby == 'peak':
             sortby = lambda x : np.argsort(np.argmax(x,1-sortax))
-        sort_idx = sortby(data)
+        elif callable(sortby):
+            sort_idx = sortby(data)
+        else:
+            sort_idx = sortby
         data = data[sort_idx,:] if sortax == 0 else data[:,sort_idx]
 
     if xzoom is not None or yzoom is not None:
@@ -197,21 +203,26 @@ def plotColorMap(data: npt.NDArray[np.floating], vmin: float = None, vmax: float
     return im
 
 
-def semPlot(x, y, ci:Callable=None, zscore:bool|int=None, color=None, mode:Literal['area','error']='area', alpha:float=0.5, label:str=None, lprop:dict=None, aprop:dict=None, ax:mpla.Axes=None):
-    # plot mean +/- confidence intervals of matrix data
-    #
-    # arguments:
-    #     x         (n) float, x coordinates
-    #     y         (:,n) float, data to plot, each column corresponds to a value of x
-    #     ci        callable, used to compute confidence intervals for every column of y, must have signature:  low, high = ci(y)
-    #     zscore    bool = False | int, if True (or 1), z-score w.r.t. average of y, if 2, z-score each row of y independently
-    #     color     color = None
-    #     mode      str = 'area' | 'error', plot 'ci' either as a shaded area or as error bars
-    #     alpha     float = 0.5, shaded area transparency value (only for 'area' mode)
-    #     label     str = None, legend label for line
-    #     lprop     dict = {}, keyword arguments passed to matplotlib.pyplot.plot
-    #     aprop     dict = {}, keyword arguments passed to matplotlib.pyplot.fill_between (only for 'area' mode)
-    #     ax        matplotlib.axes.Axes = matplotlib.pyplot.gca(), axes to plot in
+def semPlot(x, y, ci:str|Callable=None, zscore:bool|int=None, color:mplt.ColorType=None, mode:Literal['area','error']='area', alpha:float=0.5, label:str=None, lprop:dict=None, aprop:dict=None, ax:mpla.Axes=None):
+    '''
+    plot mean +/- confidence intervals of matrix data
+
+    arguments:
+        x         (n) float, x coordinates
+        y         (:,n) float, data to plot, each column corresponds to a value of x
+        ci        callable | 'nansem', used to compute confidence intervals for every column of `y`, either:
+                  - 'nansem', standard error of the mean (SEM) for each column of `y`, ignoring missing values
+                  - callable, must have signature ``low, high = ci(y)``
+        zscore    bool = False | int, if True (or 1), z-score w.r.t. average of y, if 2, z-score each row of y independently
+        color     color = None
+        mode      str = 'area' | 'error', plot 'ci' either as a shaded area or as error bars
+        alpha     float = 0.5, shaded area transparency value (only for 'area' mode)
+        label     str = None, legend label for line
+        lprop     dict = {}, keyword arguments passed to matplotlib.pyplot.plot
+        aprop     dict = {}, keyword arguments passed to matplotlib.pyplot.fill_between (only for 'area' mode)
+        ax        matplotlib.axes.Axes = matplotlib.pyplot.gca(), axes to plot in
+    '''
+    # NOTE: should maybe change y to match plt.plot: each row of 'y' corresponds to a values of 'x'
     
     y = np.array(y,ndmin=2)
     y = y[~np.isnan(y).all(axis=1)] # ŕemove full-nan rows
@@ -227,7 +238,11 @@ def semPlot(x, y, ci:Callable=None, zscore:bool|int=None, color=None, mode:Liter
     if not (set(['edgecolor','edgecolors','ec','facecolor','facecolors','fc','color']) & aprop.keys()): aprop['color'] = color
     aprop.setdefault('alpha',alpha)
     aprop.setdefault('lw',0)
-    if ci is None:
+
+    if isinstance(ci,str) and ci == 'nansem':
+        ci = lambda x : (np.nanmean(x,axis=0) - np.nanstd(x,axis=0,ddof=1)/np.sqrt(np.sum(~np.isnan(x),axis=0)),
+                         np.nanmean(x,axis=0) + np.nanstd(x,axis=0,ddof=1)/np.sqrt(np.sum(~np.isnan(x),axis=0)))
+    elif ci is None:
         if y.shape[0] == 1:
             ci = lambda x : (x.flatten(), x.flatten())
         elif y.shape[0] < 500:
@@ -268,7 +283,7 @@ def semPlot(x, y, ci:Callable=None, zscore:bool|int=None, color=None, mode:Liter
     return
 
 
-def boxPlot(data, x=None, color=None, label=None, ax:mpla.Axes=None):
+def boxPlot(data, x=None, color:mplt.ColorType=None, label=None, ax:mpla.Axes=None):
 
     if ax is None:
         ax = plt.gca()
@@ -282,6 +297,7 @@ def boxPlot(data, x=None, color=None, label=None, ax:mpla.Axes=None):
     else:
         data = [np.array(d)[~np.isnan(d)] for d in data]
 
+    if color is None: color = 'b'
     try:
         color = mplc.to_rgba(color)
         color = [color] * len(data)
@@ -372,7 +388,7 @@ def pBar(p, x = None, alpha=0.05, dy=1, draw=(False,True,True,True), ax:mpla.Axe
     return
 
 
-def pHorzLine(p,t=None,dy=None,color=None,ax=None):
+def pHorzLine(p, t=None, dy=None, color:mplt.ColorType=None, ax:mpla.Axes=None):
     # p: (n_times, n_cond)
 
     p = np.asarray(p).astype(float)
@@ -403,7 +419,7 @@ def pHorzLine(p,t=None,dy=None,color=None,ax=None):
     return
 
 
-def plotIntervals(intervals,alpha=0.3,color='gray',ax:mpla.Axes=None):
+def plotIntervals(intervals, alpha=0.3, color:mplt.ColorType='gray', ax:mpla.Axes=None):
 
     intervals = np.array(intervals,ndmin=2)
     if intervals.ndim != 2 or intervals.shape[1] != 2:
@@ -416,12 +432,29 @@ def plotIntervals(intervals,alpha=0.3,color='gray',ax:mpla.Axes=None):
         ax.axvspan(start,stop,alpha=alpha,color=color)
 
 
-def plotPDF(x, log:bool=False, bandwidth:float|str=None, eps:float=1e-12, n_points:int=50, color=None, label=None, ax:mpla.Axes=None, **plot_kwargs):
-
-    if bandwidth is None:
-        bandwidth = 'scott'
-    if ax is None:
-        ax = plt.gca()
+def plotPDF(x, mode:str=None, bandwidth:float|str=None, eps:float=None, n_points:int=None, norm=None, color:mplt.ColorType=None, label=None, ax:mpla.Axes=None, **plot_kwargs):
+    '''
+    estimate and plot probability density function (PDF) of data
+
+    arguments:
+        x            (n,) tuple | array, data to plot
+        mode         str = {'normal','log','polar'}, DESCRIBE
+        log          bool = False, plot log-transformed PDF, DEPRECATED
+        bandwidth    float | str = 'scott', bandwidth for gaussian kernel
+        eps          float = 1e-12, small value used to avoid log(0)
+        n_points     int = 50, number of points used to evaluate PDF
+        norm         str = {'density','max'}, normalization mode, 'density' computes PDF, 'max' normalizes its maximum to 1
+        color        color = None, line color
+        label        str = None, legend label for line
+        ax           matplotlib.axes.Axes = matplotlib.pyplot.gca(), axes to plot in
+    '''
+
+    if mode is None: mode = 'normal'
+    if bandwidth is None: bandwidth = 0.05 if mode == 'polar' else 'scott'
+    if eps is None: eps = 1e-12
+    if n_points is None: n_points = 50
+    if norm is None: norm = 'density'
+    if ax is None: ax = plt.gca()
     if isinstance(x,tuple):
         if color is None:
             color = [None] * len(x)
@@ -437,30 +470,54 @@ def plotPDF(x, log:bool=False, bandwidth:float|str=None, eps:float=1e-12, n_poin
     for i, data in enumerate(x):
         # cast to array and validate
         data = np.asarray(data)
+        data = data[~np.isnan(data)] # always ravels input: loosing a capability of gaussian_kde?
+        #if data.ndim == 2 and data.shape[1] == 1:
+        #    data = data.ravel()
         if data.size < 2:
             grid.append([])
             density.append([])
             continue
-        data = data[~np.isnan(data)] # always ravels input: loosing a capability of gaussian_kde?
-        #if data.ndim == 2 and data.shape[1] == 1:
-        #    data = data.ravel()
-
-        if log:
-            if data.min() <= 0:
-                raise ValueError('log-transforming data requires positive values')
-            data = np.log(data + eps) # log-transform data
-            this_grid = np.linspace(data.min(),data.max(),n_points) # linear grid in log-space
-            jacobian = np.exp(this_grid) # jacobian term to transform density back to linear
-        else:
-            this_grid = np.linspace(data.min(),data.max(),n_points) # linear grid
 
-        kde = sp.stats.gaussian_kde(data,bw_method=bandwidth)
-        if log:
-            this_density = kde(this_grid) / jacobian
-            ax.loglog(jacobian,this_density,color=color[i],label=label[i],**plot_kwargs)
-        else:
-            this_density = kde(this_grid)
-            ax.plot(this_grid,this_density,color=color[i],label=label[i],**plot_kwargs)
+        match mode:
+            # 1. real-valued data using gaussian kernel density estimator
+            case 'normal':
+                this_grid = np.linspace(data.min(),data.max(),n_points) # linear grid
+                kde = sp.stats.gaussian_kde(data,bw_method=bandwidth)
+                this_density = kde(this_grid)
+                if norm == 'max':
+                    this_density /= this_density.max()
+                ax.plot(this_grid,this_density,color=color[i],label=label[i],**plot_kwargs)
+
+            # 2. log-transformed data using gaussian kernel density estimator
+            case 'log':
+                if data.min() <= 0:
+                    raise ValueError('log-transforming data requires positive values')
+                data = np.log(data + eps) # log-transform data
+                this_grid = np.linspace(data.min(),data.max(),n_points) # linear grid in log-space
+                jacobian = np.exp(this_grid) # jacobian term to transform density back to linear
+                kde = sp.stats.gaussian_kde(data,bw_method=bandwidth)
+                this_density = kde(this_grid) / jacobian
+                if norm == 'max':
+                    this_density /= this_density.max()
+                ax.loglog(jacobian,this_density,color=color[i],label=label[i],**plot_kwargs)
+
+            # 3. circular data using von-Mises kernel density estimator
+            case 'polar':
+                data = np.mod(data,2*np.pi)
+                this_grid = np.linspace(0,2*np.pi,n_points) # linear grid in [0,2*pi]
+                this_density = np.zeros_like(this_grid)
+                for theta in data:
+                    this_density += spst.vonmises.pdf(this_grid-theta,1/bandwidth)
+                if norm == 'max':
+                    this_density /= this_density.max()
+                else:
+                    this_density /= len(data)
+                this_grid = np.concatenate((this_grid,this_grid+2*np.pi))
+                this_density = np.concatenate((this_density,this_density))
+                ax.plot(this_grid,this_density,color=color[i],label=label[i],**plot_kwargs)
+
+        grid.append(this_grid)
+        density.append(this_density)
 
     ax.set_yticks([])
 

{fmatoolbox-0.1.0 → fmatoolbox-0.1.2}/src/fmatoolbox/regions.py

@@ -57,11 +57,14 @@ class regions:
         # 2. assign session epochs
         matches = self._matchEvents(phase_names,phases) if phases else phase_names
         self.phases = {m: np.stack((loaded_events[m]['beginning'],loaded_events[m]['end']),axis=1) for m in matches}
+        epoch_intervals = np.concatenate(list(self.phases.values()))
 
         # 3. assign states
         self.states = {s: np.stack((loaded_events[s]['col0'],loaded_events[s]['col1']),axis=1) for s in states}
-        # if session phases are available, use them to compute special states 'all' and 'other' SHOULD ALSO RESTRICT states AND events TO phases
         if phase_names:
+            # restrict states to session epochs
+            self.states = {s: fmatoolbox.general.restrict(self.states[s],epoch_intervals) for s in self.states}
+            # build special states 'all' and 'other'
             self.states['all'] = np.array([[self.phases[list(self.phases)[0]][0,0],self.phases[list(self.phases)[-1]][-1,-1]]])
             self.states['other'] = self.states['all']
             for name in states:
@@ -90,6 +93,12 @@ class regions:
                     e['intervals'] = np.stack((e[start],e[end]),axis=1)
                     e.pop(start)
                     e.pop(end)
+
+                # restrict to session epochs
+                if phase_names:
+                    _, valid = fmatoolbox.general.restrict(e['intervals'],epoch_intervals,s_ind=True)
+                    e = {k: v[valid] for k, v in e.items()}
+
                 self.events[name] = e
 
         if ids:
@@ -115,7 +124,7 @@ class regions:
             if not self.all_events:
                 # restrict spikes to session phases
                 for id in self.ids:
-                    self.region[id]['spikes'] = fmatoolbox.general.restrict(self.region[id]['spikes'],self.eventIntervals())
+                    self.region[id]['spikes'] = fmatoolbox.general.restrict(self.region[id]['spikes'],epoch_intervals)
 
         return
     
@@ -369,23 +378,25 @@ class regions:
 
     def firingRate(self, regs:Iterable[str]=None, e_groups:Iterable[int]=None, states:Iterable[str]=None, when=None, shift=False,
                    window=None, step=None, smooth=None, norm=False):
-        # get region firing rate
-        #
-        # arguments:
-        #     regs        (n) string = None, brain regions to compute firing rate of, default is all regions
-        #     e_groups    (m) int = None, electrode groups (starting at 1) to compute firing rate of, default is none
-        #     states      (:) string = None, behavioral states, default is all
-        #     when        DESCRIBE, same input as eventIntervals
-        #     shift       bool = False, shift epochs together in time after filtering by state
-        #     window      float = 0.05, window size to count spikes
-        #     step        int = 1, firing rate is computed in windows of length 'binSize' and overlap 'binSize' / 'step',
-        #                 default is no overlap
-        #     smooth      float = None, gaussian kernel std for smoothing over time
-        #     norm        bool = False, normalize by neuron number per region
-        #
-        # output:
-        #     rate        (:,n+m+1) float, every row is [time stamp, firing rates for n regions, firing rates for m electrodes],
-        #                 input order of regions and electrodes is preserved
+        '''
+        get region firing rate
+
+        arguments:
+            regs        (n) string = None, brain regions to compute firing rate of, default is all regions
+            e_groups    (m) int = None, electrode groups (starting at 1) to compute firing rate of, default is none
+            states      (:) string = None, behavioral states, default is all
+            when        DESCRIBE, same input as eventIntervals
+            shift       bool = False, shift epochs together in time after filtering by state
+            window      float = 0.05, window size to count spikes
+            step        int = 1, firing rate is computed in windows of length 'binSize' and overlap 'binSize' / 'step',
+                        default is no overlap
+            smooth      float = None, gaussian kernel std for smoothing over time
+            norm        bool = False, normalize by neuron number per region
+
+        output:
+            rate        (:,n+m+1) float, every row is [time stamp, firing rates for n regions, firing rates for m electrodes],
+                        input order of regions and electrodes is preserved
+        '''
 
         if states is not None and when is not None:
             raise ValueError("'states' and 'when' cannot be specified at the same time")
@@ -394,7 +405,8 @@ class regions:
 
         regs, e_groups, states = self._checkIDs(regs=regs,e_groups=e_groups,states=states,fuse=True)
 
-        # find big holes in 'when' intervals, to speed up computation, NOTE: might not be speeding it up after all...
+        # find big holes in 'when' intervals, to speed up computation
+        # NOTE: it is actually number of time bins which defines big! Also, this looks every element of spikes many times, maybe useless!
         when = self.eventIntervals(when)
         holes = when[1:,0] - when[:-1,1] > 5000 # s
         partition_idx = np.insert(np.cumsum(holes),0,0) # partition_idx[i] indexes partition to which when[i] belongs
@@ -410,12 +422,12 @@ class regions:
 
             if np.any(regs != None):
                 for r in regs:
-                    fr = fmatoolbox.analysis.firingRate(self.spikes(regs=r)[:,0],np.floor(intervals[0,0]),intervals[-1,1],window,step,smooth)
+                    fr = fmatoolbox.analysis.istantaneousRate(self.spikes(regs=r)[:,0],start=np.floor(intervals[0,0]),stop=intervals[-1,1],bin=window,step=step,smooth=smooth)
                     fr_interv.append(fr[:,1])
 
             if np.any(e_groups != None):
                 for e in e_groups:
-                    fr = fmatoolbox.analysis.firingRate(self.spikes(e_groups=e)[:,0],np.floor(intervals[0,0]),intervals[-1,1],window,step,smooth)
+                    fr = fmatoolbox.analysis.istantaneousRate(self.spikes(e_groups=e)[:,0],start=np.floor(intervals[0,0]),stop=intervals[-1,1],bin=window,step=step,smooth=smooth)
                     fr_interv.append(fr[:,1])
 
             firing_rate.append(np.stack(fr_interv,1))
@@ -428,7 +440,7 @@ class regions:
         # filter by state
         if np.any(states != 'all'):
             firing_rate = fmatoolbox.general.restrict(firing_rate,self.eventIntervals([states]),shift=shift)
-            warnings.warn("option 'states' is deprecated, use 'when' instead")
+            warnings.warn("option 'states' is deprecated, use 'when' instead!")
 
         # normalize
         if norm:
@@ -468,7 +480,7 @@ class regions:
         firing_rate = np.zeros((n_times[-1],n_units[-1]))
         for i, interval in enumerate(phase_intervals):
             for j, r in enumerate(regs):
-                fr = fmatoolbox.analysis.firingRate(self.spikes(r),interval[0],interval[1],window,step,smooth,u_range=self.units(r))
+                fr = fmatoolbox.analysis.istantaneousRate(self.spikes(r),start=interval[0],stop=interval[1],bin=window,step=step,smooth=smooth,g_range=self.units(r))
                 firing_rate[n_times[i]:n_times[i+1],n_units[j]:n_units[j+1]] = fr[:,1:]
             firing_rate[n_times[i]:n_times[i+1],0] = fr[:,0]
 

{fmatoolbox-0.1.0 → fmatoolbox-0.1.2/src/fmatoolbox.egg-info}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: fmatoolbox
-Version: 0.1.0
+Version: 0.1.2
 Summary: Python port of FMAToolbox
 Author: Pietro Bozzo
 License-Expression: GPL-3.0-or-later
 Project-URL: Homepage, https://github.com/pietro-bozzo/FMAToolboxPython
 Project-URL: Repository, https://github.com/pietro-bozzo/FMAToolboxPython
 Project-URL: Issues, https://github.com/pietro-bozzo/FMAToolboxPython/issues
-Requires-Python: >=3.9
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy