Timetags and time intervals functions

Functions:

`array2intervals`(t[, tgap, tblock])	Convert from timetags to time intervals.
`intervals2weights`(a[, step, min, max, norm])	Convert from time intervals to timetags and weights.
`intersect`(a, b)	Calculate the intersection of two arrays of time intervals.
`split`(a[, base])	Split time intervals in regular steps.
`semi_split`(a[, base, offset, mino])	Add time intervals in regular steps.
`regvals`(tstart, tstop[, base, offset, extend])	Generate regular time intervals.
`raverage`(data, t[, base, offset, step, gap_ext])	Average data in regular intervals.
`maverage`(data, t, intervals)	Average data in given intervals.
`csaverage`(f, ti, to[, axis])	Average data in different time intervals.
`add_break`(vals, brk)	Add a break to given start-stop intervals.
`remove_break`(vals, brk)	Remove a break from given start/stop intervals.

tintervals.intervals.array2intervals(t, tgap=1.0, tblock=0.0)

Convert from timetags to time intervals.

Calculate from an array of timetags t a 2-d array in the form (start,stop), including gaps > tgap and removing intervals < tblock.

Parameters:

t (1-d array) – timetags (assumed sorted).
tgap (float) – resulting intervals will mark gaps > tgap, by default 1.
tblock (float) – intervals shorter than tblock will be removed, by default 0.

Returns:

start, stop intervals

Return type:

2-d array

Examples

>>> array2intervals(np.array([1,2,3,7,8]))
array([[1, 3],[7, 8]])

tintervals.intervals.intervals2weights(a, step=1, min=None, max=None, norm=False)

Convert from time intervals to timetags and weights.

Given some interval start-stop return an arange of timetags and an array of weights.

Parameters:

a (2-d array) – intervals in the form (start,stop).
step (float) – spacing between timetags.
min (float) – fix the minimum of the timetags, by default min of a.
max (float) – fix the maximum of the timetags, by default max of a.
norm (bool) – if True normalize the weights, by default False

Returns:

1-d array – timetags.
1-d array – weights (positive only between each start,stop).

tintervals.intervals.intersect(a, b)

Calculate the intersection of two arrays of time intervals.

Parameters:

a (2-d array) – intervals in the form (start,stop).
b (2-d array) – intervals in the form (start,stop).

Returns:

intersection of a and b

Return type:

2-d array

Examples

>>> intersect([[1,3],[5,7]],[[2,6]])
array([[2, 3], [5, 6]])

tintervals.intervals.split(a, base=10.0)

Split time intervals in regular steps.

Given some interval start-stop return all the included intervals with start and stop multiple of base

Parameters:

a (2-d array) – intervals in the form (start,stop).
base (float) – base interval (generated intervals will be multiple of base).

Returns:

intervals in the form (start,stop), with start and stop every multiple of base

Return type:

2-d array

Examples

>>> split(np.array([[1,31]]), 10)
array([[10., 20.],[20., 30.]])

tintervals.intervals.semi_split(a, base=10.0, offset=0, mino=0.5)

Add time intervals in regular steps.

Given some intervals, return new intervals in a finer grid, where new start/stop are in regular steps avoiding adding intervals that are too small.

Parameters:

a (2-d array) – intervals in the form (start,stop).
base (float) – base interval (generated intervals will be multiple of base).
mino (float) – minimum fraction of base required to introduce a new interval by default 0.5

Returns:

intervals in the form (start,stop), with added start/stop multiple of base (only if the new interval is > base * mino)

Return type:

2-d array

Examples

>>> semi_split(np.array([[1,31]]), 10)
array([[ 1., 10.],[ 10., 20.],[ 20., 31.])

tintervals.intervals.regvals(tstart, tstop, base=1.0, offset=0.0, extend=True)

Generate regular time intervals.

Parameters:

tstart (float) – starting time.
tstop (float) – stopping time.
base (float, optional) – base interval (generated intervals will be mutiple of base), by default 1.
offset (float, optional) – time offset in the generated intervals, by default 0.
extend (bool, optional) – if True, extend the intervals to include the extremes, by default True.

Returns:

regular start/stop intervals

Return type:

2-d array

tintervals.intervals.raverage(data, t, base=1.0, offset=0.0, step=None, gap_ext=10)

Average data in regular intervals.

The algorithm perform the average by reshaping data.

Parameters:

data (ndarray) – data to be averaged (along the first axis).
t (1-d array) – timetags of the data to be averaged. The length should match the first dimension of data. Timetags are assumed sorted and it should be a subset of an arange with step = base
base (float, optional) – base intervals (average will be at the mutiple of base, if offset=0), by default 1.
offset (float, optional) – time offset for the averages (averages will be at mutiple of base + offset), by default 0.
step (float, optional) – spacing between timetags, by default the median of the differences of t.
gap_ext (int, optional) – algorithm will automatically skip gaps > gap_ext*base, by default 10. Changing this value may change the efficiency of the algorithm dependning on the input data. (Lower values will split the data more, but will have less gaps to fill.)

Returns:

2-d array – start/stop intervals of the averages.
ndarray – averaged data.
1-d array – number of averaged point for each intervals.

Notes

Timetags are included in the start intervals but excluded in the stop intervals.

tintervals.intervals.maverage(data, t, intervals)

Average data in given intervals.

The average is done masking the data.

Parameters:

data (ndarray) – data to be averaged (along the first axis).
t (1-d array) – timetags of the data to be averaged. The length should match the first dimension of data.
intervals (2-d array) – start/stop intervals where average the data.

Returns:

2-d array – start/stop intervals of the averages.
ndarray – averaged data.
1-d array – number of averaged point for each intervals.

Notes

Timetags are included in the start intervals but excluded in the stop intervals.

tintervals.intervals.csaverage(f, ti, to, axis=0)

Average data in different time intervals.

Perform the average of data given in (tistart,tistop) ranges in the intervals (tostart, tostop). It uses linear interpolation of the data and can work with gaps in the data.

The average is made by a “cumsum” algorithm

Parameters:

f (ndarray) – input data to be averaged.
ti (2-d array) – start/stop time for each measurement.
to (2-d array) – start/stop time for the output average.
axis (int, optional) – axis of interpolation, by default 0.

Returns:

ndarray – averaged array.
1-d array – number of points averaged for each result.

tintervals.intervals.add_break(vals, brk)

Add a break to given start-stop intervals.

Parameters:

vals (2d array) – Start/stop intervals
brk (float) – Break to be inserted.

Returns:

New intervals with added break.

Return type:

2d array

Examples

>>> vals = np.array([[0,1],[1,2],[2,3]])
>>> add_break(vals, 1.5)
array([[0. , 1. ],
           [1. , 1.5],
           [1.5, 2. ],
           [2. , 3. ]])

tintervals.intervals.remove_break(vals, brk)

Remove a break from given start/stop intervals.

Parameters:

vals (2d array) – Start/stop intervals
brk (float) – Break to be removed

Returns:

New intervals with break removed.

Return type:

2d array

Returns:

New intervals with added break.

Return type:

2d array

Examples

>>> vals = np.array([[0,1],[1,2],[2,3]])
>>> remove_break(vals, 2)
array([[0. , 1. ],
           [1. , 3. ]])