fmatoolbox 0.1.2__tar.gz → 0.1.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fmatoolbox
-Version: 0.1.2
+Version: 0.1.4
 Summary: Python port of FMAToolbox
 Author: Pietro Bozzo
 License-Expression: GPL-3.0-or-later
@@ -11,11 +11,13 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy
+Requires-Dist: numba
 Requires-Dist: scipy
 Requires-Dist: matplotlib
 Requires-Dist: statsmodels
-Requires-Dist: scikit-learn
-Requires-Dist: scikit-image
+Provides-Extra: assemblies
+Requires-Dist: scikit-learn; extra == "assemblies"
+Requires-Dist: scikit-image; extra == "assemblies"
 Dynamic: license-file
 
 # FMAToolbox (Python Port)

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fmatoolbox"
-version = "0.1.2"
+version = "0.1.4"
 description = "Python port of FMAToolbox"
 authors = [{name = "Pietro Bozzo"}]
 readme = "README.md"
@@ -13,9 +13,14 @@ license = "GPL-3.0-or-later"
 requires-python = ">=3.11"
 dependencies = [
     "numpy",
+    "numba",
     "scipy",
     "matplotlib",
     "statsmodels",
+]
+
+[project.optional-dependencies]
+assemblies = [
     "scikit-learn",
     "scikit-image",
 ]

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

@@ -3,20 +3,19 @@
 import fmatoolbox.general
 import numpy as np
 import scipy as sp
-import sklearn.decomposition as skdc
-import skimage.filters as skif
 import joblib
 import statsmodels.stats.multitest
 import warnings
+from numba import njit
 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)
+        samples     (n,) float | (n,2) 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
@@ -27,7 +26,7 @@ def istantaneousRate(samples, start:float=None, stop:float=None, bin:float=None,
 
     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)
