pynapple.core.time_series.TsdTensor#

class pynapple.core.time_series.TsdTensor(t, d, time_units='s', time_support=None, load_array=True, **kwargs)[source]#

Bases: _BaseTsd

Container for neurophysiological time series with more than 2 dimensions (movies).

rate#

Frequency of the time series (Hz) computed over the time support

Type:: float

time_support#

The time support of the time series

Type:: IntervalSet

__init__(t, d, time_units='s', time_support=None, load_array=True, **kwargs)[source]#

TsdTensor initializer

Parameters:

t (numpy.ndarray) – the time index t
d (numpy.ndarray) – The data
time_units (str, optional) – The time units in which times are specified (‘us’, ‘ms’, ‘s’ [default]).
time_support (IntervalSet, optional) – The time support of the TsdFrame object
load_array (bool, optional) – Whether the data should be converted to a numpy (or jax) array. Useful when passing a memory map object like zarr. Default is True. Does not apply if d is already a numpy array.

Methods

`__init__`(t, d[, time_units, time_support, ...])	TsdTensor initializer
`as_array`()	Return the data.
`bin_average`(bin_size[, ep, time_units])	Bin the data by averaging points within bin_size bin_size should be seconds unless specified.
`convolve`(array[, ep, trim])	Return the discrete linear convolution of the time series with a one dimensional sequence.
`copy`()	Copy the data, index and time support
`count`(*args[, dtype])	Count occurences of events within bin_size or within a set of bins defined as an IntervalSet.
`data`()	Return the data.
`dropna`([update_time_support])	Drop every rows containing NaNs.
`end_time`([units])	The last time index in the time series object
`find_support`(min_gap[, time_units])	find the smallest (to a min_gap resolution) IntervalSet containing all the times in the Tsd
`get`(start[, end, time_units])	Slice the time series from start to end such that all the timestamps satisfy start<=t<=end.
`get_slice`(start[, end, time_unit])	Get a slice object from the time series data based on the start and end values such that all the timestamps satisfy start<=t<=end.
`interpolate`(ts[, ep, left, right])	Wrapper of the numpy linear interpolation method.
`restrict`(iset)	Restricts a time series object to a set of time intervals delimited by an IntervalSet object
`save`(filename)	Save TsdTensor object in npz format.
`smooth`(std[, windowsize, time_units, ...])	Smooth a time series with a gaussian kernel.
`start_time`([units])	The first time index in the time series object
`times`([units])	The time index of the object, returned as np.double in the desired time units.
`to_numpy`()	Return the data as a numpy.ndarray.
`value_from`(data[, ep])	Replace the value with the closest value from Tsd/TsdFrame/TsdTensor argument

Attributes

`d`
`end`
`ndim`
`shape`
`size`
`start`
`t`

as_array()#

Return the data.

Returns:: out – _
Return type:: array-like

bin_average(bin_size, ep=None, time_units='s')#

Bin the data by averaging points within bin_size bin_size should be seconds unless specified. If no epochs is passed, the data will be binned based on the time support.

Parameters:

bin_size (float) – The bin size (default is second)
ep (None or IntervalSet, optional) – IntervalSet to restrict the operation
time_units (str, optional) – Time units of bin size (‘us’, ‘ms’, ‘s’ [default])

Returns:

out – A Tsd object indexed by the center of the bins and holding the averaged data points.

Return type:

Tsd, TsdFrame, TsdTensor

Examples

This example shows how to bin data within bins of 0.1 second.

>>> import pynapple as nap
>>> import numpy as np
>>> tsd = nap.Tsd(t=np.arange(100), d=np.random.rand(100))
>>> bintsd = tsd.bin_average(0.1)

An epoch can be specified:

>>> ep = nap.IntervalSet(start = 10, end = 80, time_units = 's')
>>> bintsd = tsd.bin_average(0.1, ep=ep)

And bintsd automatically inherit ep as time support:

>>> bintsd.time_support
>>>    start    end
>>> 0  10.0     80.0

convolve(array, ep=None, trim='both')#

Return the discrete linear convolution of the time series with a one dimensional sequence.

A parameter ep can control the epochs for which the convolution will apply. Otherwise the convolution is made over the time support.

This function assume a constant sampling rate of the time series.

The only mode supported is full. The returned object is trimmed to match the size of the original object. The parameter trim controls which side the trimming operates. Default is ‘both’.

See the numpy documentation here : https://numpy.org/doc/stable/reference/generated/numpy.convolve.html

Parameters:

array (array-like) – 1-D or 2-D array with kernel(s) to be used for convolution. First dimension is assumed to be time.
ep (None, optional) – The epochs to apply the convolution
trim (str, optional) – The side on which to trim the output of the convolution (‘left’, ‘right’, ‘both’ [default])

Returns:

The convolved time series

Return type:

Tsd, TsdFrame or TsdTensor

copy()#: Copy the data, index and time support

count(*args, dtype=None, **kwargs)#

Count occurences of events within bin_size or within a set of bins defined as an IntervalSet. You can call this function in multiple ways :

1. tsd.count(bin_size=1, time_units = ‘ms’) -> Count occurence of events within a 1 ms bin defined on the time support of the object.

