add_events#

pypillometry.add_events(events)#

Pipeline step for add_events() (d | pp.add_events(...)).

Add events to the events of the dataset.

The new events are merged with the existing ones and all events are sorted by onset (events at the same time keep their order, existing ones first). Metadata columns that only the existing or only the new events have get missing values (NaN or “”) for the other events. Events from a behaviour log on another clock must be mapped to the eye-tracker clock with sync_clocks() first; a warning is given for events that are marked as being on another clock (needs_sync, e.g., from from_table()).

Parameters:

  • events (Events) – the events to add (converted to ms if needed)

  • inplace (bool or None, optional) – if True, make change in-place and return the object; if False, make and return copy before making changes; if None, use the object-level setting (specified in the constructor)

Return type:

EyeData

Returns:

the object with the added events (self or a copy, depending on inplace)

Raises:

  • TypeError – if events is not an Events object

  • ValueError – if an onset is outside the time range of the data

See also

set_events

replace all events

Examples

Events from a behaviour log behav (a table with times in sec, already on the eye-tracker clock; otherwise, see sync_clocks()):

>>> ev = pp.Events.from_table(behav, ["stim_on", "response"], units="sec",
...                           needs_sync=False)
>>> d = d.add_events(ev)