@@ -78,107 +77,41 @@ def istantaneousRate(samples, start:float=None, stop:float=None, bin:float=None,
         rate = np.array(rate).T / bin
 
     # make time axis
-    t = bin/step/2 + np.linspace(0,(n_bins-1)*bin,n_bins*step)
+    t = start + 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)
+        rate = sp.ndimage.gaussian_filter(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
-    #
-    # arguments:
-    #     spikes         (n,:) float, every row is either [spike time] (s) or [spike time, unit id]
-    #     start          float = min(spike_times) s, time to start count at
-    #     stop           float = max(spike_times) s, time to stop count at
-    #     bin_size       float = 0.05 s, time bin to count spikes
-    #     step           int = 1, firing rate is computed in windows of length 'bin_size' and overlap 'bin_size' / 'step', default is no overlap
-    #     smooth         float = None, gaussian kernel std for smoothing over time
-    #     u_range        (2) int, range of units to consider in computation, default is [min(spikes[:,1]), max(spikes[:,1])]
-    #                    (boundaries included, only for 2-columns 'spikes')
-    #
-    # 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
-    if step is None: step = 1
-    if step % 1 or step == 0:
-        raise ValueError("'step' must be a non-zero integer")
-    
-    units = []
-    if spikes.ndim == 1:
-        times = spikes
-    elif spikes.shape[1] == 1:
-        times = spikes.reshape(-1)
-    else:
-        times = spikes[:,0]
-        units = spikes[:,1]
-        if u_range is None:
-            u_range = np.unique(units).astype(int)[[0,-1]]
-        else:
-            u_range = np.array(u_range,dtype=int)
-    
-    # build time bins, overlapping if requested
-    if start is None:
-        start = times.min()
-    if stop is None:
-        stop = times.max()
-    time_bins = [np.arange(start,stop+bin_size,bin_size) + i*bin_size/step for i in range(step)]
-    
-    if len(units) == 0:
-        # compute firing rate once
-        firing_rate = [np.histogram(times,bins=tb)[0] for tb in time_bins]
-        # flatten and convert to Hz
-        firing_rate = np.array(firing_rate).reshape((-1,1),order='F') / bin_size
-    else:
-        # compute firing rate once per unit and stack into a matrix
-        firing_rate = []
-        for u in range(u_range[0],u_range[-1]+1):
-            fr = [np.histogram(times[units==u],bins=tb)[0] for tb in time_bins]
-            firing_rate.append(np.array(fr).flatten('F'))
-        firing_rate = np.array(firing_rate).T / bin_size
-
-    # center times into time bins
-    time_bins = [(tb[:-1] + tb[1:]) / 2 for tb in time_bins]
-    time_bins = np.array(time_bins).reshape((-1,1),order='F')
-
-    # apply smoothing
-    if smooth is not None:
-        firing_rate = sp.ndimage.gaussian_filter(firing_rate,smooth,axes=0)
-
-    return np.concatenate((time_bins,firing_rate),1)
+def PETH(samples, events, groups=None, g_range:tuple[int,int]=None, limits:tuple[float,float]=None, n_bins:int=None, bin:float=None, step:int=None, smooth:float=None, fast:bool=False):
+    '''
+    compute peri-event time histogram of a signal relative to synchronizing events
 
+    arguments:
+        samples    float, either:
+                    - (n) array of time stamps (s), describing a point process
+                    - (n,:) array, where each row is [time stamp (s), value1, ...], describing one or more continous signals
+        events     (m) float, synchronizing events' times, their order is maintained in the output 'mat'
+        groups     (n) int, grouping indeces for samples, to compute separate PETHs (only for point process 'samples')
+        g_range    (2) int = [0,max(groups)], min and max group id
+        groups     (:) int, grouping indeces for samples, to compute separate PETHs (only for point process 'samples')
+        limits     (2) float = [-0.5,0.5] (s), defines a window around events, divided into 'n_bins' time bins to compute PETH
+        n_bins     float = 101, number of time bins around event times
+        bin        float = None (s), bin size, can be given instead of 'n_bins', which will be deduced from 'bin' and 'limits'
+        step       int = 1, only for point-process 'samples', for values higher than 1, time bins inside a window will overlap, yielding:
+                    - bin_size of (limit[1]-limit[0]) / n_bins, unchanged
+                    - time resolution of bin_size / step
+        smooth     float = None, gaussian kernel std to smooth mean output 'm' over time, has no effect on 'mat'
+        fast       bool = False, if True, 'samples' must be time sorted to save computation time (only for point process 'samples')
 
-def PETH(samples, events, groups=None, g_range:tuple[int,int]=None, limits:tuple[float,float]=None, n_bins:int=None, bin:float=None, step:int=None, fast:bool=False):
-    # compute peri-event time histogram of a signal relative to synchronizing events
-    #
-    # arguments:
-    #     samples    float, either:
-    #                 - (n) array of time stamps (s), describing a point process
-    #                 - (n,:) array, where each row is [time stamp (s), value1, ...], describing one or more continous signals
-    #     events     (m) float, synchronizing events' times, their order is maintained in the output 'mat'
-    #     groups     (n) int, grouping indeces for samples, to compute separate PETHs (only for point process 'samples')
-    #     g_range    (2) int = [0,max(groups)], min and max group id
-    #     groups     (:) int, grouping indeces for samples, to compute separate PETHs (only for point process 'samples')
-    #     limits     (2) float = [-0.5,0.5] (s), defines a window around events, divided into 'n_bins' time bins to compute PETH
-    #     n_bins     float = 101, number of time bins around event times
-    #     bin        float = None (s), bin size, can be given instead of 'n_bins', which will be deduced from 'bin' and 'limits'
-    #     step       int = 1, only for point-process 'samples', for values higher than 1, time bins inside a window will overlap, yielding:
-    #                 - bin_size of (limit[1]-limit[0]) / n_bins, unchanged
-    #                 - time resolution of bin_size / step
-    #     fast       bool = False, if True, 'samples' must be time sorted to save computation time (only for point process 'samples')
-    #
-    # output:
-    #     mat        (m,n_bins) float, every row corresponds to samples centered on an event
-    #     t          (n_bins) float, times (s)
-    #     m          (n_bins) float, average samples across events
+    output:
+        mat        (m,n_bins) float, every row corresponds to samples centered on an event
+        t          (n_bins) float, times (s)
+        m          (n_bins) float, average of 'samples' across events
+    '''
 
     # default values
     samples = np.array(samples,ndmin=1)
@@ -233,7 +166,7 @@ def PETH(samples, events, groups=None, g_range:tuple[int,int]=None, limits:tuple
             valid = counts > 0
             # repeat event indices according to how many samples they match
             event_idx = np.repeat(np.arange(len(events))[valid],counts[valid])
-            sample_idx = np.concatenate([np.arange(l,r) for l, r in zip(left[valid],right[valid])])
+            sample_idx = np.concatenate([np.arange(l,r) for l, r in zip(left[valid],right[valid])]) if np.any(valid) else []
             # build lists of matches
             e_rep = events[event_idx]
             s_sel = samples[sample_idx]
@@ -258,11 +191,193 @@ def PETH(samples, events, groups=None, g_range:tuple[int,int]=None, limits:tuple
     if squeeze:
         mat = mat.reshape(mat.shape[:2])
 
-    m = np.mean(mat,axis=0)
+    m = np.nanmean(mat,axis=0)
+    if smooth is not None:
+        m = sp.ndimage.gaussian_filter(m,smooth,axes=0)
 
     return mat, t, m
 
 
+def jointPETH(samples, events, bin:float=None, step:int=None, n_bins=None, limits=None, return_peths:bool=None, smooth:float=None):
+    '''
+    compute joint peri-event time histogram of two signals A and B relative to synchronizing events, i.e., the co-occurrence rate (Hz)
+    for different time-lag pairs applied to A and B
+
+    arguments:
+        samples       (2,) tuple, whose elements can be either:
+                      - (n) float of time stamps (s), describing a point process
+                      - (n,:) float, where each row is [time stamp (s), value1, ...], describing one or more continous signals
+        events        (m) float, synchronizing events' times, their order is maintained in the output 'mat' /!\
+        bin           float = 0.05 (s), bin size to compute PETHs
+        n_bins        int | (2,) int = 101, number of time bins around event times, either one for both PETHS or two values
+        limits        (2,) float | (2,2) float = None, can be given instead of 'n_bins', which will be deduced from 'bin' and 'limits', and
+                      defines a [start, stop] window (in s) around events, divided into time bins of size 'bin' to compute PETHs; can be a
+                      single tuple for both PETHS or a tuple of tuples
+        step          int = 1, only for point-process 'samples', for values higher than 1, time bins inside each window will overlap, yielding:
+                       - bin_size of (limit[1]-limit[0]) / n_bins, unchanged
+                       - time resolution of bin_size / step
+        smooth        float = None, gaussian kernel std to smooth mean output 'peth' over time, has no effect on other outputs
+        ARGS YET TO TEST
+        groups        (n) int, grouping indeces for samples, to compute separate PETHs (only for point process 'samples')
+        g_range       (2) int = [0,max(groups)], min and max group id
+        groups        (:) int, grouping indeces for samples, to compute separate PETHs (only for point process 'samples')
+        fast          bool = False, if True, 'samples' must be time sorted to save computation time (only for point process 'samples')
+
+    output:
+        joint         (n_bins0,n_bins1) float, lagged co-occurrency rate (Hz), dimensions correspond to time lags w.r.t. 'events' for
+                      A and B, respectively
+        null          (n_bins0,n_bins1) float, null model for 'joint' in case A and B occurr independently, conditioned on 'events';
+                      i.e., their conditioned co-occurrence probability is the product of their average event PETHs
+        difference    (n_bins0,n_bins1) float, 'joint' - 'null', co-occurrence rate (Hz) unexplained by the null model, values far from 0 suggest
+                      that conditioning on 'events' is not sufficient to explain the co-occurrence of the two signals
+        '''
+
+    # 1. ensure PETHs are produced with the same bin size
+    isscalar = lambda x: x is None or np.isscalar(x)
+    if bin is None: bin = 0.05
+    # duplicate single-peth inputs for two peths
+    if isscalar(n_bins):
+        n_bins = [n_bins,n_bins]
+    else:
+        n_bins = list(n_bins)
+    if limits is None:
+        limits = [None,None]
+    else:
+        limits = [list(limits),list(limits)] if np.isscalar(limits[0]) and np.isscalar(limits[1]) else [l if isscalar(l) else list(l) for l in limits]
+    # deduce 'n_bins' or 'limits'
+    for i in [0,1]:
+        if n_bins[i] is None:
+            if limits[i] is None:
+                n_bins[i] = 101
+                limits[i] = (-bin * n_bins[i] / 2, bin * n_bins[i] / 2)
+            else:
+                window = np.diff(limits[i]).item()
+                n_bins[i] = np.ceil(window / bin).astype(int)
+                extra = n_bins[i] * bin - window
+                limits[i][0] -= extra / 2
+                limits[i][1] += extra / 2
+        else:
+            limits[i] = (-bin * n_bins[i] / 2, bin * n_bins[i] / 2)
+
+    # 2. PETHs
+    mat0, t0, mean0 = PETH(samples[0],events,limits=limits[0],n_bins=n_bins[0],bin=bin,step=step)
+    mat1, t1, mean1 = PETH(samples[1],events,limits=limits[1],n_bins=n_bins[1],bin=bin,step=step)
+    dt = t0[1] - t0[0]
+    if not np.isclose(dt, t1[1]-t1[0]):
+        raise ValueError('time resolution of the two PETHs must coincide')
+
+    # observed co-occurrence between 'samples0' and 'samples1' at every time bin
+    joint = (mat0.T @ mat1) / len(events)
+    # expected co-occurrence if the signals were independent: product
+    null = np.outer(mean0, mean1)
+    # convert to Hz
+    joint = np.sqrt(joint) / dt
+    null = np.sqrt(null) / dt
+    # difference(i,j) = sqrt[ mean_e( mat0(e,i) * mat1(e,j) ) ] - sqrt[ mean0(i) * mean1(j) ]
+    difference = joint - null
+
+    if return_peths:
+        if smooth is not None:
+            # recompute with smoothing
+            _, _, mean0 = PETH(samples[0],events,limits=limits[0],n_bins=n_bins[0],bin=bin,step=step,smooth=smooth)
+            _, _, mean1 = PETH(samples[1],events,limits=limits[1],n_bins=n_bins[1],bin=bin,step=step,smooth=smooth)
+        mean0 /= dt
+        mean1 /= dt
+        return joint, null, difference, t0, t1, mean0, mean1
+    return joint, null, difference, t0, t1
+
+
+@njit
+def _ccg_numba(times, proc, nproc, bin_width, lag_start, lag_stop):
+    # ccg: (reference process, target process, lag bin)
+
+    n = len(times)
+    nbins = int(np.ceil((lag_stop - lag_start) / bin_width))
+    inv_bin = nbins / (lag_stop - lag_start) # faster than dividing at every iteration
+
+    n_samples = np.zeros(nproc,dtype=np.int64)
+    ccg = np.zeros((nproc,nproc,nbins),dtype=np.int64)
+    for i in range(n):
+        ti = times[i]
+        pi = proc[i]
+        n_samples[pi] += 1
+
+        # find first event that can contribute, starting from next event
+        j0 = i + 1
+        while j0 < n and times[j0] - ti < lag_start:
+            j0 += 1
+        j = j0
+
+        while j < n:
+            dt = times[j] - ti
+            if dt >= lag_stop:
+                break
+            pj = proc[j]
+
+            # positive lag contribution
+            if dt >= lag_start:
+                b = int((dt - lag_start) * inv_bin)
+                if 0 <= b < nbins:
+                    ccg[pi,pj,b] += 1
+
+            # negative lag contribution (swap reference and target)
+            if -dt >= lag_start and -dt < lag_stop:
+                b = int((-dt - lag_start) * inv_bin)
+                if 0 <= b < nbins:
+                    ccg[pj,pi,b] += 1
+
+            j += 1
+
+    return ccg, n_samples
+
+
+def CCG(samples, bin:float=None, limits:tuple[float,float]=None, fast:bool=None, norm:str=None):
+    '''
+    compute cross-correlograms from time stamps generated by point processes
+
+    arguments:
+        samples    (:,) float | (:,2) float, every row is either [sample time (s)] or [sample time (s), process id]; if 1d, interpreted as (n,1)
+        bin        float = 0.05 s, time bin to count samples
+        limits     (2) float = [-0.5,0.5] (s), defines a window around time stamps, divided into time bins to compute CCG
+        fast       bool = False, if True, 'samples' must be time sorted to save computation time
+        norm       str = {'rate','count'}, determines unit of measurement of 'ccg'
+
+    output:
+        ccg        DESCRIBE
+        t          DESCRIBE
+    '''
+
+    if bin is None: bin = 0.05
+    if limits is None: limits = (-0.5,0.5)
+    if norm is None: norm = 'rate'
+
+    samples = np.asarray(samples)
+    if samples.ndim == 1:
+        times = samples.astype(np.float64)
+        id = np.zeros(len(times),dtype=np.int64)
+    elif samples.shape[1] == 2:
+        times = samples[:,0].astype(np.float64)
+        id = samples[:,1].astype(np.int64)
+    else:
+        raise ValueError("'samples' must be (n,) or (n,2)")
+    nproc = id.max() + 1
+
+    # sort by time
+    if not fast:
+        order = np.argsort(times)
+        times = times[order]
+        id = id[order]
+
+    ccg, n_samples = _ccg_numba(times, id, nproc, float(bin), float(limits[0]), float(limits[1]))
+    edges = np.linspace(limits[0],limits[1],ccg.shape[2]+1)
+    t = (edges[1:] + edges[:-1]) / 2
+
+    if norm == 'rate':
+        ccg = ccg.astype(float) / (n_samples[:,None,None] * bin)
+
+    return ccg, t
+
+
 def avalanchesFromProfile(x, threshold:float, time_step:float, t0:float=0):
     # compute avalanches' sizes and [start,stop] intervals from a time series
     #
@@ -304,6 +419,12 @@ def avalanchesFromProfile(x, threshold:float, time_step:float, t0:float=0):
 def cellAssembliesICA(spikes, window:float=None, when=None, drop_mix:bool=False):
     # detect assemblies from spike trains with PCA + ICA
 
+    try:
+        import sklearn.decomposition as skdc
+        import skimage.filters as skif
+    except ImportError as e:
+        raise ImportError('cellAssembliesICA requires scikit-learn, did you do: pip install "fmatoolbox[assemblies]" ?') from e
+
     if window is None: window = 0.025
 
     raster = firingRate(spikes,bin_size=window)

{fmatoolbox-0.1.2 → fmatoolbox-0.1.4}/src/fmatoolbox/data.py

@@ -1,5 +1,5 @@
-''' Session data handling functions for FMAToolbox '''
-from typing import Any, Callable
+''' Functions to load data for a recording session '''
+
 import pathlib
 import scipy.io
 import numpy as np
@@ -10,27 +10,32 @@ import re
 import fmatoolbox.exceptions
 import collections
 import concurrent.futures
-
-
-def loadSpikeTimes(session:str, output:str='dict', anat_file:str=None, return_elec:bool=False, return_loc:bool=False, reload:bool=False):
-    # load spikes from a session
-    #
-    # arguments:
-    #     session         string, path to session .xml file, spike files must be in session folder
-    #     output          string = None, determines output type, can be:
-    #                       'dict', dictionary of spike times per unit
-    #                       'compact', (:,2) array of [timestamps, unit ids]
-    #                       'full', (:,2) array of [timestamps, electrode groups, clusters]
-    #                       'regions', dict of {region id: dict}, entries are {'spikes': region spikes, 'units': region units}
-    #     anat_file        str = None, DESCRIBE
-    #     return_elec      bool = False, if true, return cluster_loc
-    #     return_loc       bool = False, if true, return cluster_loc
-    #     reload           bool = False, load original files, bypassing Regions/<basename>_spikes.npz backup (for 'output' = 'regions')
-    #
-    # output:
-    #     spikes          (see 'output')
-    #     electrodes      (n) float, optional, electrode id per unit
-    #     cluster_loc     (n) float, optional, index of max spike-amplitude cluster per unit
+import xml.etree.ElementTree
+from typing import Any, Callable
+from os import PathLike
+
+
+def loadSpikeTimes(session:str|PathLike[str], output:str='dict', anat_file:str=None, return_elec:bool=False, return_loc:bool=False, reload:bool=False):
+    """
+    load spikes for a session
+
+    arguments:
+        session        file, path to session .xml file, spike files must be in session folder
+        output         string = None, determines output type, either:
+                        - 'dict', dictionary of spike times per unit
+                        - 'compact', (:,2) array of [timestamps, unit ids]
+                        - 'full', (:,2) array of [timestamps, electrode groups, clusters]
+                        - 'regions', dict of {region id: dict}, entries are {'spikes': region spikes, 'units': region units}
+        anat_file      str = None, DESCRIBE
+        return_elec    bool = False, if true, return cluster_loc
+        return_loc     bool = False, if true, return cluster_loc
+        reload         bool = False, load original files, bypassing Regions/<basename>_spikes.npz backup (for 'output' = 'regions')
+
+    output:
+        spikes         (see 'output')
+        electrodes     (n) float, optional, electrode id per unit
+        cluster_loc    (n) float, optional, index of max spike-amplitude cluster per unit
+    """
 
     file_root = pathlib.Path(session).with_suffix('')
     cell_metrics_file = file_root.with_suffix('.cell_metrics.cellinfo.mat')
@@ -50,7 +55,7 @@ def loadSpikeTimes(session:str, output:str='dict', anat_file:str=None, return_el
     return out[:2+return_loc:2-return_elec]
 
 
-def loadCellMetricsFile(session:str, output:str='dict', anat_file:str=None, return_extra:bool=False, reload:bool=False):
+def loadCellMetricsFile(session:str|PathLike[str], output:str='dict', anat_file:str=None, return_extra:bool=False, reload:bool=False):
 
     file_root = pathlib.Path(session).with_suffix('')
 
@@ -92,7 +97,7 @@ def loadCellMetricsFile(session:str, output:str='dict', anat_file:str=None, retu
             if anat_file is None:
                 raise ValueError("'anat_file' must be provided when 'output' = 'regions'")
             anat = loadAnatomyFile(anat_file)
-            anat = anat[anat['rat'] == int(file_root.stem[3:6])]  # keep rat of interest, deduced from file name
+            anat = anat[anat['rat'] == int(file_root.stem[3:6])] # keep rat of interest, deduced from file name
             ids = np.unique(anat['region'])
             spikes = {str(id): {} for id in ids}
             for id in ids:
@@ -108,7 +113,7 @@ def loadCellMetricsFile(session:str, output:str='dict', anat_file:str=None, retu
                     s = np.concatenate(s)
                     spikes[id]['spikes'] = s[s[:,0].argsort()]
                 else:
-                    spikes[id]['spikes'] = np.array(s,ndmin=2)
+                    spikes[id]['spikes'] = np.empty((0,2))
             # save
             saveRegionSpikes(spike_file,spikes)
 
@@ -120,13 +125,19 @@ def loadCellMetricsFile(session:str, output:str='dict', anat_file:str=None, retu
     return spikes
 
 
-def loadCluFiles(session:str, rate:float=20000, output:str='dict', anat_file:str=None, reload:bool=False):
+def loadCluFiles(session:str|PathLike[str], rate:float=None, output:str='dict', anat_file:str=None, reload:bool=False):
 
     if output not in ['dict','compact','full','regions']:
         raise ValueError("'output' must be 'dict', 'compact', 'full', or 'regions'")
 
-    # load .res and .clu files
+    # load parameters n_channels from .xml
     froot = pathlib.Path(session).with_suffix('')
+    if rate is None:
+        tree = xml.etree.ElementTree.parse(froot.with_suffix(".xml"))
+        root = tree.getroot()
+        rate = float(root.find(".//samplingRate").text)
+
+    # load .res and .clu files
     res_files = {int(p.name[len(froot.name)+5:]): p for p in froot.parent.iterdir()
                  if p.is_file() and p.name.startswith(froot.name + '.res.') and p.name[len(froot.name)+5:].isdigit()}
     clu_files = {int(p.name[len(froot.name)+5:]): p for p in froot.parent.iterdir()
@@ -203,7 +214,7 @@ def loadCluFiles(session:str, rate:float=20000, output:str='dict', anat_file:str
     return spikes
 
 
-def loadAnatomyFile(file_path):
+def loadAnatomyFile(file_path:str|PathLike[str]):
     # load .anat file, whose columns must be [rat, electrode, brain region] (comma separated)
     #
     # arguments:
@@ -212,7 +223,7 @@ def loadAnatomyFile(file_path):
     return np.genfromtxt(file_path,delimiter=",",comments="%",dtype=[("rat",int),("electrode",int),("region","U50")])
 
 
-def loadRegionSpikes(file):
+def loadRegionSpikes(file:str|PathLike[str]):
     spike_npz = np.load(file)
     spikes = {r[3:]: {'spikes': spike_npz[r]} for r in spike_npz.files if r.startswith('sp_')}
     for reg in spikes:
@@ -221,7 +232,7 @@ def loadRegionSpikes(file):
     return spikes
 
 
-def saveRegionSpikes(file,spikes):
+def saveRegionSpikes(file:str|PathLike[str], spikes):
     file = pathlib.Path(file)
     if not file.parent.exists():
         pathlib.Path.mkdir(file.parent)
@@ -231,7 +242,7 @@ def saveRegionSpikes(file,spikes):
     return
 
 
-def loadEventFile(filename: str, compact: bool = False):
+def loadEventFile(filename:str|PathLike[str], compact:bool=False):
     # load events from a .evt file
     #
     # arguments:
@@ -289,8 +300,8 @@ def loadEventFile(filename: str, compact: bool = False):
     return events
 
 
-def loadEvents(session:str, extra:str|list[str]):
-    # load event files from a session
+def loadEvents(session:str|PathLike[str], extra:str|list[str]):
+    # load event files for a session
     #
     # arguments:
     #     session      string, path to session .xml file, event files must be in session folder
@@ -340,7 +351,7 @@ def loadEvents(session:str, extra:str|list[str]):
     return events, cat_names
 
 
-def loadSpikeWaveforms(session: str):
+def loadSpikeWaveforms(session:str|PathLike[str]):
 
     file_root = pathlib.Path(session).with_suffix('')
     data = scipy.io.loadmat(file_root.with_suffix('.cell_metrics.cellinfo.mat'),simplify_cells=True)['cell_metrics']
@@ -351,7 +362,98 @@ def loadSpikeWaveforms(session: str):
     return
 
 
-def loadLFP(session: str):
+def loadWideband(session:str|PathLike[str], dtype=None, channels=None, intervals=None, skip:int=None, cat:bool=None, trim:bool=None):
+    '''
+    load wideband data for a session, which is organized in records: chunks of data containing one sample for each channel
+
+    arguments:
+        session      file, path to session .xml file, spike files must be in session folder
+        dtype        type = np.int16
+        channels     (:,) int = None, channels to load, if None, load all channels; counted base 0 as NeuroScope
+        intervals    (:,2) float = None, time intervals to load, if None, load all data
+        skip         int = 0, number of records to skip after each record is read (to subsample data)
+        cat          bool = True, concatenate loaded data into a single array; if False, return a list of arrays for each interval
+        trim         bool = False, trim each loaded chunk of data so that they all have the same number of time points (useful if
+                     'intervals' are of the same length)
+
+    output:
+        data         (records, channels) dtype, data for each channel, each row is a record; list of arrays if 'cat' is False
+        t            (records,) float, time of each record; list of arrays if 'cat' is False (contrary to FMAT standard 't' returned
+                     separately from 'data' to preserve different data types)
+    '''
+
+    file_root = pathlib.Path(session).with_suffix("")
+    dat_file = file_root.with_suffix(".dat")
+
+    # load parameters n_channels from .xml
+    tree = xml.etree.ElementTree.parse(file_root.with_suffix(".xml"))
+    root = tree.getroot()
+    frequency = float(root.find(".//samplingRate").text)
+    n_channels = int(root.find(".//nChannels").text)
+
+    if dtype is None: dtype = np.int16
+    if channels is not None: channels = np.array(channels, ndmin=1)
+    if intervals is None: intervals = [[0,np.inf]]
+    intervals = np.array(intervals,ndmin=2)
+    if skip is None: skip = 0
+    if cat is None: cat = True
+
+    sample_size = np.dtype(dtype).itemsize
+    file_size = dat_file.stat().st_size
+    results = []
+    t = []
+    min_len = np.inf
+    with open(dat_file,'rb') as f:
+        for start, stop in intervals:
+
+            # locate 'start' in file
+            record_offset = int(np.floor(start * frequency))
+            byte_offset = record_offset * n_channels * sample_size
+            f.seek(byte_offset)
+
+            # copute number of records to read
+            if np.isinf(stop):
+                remaining_bytes = file_size - byte_offset
+                n_records = remaining_bytes // (n_channels * sample_size)
+            else:
+                n_records = int(np.floor((stop-start) * frequency))
+            max_records = (file_size - byte_offset) // (n_channels * sample_size)
+            n_records = min(n_records,max_records)
+
+            raw = np.fromfile(f,dtype=dtype,count=n_records*n_channels).reshape((-1,n_channels))
+            if raw.size == 0:
+                break
+
+            # select requested channels
+            if channels is not None:
+                raw = raw[:,channels]
+            # apply skipping
+            if skip > 0:
+                raw = raw[::skip+1]
+
+            results.append(raw)
+            t.append(np.linspace(start, start+raw.shape[0]/frequency*(skip+1), raw.shape[0]))
+            min_len = min(min_len,raw.shape[0])
+
+    # handle empty output
+    if len(results) == 0:
+        if channels is None: channels = np.arange(n_channels)
+        results = [np.empty((0,len(channels)),dtype=dtype)]
+        t = [np.empty(0)]
+
+    if trim:
+        results = [r[:min_len,:] for r in results]
+        t = [_t[:min_len] for _t in t]
+
+    # concatenate results from intervals
+    if cat:
+        results = np.vstack(results)
+        t = np.concatenate(t)
+
+    return results, t
+
+
+def loadLFP(session:str|PathLike[str]):
 
     print('implement!')
 
@@ -365,9 +467,36 @@ def saveMatrix():
 
     return
 
+
+def printXML(session:str|PathLike[str]):
+    """
+    simple utility to print contents of a session's .xml file
+    """
+
+    def print_xml(element,level=0):
+        indent = "  " * level
+        # print tag and attributes
+        print(f"{indent}{element.tag}",end="")
+        if element.attrib:
+            print(f" {element.attrib}",end="")
+        # print text if present
+        text = element.text.strip() if element.text else ""
+        if text:
+            print(f" -> {text}",end="")
+        print()
+        # recurse into children
+        for child in element:
+            print_xml(child,level+1)
+
+    tree = xml.etree.ElementTree.parse(pathlib.Path(session).with_suffix(".xml"))
+    root = tree.getroot()
+    print_xml(root)
+
+    return
+
 # functions to run batch
 
-def readBatchFile(file_path: str):
+def readBatchFile(file_path:str|PathLike[str]):
     # read batch file
     #
     # arguments:
@@ -425,7 +554,7 @@ def _batchWorker(payload):
         return -i-1, e
 
 
-def runBatch(batch_file:str, func:Callable, args:list[list[Any]]=None, rnd_seed:str=None, kwargs:dict|list[dict]=None, ignore_args:bool=False,
+def runBatch(batch_file:str|PathLike[str], func:Callable, args:list[list[Any]]=None, rnd_seed:str=None, kwargs:dict|list[dict]=None, ignore_args:bool=False,
              sessions:list[int]=None, parallel:bool|int=False, verbose:bool=True) -> tuple[list, ...]:
     # run a routine on multiple sessions
     #

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

@@ -154,12 +154,9 @@ def restrict(samples, intervals, shift:bool=False, s_ind:bool=False, i_ind:bool=
     #     samples      (p,m) float, restricted samples, i. e., rows of 'samples' whose first element falls into 'intervals'
     #     Is           (n) bool, optional, indicese of original samples which were kept
     #     Ii           (n) bool, optional, indicese of intervals which contain kept samples
-
-    samples = np.asarray(samples)
-    if samples.size == 0:
-        samples = np.array([])
     
     # promote 1d arrays to 2d
+    samples = np.asarray(samples)
     squeeze = samples.ndim == 1
     if squeeze:
         samples = samples.reshape((-1,1))

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

@@ -1,5 +1,6 @@
 ''' Plotting utilities for publication grade figures '''
 
+import fmatoolbox
 import numpy as np
 import numpy.typing as npt
 import matplotlib.axes as mpla
@@ -9,11 +10,13 @@ import matplotlib.typing as mplt
 import scipy.stats as spst
 import scipy as sp
 from collections.abc import Iterable
+from networkx.algorithms.centrality import flow_matrix
 from typing import Literal, Callable
+import matplotlib as mpl
 
 
 def adjustAxes(axs:mpla.Axes|Iterable[mpla.Axes], format:Literal['paper','poster']='paper'):
-    # adjust axes properties to emprove figure appearance
+    # adjust axes properties to improve figure appearance
     #
     # arguments:
     #     axs        iterable of matplotlib.axes.Axes
@@ -26,8 +29,11 @@ def adjustAxes(axs:mpla.Axes|Iterable[mpla.Axes], format:Literal['paper','poster
 
     lw = 1 if format == 'paper' else 2
     axw = 1.3 if format == 'paper' else 2.1
-    axtick = 9 if format == 'paper' else 14
-    axfont = 10 if format == 'paper' else 18
+    ax_label_fs = 9 if format == 'paper' else 18
+    ax_label_pad = 0.1 if format == 'paper' else 1
+    ax_tick_fs = 8 if format == 'paper' else 14
+    ax_tick_l = 2 if format == 'paper' else 5
+    ax_tick_pad = 1 if format == 'paper' else 2
 
     for ax in axs:
         
@@ -36,9 +42,11 @@ def adjustAxes(axs:mpla.Axes|Iterable[mpla.Axes], format:Literal['paper','poster
 
         # adjust thickness and font size
         [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)
+        ax.tick_params(width=axw,labelsize=ax_tick_fs,pad=ax_tick_pad,length=ax_tick_l)
+        ax.xaxis.label.set_fontsize(ax_label_fs)
+        ax.yaxis.label.set_fontsize(ax_label_fs)
+        ax.xaxis.labelpad = ax_label_pad
+        ax.yaxis.labelpad = ax_label_pad
 
     return
 
@@ -141,8 +149,8 @@ def plotXY(data, start=None, stop=None, color:mplt.ColorType=None, label=None, a
     return
 
 
-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):
+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=None,
+                 xzoom:float=None, yzoom:float=None, x=None, y=None, aspect:float=None, bar:str=None, ax:mpla.Axes=None):
     '''
     plot a 2D array as a colormap with optional normalization, sorting, and resampling
 
@@ -159,6 +167,7 @@ def plotColorMap(data:npt.NDArray[np.floating], vmin:float=None, vmax:float=None
         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
+        bar             str = None, if given, draw colorbar next to `ax` with label specified by `bar`
         ax              matplotlib.axes.Axes = matplotlib.pyplot.gca(), axes to plot in
     '''
 
@@ -170,6 +179,7 @@ def plotColorMap(data:npt.NDArray[np.floating], vmin:float=None, vmax:float=None
             zscore = None
         data = spst.zscore(data,axis=zscore,nan_policy='omit')
 
+    if sortax is None: sortax = 0
     if sortby is not None:
         if isinstance(sortby,str) and sortby == 'peak':
             sortby = lambda x : np.argsort(np.argmax(x,1-sortax))
@@ -197,8 +207,11 @@ def plotColorMap(data:npt.NDArray[np.floating], vmin:float=None, vmax:float=None
     if ax is None:
         ax = plt.gca()
 
+    if aspect is None: aspect = 3 / 4
     ax.set_aspect(aspect)
     im = ax.imshow(data,aspect='auto',vmin=vmin,vmax=vmax,origin='lower',extent=[x[0]-dx,x[-1]+dx,y[0]-dy,y[-1]+dy])
+    if bar is not None:
+        plt.colorbar(im,label=bar,ax=ax)
 
     return im
 
@@ -214,6 +227,7 @@ def semPlot(x, y, ci:str|Callable=None, zscore:bool|int=None, color:mplt.ColorTy
                   - '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
+        smooth    float = None, gaussian kernel std for smoothing over time, NOT IMPLEMENTED
         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)
@@ -419,30 +433,28 @@ def pHorzLine(p, t=None, dy=None, color:mplt.ColorType=None, ax:mpla.Axes=None):
     return
 
 
-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:
-        raise ValueError("'intervals' must have shape (n,2)")
+def plotIntervals(intervals, color:mplt.ColorType='gray', alpha=0.3, label:str=None, ax:mpla.Axes=None, **plot_kwargs):
 
+    intervals = fmatoolbox.general.consolidateIntervals(intervals)
     if ax is None:
         ax = plt.gca()
 
-    for start, stop in intervals:
-        ax.axvspan(start,stop,alpha=alpha,color=color)
+    ax.axvspan(intervals[0,0],intervals[0,1],color=color,alpha=alpha,label=label,**plot_kwargs)
+    for start, stop in intervals[1:]:
+        ax.axvspan(start,stop,color=color,alpha=alpha,**plot_kwargs)
 
 
-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):
+def plotPDF(x, mode:str=None, bandwidth:float|str=None, eps:float=None, n_points:int=None, bins=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
+        bins         (:,) float = None, bin edges, if None, bins are linearly spaced between min and max of x
         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
@@ -452,14 +464,14 @@ def plotPDF(x, mode:str=None, bandwidth:float|str=None, eps:float=None, n_points
     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 n_points is None and bins 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)
-        if label is None:
-            label = [None] * len(x)
+        if color is None or isinstance(color,str):
+            color = [color] * len(x)
+        if label is None or isinstance(label,str):
+            label = [label] * len(x)
     else:
         x = (x,)
         color = [color]
@@ -481,7 +493,10 @@ def plotPDF(x, mode:str=None, bandwidth:float|str=None, eps:float=None, n_points
         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
+                if n_points is None:
+                    this_grid = bins
+                else:
+                    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':
@@ -493,7 +508,10 @@ def plotPDF(x, mode:str=None, bandwidth:float|str=None, eps:float=None, n_points
                 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
+                if n_points is None:
+                    this_grid = bins
+                else:
+                    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
@@ -504,7 +522,10 @@ def plotPDF(x, mode:str=None, bandwidth:float|str=None, eps:float=None, n_points
             # 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]
+                if n_points is None:
+                    this_grid = bins
+                else:
+                    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)

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

@@ -7,6 +7,7 @@ import re
 import fmatoolbox.analysis
 import fmatoolbox.data
 import warnings
+import xml.etree.ElementTree
 from collections.abc import Iterable
 
 def _regionDataPath():
@@ -34,8 +35,9 @@ class regions:
         #     reload         bool = False, load spikes from original files, bypassing Regions/<basename>_spikes.npz backup
         #     anat_file      string = None, DESCRIBE
 
-        self.session = pathlib.Path(session).parent
-        self.basename = pathlib.Path(session).stem
+        session = pathlib.Path(session)
+        self.session = session.parent
+        self.basename = session.stem
         self.rat = self.basename[3:6]
 
         # 1. load events
@@ -97,10 +99,12 @@ class regions:
                 # 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()}
+                    e = {k: v[valid] for k, v in e.items() if len(v) == len(valid)}
 
                 self.events[name] = e
 
+        if isinstance(ids,str):
+            ids = [ids]
         if ids:
             self.ids = list(dict.fromkeys(ids))
             self.region = {id : {} for id in ids}
@@ -109,13 +113,13 @@ class regions:
             self.region = {}
 
         # 4. load spikes and store them per region
+        if anat_file is None:
+            anat_file = next(_regionDataPath().glob('*.anat'), None)
+        else:
+            anat_file = pathlib.Path(anat_file)
+            if not anat_file.exists():
+                anat_file = _regionDataPath() / anat_file
         if load_spikes:
-            if anat_file is None:
-                anat_file = next(_regionDataPath().glob('*.anat'), None)
-            else:
-                anat_file = pathlib.Path(anat_file)
-                if not anat_file.exists():
-                    anat_file = _regionDataPath() / anat_file
             self.region = fmatoolbox.data.loadSpikeTimes(session,output='regions',anat_file=anat_file,reload=reload)
             if ids:
                 self.region = {r: self.region[r] for r in ids}
@@ -126,6 +130,25 @@ class regions:
                 for id in self.ids:
                     self.region[id]['spikes'] = fmatoolbox.general.restrict(self.region[id]['spikes'],epoch_intervals)
 
+        # 5. load electrode groups and channels per region
+        try:
+            anat = fmatoolbox.data.loadAnatomyFile(anat_file)
+            anat = anat[anat['rat'] == int(self.rat)] # keep rat of interest, deduced from file name
+            anat_ids = np.unique(anat['region'])
+            tree = xml.etree.ElementTree.parse(session.with_suffix(".xml"))
+            root = tree.getroot()
+            channel_groups = root.find(".//channelGroups").findall("group")
+            channel_groups = [[int(element.text) for element in c.findall(".//channel")] for c in channel_groups]
+            if len(self.region):
+                for id in self.ids:
+                    self.region[id]['channels'] = {int(e): channel_groups[e-1] for e in anat[anat['region'] == id]['electrode']}
+            else:
+                self.ids = anat_ids.tolist()
+                for id in self.ids:
+                    self.region[id] = {'channels': {int(e): channel_groups[e-1] for e in anat[anat['region'] == id]['electrode']} }
+        except FileNotFoundError:
+            pass
+
         return
     
 
@@ -166,7 +189,8 @@ class regions:
             regs = regs[np.sort(idx)]
 
         # default: all electrode groups
-        all_e_groups = np.concatenate([list(self.region[r]['e_group'].keys()) for r in self.ids])
+        all_e_groups = [list(self.region[r]['e_group'].keys()) for r in self.ids if 'e_group' in self.region[r]]
+        if len(all_e_groups): all_e_groups = np.concatenate(all_e_groups)
         if np.all(e_groups == None):
             if exclusive and np.any(regs != None):
                 e_groups = np.array([None])
@@ -296,17 +320,36 @@ class regions:
 
 
     def electrodes(self,regs=None):
-        # get pooled list of electrode groups for regions
-        #
-        # arguments:
-        #     regs        (:) string = None, electrode of these regions are returned as an array, default is all regions
-        #
-        # output:
-        #     electrodes       (:) int, sorted by value
+        """
+        get pooled list of electrode groups for regions
+        
+        arguments:
+            regs          (:) string = None, electrode of these regions are returned as an array, default is all regions
+        
+        output:
+            electrodes    (:) int, sorted by value
+        """
 
         regs, _, _ = self._checkIDs(regs=regs)
 
         return np.concatenate([list(self.region[r]['e_group'].keys()) for r in regs])
+    
+
+    def channels(self,regs=None):
+        """
+        get pooled list of recording channels for regions
+        
+        arguments:
+            regs        (:) string = None, channels of these regions are returned as an array, default is all regions
+        
+        output:
+            channels    (:) int
+        """
+
+        regs, _, _ = self._checkIDs(regs=regs)
+        values = [list(self.region[r]['channels'].values()) for r in regs]
+        
+        return np.array([x for outer in values for inner in outer for x in inner])
 
 
     def units(self,regs=None,e_groups=None):
@@ -376,8 +419,8 @@ class regions:
 
     ## functions to compute quantities ##
 
-    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):
+    def firingRate(self, regs:Iterable[str]=None, e_groups:Iterable[int]=None, states:Iterable[str]=None, when=None, shift:bool=None,
+                   window=None, step:int=None, smooth=None, norm:bool=None):
         '''
         get region firing rate
 
@@ -390,7 +433,7 @@ class regions:
             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
+            smooth      float = None, gaussian kernel std to smooth rate over time
             norm        bool = False, normalize by neuron number per region
 
         output:
@@ -400,8 +443,10 @@ class regions:
 
         if states is not None and when is not None:
             raise ValueError("'states' and 'when' cannot be specified at the same time")
+        if shift is None: shift = False
         if window is None: window = 0.05
         if step is None: step = 1
+        if norm is None: norm = False
 
         regs, e_groups, states = self._checkIDs(regs=regs,e_groups=e_groups,states=states,fuse=True)
 
@@ -450,7 +495,7 @@ class regions:
         return firing_rate
     
 
-    def unitFiringRate(self,regs=None,states=None,when=None,shift=False,window=None,step=None,smooth=None):
+    def unitFiringRate(self, regs=None, states=None, when=None, shift:bool=None, window=None, step:int=None, smooth:bool=None):
         # get units' firing rate
         #
         # arguments:
@@ -461,13 +506,14 @@ class regions:
         #     window    float = 0.05 s, 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
+        #     smooth    float = None, gaussian kernel std to smooth rate over time
         #
         # output:
         #     rate      (:,n+1) float, every row is [time stamp, firing rates for n units]
 
         if states is not None and when is not None:
             raise ValueError("'states' and 'when' cannot be specified at the same time")
+        if shift is None: shift = False
         if window is None: window = 0.05
         if step is None: step = 1
 
@@ -498,7 +544,7 @@ class regions:
         return firing_rate
     
 
-    def avalanches(self,regs=None,states=None,when=None,shift=False,thresh=30,window=0.05,step=1,smooth=None,return_fr=False,norm=False):
+    def avalanches(self, regs=None, states=None, when=None, shift:bool=None, thresh:float=None, window:float=None, step:int=None, smooth:bool=None, norm:bool=None, return_fr:bool=None):
         # compute avalanches per region from population firing rate
         #
         # arguments:
@@ -510,7 +556,7 @@ class regions:
         #     window       float = 0.05 s, window size to count spikes
         #     step         float = 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
+        #     smooth       float = None, gaussian kernel std to smooth rate over time before finding avalanches
         #     norm         bool = False, normalize by neuron number per region
         #
         # output:
@@ -519,6 +565,9 @@ class regions:
         #     size_t       (m) float, size over time, in which every avalanche is separated by a 0
         #     fr           (:,r+1) float, every row is [time stamp, firing rates for r regions], optional
 
+        if thresh is None: thresh = 30
+        if return_fr is None: return_fr = False
+
         none_state = states is None
         regs, _, states = self._checkIDs(regs=regs,states=states,fuse=True)
         if none_state:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fmatoolbox
-Version: 0.1.2
+Version: 0.1.4
 Summary: Python port of FMAToolbox
 Author: Pietro Bozzo
 License-Expression: GPL-3.0-or-later
@@ -11,11 +11,13 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy
+Requires-Dist: numba
 Requires-Dist: scipy
 Requires-Dist: matplotlib
 Requires-Dist: statsmodels
-Requires-Dist: scikit-learn
-Requires-Dist: scikit-image
+Provides-Extra: assemblies
+Requires-Dist: scikit-learn; extra == "assemblies"
+Requires-Dist: scikit-image; extra == "assemblies"
 Dynamic: license-file
 
 # FMAToolbox (Python Port)

{fmatoolbox-0.1.2 → fmatoolbox-0.1.4}/src/fmatoolbox.egg-info/requires.txt

@@ -1,6 +1,9 @@
 numpy
+numba
 scipy
 matplotlib
 statsmodels
+
+[assemblies]
 scikit-learn
 scikit-image