2. tsd.count(1, ep=my_epochs) -> Count occurent of events within a 1 second bin defined on the IntervalSet my_epochs.

3. tsd.count(ep=my_bins) -> Count occurent of events within each epoch of the intervalSet object my_bins

4. tsd.count() -> Count occurent of events within each epoch of the time support.

bin_size should be seconds unless specified. If bin_size is used and no epochs is passed, the data will be binned based on the time support of the object.

Parameters:

bin_size (None or float, optional) – The bin size (default is second)
ep (None or IntervalSet, optional) – IntervalSet to restrict the operation
time_units (str, optional) – Time units of bin size (‘us’, ‘ms’, ‘s’ [default])
dtype (type, optional) – Data type for the count. Default is np.int64.

Returns:

out – A Tsd object indexed by the center of the bins.

Return type:

Tsd

Examples

This example shows how to count events within bins of 0.1 second.

>>> import pynapple as nap
>>> import numpy as np
>>> t = np.unique(np.sort(np.random.randint(0, 1000, 100)))
>>> ts = nap.Ts(t=t, time_units='s')
>>> bincount = ts.count(0.1)

An epoch can be specified:

>>> ep = nap.IntervalSet(start = 100, end = 800, time_units = 's')
>>> bincount = ts.count(0.1, ep=ep)

And bincount automatically inherit ep as time support:

>>> bincount.time_support
    start    end
0  100.0  800.0

property d#

data()#

Return the data.

Returns:: out – _
Return type:: array-like

dropna(update_time_support=True)#

Drop every rows containing NaNs. By default, the time support is updated to start and end around the time points that are non NaNs. To change this behavior, you can set update_time_support=False.

Parameters:: update_time_support (bool, optional)
Returns:: The time series without the NaNs
Return type:: Tsd, TsdFrame or TsdTensor

property end#

end_time(units='s')#

The last time index in the time series object

Parameters:: units (str, optional) – (‘us’, ‘ms’, ‘s’ [default])
Returns:: out – _
Return type:: numpy.float64

find_support(min_gap, time_units='s')#

find the smallest (to a min_gap resolution) IntervalSet containing all the times in the Tsd

Parameters:

min_gap (float or int) – minimal interval between timestamps
time_units (str, optional) – Time units of min gap

Returns:

Description

Return type:

IntervalSet

get(start, end=None, time_units='s')#

Slice the time series from start to end such that all the timestamps satisfy start<=t<=end. If end is None, only the timepoint closest to start is returned.

By default, the time support doesn’t change. If you want to change the time support, use the restrict function.

Parameters:

start (float or int) – The start (or closest time point if end is None)
end (float or int or None) – The end

get_slice(start, end=None, time_unit='s')#

Get a slice object from the time series data based on the start and end values such that all the timestamps satisfy start<=t<=end. If end is None, only the timepoint closest to start is returned.

By default, the time support doesn’t change. If you want to change the time support, use the restrict function.

This function is equivalent of calling the get method.

Parameters:

start (int or float) – The starting value for the slice.
end (int or float, optional) – The ending value for the slice. Defaults to None.
time_unit (str, optional) – The time unit for the start and end values. Defaults to “s” (seconds).

Returns:

slice – A slice determining the start and end indices, with unit step Slicing the array will be equivalent to calling get: ts[s].t == ts.get(start, end).t with s being the slice object.

Return type:

slice

Raises:

ValueError –

If start or end is not a number. - If start is greater than end.

Examples

>>> import pynapple as nap

>>> ts = nap.Ts(t = [0, 1, 2, 3])

>>> # slice over a range
>>> start, end = 1.2, 2.6
>>> print(ts.get_slice(start, end))  # returns `slice(2, 3, None)`
>>> start, end = 1., 2.
>>> print(ts.get_slice(start, end, mode="forward"))  # returns `slice(1, 3, None)`

>>> # slice a single value
>>> start = 1.2
>>> print(ts.get_slice(start))  # returns `slice(1, 2, None)`
>>> start = 2.
>>> print(ts.get_slice(start)) # returns `slice(2, 3, None)`

interpolate(ts, ep=None, left=None, right=None)#

