Quickstart¶

Setup¶

Example events for quickstart.

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

Finding Events¶

Find all occurrences where the numpy.array x is greater than zero. Assume the sample period is one second.

>>> sample_period = 1 #second
>>> example = find_events(x > 0, period=sample_period, name='example')
>>> len(example)
2

Applying Transformations¶

Transformation functions are applied in the specified order. Each transformation alters events inplace to avoid making unnecessary copies.

>>> deb = tt.debounce(2, 1)
>>> offset = tt.offset_events(0, 1)
>>> cond = x > 0
>>> deb_first = tr.find_events(cond, period=1,
... transformations=[deb, offset])
>>> deb_first.to_array()
array([ 0.,  1.,  1.,  1.,  0.,  0.])

Note

Order matters with transformations.

Observe how the events change if the offset is applied before debouncing.

>>> offset_first = find_events(cond, period=1, transformations=[offset, deb])
>>> offset_first.to_array()
array([ 0.,  1.,  1.,  1.,  1.,  1.])
>>> offset_first == deb_first
False

Array Methods¶

Events provides several methods to produce array representations of events.

numpy.ndarray s via Events.to_array .

>>> example.to_array()
array([ 0.,  1.,  1.,  0.,  1.,  0.])

>>> example.to_array()
array([ 0.,  1.,  1.,  0.,  1.,  0.])

>>> example.to_array()
array([ 0.,  1.,  1.,  0.,  1.,  0.])

pandas.Series s via Events.to_series .

>>> example.to_series()
  0.0
  1.0
  1.0
  0.0
  1.0
  0.0
Name: example, dtype: float64

Boolean masks via

>>> example.to_series()
  0.0
  1.0
  1.0
  0.0
  1.0
  0.0
Name: example, dtype: float64

Boolean masks via

>>> example.to_series()
  0.0
  1.0
  1.0
  0.0
  1.0
  0.0
Name: example, dtype: float64

Boolean masks via Events.to_array for use with the numpy.ma module.

>>> example.to_array(1, 0, dtype=np.bool)
array([ True, False, False,  True, False,  True], dtype=bool)
>>> x > 0
array([False,  True,  True, False,  True, False], dtype=bool)

Inspecting Events¶

The trouve.Events class implements __getitem__ which returns an Occurrence .

>>> first_event = example[0]
>>> first_event.duration
2
>>> x[first_event.slice]
array([1, 1])

trouve.Events is also an iterable through implementation of both __iter__ and __next__. Every iteration returns an Occurrence .

>>> for event in example:
...     print(event.duration)
2
1

Magic Methods¶

Trouve implements several magic methods including:

__len__ for determining the number of events found using len.

>>> len(example)
2

__str__ for printing a summary of the events with print.

>>> print(example)
example
Number of events: 2
Min, Max, Mean Duration: 1.000s, 2.000s, 1.500s

__eq__ for determining if two events are equal.

>>> example == example_2
True

Note

Equality compares _starts, _stops, _period and _condition_size of both Event``s. The event ``name does not have to be the same for both events.

__repr__ for help with trouble-shooting using repr.

>>> repr(example)
"Events(_starts=array([1, 4]), _stops=array([3, 5]), _period=1, name='example', _condition_size=6)"