Transformations

This page contains all available transformations, relevant functions, and classes available in trouve.

debounce([activate_debounce, …])	Debounce activation and deactivation of events
filter_durations([min_duration, max_duration])	Filter out durations based on length of time active
offset_events([start_offset, stop_offset])	Apply an offset to event start and stops
merge_overlap(events)	Merge any events that overlap

Definitions

trouve.transformations.debounce(activate_debounce=None, deactivate_debounce=None)

Debounce activation and deactivation of events

Find an occurrence that is active for time >= activate_debounce and activate event. Deactivate event only after an occurrence is found that is inactive for time >= to deactivate_debounce. Filter out all events that fall outside of these bounds. This function is used to prevent short duration occurrences from activating or deactivating longer events. See mechanical debounce in mechanical switches and relays for a similar concept.

Parameters:

• activate_debounce (float) – Default is None. Default value does not apply an activate_debounce. Minimum time in seconds an occurrence must be active to activate an event. (event active >= activate_debounce)
• deactivate_debounce (float) – Default is None. Default value does not apply an deactivate_debounce. Maximum time in seconds an occurrence must be inactive to deactivate an event. (event inactive >= deactivate_debounce)

Returns:

Partial function

Return type:

callable

Examples

>>> import trouve as tr
>>> import trouve.transformations as tt
>>> import numpy as np
>>> y = np.array([2, 3, 2, 3, 4, 5, 2, 3, 3])
>>> condition = y > 2
>>> events = tr.find_events(condition, period=1)
>>> deb = tt.debounce(2, 2)
>>> trans_events = tr.find_events(condition, period=1, transformations=[deb])
>>> events.to_array()  # doctest: +SKIP
array([ 0.,  1.,  0.,  1.,  1.,  1.,  0.,  1.,  1.])
>>> trans_events.to_array()  # doctest: +SKIP
array([ 0.,  0.,  0.,  1.,  1.,  1.,  1.,  1.,  1.])

Raises:ValueError – If activate_debounce or deactivate_debounce < 0

trouve.transformations.filter_durations(min_duration=None, max_duration=None)

Filter out durations based on length of time active

Filter out events that are < min_duration and > max_duration (time in seconds).

Parameters:

• min_duration (float) – Default is None. Default value does not apply a min_duration filter. Filter out events whose duration in seconds is < min_duration.
• max_duration (float) – Default is None. Default value does not apply a max_duration filter. Filter out events whose duration in seconds is > max_duration.

Returns:

Partial function

Return type:

callable

Raises:

ValueError – If min_duration or max_duration is < 0

Examples

>>> import trouve as tr
>>> import trouve.transformations as tt
>>> y = np.array([2, 3, 2, 3, 4, 5, 2, 3, 3])
>>> condition = y > 2
>>> events = tr.find_events(condition, period=1)
>>> filt_dur = filter_durations(1.5, 2.5)
>>> trans_events = tr.find_events(condition, period=1, transformations=[filt_dur])
>>> events.to_array()  # doctest: +SKIP
array([ 0.,  1.,  0.,  1.,  1.,  1.,  0.,  1.,  1.])
>>> trans_events.to_array()  # doctest: +SKIP
array([ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  1.,  1.])

trouve.transformations.offset_events(start_offset=None, stop_offset=None)

Apply an offset to event start and stops

Offset the starts and stops of events by the time in seconds specified by start_offset and stop_offset.

Parameters:

• start_offset (float) – Default is None. Time in seconds to offset event starts. Value must be <= 0.
• stop_offset (float) – Default is None. Time in seconds to offset event stops. Value must be >= 0.

Returns:

Partial function

Return type:

callable

Raises:

ValueError – If start_offset > 0 or stop_offset < 0

Examples

>>> import trouve as tr
>>> import trouve.transformations as tt
>>> y = np.array([2, 2, 2, 3, 4, 5, 2, 2, 2])
>>> condition = y > 2
>>> events = tr.find_events(condition, period=1)
>>> offset = tt.offset_events(-1, 1)
>>> trans_events = tr.find_events(condition, period=1, transformations=[offset])
>>> events.to_array()  # doctest: +SKIP
array([ 0.,  0.,  0.,  1.,  1.,  1.,  0.,  0.,  0.])
>>> trans_events.to_array()  # doctest: +SKIP
array([ 0.,  0.,  1.,  1.,  1.,  1.,  1.,  0.,  0.])

trouve.transformations.merge_overlap(events)

Merge any events that overlap

Some events such as offset_events can cause events to overlap. If this transformation is applied, any events that overlap will become one contiguous event.

Parameters:events (trouve.events.Events) – Returns:Any overlapping events merged into one event. Return type:trouve.events.Events

Examples

>>> import trouve as tr
>>> import trouve.transformations as tt
>>> y = np.array([2, 3, 2, 3, 4, 5, 2, 2, 2])
>>> condition = y > 2
>>> offset = tt.offset_events(-1, 1)
>>> events = tr.find_events(condition, period=1, transformations=[offset])
>>> merged_events = tr.find_events(condition,  period=1,
... transformations=[offset, merge_overlap])
>>> events.to_array()  # doctest: +SKIP
array([ 1.,  1.,  1.,  1.,  1.,  1.,  1.,  0.,  0.])
>>> merged_events.to_array()  # doctest: +SKIP
array([ 1.,  1.,  1.,  1.,  1.,  1.,  1.,  0.,  0.])
>>> len(events)
2
>>> len(merged_events)
1