pynapple.core.interval_set.IntervalSet#

class pynapple.core.interval_set.IntervalSet(start, end=None, time_units='s')[source]#

Bases: NDArrayOperatorsMixin

A class representing a (irregular) set of time intervals in elapsed time, with relative operations

The IntervalSet object behaves like a numpy ndarray with the limitation that the object is not mutable.

You can still apply any numpy array function to it :

>>> import pynapple as nap
>>> import numpy as np
>>> ep = nap.IntervalSet(start=[0, 10], end=[5,20])
        start    end
    0        0      5
    1       10     20
    shape: (1, 2)

>>> np.diff(ep, 1)
    UserWarning: Converting IntervalSet to numpy.array
    array([[ 5.],
           [10.]])

You can slice :

>>> ep[:,0]
    array([ 0., 10.])

>>> ep[0]
    start    end
    0        0      5
    shape: (1, 2)

But modifying the IntervalSet with raise an error:

>>> ep[0,0] = 1
    RuntimeError: IntervalSet is immutable. Starts and ends have been already sorted.

__init__(start, end=None, time_units='s')[source]#

If start and end are not aligned, meaning that: 1. len(start) != len(end) 2. end[i] > start[i] 3. start[i+1] > end[i] 4. start and end are not sorted,

IntervalSet will try to “fix” the data by eliminating some of the start and end data points.

Parameters:

start (numpy.ndarray or number or pandas.DataFrame or pandas.Series or iterable of (start, end) pairs) –
Beginning of intervals. Alternatively, the end argument can be left out and start can be one of the following:
- IntervalSet
- pandas.DataFrame with columns [“start”, “end”]
- iterable of (start, end) pairs
- a single (start, end) pair
end (numpy.ndarray or number or pandas.Series, optional) – Ends of intervals.
time_units (str, optional) – Time unit of the intervals (‘us’, ‘ms’, ‘s’ [default]).

Raises:

RuntimeError – If start and end arguments are of unknown type.

Methods

`__init__`(start[, end, time_units])	If start and end are not aligned, meaning that: 1.
`as_dataframe`()	Convert the IntervalSet object to a pandas.DataFrame object.
`as_units`([units])	returns a pandas DataFrame with time expressed in the desired unit
`drop_long_intervals`(threshold[, time_units])	Drops the long intervals in the interval set with duration longer than threshold.
`drop_short_intervals`(threshold[, time_units])	Drops the short intervals in the interval set with duration shorter than threshold.
`get_intervals_center`([alpha])	Returns by default the centers of each intervals.
`in_interval`(tsd)	finds out in which element of the interval set each point in a time series fits.
`intersect`(a)	Set intersection of IntervalSet
`merge_close_intervals`(threshold[, time_units])	Merges intervals that are very close.
`save`(filename)	Save IntervalSet object in npz format.
`set_diff`(a)	set difference of IntervalSet
`split`(interval_size[, time_units])	Split IntervalSet to a new IntervalSet with each interval being of size interval_size.
`time_span`()	Time span of the interval set.
`tot_length`([time_units])	Total elapsed time in the set.
`union`(a)	set union of IntervalSet

Attributes

`end`
`ends`	Return the ends of the IntervalSet as a Ts object
`loc`	Slicing function to add compatibility with pandas DataFrame after removing it as a super class of IntervalSet
`ndim`
`shape`
`size`
`start`
`starts`	Return the starts of the IntervalSet as a Ts object

as_dataframe()[source]#

Convert the IntervalSet object to a pandas.DataFrame object.

Returns:: out – _
Return type:: pandas.DataFrame

as_units(units='s')[source]#

returns a pandas DataFrame with time expressed in the desired unit

Parameters:: units (None, optional) – ‘us’, ‘ms’, or ‘s’ [default]
Returns:: out – DataFrame with adjusted times
Return type:: pandas.DataFrame

drop_long_intervals(threshold, time_units='s')[source]#

Drops the long intervals in the interval set with duration longer than threshold.

Parameters:

threshold (numeric) – Time threshold for “long” intervals
time_units (None, optional) – The time units for the treshold (‘us’, ‘ms’, ‘s’ [default])

Returns:

