Event Iterators

In general, iterators are never created directly by the user but provided by the respective data source through the get_event_iterator method. E.g. Stream provides a StreamIterator and RDTChannel provides an RDTIterator. Irrespective of what the underlying data source is, all iterators inherit from IteratorBaseClass and share its methods and properties which are documented below.

class cait.versatile.iterators.iteratorbase.IteratorBaseClass(inds: List[int], batch_size: Optional[int] = None)

add_processing(f: Union[Callable, List[Callable]])

Add functions to be applied to each event before returning it. Batches are supported, i.e. if the iterator returns events in batches, the specified functions are applied to all events in a batch separately. However, the user is responsible for handling multiple channels correctly: Events are passed to the functions directly, even if it includes multiple channels.

Parameters

f (Union[Callable, List[Callable]]) – Function(s) to be applied. Function signature: f(event: np.ndarray) -> np.ndarray

Example:

import cait.versatile as vai

def f1(event): return event + 1
def f2(event): return event*2

it = vai.MockData().get_event_iterator()
it.add_processing([f1, f2])

with_processing(f: Union[Callable, List[Callable]])

Same as add_processing but it returns a new iterator instead of modifying the original one.

Parameters

f (Union[Callable, List[Callable]]) – Function(s) to be applied. Function signature: f(event: np.ndarray) -> np.ndarray

Example:

import cait.versatile as vai

def f1(event): return event + 1
def f2(event): return event*2

it = vai.MockData().get_event_iterator()
new_it = it.with_processing([f1, f2])

grab(which: Union[int, list])

Grab specified event(s) and return it/them as numpy array.

Parameters

which (Union[int, list]) – Events of interest.

Example:

import cait.versatile as vai

it = vai.MockData().get_event_iterator() # Get events from mock data
selected_event = it.grab(-1)             # Get the last event in the iterator
selected_events = it.grab([1,7,9])       # Get events with indices 1, 7, 9

property t

Return the time axis (record window) of the events in the iterator. It is a millisecond array with 0 being at 1/4th of the window.

property uses_batches

Returns True if the iterator returns batches.

property n_batches

Returns the number of batches in the iterator.

property hours

Returns the times (in hours) of the events in this iterators since the start of the underlying datasource.

abstract property record_length

Returns the record length (in samples) of the events in the iterator.

abstract property dt_us

Returns the time base (in microseconds) of the events in the iterator.

abstract property ds_start_us

The microsecond timestamp of the start of the recording for the datasource underlying this iterator object.

abstract property timestamps

Returns microsecond timestamps corresponding to the trigger times of the events in the iterator.

abstract property n_channels

Returns the number of channels in the iterator.