pynapple.core.time_series.Ts#

class pynapple.core.time_series.Ts(t, time_units='s', time_support=None)[source]#

Bases: _Base

Timestamps only object for a time series with only time index.

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, time_units='s', time_support=None)[source]#

Ts Initializer

Parameters:

t (numpy.ndarray or pandas.Series) – An object transformable in timestamps, or a pandas.Series equivalent (if d is None)
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 Ts object

Methods

`__init__`(t[, time_units, time_support])	Ts Initializer
`as_series`()	Convert the Ts/Tsd object to a pandas.Series object.
`as_units`([units])	Returns a pandas Series with time expressed in the desired unit.
`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.
`end_time`([units])	The last time index in the time series object
`fillna`(value)	Similar to pandas fillna function.
`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.
`restrict`(iset)	Restricts a time series object to a set of time intervals delimited by an IntervalSet object
`save`(filename)	Save Ts object in npz format.
`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.
`value_from`(data[, ep])	Replace the value with the closest value from Tsd/TsdFrame/TsdTensor argument

Attributes

`end`
`shape`
`start`
`t`

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

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

count(*args, dtype=None, **kwargs)[source]#

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 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

fillna(value)[source]#

Similar to pandas fillna function.

Parameters:: value (Number) – Value for filling
Return type:: Tsd

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)`

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 Ts object in npz format. The file will contain the timestamps and the time support.

The main purpose of this function is to save small/medium sized timestamps object.

You can load the object with nap.load_file. Keys are ‘t’, ‘start’ and ‘end’ and ‘type’. See the example below.

Parameters:: filename (str) – The filename

Examples

>>> import pynapple as nap
>>> import numpy as np
>>> ts = nap.Ts(t=np.array([0., 1., 1.5]))
>>> ts.save("my_path/my_ts.npz")

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

>>> ts = nap.load_file("my_path/my_ts.npz")
>>> ts
Time (s)
0.0
1.0
1.5

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

property shape#

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

value_from(data, ep=None)[source]#

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 is the same size as ts restrict to ep.

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