out – A copied IntervalSet with the dropped intervals

Return type:

IntervalSet

drop_short_intervals(threshold, time_units='s')[source]#

Drops the short intervals in the interval set with duration shorter than threshold.

Parameters:

threshold (numeric) – Time threshold for “short” intervals
time_units (None, optional) – The time units for the treshold (‘us’, ‘ms’, ‘s’ [default])

Returns:

out – A copied IntervalSet with the dropped intervals

Return type:

IntervalSet

property end#

property ends#

Return the ends of the IntervalSet as a Ts object

Returns:: The ends of the IntervalSet
Return type:: Ts

get_intervals_center(alpha=0.5)[source]#

Returns by default the centers of each intervals.

It is possible to bias the midpoint by changing the alpha parameter between [0, 1] For each epoch: t = start + (end-start)*alpha

Parameters:: alpha (float, optional) – The midpoint within each interval.
Returns:: Timestamps object
Return type:: Ts

in_interval(tsd)[source]#

finds out in which element of the interval set each point in a time series fits.

NaNs for those that don’t fit an interval

Parameters:: tsd (Tsd) – The tsd to be binned
Returns:: out – an array with the interval index labels for each time stamp (NaN) for timestamps not in IntervalSet
Return type:: numpy.ndarray

intersect(a)[source]#

Set intersection of IntervalSet

Parameters:: a (IntervalSet) – the IntervalSet to intersect self with
Returns:: out – _
Return type:: IntervalSet

property loc#: Slicing function to add compatibility with pandas DataFrame after removing it as a super class of IntervalSet

merge_close_intervals(threshold, time_units='s')[source]#

Merges intervals that are very close.

Parameters:

threshold (numeric) – time threshold for the closeness of the intervals
time_units (None, optional) – time units for the threshold (‘us’, ‘ms’, ‘s’ [default])

Returns:

out – a copied IntervalSet with merged intervals

Return type:

IntervalSet

property ndim#

save(filename)[source]#

Save IntervalSet object in npz format. The file will contain the starts and ends.

The main purpose of this function is to save small/medium sized IntervalSet objects. For example, you determined some epochs for one session that you want to save to avoid recomputing them.

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

Parameters:: filename (str) – The filename

Examples

>>> import pynapple as nap
>>> import numpy as np
>>> ep = nap.IntervalSet(start=[0, 10, 20], end=[5, 12, 33])
>>> ep.save("my_ep.npz")

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

>>> ep = nap.load_file("my_path/my_ep.npz")
>>> ep
   start   end
0    0.0   5.0
1   10.0  12.0
2   20.0  33.0

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

set_diff(a)[source]#

set difference of IntervalSet

Parameters:: a (IntervalSet) – the IntervalSet to set-substract from self
Returns:: out – _
Return type:: IntervalSet

property shape#

property size#

split(interval_size, time_units='s')[source]#

Split IntervalSet to a new IntervalSet with each interval being of size interval_size.

Used mostly for chunking very large dataset or looping throught multiple epoch of same duration.

This function skips the epochs that are shorter than interval_size.

Note that intervals are strictly non-overlapping in pynapple. One microsecond is removed from contiguous intervals.

Parameters:

interval_size (Number) – Description
time_units (str, optional) – time units for the interval_size (‘us’, ‘ms’, ‘s’ [default])

Returns:

New IntervalSet with equal sized intervals

Return type:

IntervalSet

Raises:

IOError – If interval_size is not a Number or is below 0 If time_units is not a string

property start#

property starts#

Return the starts of the IntervalSet as a Ts object

Returns:: The starts of the IntervalSet
Return type:: Ts

time_span()[source]#

Time span of the interval set.

Returns:: out – an IntervalSet with a single interval encompassing the whole IntervalSet
Return type:: IntervalSet

tot_length(time_units='s')[source]#

Total elapsed time in the set.

Parameters:: time_units (None, optional) – The time units to return the result in (‘us’, ‘ms’, ‘s’ [default])
Returns:: out – _
Return type:: float

union(a)[source]#

set union of IntervalSet

Parameters:: a (IntervalSet) – the IntervalSet to union self with
Returns:: out – _
Return type:: IntervalSet