Introduction to pynapple#
The goal of this tutorial is to quickly learn enough about pynapple to get started with data analysis. This tutorial assumes familiarity with the basics functionalities of numpy.
You can check how to install pynapple here.
Important
By default, pynapple will assume a time units in seconds when passing timestamps array or time parameters such as bin size (unless specified with the time_units argument)
Importing pynapple#
The convention is to import pynapple with a namespace:
import pynapple as nap
Show code cell content
import numpy as np
import matplotlib.pyplot as plt
import pandas as pd
import seaborn as sns
custom_params = {"axes.spines.right": False, "axes.spines.top": False}
sns.set_theme(style="ticks", palette="colorblind", font_scale=1.5, rc=custom_params)
Instantiating pynapple objects#
nap.Tsd: 1-dimensional time serie#
If you have a 1-dimensional time series, you use the nap.Tsd object. The arguments t and d are the arguments for timestamps and data.
tsd = nap.Tsd(t=np.arange(100), d=np.random.rand(100))
print(tsd)
Time (s)
---------- ---------
0.0 0.991691
1.0 0.878054
2.0 0.56957
3.0 0.0217641
4.0 0.595506
5.0 0.527773
6.0 0.481971
...
93.0 0.704771
94.0 0.53313
95.0 0.583912
96.0 0.95727
97.0 0.361527
98.0 0.081336
99.0 0.36766
dtype: float64, shape: (100,)
nap.TsdFrame: 2-dimensional time series#
If you have a 2-dimensional time series, you use the nap.TsdFrame object. The arguments t and d are the arguments for timestamps and data. You can add the argument columns to label each columns.
tsdframe = nap.TsdFrame(
t=np.arange(100), d=np.random.rand(100, 3), columns=["a", "b", "c"]
)
print(tsdframe)
Time (s) a b c
---------- ------- ------- -------
0.0 0.63868 0.42384 0.23059
1.0 0.14538 0.3373 0.44784
2.0 0.54242 0.44937 0.24066
3.0 0.92209 0.34345 0.84512
4.0 0.7013 0.16674 0.01028
5.0 0.70893 0.40511 0.48764
6.0 0.03873 0.46218 0.4323
... ... ... ...
93.0 0.81708 0.13351 0.85226
94.0 0.82517 0.1992 0.26928
95.0 0.66634 0.51917 0.4834
96.0 0.56898 0.65701 0.07679
97.0 0.78973 0.96988 0.72789
98.0 0.56096 0.79381 0.32728
99.0 0.50694 0.86009 0.08777
dtype: float64, shape: (100, 3)
nap.TsdTensor: n-dimensionals time series#
If you have larger than 2 dimensions time series (typically movies), you use the nap.TsdTensor object . The arguments t and d are the arguments for timestamps and data.
tsdtensor = nap.TsdTensor(
t=np.arange(100), d=np.random.rand(100, 3, 4)
)
print(tsdtensor)
Time (s)
---------- -----------------------------
0.0 [[0.299382 ... 0.09484 ] ...]
1.0 [[0.534376 ... 0.738099] ...]
2.0 [[0.628674 ... 0.207617] ...]
3.0 [[0.970707 ... 0.726446] ...]
4.0 [[0.794445 ... 0.335502] ...]
5.0 [[0.437695 ... 0.921305] ...]
6.0 [[0.40391 ... 0.124282] ...]
...
93.0 [[0.982722 ... 0.979301] ...]
94.0 [[0.873808 ... 0.454348] ...]
95.0 [[0.84631 ... 0.607331] ...]
96.0 [[0.815375 ... 0.346971] ...]
97.0 [[0.421769 ... 0.013565] ...]
98.0 [[0.204804 ... 0.81888 ] ...]
99.0 [[0.357628 ... 0.134676] ...]
dtype: float64, shape: (100, 3, 4)
nap.IntervalSet: intervals#
The IntervalSet object stores multiple epochs with a common time unit in a table format. The epochs are strictly non-overlapping. Both start and end arguments are necessary.
epochs = nap.IntervalSet(start=[0, 10], end=[5, 15])
print(epochs)
index start end
0 0 5
1 10 15
shape: (2, 2), time unit: sec.
nap.Ts: timestamps#
Ts object stores timestamps data (typically spike times or reward times). The argument t for timestamps is necessary.
ts = nap.Ts(t=np.sort(np.random.uniform(0, 100, 10)))
print(ts)
Time (s)
6.667306675
19.408275516
21.798220176
22.912328015
26.09514005
27.910689125
38.013489225
43.317813103
68.029660241
95.924484229
shape: 10
nap.TsGroup: group of timestamps#
TsGroup is a dictionnary that stores multiple time series with different time stamps (.i.e. a group of neurons with different spike times from one session). The first argument data can be a dictionnary of Ts, Tsd or numpy 1d array.
data = {
0: nap.Ts(t=np.sort(np.random.uniform(0, 100, 1000))),
1: nap.Ts(t=np.sort(np.random.uniform(0, 100, 2000))),
2: nap.Ts(t=np.sort(np.random.uniform(0, 100, 3000))),
}
tsgroup = nap.TsGroup(data)
print(tsgroup, "\n")
Index rate
------- -------
0 10.0007
1 20.0014
2 30.002
Interaction between pynapple objects#
Time support : attribute of time series#
A key feature of how pynapple manipulates time series is an inherent time support object defined for Ts, Tsd, TsdFrame and TsGroup objects. The time support object is defined as an IntervalSet that provides the time serie with a context. For example, the restrict operation will automatically update the time support object for the new time series. Ideally, the time support object should be defined for all time series when instantiating them. If no time series is given, the time support is inferred from the start and end of the time series.
In this example, a Tsd is instantiated with and without a time support of intervals 0 to 5 seconds. Notice how the shape of the Tsd varies.
time_support = nap.IntervalSet(start=0, end=2)
print(time_support)
index start end
0 0 2
shape: (1, 2), time unit: sec.
Without time support :
print(nap.Tsd(t=[0, 1, 2, 3, 4], d=[0, 1, 2, 3, 4]))
Time (s)
---------- --
0 0
1 1
2 2
3 3
4 4
dtype: int64, shape: (5,)
With time support :
print(
nap.Tsd(
t=[0, 1, 2, 3, 4], d=[0, 1, 2, 3, 4],
time_support = time_support
)
)
Time (s)
---------- --
0 0
1 1
2 2
dtype: int64, shape: (3,)
The time support object has become an attribute of the time series. Depending on the operation applied to the time series, it will be updated.
tsd = nap.Tsd(
t=np.arange(10), d=np.random.randn(10),
time_support = time_support
)
print(tsd.time_support)
index start end
0 0 2
shape: (1, 2), time unit: sec.
Restricting time series to epochs#
The central function of pynapple is the restrict method of Ts, Tsd, TsdFrame and TsGroup. The argument is an IntervalSet object. Only time points within the intervals of the IntervalSet object are returned. The time support of the time series is updated accordingly.
tsd = nap.Tsd(t=np.arange(10), d=np.random.randn(10))
ep = nap.IntervalSet(start=[0, 7], end=[3.5, 12.4])
print(ep)
index start end
0 0 3.5
1 7 12.4
shape: (2, 2), time unit: sec.
From :
print(tsd)
Time (s)
---------- ---------
0 0.322283
1 0.254975
2 -1.34129
3 0.537378
4 0.334428
5 1.0228
6 1.31155
7 -2.01892
8 -0.161858
9 1.87146
dtype: float64, shape: (10,)
to :
new_tsd = tsd.restrict(ep)
print(new_tsd)
Time (s)
---------- ---------
0 0.322283
1 0.254975
2 -1.34129
3 0.537378
7 -2.01892
8 -0.161858
9 1.87146
dtype: float64, shape: (7,)
Numpy & pynapple#
Pynapple relies on numpy to store the data. Pynapple objects behave very similarly to numpy and numpy functions can be applied directly
tsdtensor = nap.TsdTensor(t=np.arange(100), d=np.random.rand(100, 3, 4))
If a numpy function preserves the time axis, a pynapple object is returned.
In this example, averaging a TsdTensor along the second dimension returns a TsdFrame:
print(
np.mean(tsdtensor, 1)
)
Time (s) 0 1 2 3
---------- ------- ------- ------- -------
0.0 0.91931 0.49163 0.48314 0.53558
1.0 0.41381 0.26711 0.71669 0.83024
2.0 0.44027 0.72343 0.21441 0.50981
3.0 0.52665 0.38373 0.50334 0.39794
4.0 0.52574 0.74995 0.47634 0.31235
5.0 0.76383 0.40585 0.47274 0.60316
6.0 0.43952 0.59599 0.56904 0.5767
... ... ... ... ...
93.0 0.24024 0.5717 0.67806 0.33904
94.0 0.50897 0.62184 0.58588 0.53154
95.0 0.25661 0.33535 0.41324 0.54158
96.0 0.60767 0.55604 0.48225 0.35808
97.0 0.23438 0.34217 0.47929 0.5564
98.0 0.48492 0.36057 0.89394 0.5369
99.0 0.3236 0.28738 0.24517 0.84952
dtype: float64, shape: (100, 4)
Averaging along the time axis will return a numpy array object:
print(
np.mean(tsdtensor, 0)
)
[[0.50734676 0.49481297 0.51421095 0.5182 ]
[0.509968 0.52054223 0.53097932 0.47655847]
[0.51991377 0.46976489 0.48901156 0.4984729 ]]
Slicing objects#
Slicing time series and intervals#
Like numpy array#
Ts, Tsd, TsdFrame, TsdTensor and IntervalSet can be sliced similar to numpy array:
tsdframe = nap.TsdFrame(t=np.arange(10)/10, d=np.random.randn(10,4))
print(tsdframe)
Time (s) 0 1 2 3
---------- -------- -------- -------- --------
0 0.55312 -1.56861 -0.29659 2.02334
0.1 -0.09579 0.70111 1.58219 1.08283
0.2 0.1258 0.67881 1.3887 -0.27204
0.3 1.17151 1.53438 0.39724 0.66557
0.4 -1.44539 0.35818 0.78005 -0.06092
0.5 0.0402 0.10742 1.09954 0.33018
0.6 -0.0799 -1.28335 0.93629 0.24307
0.7 -0.93259 -0.07853 -0.25258 0.04213
0.8 -0.15499 -0.20272 0.90472 -2.89585
0.9 1.0779 0.8528 -1.59111 0.5121
dtype: float64, shape: (10, 4)
print(tsdframe[4:7])
Time (s) 0 1 2 3
---------- -------- -------- ------- --------
0.4 -1.44539 0.35818 0.78005 -0.06092
0.5 0.0402 0.10742 1.09954 0.33018
0.6 -0.0799 -1.28335 0.93629 0.24307
dtype: float64, shape: (3, 4)
print(tsdframe[:,0])
Time (s)
---------- ----------
0 0.553121
0.1 -0.095791
0.2 0.125801
0.3 1.17151
0.4 -1.44539
0.5 0.0401954
0.6 -0.0799005
0.7 -0.932593
0.8 -0.154992
0.9 1.0779
dtype: float64, shape: (10,)
ep = nap.IntervalSet(start=[0, 10, 20], end=[4, 15, 25])
print(ep)
index start end
0 0 4
1 10 15
2 20 25
shape: (3, 2), time unit: sec.
print(ep[0:2])
index start end
0 0 4
1 10 15
shape: (2, 2), time unit: sec.
print(ep[1])
index start end
0 10 15
shape: (1, 2), time unit: sec.
Like pandas DataFrame#
Important
This page references all the way to slice TsdFrame
TsdFrame can be sliced like pandas DataFrame when the columns have been labelled with strings :
tsdframe = nap.TsdFrame(t=np.arange(10), d=np.random.randn(10,3), columns=['a', 'b', 'c'])
print(tsdframe['a'])
Time (s)
---------- ---------
0 -1.14896
1 0.862212
2 -0.254708
3 0.532517
4 -0.613053
5 0.345788
6 1.21915
7 1.17997
8 -1.7677
9 0.574119
dtype: float64, shape: (10,)
but integer-indexing only works like numpy if a list of integers is used to label columns :
tsdframe = nap.TsdFrame(t=np.arange(4), d=np.random.randn(4,3), columns=[3, 2, 1])
print(tsdframe, "\n")
print(tsdframe[3])
Time (s) 3 2 1
---------- -------- -------- --------
0 0.82394 -0.33304 -0.61448
1 -1.75338 -0.14331 -1.40093
2 0.52168 -0.56481 -0.27352
3 -1.43815 1.66964 0.63027
dtype: float64, shape: (4, 3)
Time (s) 3 2 1
---------- -------- ------- -------
3 -1.43815 1.66964 0.63027
dtype: float64, shape: (1, 3)
The loc method can be used to slice column-based only :
print(tsdframe.loc[3])
Slicing TsGroup#
TsGroup object can be indexed to return directly the timestamp object or sliced to return a new TsGroup.
Indexing :
print(tsgroup[0], "\n")
Time (s)
0.117286627
0.131987052
0.168733937
0.296463959
0.340591132
0.379308433
0.431619699
...
99.301702839
99.405566924
99.615858077
99.643328302
99.728752203
99.917037375
99.95328196
shape: 1000
Slicing :
print(tsgroup[[0, 2]])
Index rate
------- -------
0 10.0007
2 30.002
Core functions#
Objects have methods that can help transform and refine time series. This is a non exhaustive list.
Binning : counting events#
Time series objects have the count method that count the number of timestamps. This is typically used when counting number of spikes within a particular bin over multiple intervals. The returned object is a Tsd or TsdFrame with the timestamps being the center of the bins.
count = tsgroup.count(1)
print(count)
Time (s) 0 1 2
------------ ---- ---- ----
0.505556632 12.0 19.0 33.0
1.505556632 11.0 23.0 30.0
2.505556632 7.0 16.0 29.0
3.505556632 10.0 26.0 35.0
4.505556632 10.0 23.0 35.0
5.505556632 13.0 15.0 25.0
6.505556632 15.0 16.0 36.0
... ... ... ...
93.505556632 12.0 20.0 33.0
94.505556632 6.0 14.0 34.0
95.505556632 14.0 21.0 29.0
96.505556632 10.0 18.0 29.0
97.505556632 11.0 30.0 26.0
98.505556632 11.0 18.0 32.0
99.505556632 10.0 17.0 34.0
dtype: float64, shape: (100, 3)
Thresholding#
Some time series have specific methods. The threshold method of Tsd returns a new Tsd with all the data above or below a given value.
tsd = nap.Tsd(t=np.arange(10), d=np.random.rand(10))
print(tsd)
print(tsd.threshold(0.5))
Time (s)
---------- ---------
0 0.908153
1 0.196309
2 0.0422342
3 0.0303763
4 0.319643
5 0.432593
6 0.246234
7 0.433284
8 0.548415
9 0.830386
dtype: float64, shape: (10,)
Time (s)
---------- --------
0 0.908153
8 0.548415
9 0.830386
dtype: float64, shape: (3,)
An important aspect of the tresholding is that the time support get updated based on the time points remaining. To get the epochs above/below a certain threshold, you can access the time support of the returned object.
print(tsd.time_support)
print(tsd.threshold(0.5, "below").time_support)
index start end
0 0 9
shape: (1, 2), time unit: sec.
index start end
0 0.5 7.5
shape: (1, 2), time unit: sec.
Time-bin averaging of data#
Many analyses requires to bring time series to the same rates and same dimensions. A quick way to downsample a time series to match in size for example a count array is to bin average. The bin_average method takes a bin size in unit of time.
tsdframe = nap.TsdFrame(t=np.arange(0, 100)/10, d=np.random.randn(100,3))
print(tsdframe)
Time (s) 0 1 2
---------- -------- -------- --------
0.0 -0.20728 0.33284 2.62153
0.1 1.25891 0.13394 -0.28154
0.2 1.13409 -0.48356 0.78428
0.3 1.06915 -0.35117 0.33834
0.4 0.57323 -0.9018 1.5373
0.5 0.61097 1.13733 0.2125
0.6 0.44079 1.13579 0.39532
... ... ... ...
9.3 0.87495 0.36067 -0.25547
9.4 -0.95447 -0.23164 -1.66755
9.5 0.77798 -0.71692 0.01233
9.6 0.73776 1.47585 -0.27698
9.7 -0.61964 2.51276 0.35579
9.8 0.17757 1.5973 0.53888
9.9 1.14688 0.67403 -2.11027
dtype: float64, shape: (100, 3)
Here we go from a timepoint every 100ms to a timepoint every second.
print(tsdframe.bin_average(1))
Time (s) 0 1 2
---------- -------- -------- --------
0.5 0.32056 0.23392 0.32167
1.5 0.18521 -0.13642 0.10674
2.5 -0.49167 -0.09028 0.33788
3.5 -0.11772 -0.50988 0.54054
4.5 0.54541 -0.1257 -0.07248
5.5 0.22253 -0.2187 -0.51028
6.5 -0.17116 -0.68266 -0.18762
7.5 -0.15423 0.03029 -0.39522
8.5 -0.21447 0.20737 0.20981
9.5 0.23202 0.55792 0.03235
dtype: float64, shape: (10, 3)
Loading data#
See here for more details about loading data.
Loading NWB#
Pynapple supports by default the NWB standard.
NWB files can be loaded with :
nwb = nap.load_file("path/to/my.nwb")
or directly with the NWBFile class:
nwb = nap.NWBFile("path/to/my.nwb")
print(nwb)
my.nwb
┍━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━┑
│ Keys │ Type │
┝━━━━━━━━━━━━━━━━━┿━━━━━━━━━━━━━┥
│ units │ TsGroup │
┕━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━┙
The returned object behaves like a dictionnary. The first column indicates the keys. The second column indicate the object type.
print(nwb['units'])
Index rate location group
------- ------ ---------- -------
0 1.0 brain 0
1 1.0 brain 0
2 1.0 brain 0
Overview of advanced analysis#
The process module of pynapple contains submodules that group methods that can be applied for high level analysis. All of the method are directly available from the nap namespace.
Important
Some functions have been doubled given the nature of the data. For instance, computing a 1d tuning curves from spiking activity requires the nap.compute_1d_tuning_curves. The same function for calcium imaging data which is a continuous time series is available with nap.compute_1d_tuning_curves_continuous.
This module computes correlograms of discrete events, for example the cross-correlograms of a population of neurons.
The decoding module perfoms bayesian decoding given a set of tuning curves and a TsGroup.
Bandpass, lowpass, highpass or bandstop filtering can be done to any time series using either Butterworth filter or windowed-sinc convolution.
The perievent module has a set of functions to center time series and timestamps data around a particular events.
The randomize module holds multiple technique to shuffle timestamps in order to create surrogate datasets.
The spectrum module contains the methods to return the (mean) power spectral density of a time series.
Tuning curves of neurons based on spiking or calcium activity can be computed.
The wavelets module performs Morlet wavelets decomposition of a time series.