pynapple.core.ts_group.TsGroup#
- class pynapple.core.ts_group.TsGroup(data, time_support=None, time_units='s', bypass_check=False, **kwargs)[source]#
Bases:
UserDictDictionary-like object to group objects with different timestamps (for example timestamps of spikes of a population of neurons).
- time_support#
The time support of the TsGroup
- Type:
- rates#
The rate of each element of the TsGroup
- Type:
pandas.Series
- __init__(data, time_support=None, time_units='s', bypass_check=False, **kwargs)[source]#
TsGroup Initializer.
- Parameters:
data (dict or iterable) – Dictionary or iterable of Ts/Tsd objects. The keys should be integer-convertible; if a non-dict iterator is passed, its values will be used to create a dict with integer keys.
time_support (IntervalSet, optional) – The time support of the TsGroup. Ts/Tsd objects will be restricted to the time support if passed. If no time support is specified, TsGroup will merge time supports from all the Ts/Tsd objects in data.
time_units (str, optional) – Time units if data does not contain Ts/Tsd objects (‘us’, ‘ms’, ‘s’ [default]).
bypass_check (bool, optional) – To avoid checking that each element is within time_support. Useful to speed up initialization of TsGroup when Ts/Tsd objects have already been restricted beforehand
**kwargs – Meta-info about the Ts/Tsd objects. Can be either pandas.Series, numpy.ndarray, list or tuple Note that the index should match the index of the input dictionary if pandas Series
- Raises:
RuntimeError – Raise error if the union of time support of Ts/Tsd object is empty.
ValueError –
If a key cannot be converted to integer. - If a key was a floating point with non-negligible decimal part. - If the converted keys are not unique, i.e. {1: ts_2, “2”: ts_2} is valid, {1: ts_2, “1”: ts_2} is invalid.
Methods
__init__(data[, time_support, time_units, ...])TsGroup Initializer.
clear()copy()count(*args[, dtype])Count occurences of events within bin_size or within a set of bins defined as an IntervalSet.
fromkeys(iterable[, value])get(start[, end, time_units])Slice the TsGroup object from start to end such that all the timestamps within the group satisfy start<=t<=end.
get_info(key)Returns the metainfo located in one column.
getby_category(key)Return a list of TsGroup grouped by category.
getby_intervals(key, bins)Return a list of TsGroup binned.
getby_threshold(key, thr[, op])Return a TsGroup with all Ts/Tsd objects with values above threshold for metainfo under key.
items()Return a list of key/object.
keys()Return index/keys of TsGroup
merge(*tsgroups[, reset_index, ...])Merge the TsGroup object with other TsGroup objects.
merge_group(*tsgroups[, reset_index, ...])Merge multiple TsGroup objects into a single TsGroup object.
pop(k[,d])If key is not found, d is returned if given, otherwise KeyError is raised.
popitem()as a 2-tuple; but raise KeyError if D is empty.
restrict(ep)Restricts a TsGroup object to a set of time intervals delimited by an IntervalSet object
save(filename)Save TsGroup object in npz format.
set_info(*args, **kwargs)Add metadata information about the TsGroup.
setdefault(k[,d])to_tsd(*args)Convert TsGroup to a Tsd.
update([E, ]**F)If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v
value_from(tsd[, ep])Replace the value of each Ts/Tsd object within the Ts group with the closest value from tsd argument
values()Return a list of all the Ts/Tsd objects in the TsGroup
Attributes
Returns list of metadata columns
Return the rates of each element of the group in Hz
- clear() None. Remove all items from D.#
- copy()#
- 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. tsgroup.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. tsgroup.count(1, ep=my_epochs) -> Count occurent of events within a 1 second bin defined on the IntervalSet my_epochs.
3. tsgroup.count(ep=my_bins) -> Count occurent of events within each epoch of the intervalSet object my_bins
4. tsgroup.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 TsdFrame with the columns being the index of each item in the TsGroup.
- Return type:
Examples
This example shows how to count events within bins of 0.1 second for the first 100 seconds.
>>> import pynapple as nap >>> import numpy as np >>> tmp = { 0:nap.Ts(t=np.arange(0,200), time_units='s'), 1:nap.Ts(t=np.arange(0,200,0.5), time_units='s'), 2:nap.Ts(t=np.arange(0,300,0.25), time_units='s'), } >>> tsgroup = nap.TsGroup(tmp) >>> ep = nap.IntervalSet(start=0, end=100, time_units='s') >>> bincount = tsgroup.count(0.1, ep) >>> bincount 0 1 2 Time (s) 0.05 0 0 0 0.15 0 0 0 0.25 0 0 1 0.35 0 0 0 0.45 0 0 0 ... .. .. .. 99.55 0 1 1 99.65 0 0 0 99.75 0 0 1 99.85 0 0 0 99.95 1 1 1 [1000 rows x 3 columns]
- classmethod fromkeys(iterable, value=None)#
- get(start, end=None, time_units='s')[source]#
Slice the TsGroup object from start to end such that all the timestamps within the group 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_info(key)[source]#
Returns the metainfo located in one column. The key for the column frequency is “rate”.
- Parameters:
key (str) – One of the metainfo columns name
- Returns:
The metainfo
- Return type:
pandas.Series
- getby_category(key)[source]#
Return a list of TsGroup grouped by category.
- Parameters:
key (str) – One of the metainfo columns name
- Returns:
A dictionary of TsGroup
- Return type:
dict
Examples
>>> import pynapple as nap >>> import numpy as np >>> tmp = { 0:nap.Ts(t=np.arange(0,200), time_units='s'), 1:nap.Ts(t=np.arange(0,200,0.5), time_units='s'), 2:nap.Ts(t=np.arange(0,300,0.25), time_units='s'), } >>> tsgroup = nap.TsGroup(tmp, group = [0,1,1]) Index Freq. (Hz) group ------- ------------ ------- 0 1 0 1 2 1 2 4 1
This exemple shows how to group the TsGroup according to one metainfo key.
>>> newtsgroup = tsgroup.getby_category('group') >>> newtsgroup {0: Index Freq. (Hz) group ------- ------------ ------- 0 1 0, 1: Index Freq. (Hz) group ------- ------------ ------- 1 2 1 2 4 1}
- getby_intervals(key, bins)[source]#
Return a list of TsGroup binned.
- Parameters:
key (str) – One of the metainfo columns name
bins (numpy.ndarray or list) – The bin intervals
- Returns:
A list of TsGroup
- Return type:
list
Examples
>>> import pynapple as nap >>> import numpy as np >>> tmp = { 0:nap.Ts(t=np.arange(0,200), time_units='s'), 1:nap.Ts(t=np.arange(0,200,0.5), time_units='s'), 2:nap.Ts(t=np.arange(0,300,0.25), time_units='s'), } >>> tsgroup = nap.TsGroup(tmp, alpha = np.arange(3)) Index Freq. (Hz) alpha ------- ------------ ------- 0 1 0 1 2 1 2 4 2
This exemple shows how to bin the TsGroup according to one metainfo key.
>>> newtsgroup, bincenter = tsgroup.getby_intervals('alpha', [0, 1, 2]) >>> newtsgroup [ Index Freq. (Hz) alpha ------- ------------ ------- 0 1 0, Index Freq. (Hz) alpha ------- ------------ ------- 1 2 1]
By default, the function returns the center of the bins.
>>> bincenter array([0.5, 1.5])
- getby_threshold(key, thr, op='>')[source]#
Return a TsGroup with all Ts/Tsd objects with values above threshold for metainfo under key.
- Parameters:
key (str) – One of the metainfo columns name
thr (float) – THe value for thresholding
op (str, optional) – The type of operation. Possibilities are ‘>’, ‘<’, ‘>=’ or ‘<=’.
- Returns:
The new TsGroup
- Return type:
- Raises:
RuntimeError – Raise eror is operation is not recognized.
Examples
>>> import pynapple as nap >>> import numpy as np >>> tmp = { 0:nap.Ts(t=np.arange(0,200), time_units='s'), 1:nap.Ts(t=np.arange(0,200,0.5), time_units='s'), 2:nap.Ts(t=np.arange(0,300,0.25), time_units='s'), } >>> tsgroup = nap.TsGroup(tmp) Index Freq. (Hz) ------- ------------ 0 1 1 2 2 4
This exemple shows how to get a new TsGroup with all elements for which the metainfo frequency is above 1.
>>> newtsgroup = tsgroup.getby_threshold('freq', 1, op = '>') Index Freq. (Hz) ------- ------------ 1 2 2 4
- merge(*tsgroups, reset_index=False, reset_time_support=False, ignore_metadata=False)[source]#
Merge the TsGroup object with other TsGroup objects. Common uses include adding more neurons/channels (supposing each Ts/Tsd corresponds to data from a neuron/channel) or adding more trials (supposing each Ts/Tsd corresponds to data from a trial).
- Parameters:
*tsgroups (TsGroup) – The TsGroup objects to merge with
reset_index (bool, optional) – If True, the keys will be reset to range(len(data)) If False, the keys of the TsGroup objects should be non-overlapping and will be preserved
reset_time_support (bool, optional) – If True, the merged TsGroup will merge time supports from all the Ts/Tsd objects in data If False, the time support of the TsGroup objects should be the same and will be preserved
ignore_metadata (bool, optional) – If True, the merged TsGroup will not have any metadata columns other than ‘rate’ If False, all metadata columns should be the same and all metadata will be concatenated
- Returns:
A TsGroup of merged objects
- Return type:
- Raises:
TypeError – If the input objects are not TsGroup objects
ValueError – If ignore_metadata=False but metadata columns are not the same If reset_index=False but keys overlap If reset_time_support=False but time supports are not the same
Examples
>>> import pynapple as nap >>> time_support_a = nap.IntervalSet(start=-1, end=1, time_units='s') >>> time_support_b = nap.IntervalSet(start=-5, end=5, time_units='s')
>>> dict1 = {0: nap.Ts(t=[-1, 0, 1], time_units='s')} >>> tsgroup1 = nap.TsGroup(dict1, time_support=time_support_a)
>>> dict2 = {10: nap.Ts(t=[-1, 0, 1], time_units='s')} >>> tsgroup2 = nap.TsGroup(dict2, time_support=time_support_a)
>>> dict3 = {0: nap.Ts(t=[-.1, 0, .1], time_units='s')} >>> tsgroup3 = nap.TsGroup(dict3, time_support=time_support_a)
>>> dict4 = {10: nap.Ts(t=[-1, 0, 1], time_units='s')} >>> tsgroup4 = nap.TsGroup(dict2, time_support=time_support_b)
Merge with default options if have the same time support and non-overlapping indexes:
>>> tsgroup_12 = tsgroup1.merge(tsgroup2) >>> tsgroup_12 Index rate ------- ------ 0 1.5 10 1.5
Set reset_index=True if indexes are overlapping:
>>> tsgroup_13 = tsgroup1.merge(tsgroup3, reset_index=True) >>> tsgroup_13 Index rate ------- ------ 0 1.5 1 1.5
Set reset_time_support=True if time supports are different:
>>> tsgroup_14 = tsgroup1.merge(tsgroup4, reset_time_support=True) >>> tsgroup_14 >>> tsgroup_14.time_support Index rate ------- ------ 0 0.3 10 0.3
start end
0 -5 5 shape: (1, 2), time unit: sec.
See also
[TsGroup.merge_group](./#pynapple.core.ts_group.TsGroup.merge_group)
- static merge_group(*tsgroups, reset_index=False, reset_time_support=False, ignore_metadata=False)[source]#
Merge multiple TsGroup objects into a single TsGroup object.
- Parameters:
*tsgroups (TsGroup) – The TsGroup objects to merge
reset_index (bool, optional) – If True, the keys will be reset to range(len(data)) If False, the keys of the TsGroup objects should be non-overlapping and will be preserved
reset_time_support (bool, optional) – If True, the merged TsGroup will merge time supports from all the Ts/Tsd objects in data If False, the time support of the TsGroup objects should be the same and will be preserved
ignore_metadata (bool, optional) – If True, the merged TsGroup will not have any metadata columns other than ‘rate’ If False, all metadata columns should be the same and all metadata will be concatenated
- Returns:
A TsGroup of merged objects
- Return type:
- Raises:
TypeError – If the input objects are not TsGroup objects
ValueError – If ignore_metadata=False but metadata columns are not the same If reset_index=False but keys overlap If reset_time_support=False but time supports are not the same
- property metadata_columns#
Returns list of metadata columns
- pop(k[, d]) v, remove specified key and return the corresponding value.#
If key is not found, d is returned if given, otherwise KeyError is raised.
- popitem() (k, v), remove and return some (key, value) pair#
as a 2-tuple; but raise KeyError if D is empty.
- property rates#
Return the rates of each element of the group in Hz
- restrict(ep)[source]#
Restricts a TsGroup object to a set of time intervals delimited by an IntervalSet object
- Parameters:
ep (IntervalSet) – the IntervalSet object
- Returns:
TsGroup object restricted to ep
- Return type:
Examples
>>> import pynapple as nap >>> import numpy as np >>> tmp = { 0:nap.Ts(t=np.arange(0,200), time_units='s'), 1:nap.Ts(t=np.arange(0,200,0.5), time_units='s'), 2:nap.Ts(t=np.arange(0,300,0.25), time_units='s'), } >>> tsgroup = nap.TsGroup(tmp) >>> ep = nap.IntervalSet(start=0, end=100, time_units='s') >>> newtsgroup = tsgroup.restrict(ep)
All objects within the TsGroup automatically inherit the epochs defined by ep.
>>> newtsgroup.time_support start end 0 0.0 100.0 >>> newtsgroup[0].time_support start end 0 0.0 100.0
- save(filename)[source]#
Save TsGroup object in npz format. The file will contain the timestamps, the data (if group of Tsd), group index, the time support and the metadata
The main purpose of this function is to save small/medium sized TsGroup objects.
The function will “flatten” the TsGroup by sorting all the timestamps and assigning to each the corresponding index. Typically, a TsGroup like this :
>>> TsGroup({ 0 : Tsd(t=[0, 2, 4], d=[1, 2, 3]) 1 : Tsd(t=[1, 5], d=[5, 6])})
will be saved as npz with the following keys:
>>> { 't' : [0, 1, 2, 4, 5], 'd' : [1, 5, 2, 3, 5], 'index' : [0, 1, 0, 0, 1], 'start' : [0], 'end' : [5], 'keys' : [0, 1], 'type' : 'TsGroup' }
Metadata are saved by columns with the column name as the npz key. To avoid potential conflicts, make sure the columns name of the metadata are different from [‘t’, ‘d’, ‘start’, ‘end’, ‘index’, ‘keys’]
You can load the object with nap.load_file. Default keys are ‘t’, ‘d’(optional), ‘start’, ‘end’, ‘index’, ‘keys’ and ‘type’. See the example below.
- Parameters:
filename (str) – The filename
Examples
>>> import pynapple as nap >>> import numpy as np >>> tsgroup = nap.TsGroup({ 0 : nap.Ts(t=np.array([0.0, 2.0, 4.0])), 6 : nap.Ts(t=np.array([1.0, 5.0])) }, group = np.array([0, 1]), location = np.array(['right foot', 'left foot']) ) >>> tsgroup Index rate group location ------- ------ ------- ---------- 0 0.6 0 right foot 6 0.4 1 left foot >>> tsgroup.save("my_tsgroup.npz")
To get back to pynapple, you can use the nap.load_file function :
>>> tsgroup = nap.load_file("my_tsgroup.npz") >>> tsgroup Index rate group location ------- ------ ------- ---------- 0 0.6 0 right foot 6 0.4 1 left foot
- Raises:
RuntimeError – If filename is not str, path does not exist or filename is a directory.
- set_info(*args, **kwargs)[source]#
Add metadata information about the TsGroup. Metadata are saved as a DataFrame.
- Parameters:
*args – pandas.Dataframe or list of pandas.DataFrame
**kwargs – Can be either pandas.Series, numpy.ndarray, list or tuple
- Raises:
RuntimeError – Raise an error if no column labels are found when passing simple arguments, indexes are not equals for a pandas series,+ not the same length when passing numpy array.
TypeError – If some of the provided metadata could not be set.
Examples
>>> import pynapple as nap >>> import numpy as np >>> tmp = { 0:nap.Ts(t=np.arange(0,200), time_units='s'), 1:nap.Ts(t=np.arange(0,200,0.5), time_units='s'), 2:nap.Ts(t=np.arange(0,300,0.25), time_units='s'), } >>> tsgroup = nap.TsGroup(tmp)
To add metadata with a pandas.DataFrame:
>>> import pandas as pd >>> structs = pd.DataFrame(index = [0,1,2], data=['pfc','pfc','ca1'], columns=['struct']) >>> tsgroup.set_info(structs) >>> tsgroup Index Freq. (Hz) struct ------- ------------ -------- 0 1 pfc 1 2 pfc 2 4 ca1
To add metadata with a pd.Series, numpy.ndarray, list or tuple:
>>> hd = pd.Series(index = [0,1,2], data = [0,1,1]) >>> tsgroup.set_info(hd=hd) >>> tsgroup Index Freq. (Hz) struct hd ------- ------------ -------- ---- 0 1 pfc 0 1 2 pfc 1 2 4 ca1 1
- setdefault(k[, d]) D.get(k,d), also set D[k]=d if k not in D#
- to_tsd(*args)[source]#
Convert TsGroup to a Tsd. The timestamps of the TsGroup are merged together and sorted.
- Parameters:
*args – string, list, numpy.ndarray or pandas.Series
Examples
>>> import pynapple as nap >>> import numpy as np >>> tsgroup = nap.TsGroup({0:nap.Ts(t=np.array([0, 1])), 5:nap.Ts(t=np.array([2, 3]))}) Index rate ------- ------ 0 1 5 1
By default, the values of the Tsd is the index of the timestamp in the TsGroup:
>>> tsgroup.to_tsd() Time (s) 0.0 0.0 1.0 0.0 2.0 5.0 3.0 5.0 dtype: float64
Values can be inherited from the metadata of the TsGroup by giving the key of the corresponding columns.
>>> tsgroup.set_info( phase=np.array([np.pi, 2*np.pi]) ) # assigning a phase to my 2 elements of the TsGroup >>> tsgroup.to_tsd("phase") Time (s) 0.0 3.141593 1.0 3.141593 2.0 6.283185 3.0 6.283185 dtype: float64
Values can also be passed directly to the function from a list, numpy.ndarray or pandas.Series of values as long as the length matches :
>>> tsgroup.to_tsd([-1, 1]) Time (s) 0.0 -1.0 1.0 -1.0 2.0 1.0 3.0 1.0 dtype: float64
The reverse operation can be done with the Tsd.to_tsgroup function :
>>> my_tsd Time (s) 0.0 0.0 1.0 0.0 2.0 5.0 3.0 5.0 dtype: float64 >>> my_tsd.to_tsgroup() Index rate ------- ------ 0 1 5 1
- Return type:
- Raises:
RuntimeError – “Index are not equals” : if pandas.Series indexes don’t match the TsGroup indexes “Values is not the same length” : if numpy.ndarray/list object is not the same size as the TsGroup object “Key not in metadata of TsGroup” : if string argument does not match any column names of the metadata, “Unknown argument format” ; if argument is not a string, list, numpy.ndarray or pandas.Series
- update([E, ]**F) None. Update D from mapping/iterable E and F.#
If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v
- value_from(tsd, ep=None)[source]#
Replace the value of each Ts/Tsd object within the Ts group with the closest value from tsd argument
- Parameters:
tsd (Tsd) – The Tsd object holding the values to replace
ep (IntervalSet) – The IntervalSet object to restrict the operation. If None, the time support of the tsd input object is used.
- Returns:
TsGroup object with the new values
- Return type:
Examples
>>> import pynapple as nap >>> import numpy as np >>> tmp = { 0:nap.Ts(t=np.arange(0,200), time_units='s'), 1:nap.Ts(t=np.arange(0,200,0.5), time_units='s'), 2:nap.Ts(t=np.arange(0,300,0.25), time_units='s'), } >>> tsgroup = nap.TsGroup(tmp) >>> ep = nap.IntervalSet(start=0, end=100, time_units='s')
The variable tsd is a time series object containing the values to assign, for example the tracking data:
>>> tsd = nap.Tsd(t=np.arange(0,100), d=np.random.rand(100), time_units='s') >>> ep = nap.IntervalSet(start = 0, end = 100, time_units = 's') >>> newtsgroup = tsgroup.value_from(tsd, ep)