Numpy tutorial#

This tutorial shows how pynapple interact with numpy.

Hide code cell content

import numpy as np
import pynapple as nap
import pandas as pd

Multiple time series object are available depending on the shape of the data.

  • TsdTensor : for data with of more than 2 dimensions, typically movies.

  • TsdFrame : for column-based data. It can be easily converted to a pandas.DataFrame. Columns can be labelled and selected similar to pandas.

  • Tsd : one-dimensional time series. It can be converted to a pandas.Series.

  • Ts : For timestamps data only.

Initialization#

tsdtensor = nap.TsdTensor(t=np.arange(100), d=np.random.rand(100, 5, 5), time_units="s")
tsdframe = nap.TsdFrame(t=np.arange(100), d=np.random.rand(100, 3), columns = ['a', 'b', 'c'])
tsd = nap.Tsd(t=np.arange(100), d=np.random.rand(100))
ts = nap.Ts(t=np.arange(100))

print(tsdtensor)
Time (s)
----------  -----------------------------
0.0         [[0.611523 ... 0.027079] ...]
1.0         [[0.949727 ... 0.13373 ] ...]
2.0         [[0.503115 ... 0.496432] ...]
3.0         [[0.386394 ... 0.350039] ...]
4.0         [[0.763939 ... 0.787633] ...]
5.0         [[0.114391 ... 0.540633] ...]
6.0         [[0.120549 ... 0.25243 ] ...]
...
93.0        [[0.136696 ... 0.811045] ...]
94.0        [[0.651738 ... 0.110276] ...]
95.0        [[0.368906 ... 0.618778] ...]
96.0        [[0.478228 ... 0.978061] ...]
97.0        [[0.132118 ... 0.542137] ...]
98.0        [[0.739767 ... 0.652325] ...]
99.0        [[0.257755 ... 0.52262 ] ...]
dtype: float64, shape: (100, 5, 5)

Tsd and Ts can be converted to a pandas.Series.

print(tsd.as_series())
0.0     0.646592
1.0     0.984089
2.0     0.925645
3.0     0.774598
4.0     0.788265
          ...   
95.0    0.098082
96.0    0.172970
97.0    0.763351
98.0    0.232044
99.0    0.057500
Length: 100, dtype: float64

TsdFrame to a pandas.DataFrame.

print(tsdframe.as_dataframe())
             a         b         c
0.0   0.733227  0.986379  0.669101
1.0   0.229348  0.089444  0.383686
2.0   0.449643  0.031042  0.293583
3.0   0.188225  0.428533  0.866443
4.0   0.305791  0.196290  0.673106
...        ...       ...       ...
95.0  0.995838  0.810142  0.686156
96.0  0.055568  0.004553  0.950115
97.0  0.348045  0.053083  0.941746
98.0  0.493167  0.555000  0.460708
99.0  0.664349  0.884738  0.008385

[100 rows x 3 columns]

Attributes#

The numpy array is accessible with the attributes .values, .d and functions as_array(), to_numpy(). The time index array is a TsIndex object accessible with .index or .t. .shape and .ndim are also accessible.

print(tsdtensor.ndim)
print(tsdframe.shape)
print(len(tsd))
3
(100, 3)
100

Slicing#

Slicing is very similar to numpy array. The first dimension is always time and time support is always passed on if a pynapple object is returned.

First 10 elements. Return a TsdTensor

print(tsdtensor[0:10])
Time (s)
----------  -----------------------------
0           [[0.611523 ... 0.027079] ...]
1           [[0.949727 ... 0.13373 ] ...]
2           [[0.503115 ... 0.496432] ...]
3           [[0.386394 ... 0.350039] ...]
4           [[0.763939 ... 0.787633] ...]
5           [[0.114391 ... 0.540633] ...]
6           [[0.120549 ... 0.25243 ] ...]
7           [[0.900084 ... 0.238779] ...]
8           [[0.12075 ... 0.38279] ...]
9           [[0.603163 ... 0.278725] ...]
dtype: float64, shape: (10, 5, 5)

First column. Return a Tsd

print(tsdframe[:,0])
Time (s)
----------  ---------
0.0         0.733227
1.0         0.229348
2.0         0.449643
3.0         0.188225
4.0         0.305791
5.0         0.105586
6.0         0.72852
...
93.0        0.873075
94.0        0.624198
95.0        0.995838
96.0        0.0555676
97.0        0.348045
98.0        0.493167
99.0        0.664349
dtype: float64, shape: (100,)

