SegmentedGazeNamespace#

class pypillometry.segmented.SegmentedGazeNamespace(data=None)[source]#

Bases: Namespace

Methods for gaze segments and regions of interest (ROIs), accessed as seg.gaze (e.g., seg.gaze.roi_hits(roi)).

The methods need the gaze position (<eye>_x and <eye>_y) of a SegmentedEyeData object (all eyes that have both, or those given in eyes) and raise a KeyError if there is none.

The ROIs (CircularROI, RectangularROI) are in pixels, like the gaze position. Where the gaze is in an ROI becomes a channel with the values 1 (in the ROI) and 0 (outside), masked where x or y are masked (roi_hits()). Its mean over the segments at each time point is the share of the (usable) trials in which the gaze is in the ROI (a fixation curve, plot_roi()); mean ± error plots and averaging (average(), group_segments()) work for it like for any channel. Measures per trial (dwell_time(), first_entry()) are returned as tables with the epochs’ onsets, labels and metadata.

Where the gaze is in an ROI is a property of single trials: the ROI channels must be added before averaging (the mean gaze position of several trials says nothing about where the gaze was), and roi_hits() and first_entry() raise a ValueError for averaged segments.

Methods

`dwell_time`	Time the gaze spends in a region of interest in each trial (ms).
`first_entry`	Time of the first usable sample in a region of interest in each trial (ms).
`plot_roi`	Plot the share of trials in which the gaze is in a region of interest over time (fixation curve), with an error ribbon.
`roi_hits`	Add channels that say where the gaze is in a region of interest.

Details

dwell_time(roi, eyes=[], window=None)[source]#

Time the gaze spends in a region of interest in each trial (ms).

The dwell time is the number of usable samples in the ROI times the sampling interval; masked samples are not counted. Trials without usable samples in the window get NaN. For averaged segments, whose ROI channels are shares of trials, it is the mean dwell time of the trials of each average.

Parameters:

roi (ROI or str) – the region of interest, or the name of ROI channels added with roi_hits()
eyes (str or list of str, optional) – eyes to use (default: all that have x and y, or the ROI channel)
window (tuple (start, end), Quantity or None, optional) – part of the segments to use, in ms relative to the event onsets (or with units); the end is exclusive, None as start or end leaves that side open; default: the whole segments

Return type:

Table

Returns:

a table (column name -> array with one value per trial): the onsets, labels and metadata of the epochs (if the segments have them) and the dwell time of each eye in ms ("<eye>_<roi name>"), displayed as a table (see Table)

Examples

>>> import pypillometry as pp
>>> from pypillometry import u, CircularROI
>>> d = pp.get_example_data("rlmw_002_short")
>>> seg = d.get_segments(d.get_epochs("S_", (-500, 2500) * u.ms))
>>> center = CircularROI((640, 512), radius=200, name="center")
>>> table = seg.gaze.dwell_time(center, eyes="left", window=(0, 2000))
>>> sorted(table)
['label', 'left_center', 'onset']

first_entry(roi, eyes=[], window=(0, None))[source]#

Time of the first usable sample in a region of interest in each trial (ms).

The time is relative to the event onset, from the start of window (by default, the onset): a trial in which the gaze is in the ROI at the onset gets 0. Trials in which the gaze is never in the ROI (in the usable samples of the window) get NaN. Averaged segments have no first entry (a ValueError is raised).

Parameters:

roi (ROI or str) – the region of interest, or the name of ROI channels added with roi_hits()
eyes (str or list of str, optional) – eyes to use (default: all that have x and y, or the ROI channel)
window (tuple (start, end), Quantity or None, optional) – part of the segments to search, in ms relative to the event onsets (or with units); the end is exclusive, None as start or end leaves that side open, None searches the whole segments; default (0, None): from the onset on

Return type:

Table

Returns:

a table (column name -> array with one value per trial): the onsets, labels and metadata of the epochs (if the segments have them) and the time of the first entry of each eye in ms ("<eye>_<roi name>"), displayed as a table (see Table)

Examples

>>> import pypillometry as pp
>>> from pypillometry import u, CircularROI
>>> d = pp.get_example_data("rlmw_002_short")
>>> seg = d.get_segments(d.get_epochs("S_", (-500, 2500) * u.ms))
>>> center = CircularROI((640, 512), radius=200, name="center")
>>> table = seg.gaze.first_entry(center)
>>> len(table["left_center"]) == seg.n_segments
True

plot_roi(roi, eyes=[], meanfct=<function mean>, varfct=<function sem>, show_missing=None, show_zero_line=True, show_legend=None, title=None, label=None, ribbon_alpha=0.3, ax=None, **kwargs)[source]#

Plot the share of trials in which the gaze is in a region of interest over time (fixation curve), with an error ribbon.

This is SegmentedEyeData.plot for the ROI channels (one line per eye); see there for the parameters.

Parameters:

roi (ROI or str) – the region of interest, or the name of ROI channels added with roi_hits()
eyes (str or list of str, optional) – eyes to plot (default: all that have x and y, or the ROI channel)

Returns:

ax (matplotlib.axes.Axes) – The axes object for further customization

Examples

>>> import pypillometry as pp
>>> from pypillometry import u, CircularROI
>>> d = pp.get_example_data("rlmw_002_short")
>>> seg = d.get_segments(d.get_epochs("S_", (-500, 2500) * u.ms))
>>> center = CircularROI((640, 512), radius=200, name="center")
>>> ax = seg.gaze.plot_roi(center)

../../_images/pypillometry-segmented-SegmentedGazeNamespace-1.png

roi_hits(roi, name=None, eyes=[], inplace=None)[source]#

Add channels that say where the gaze is in a region of interest.

For each eye, the channel <eye>_<name> is 1 where the gaze position (<eye>_x, <eye>_y) is in roi and 0 where it is outside; it is masked where x or y are masked. Its mean over the segments (e.g., with plot_roi() or SegmentedEyeData.plot) is the share of the usable trials in which the gaze is in the ROI at each time point. An existing channel of that name is replaced.

Parameters:

roi (ROI) – the region of interest (e.g., CircularROI, in pixels)
name (str) – name of the ROI in the channel names (default: the name of roi)
eyes (str or list of str, optional) – eyes to use (default: all that have x and y)
inplace (bool or None, optional) – if True, add the channels to the object and return it; if False, return a new object with the channels added; if None, use the package-level setting (see set_default_inplace())

Return type:

SegmentedEyeData

Returns:

the segments with the ROI channels (the object or a new one, depending on inplace)

Raises:

ValueError – if neither name nor the ROI give a name, or the name is "x", "y" or "pupil"
KeyError – if there are no gaze channels (of eyes)

Examples

>>> import pypillometry as pp
>>> from pypillometry import u, CircularROI
>>> d = pp.get_example_data("rlmw_002_short")
>>> seg = d.get_segments(d.get_epochs("S_", (-500, 2500) * u.ms))
>>> center = CircularROI((640, 512), radius=200, name="center")
>>> seg = seg.gaze.roi_hits(center, inplace=False)
>>> [ch for ch in seg.channels if ch.endswith("center")]
['left_center', 'right_center']