pynapple.core.time_series.Tsd#
- class pynapple.core.time_series.Tsd(t, d=None, time_units='s', time_support=None, load_array=True, **kwargs)[source]#
Bases:
_BaseTsd1-dimensional container for neurophysiological time series.
Tsd provides standardized time representation, plus various functions for manipulating times series.
- rate#
Frequency of the time series (Hz) computed over the time support
- Type:
float
- time_support#
The time support of the time series
- Type:
- __init__(t, d=None, time_units='s', time_support=None, load_array=True, **kwargs)[source]#
Tsd Initializer.
- Parameters:
t (numpy.ndarray or pandas.Series) – An object transformable in a time series, or a pandas.Series equivalent (if d is None)
d (numpy.ndarray, optional) – The data of the time series
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 tsd 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, ...])Tsd Initializer.
as_array()Return the data.
Convert the Ts/Tsd object to a pandas.Series object.
as_units([units])Returns a pandas Series with time expressed in the desired unit.
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 Tsd 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
threshold(thr[, method])Apply a threshold function to the tsd to return a new tsd with the time support being the epochs above/below/>=/<= the threshold
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.
Convert Tsd to a TsGroup by grouping timestamps with the same values.
value_from(data[, ep])Replace the value with the closest value from Tsd/TsdFrame/TsdTensor argument
Attributes
- as_array()#
Return the data.
- Returns:
out – _
- Return type:
array-like
- as_series()[source]#
Convert the Ts/Tsd object to a pandas.Series object.
- Returns:
out – _
- Return type:
pandas.Series
- as_units(units='s')[source]#
Returns a pandas Series with time expressed in the desired unit.
- Parameters:
units (str, optional) – (‘us’, ‘ms’, ‘s’ [default])
- Returns:
the series object with adjusted times
- Return type:
pandas.Series
- 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:
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:
- 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:
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.
- 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:
- 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:
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 Tsd 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 one channel from your recording and filtered it. You can save the filtered channel as a npz to avoid reprocessing it.
You can load the object with nap.load_file. Keys are ‘t’, ‘d’, ‘start’, ‘end’ and ‘type’. See the example below.
- Parameters:
filename (str) – The filename
Examples
>>> import pynapple as nap >>> import numpy as np >>> tsd = nap.Tsd(t=np.array([0., 1.]), d = np.array([2, 3])) >>> tsd.save("my_path/my_tsd.npz")
To load you file, you can use the nap.load_file function :
>>> tsd = nap.load_file("my_path/my_tsd.npz") >>> tsd Time (s) 0.0 2 1.0 3 dtype: int64
- 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:
- 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#
- threshold(thr, method='above')[source]#
Apply a threshold function to the tsd to return a new tsd with the time support being the epochs above/below/>=/<= the threshold
- Parameters:
thr (float) – The threshold value
method (str, optional) – The threshold method (“above”[default], “below”, “aboveequal”, “belowequal”)
- Returns:
out – All the time points below/ above/greater than equal to/less than equal to the threshold
- Return type:
- Raises:
ValueError – Raise an error if method is unknown.
RuntimeError – Raise an error if thr is too high/low and no epochs is found.
Examples
This example finds all epoch above 0.5 within the tsd object.
>>> import pynapple as nap >>> tsd = nap.Tsd(t=np.arange(100), d=np.random.rand(100)) >>> newtsd = tsd.threshold(0.5)
The epochs with the times above/below the threshold can be accessed through the time support:
>>> tsd = nap.Tsd(t=np.arange(100), d=np.arange(100), time_units='s') >>> tsd.threshold(50).time_support >>> start end >>> 0 50.5 99.0
- 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).
- to_tsgroup()[source]#
Convert Tsd to a TsGroup by grouping timestamps with the same values. By default, the values are converted to integers.
Examples
>>> import pynapple as nap >>> import numpy as np >>> tsd = nap.Tsd(t = np.array([0, 1, 2, 3]), d = np.array([0, 2, 0, 1])) Time (s) 0.0 0 1.0 2 2.0 0 3.0 1 dtype: int64
>>> tsd.to_tsgroup() Index rate ------- ------ 0 0.67 1 0.33 2 0.33
The reverse operation can be done with the TsGroup.to_tsd function :
>>> tsgroup.to_tsd() Time (s) 0.0 0.0 1.0 2.0 2.0 0.0 3.0 1.0 dtype: float64
- Returns:
Grouped timestamps
- Return type:
- 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:
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