First element. Return a numpy ndarray

print(tsdtensor[0])
[[0.61152332 0.96238718 0.83985532 0.11649124 0.02707877]
 [0.29979916 0.05598834 0.02775713 0.96529415 0.54700353]
 [0.60165231 0.05826709 0.13514485 0.87337677 0.74578826]
 [0.0192148  0.41589079 0.90698427 0.06381839 0.63473013]
 [0.75152441 0.13318887 0.87821308 0.63765204 0.92611065]]

The time support is never changing when slicing time down.

print(tsd.time_support)
print(tsd[0:20].time_support)
  index    start    end
      0        0     99
shape: (1, 2), time unit: sec.
  index    start    end
      0        0     99
shape: (1, 2), time unit: sec.

TsdFrame offers special slicing similar to pandas.DataFrame.

Only TsdFrame can have columns labelling and indexing.

print(tsdframe.loc['a'])
print(tsdframe.loc[['a', 'c']])
Time (s)
----------  ---------
0.0         0.733227
1.0         0.229348
2.0         0.449643
3.0         0.188225
4.0         0.305791
5.0         0.105586
6.0         0.72852
...
93.0        0.873075
94.0        0.624198
95.0        0.995838
96.0        0.0555676
97.0        0.348045
98.0        0.493167
99.0        0.664349
dtype: float64, shape: (100,)
Time (s)            a           c
----------  ---------  ----------
0.0         0.733227   0.669101
1.0         0.229348   0.383686
2.0         0.449643   0.293583
3.0         0.188225   0.866443
4.0         0.305791   0.673106
5.0         0.105586   0.744873
6.0         0.72852    0.186156
...
93.0        0.873075   0.839322
94.0        0.624198   0.189345
95.0        0.995838   0.686156
96.0        0.0555676  0.950115
97.0        0.348045   0.941746
98.0        0.493167   0.460708
99.0        0.664349   0.00838512
dtype: float64, shape: (100, 2)

Arithmetic#

Arithmetical operations works similar to numpy

tsd = nap.Tsd(t=np.arange(5), d=np.ones(5))
print(tsd + 1)
Time (s)
----------  --
0            2
1            2
2            2
3            2
4            2
dtype: float64, shape: (5,)

It is possible to do array operations on the time series provided that the dimensions matches. The output will still be a time series object.

print(tsd - np.ones(5))
Time (s)
----------  --
0            0
1            0
2            0
3            0
4            0
dtype: float64, shape: (5,)

Nevertheless operations like this are not permitted :

try:
	tsd + tsd
except Exception as error:
	print(error)
operand type(s) all returned NotImplemented from __array_ufunc__(<ufunc 'add'>, '__call__', Time (s)
----------  --
0            1
1            1
2            1
3            1
4            1
dtype: float64, shape: (5,), Time (s)
----------  --
0            1
1            1
2            1
3            1
4            1
dtype: float64, shape: (5,)): 'Tsd', 'Tsd'

Array operations#

The most common numpy functions will return a time series if the output first dimension matches the shape of the time index.

Here the TsdTensor is averaged along the time axis. The output is a numpy array.

print(np.mean(tsdtensor, 0))
[[0.536599   0.54164155 0.48839922 0.49385691 0.52099498]
 [0.52383804 0.50186069 0.48628244 0.55292889 0.48339302]
 [0.52317115 0.47182542 0.48364284 0.50135417 0.52876523]
 [0.47794725 0.48380574 0.52918171 0.49405399 0.51939713]
 [0.43540926 0.51951296 0.52159607 0.50852038 0.50354151]]

Here averaging across the second dimension returns a TsdFrame.

