Events

The primary function of trouve is to find events in time-series data and apply functional transformations in a specified order. The main function is find_events. This function takes in a conditional bool and then returns the class Events. The Events class finds each distinct occurrence and records it’s start and stop index value. These values then allow a user to inspect each event in a Pythonic manner.

trouve.find_events.find_events()

Find events based off a condition

Find events based off a bool conditional array and apply a sequence of transformation functions to them. The find_events function is curried via toolz.curry. Most datasets are of the same sample rate, this is a convenience so that one can specify it once.

Parameters:

• condition (numpy.ndarray or pandas.Series of bool) – Boolean conditional array.
• period (float) – Time in seconds between each data point. Requires constant increment data that is uniform across the array. (1/Hz = s)
• transformations (sequence of callable ‘s, optional) – Ordered sequence of transformation functions to apply to events. Transformations are applied via toolz.pipe()
• name (str, optional) – Default is 'events'. User provided name for events.

Returns:

Returns events found from condition with any supplied transformations applied.

Return type:

trouve.events.Events

Examples

>>> import trouve as tr
>>> import trouve.transformations as tt
>>> import numpy as np
>>> deb = tt.debounce(2, 2)
>>> offsets = tt.offset_events(-1,2)
>>> filt_dur = tt.filter_durations(3, 5)
>>> x = np.array([4, 5, 1, 2, 3, 4, 5, 1, 3])
>>> condition = (x > 2)
>>> no_transforms = tr.find_events(condition, period=1)
>>> events = tr.find_events(condition, period=1,
... transformations=[deb, filt_dur, offsets])
>>> no_transforms.to_array()  # doctest: +SKIP
array([ 1.,  1.,  0.,  0.,  1.,  1.,  1.,  0.,  1.])
>>> events.to_array()  # doctest: +SKIP
array([ 0.,  0.,  0.,  1.,  1.,  1.,  1.,  1.,  1.])

class trouve.events.Events(starts, stops, period, name, condition_size)

Object to represent events found in time series data

A representation of events based off a bool conditional array.

name

User provided name for events.

Type:str

_starts

The index for event starts

Type:np.array of int

_stops

The index for event stops

Type:np.array of int

_period

Time between each value of the original condition array

Type:float

_condition_size

The size of the original condition array

Type:int

durations

Return a numpy.ndarray of event durations in seconds.

Examples

>>> import trouve as tr
>>> x = np.array([2, 2, 4, 5, 3, 2])
>>> condition = x == 2
>>> events = tr.find_events(condition, period=1)
>>> events.to_array()  # doctest: +SKIP
array([1., 1., 0., 0., 0., 1.])
>>> print(events.durations)
[2 1]

to_array(inactive_value=0, active_value=1, dtype=None, order='C')

Returns a numpy.ndarray identifying found events

Useful for plotting or building another mask based on identified events.

Parameters:

• inactive_value (float, optional) – Default is 0. Value of array where events are not active.
• active_value (float, optional) – Default is 1. Value of array where events are active.
• dtype (numpy.dtype, optional) – Default is numpy.float64. The datatype of returned array.
• order (str, optional) – Default is ‘C’. {‘C’, ‘F’} whether to store multidimensional data in C- or Fortran-contiguous (row- or column-wise) order in memory.

Returns:

An array where values are coded to

identify when events are active or inactive.

Return type:

numpy.ndarray

Examples

>>> import trouve as tr
>>> x = np.array([2, 2, 4, 5, 3, 2])
>>> condition = x > 2
>>> print(condition)
[False False  True  True  True False]
>>> events = tr.find_events(condition, period=1)
>>> events.to_array()  # doctest: +SKIP
array([0., 0., 1., 1., 1., 0.])

to_series(inactive_value=0, active_value=1, index=None, dtype=None, name=None)

Returns a pandas.Series identifying found events

Useful for plotting and for filtering a pandas.DataFrame

Parameters:

• inactive_value (float, optional) – Default is 0. Value of array where events are not active.
• active_value (float, optional) – Default is 1. Value of array where events are active.
• index (array-like or Index (1d)) – Values must be hashable and have the same length as data. Non-unique index values are allowed. Will default to RangeIndex(len(data)) if not provided. If both a dict and index sequence are used, the index will override the keys found in the dict.
• dtype (numpy.dtype or None) – If None, dtype will be inferred.
• name (str, optional) – Default is Events.name. Name of series.

Returns:

A series where values are coded to identify when events are active or inactive.

Return type:

pandas.Series

Examples

>>> import trouve as tr
>>> x = np.array([2, 2, 4, 5, 3, 2])
>>> condition = x > 2
>>> print(condition)
[False False  True  True  True False]
>>> events = tr.find_events(condition, period=1)
>>> events.to_series()
0    0.0
1    0.0
2    1.0
3    1.0
4    1.0
5    0.0
Name: events, dtype: float64

__getitem__(item)

Get a specific Occurrence

Examples

>>> import numpy as np
>>> import trouve as tr
>>> x = np.array([0, 1, 1, 0, 1, 0])
>>> example = tr.find_events(x, period=1, name='example')
>>> first_event = example[0]
>>> print(first_event)
Occurrence(start=1, stop=2, slice=slice(1, 3, None), duration=2)

__len__()

Returns the number of events found

Redirects to Events._starts and returns Events._starts.size

Examples

>>> import numpy as np
>>> import trouve as tr
>>> x = np.array([0, 1, 1, 0, 1, 0])
>>> example = tr.find_events(x, period=1, name='example')
>>> len(example)
2

__repr__()

Return repr(self).

__str__()

Prints a summary of the events

Examples

>>> import numpy as np
>>> import trouve as tr
>>> x = np.array([0, 1, 1, 0, 1, 0])
>>> example = tr.find_events(x, period=1, name='example')
>>> print(example)
example
Number of events: 2
Min, Max, Mean Duration: 1.000s, 2.000s, 1.500s

__eq__(other)

Determine if two Events objects are identical

Compares Events._starts, Events._stops, Events._period and Events.condition.size to determine if equality of two events. Events objects can have different names and still be equal.

Examples

>>> import numpy as np
>>> import trouve as tr
>>> x = np.array([0, 1, 1, 0, 1, 0])
>>> example = tr.find_events(x, period=1, name='example')
>>> other = tr.find_events(x, period=1, name='other')
>>> id(example) # doctest: +SKIP
2587452050568
>>> id(other) # doctest: +SKIP
2587452084352
>>> example == other
True
>>> example != other
False

class trouve.events.Occurrence(start, stop, slice, duration)

trouve.events.Occurrence is a collections.namedtuple that is returned by both Events.__getitem__ and Events.__next__

Parameters:

• start (int): Index of the start of the occurrence
• stop (int): Index of the stop of the occurrence
• slice (slice): slice object for the entire occurrence
• duration (float): Duration in seconds of the occurrence

Examples:

>>> import numpy as np
>>> import trouve as tr
>>> x = np.array([0, 1, 1, 0, 1, 0])
>>> example = tr.find_events(x, period=1, name='example')
>>> first_event = example[0]
>>> print(first_event)
Occurrence(start=1, stop=2, slice=slice(1, 3, None), duration=2)
>>> first_event.start
1
>>> x[first_event.slice]
array([1, 1])