Wrapper of the numpy linear interpolation method. See [numpy interpolate](https://numpy.org/doc/stable/reference/generated/numpy.interp.html) for an explanation of the parameters. The argument ts should be Ts, Tsd, TsdFrame, TsdTensor to ensure interpolating from sorted timestamps in the right unit,

Parameters:

ts (Ts, Tsd, TsdFrame or TsdTensor) – The object holding the timestamps
ep (IntervalSet, optional) – The epochs to use to interpolate. If None, the time support of Tsd is used.
left (None, optional) – Value to return for ts < tsd[0], default is tsd[0].
right (None, optional) – Value to return for ts > tsd[-1], default is tsd[-1].

property ndim#

restrict(iset)#

Restricts a time series object to a set of time intervals delimited by an IntervalSet object

Parameters:: iset (IntervalSet) – the IntervalSet object
Returns:: Tsd object restricted to ep
Return type:: Ts, Tsd, TsdFrame or TsdTensor

Examples

The Ts object is restrict to the intervals defined by ep.

>>> import pynapple as nap
>>> import numpy as np
>>> t = np.unique(np.sort(np.random.randint(0, 1000, 100)))
>>> ts = nap.Ts(t=t, time_units='s')
>>> ep = nap.IntervalSet(start=0, end=500, time_units='s')
>>> newts = ts.restrict(ep)

The time support of newts automatically inherit the epochs defined by ep.

>>> newts.time_support
    start    end
0    0.0  500.0

save(filename)[source]#

Save TsdTensor object in npz format. The file will contain the timestamps, the data and the time support.

The main purpose of this function is to save small/medium sized time series objects. For example, you extracted several channels from your recording and filtered them. You can save the filtered channels as a npz to avoid reprocessing it.

You can load the object with nap.load_file. Keys are ‘t’, ‘d’, ‘start’, ‘end’, ‘type’ and ‘columns’ for columns names.

Parameters:: filename (str) – The filename

Examples

>>> import pynapple as nap
>>> import numpy as np
>>> tsdtensor = nap.TsdTensor(t=np.array([0., 1.]), d = np.zeros((2,3,4)))
>>> tsdtensor.save("my_path/my_tsdtensor.npz")

To load you file, you can use the nap.load_file function :

>>> tsdtensor = nap.load_file("my_path/my_tsdtensor.npz")

Raises:: RuntimeError – If filename is not str, path does not exist or filename is a directory.

property shape#

property size#

smooth(std, windowsize=None, time_units='s', size_factor=100, norm=True)#

Smooth a time series with a gaussian kernel.

std is the standard deviation of the gaussian kernel in units of time. If only std is passed, the function will compute the standard deviation and size in number of time points automatically based on the sampling rate of the time series. For example, if the time series tsd has a sample rate of 100 Hz and std is 50 ms, the standard deviation will be converted to an integer through tsd.rate * std = int(100 * 0.05) = 5.

If windowsize is None, the function will select a kernel size as 100 times the std in number of time points. This behavior can be controlled with the parameter size_factor.

norm set to True normalizes the gaussian kernel to sum to 1.

In the following example, a time series tsd with a sampling rate of 100 Hz is convolved with a gaussian kernel. The standard deviation is 0.05 second and the windowsize is 2 second. When instantiating the gaussian kernel from scipy, it corresponds to parameters M = 200 and std=5

>>> tsd.smooth(std=0.05, windowsize=2, time_units='s', norm=False)

This line is equivalent to :

>>> from scipy.signal.windows import gaussian
>>> kernel = gaussian(M = 200, std=5)
>>> tsd.convolve(window)

It is generally a good idea to visualize the kernel before applying any convolution.

See the scipy documentation for the [gaussian window](https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.windows.gaussian.html)

Parameters:

std (Number) – Standard deviation in units of time
windowsize (Number) – Size of the gaussian window in units of time.
time_units (str, optional) – The time units in which std and windowsize are specified (‘us’, ‘ms’, ‘s’ [default]).
size_factor (int, optional) – How long should be the kernel size as a function of the standard deviation. Default is 100. Bypassed if windowsize is used.
norm (bool, optional) – Whether to normalized the gaussian kernel or not. Default is True.

Returns:

Time series convolved with a gaussian kernel

Return type:

Tsd, TsdFrame, TsdTensor

property start#

start_time(units='s')#

The first time index in the time series object

Parameters:: units (str, optional) – (‘us’, ‘ms’, ‘s’ [default])
Returns:: out – _
Return type:: numpy.float64

property t#

times(units='s')#

The time index of the object, returned as np.double in the desired time units.

Parameters:: units (str, optional) – (‘us’, ‘ms’, ‘s’ [default])
Returns:: out – the time indexes
Return type:: numpy.ndarray

to_numpy()#

Return the data as a numpy.ndarray.

Mostly useful for matplotlib plotting when calling plot(tsd).

value_from(data, ep=None)#

Replace the value with the closest value from Tsd/TsdFrame/TsdTensor argument

Parameters:

data (Tsd, TsdFrame or TsdTensor) – The object holding the values to replace.
ep (IntervalSet (optional)) – The IntervalSet object to restrict the operation. If None, the time support of the tsd input object is used.

Returns:

out – Object with the new values

Return type:

Tsd, TsdFrame or TsdTensor

Examples

In this example, the ts object will receive the closest values in time from tsd.

>>> import pynapple as nap
>>> import numpy as np
>>> t = np.unique(np.sort(np.random.randint(0, 1000, 100))) # random times
>>> ts = nap.Ts(t=t, time_units='s')
>>> tsd = nap.Tsd(t=np.arange(0,1000), d=np.random.rand(1000), time_units='s')
>>> ep = nap.IntervalSet(start = 0, end = 500, time_units = 's')

The variable ts is a time series object containing only nan. The tsd object containing the values, for example the tracking data, and the epoch to restrict the operation.

>>> newts = ts.value_from(tsd, ep)

newts has the same size of ts restrict to ep.

>>> print(len(ts.restrict(ep)), len(newts))
    52 52