print(np.mean(tsdtensor, 1))
Time (s)           0         1         2         3         4
----------  --------  --------  --------  --------  --------
0.0         0.456743  0.325144  0.557591  0.531327  0.576142
1.0         0.783584  0.512371  0.427424  0.643128  0.470464
2.0         0.489323  0.355449  0.334267  0.43296   0.620413
3.0         0.512438  0.424747  0.523701  0.468134  0.325161
4.0         0.602308  0.418895  0.604669  0.561424  0.617678
5.0         0.404158  0.580569  0.66613   0.345294  0.602184
6.0         0.480735  0.555899  0.598439  0.45478   0.317449
...
93.0        0.153355  0.484987  0.40378   0.364508  0.594428
94.0        0.660447  0.394708  0.307995  0.445763  0.395597
95.0        0.564027  0.576455  0.62835   0.370878  0.487437
96.0        0.566497  0.67298   0.486008  0.465328  0.463802
97.0        0.302482  0.327147  0.366494  0.291806  0.575064
98.0        0.540577  0.490841  0.745808  0.477604  0.695232
99.0        0.373081  0.267232  0.672724  0.424779  0.517331
dtype: float64, shape: (100, 5)

This is not true for FFT functions though.

try:
	np.fft.fft(tsd)
except Exception as error:
	print(error)
no implementation found for 'numpy.fft.fft' on types that implement __array_function__: [<class 'pynapple.core.time_series.Tsd'>]

Concatenating#

It is possible to concatenate time series providing than they don’t overlap meaning time indexe should be already sorted through all time series to concatenate

tsd1 = nap.Tsd(t=np.arange(5), d=np.ones(5))
tsd2 = nap.Tsd(t=np.arange(5)+10, d=np.ones(5)*2)
tsd3 = nap.Tsd(t=np.arange(5)+20, d=np.ones(5)*3)

print(np.concatenate((tsd1, tsd2, tsd3)))
Time (s)
----------  --
0.0          1
1.0          1
2.0          1
3.0          1
4.0          1
10.0         2
11.0         2
...
13.0         2
14.0         2
20.0         3
21.0         3
22.0         3
23.0         3
24.0         3
dtype: float64, shape: (15,)

It’s also possible to concatenate vertically if time indexes matches up to pynapple float precision

tsdframe = nap.TsdFrame(t=np.arange(5), d=np.random.randn(5, 3))

print(np.concatenate((tsdframe, tsdframe), 1))
Time (s)            0           1           2          0           1  ...
----------  ---------  ----------  ----------  ---------  ----------  -----
0           -0.521293  -0.232515    0.0285713  -0.521293  -0.232515   ...
1            1.21877    2.01618     0.7841      1.21877    2.01618    ...
2           -0.161076   0.11268    -0.334949   -0.161076   0.11268    ...
3            0.347291   0.339148    0.297549    0.347291   0.339148   ...
4           -0.191611  -0.0128921   0.45322    -0.191611  -0.0128921  ...
dtype: float64, shape: (5, 6)

Splitting#

Array split functions are also implemented

print(np.array_split(tsdtensor[0:10], 2))
[Time (s)
----------  -----------------------------
0           [[0.611523 ... 0.027079] ...]
1           [[0.949727 ... 0.13373 ] ...]
2           [[0.503115 ... 0.496432] ...]
3           [[0.386394 ... 0.350039] ...]
4           [[0.763939 ... 0.787633] ...]
dtype: float64, shape: (5, 5, 5), Time (s)
----------  -----------------------------
5           [[0.114391 ... 0.540633] ...]
6           [[0.120549 ... 0.25243 ] ...]
7           [[0.900084 ... 0.238779] ...]
8           [[0.12075 ... 0.38279] ...]
9           [[0.603163 ... 0.278725] ...]
dtype: float64, shape: (5, 5, 5)]

Modifying#

It is possible to modify a time series element wise

print(tsd1)

tsd1[0] = np.pi

print(tsd1)
Time (s)
----------  --
0            1
1            1
2            1
3            1
4            1
dtype: float64, shape: (5,)
Time (s)
----------  -------
0           3.14159
1           1
2           1
3           1
4           1
dtype: float64, shape: (5,)

It is also possible to modify a time series with logical operations

tsd[tsd.values>0.5] = 0.0

print(tsd)
Time (s)
----------  --
0            0
1            0
2            0
3            0
4            0
dtype: float64, shape: (5,)

Sorting#

It is not possible to sort along the first dimension as it would break the sorting of the time index

tsd = nap.Tsd(t=np.arange(100), d=np.random.rand(100))

try:
	np.sort(tsd)
except Exception as error:
	print(error)
no implementation found for 'numpy.sort' on types that implement __array_function__: [<class 'pynapple.core.time_series.Tsd'>]