Epochs#

class pypillometry.Epochs(onsets, window, labels=None, meta=None, label=None)[source]#

Bases: Stateful

Event-locked windows: the onsets of events and one time window around them.

An Epochs object describes the same window around each of several events, e.g., -200 to 800 ms around every stimulus. It is returned by get_epochs() and is the input of get_segments(), which takes the length and the time axis of the segments from the window. Spans of time that are not locked to one event (e.g., between two events) are Intervals.

The columns of averaged segments (see average()) have Epochs without a time: their onsets are NaN. Such epochs can be selected and their metadata used, but they have no spans in the data.

Epochs iterate like spans ((onset + window[0], onset + window[1]) in ms), so they can be used wherever the eyedata methods take Intervals (e.g., mask_intervals() or stat_per_event()); to_intervals() converts them explicitly. Windows that extend beyond the data are not clipped; the methods that read the data handle the parts outside of it.

The events are kept as an Events object (events, in ms). Epochs are selected like events, by label, time or metadata (filter(), keep()), and their metadata are changed with set_meta(), drop_meta() and parse_labels(); these methods return new Epochs with the same window.

Parameters:

onsets (array-like or Quantity) – onsets of the events in ms (or with units, e.g., [1, 2] * u.sec); NaN for epochs without a time (averages)
window (tuple (start, end) or Quantity) – the window relative to each onset in ms (or with units, e.g., (-200, 800) * u.ms); start < end
labels (array-like of str, optional) – label of each event (default: empty strings)
meta (dict, optional) – metadata of the events (column name -> array with one value per event, see Events)
label (str, optional) – name of the epochs (e.g., the event selector)

Attributes:

eventsEvents: the events the epochs are locked to (onsets in ms)
onsetsnp.ndarray: Onsets of the events in ms (read-only).
windowtuple of float: window in ms
labelsnp.ndarray: Labels of the events (read-only).
metamapping: Metadata of the events (read-only mapping: column name -> array).
labelstr or None: name of the epochs

Examples

>>> ep = Epochs([1000, 3000], (-200, 800), labels=["stim", "stim"])
>>> list(ep)
[(800.0, 1800.0), (2800.0, 3800.0)]
>>> ep.to_intervals("sec").intervals[0]
(0.8, 1.8)
>>> ep = Epochs([1000, 3000], (-200, 800), meta={"cond": ["easy", "hard"]})
>>> ep.filter(cond="easy").onsets
array([1000.])

Methods

`as_pandas`	The epochs as a `pandas.DataFrame`.
`drop_meta`	Epochs without the metadata columns names (all, if none given; see `Events.drop_meta`).
`filter`	Epochs whose events match the criteria.
`from_events`	Epochs around all events of an `Events` object.
`keep`	Epochs where mask is True.
`merge_table`	Epochs with metadata from a table with one row per trial (see `Events.merge_table`).
`parse_labels`	Epochs with metadata from the labels of the events (see `Events.parse_labels`).
`set_meta`	Epochs with a metadata column set (see `Events.set_meta`).
`to_intervals`	The spans of the epochs as `Intervals`.

Details

classmethod from_events(events, window, label=None)[source]#

Epochs around all events of an Events object.

Parameters:

events (Events) – the events (in any time units)
window (tuple (start, end) or Quantity) – window relative to each onset, in ms or with units
label (str, optional) – name of the epochs

Return type:

Epochs

as_pandas()[source]#

The epochs as a pandas.DataFrame.

Return type:: pandas.DataFrame
Returns:: columns onset, start, end (in ms; NaN for epochs without a time), label and the metadata columns

drop_meta(*names)[source]#

Epochs without the metadata columns names (all, if none given; see Events.drop_meta).

Return type:: Epochs

filter(selector=None, exact=False, **conditions)[source]#

Epochs whose events match the criteria.

The events are selected as in Events.filter: by label, onset time (in ms), a boolean array or metadata.

Parameters:

selector (str, callable, tuple or boolean array, optional) – criterion for the events (see Events.filter)
exact (bool) – if True, a string selector matches only labels equal to it
**conditions – criteria for metadata columns, e.g. cond="easy", trial=[1, 2] or rt=lambda rt: rt < 800

Return type:

Epochs

Returns:

the selected epochs (same window and label)

Examples

>>> ep = Epochs([100, 500, 900], (0, 100), labels=["A", "B", "A"],
...             meta={"rt": [300, 900, 500]})
>>> ep.filter("A", rt=lambda rt: rt < 400).onsets
array([100.])

keep(mask)[source]#

Epochs where mask is True.

Parameters:: mask (array-like of bool) – one value per epoch
Return type:: Epochs
Returns:: the selected epochs (with their labels and metadata)

Examples

>>> ep = Epochs([100, 500, 900], (0, 100), labels=["A", "B", "C"])
>>> ep.keep(ep.onsets < 600).labels
array(['A', 'B'], dtype='<U1')

merge_table(table, on, columns=None)[source]#

Epochs with metadata from a table with one row per trial (see Events.merge_table).

Return type:: Epochs

parse_labels(parser)[source]#

Epochs with metadata from the labels of the events (see Events.parse_labels).

Return type:: Epochs

set_meta(name, values, select=None, exact=False)[source]#

Epochs with a metadata column set (see Events.set_meta).

Return type:: Epochs
Returns:: new Epochs with the changed metadata

to_intervals(units='ms', data=None)[source]#

The spans of the epochs as Intervals.

The Intervals keep the event labels, onsets and metadata per row.

Parameters:

units (str, optional) – units of the Intervals (“ms” (default), “sec”, “min”, “h”, or “samples” for sample indices of data)
data (EyeData, optional) – data object the epochs belong to; needed for “samples”

Return type:

Intervals

property duration: float#: Length of the window in ms.

property labels: ndarray#: Labels of the events (read-only).

property meta#: Metadata of the events (read-only mapping: column name -> array).

property onsets: ndarray#: Onsets of the events in ms (read-only).