EyeData#

class pypillometry.EyeData(time=None, left_x=None, left_y=None, left_pupil=None, right_x=None, right_y=None, right_pupil=None, event_onsets=None, event_labels=None, events=None, sampling_rate=None, experimental_setup=None, name=None, calibration=None, fill_time_discontinuities=True, keep_orig=False, info=None, inplace=None)[source]#

Bases: VersionedState

Class for eye-tracking and pupillometric data: pupil size and/or gaze position (x, y) of one or two eyes.

The object can hold any of these channels (e.g., only pupil data, only gaze data, or both). The methods for pupil data are in the namespace d.pupil (PupilNamespace, e.g. d.pupil.blinks_detect()), those for gaze data in d.gaze (GazeNamespace) and the plots in d.plot (PlotNamespace, e.g. d.plot.plot_pupil()); they raise a ValueError if the object has no such data. The methods for any channel (e.g., crop()) are methods of the object. All transforming methods can also be used as pipeline steps, e.g. d | pp.pupil.blinks_detect() | pp.crop(0, "10 min") (see Pipeline).

Parameters:

time (ndarray) – timing array (in ms) or None, in which case the time-array goes from [0,maxT] using sampling_rate
left_x (ndarray) – data from the left eye: gaze position (x and y, both or neither) and pupil size; at least one channel of one eye must be provided
left_y (ndarray) – data from the left eye: gaze position (x and y, both or neither) and pupil size; at least one channel of one eye must be provided
left_pupil (ndarray) – data from the left eye: gaze position (x and y, both or neither) and pupil size; at least one channel of one eye must be provided
right_x (ndarray) – data from the right eye (as for the left eye)
right_y (ndarray) – data from the right eye (as for the left eye)
right_pupil (ndarray) – data from the right eye (as for the left eye)
event_onsets (ndarray) – time-onsets of any events in the data (in ms, matched in time vector)
event_labels (ndarray) – for each event in event_onsets, provide a label
events (Optional[Events]) – the events as an Events object (e.g., with metadata); instead of event_onsets and event_labels
sampling_rate (float) – sampling-rate of the signal in Hz; if None, it is estimated from the median difference in time (either time or sampling_rate must be provided)
experimental_setup (Optional[ExperimentalSetup]) – Geometric model of the experimental setup including screen geometry, eye position, camera position, and screen orientation.
name (str) – name of the dataset or None (in which case a random string is selected)
calibration (Optional[Dict[str, SpatialCalibration]]) – Dictionary of SpatialCalibration objects, one per eye (keys: ‘left’, ‘right’)
fill_time_discontinuities (bool) – sometimes, when the eyetracker loses signal, no entry in the EDF is made; when this option is True, such entries will be made and the signal set to 0 there (or do it later using fill_time_discontinuities())
keep_orig (bool) – keep a copy of the original dataset? If True, a copy of the object as initiated in the constructor is stored in member original
info (dict) – optional dictionary with additional information about the dataset (stored in member info)
inplace (Optional[bool]) – default for methods called with inplace=None: if True, they modify the object in place; if False, they return a modified copy; if None (default), use the package-level setting (see set_default_inplace(), initially True). The method-level inplace argument overrides this.

Examples

>>> import numpy as np
>>> import pypillometry as pp
>>> rng = np.random.default_rng(1)
>>> d = pp.EyeData(time=np.arange(0, 1000, 1),
...                left_x=rng.normal(size=1000),
...                left_y=rng.normal(size=1000),
...                left_pupil=rng.normal(5, 0.1, size=1000))
>>> d.eyes, d.variables, len(d)
(['left'], ['x', 'y', 'pupil'], 1000)
>>> print(d)  # summary of the data

Methods

`add_events`	Add events to the events of the dataset.
`add_to_history`	Add event to history.
`blink_stats`	Return statistics on blink durations.
`clear_layer`	Clear a mask layer (e.g., `"blink"`) for the selected channels.
`copy`	Make and return a deep-copy of the eyedata object.
`crop`	Crop the data to the time range from start to end.
`downsample`	Simple downsampling scheme using mean within the downsampling window.
`drop_data`	Drop specified eyes and/or variables from the data.
`drop_original`	Drop original dataset from record (e.g., to save space).
`exclude_intervals`	Exclude periods that are not part of the analysis (e.g., breaks or the calibration at the start).
`excluded_duration`	Total duration of the excluded periods within the data.
`fill_time_discontinuities`	Find gaps in the time-vector and fill them in.
`from_eyelink`	Reads an eyedata object from an Eyelink file.
`from_file`	Reads a `EyeData` object from a pickle or HDF5 file (see `write_file()`).
`get_blinks`	Get blinks as a dict of Intervals (one per eye/variable).
`get_duration`	Return duration of the dataset in units specified.
`get_epochs`	Return the time windows around events (Epochs).
`get_excluded`	Return the excluded periods (see `exclude_intervals()`).
`get_included`	Return the periods that are not excluded (see `exclude_intervals()`).
`get_interpolated`	Get the interpolated stretches as a dict of Intervals (one per eye/variable).
`get_intervals`	Return the spans between two kinds of events (Intervals).
`get_layer_intervals`	Get the runs of a mask layer (e.g., `"offscreen"`) as a dict of Intervals.
`get_segments`	Cut the data around events into segments of equal length.
`get_size`	Return the size of the object in bytes.
`get_values`	Values of a channel with NaN where the sample is unusable under policy.
`interpolate_intervals`	Interpolate data within specified intervals.
`keep_intervals`	Exclude everything outside the given periods (e.g., keep only the task blocks or the fMRI run).
`layer_stats`	Statistics of the mask layers: how often and how long each channel is marked by each layer.
`mask`	Mask of a channel under a mask policy (True: unusable sample).
`mask_as_intervals`	Convert masks to Intervals objects.
`mask_intervals`	Apply Intervals as masks to selected data.
`merge_eyes`	Merge data from both eyes into a single variable.
`merge_masks`	Merge masks of all variables into a single joint mask.
`nevents`	Return number of events in data.
`print_history`	Pretty-print the history of the current dataset (which manipulations where done on it).
`quality_report`	Report the quality of the data.
`remove_intervals`	Remove the data in the given periods (e.g., breaks) and join the rest.
`reset_time`	Resets time so that time t0 becomes time zero.
`scale`	Scale the signal: subtract center and divide by scale.
`set_blinks`	Set blinks for specified eyes and variables (in-place).
`set_events`	Replace the events of the dataset (in-place).
`set_experimental_setup`	Set or update the experimental setup geometry (in-place).
`split_excluded`	Split the data at the excluded periods (see `exclude_intervals()`).
`stat_per_event`	Return result of applying a statistical function to data in a given interval relative to event-onsets.
`summary`	Return a summary of the dataset as a dictionary.
`unscale`	Scale back to original values using either values provided as arguments or the values stored in params["scale"] by `scale()`.
`write_file`	Save to file (using `write_file()`).

Details

gaze#: alias of GazeNamespace

plot#: alias of PlotNamespace

pupil#: alias of PupilNamespace

classmethod from_eyelink(fname, return_edf_obj=False, remove_eyelink_triggers=True, **kwargs)[source]#

Reads an eyedata object from an Eyelink file.

All “messages” are stored as events (can be filtered later) and it tries to be smart to detect different information from the EDF file. Spatial calibration/validation data is automatically parsed and stored in the calibration attribute as SpatialCalibration objects. Eyelink codes missing pupil samples (e.g., during blinks) as 0; these are converted to NaN (and therefore masked).

However, the EDF file may contain other information of interest, e.g., eyelink-detected saccades, etc. If you need more control, use the “eyelinkio” package directly and create the object manually.

Reading EDF files is slow (about a minute for a 90 MB file). Save the object with write_file() and read it with from_file() later, or convert the files once with the command-line program edf2pypil.

Parameters:

fname (str) – filename of the EDF file, HTTP(S) URL or SSH URL (ssh://server/folder/file.edf, see pypillometry.io.fetch_url())
return_edf_obj (bool) – if True, return a tuple with the eyedata object and the object returned by the “eyelinkio” package; if False (default), return only the eyedata object
remove_eyelink_triggers (bool) – if True (default), remove all Eyelink triggers from the events (related to eye-tracker settings, calibration, validation etc)
**kwargs – additional arguments passed to pypillometry.io.read_eyelink() (e.g., cache_file, cache_dir, cache_layout, autodelete, session)

Return type:

EyeData or tuple

Returns:

object of the class this method is called on (e.g., EyeData), or tuple with that object and the object returned by the “eyelinkio” package

Examples

>>> import pypillometry as pp
>>> d = pp.EyeData.from_eyelink('data.edf')
>>> # Access calibration data
>>> print(d.calibration['left'])
<SpatialCalibration: left eye, HV9, n=9, error=0.45±0.23° (max=0.79°)>

classmethod from_file(fname, **kwargs)[source]#

Reads a EyeData object from a pickle or HDF5 file (see write_file()). Use as pypillometry.EyeData.from_file("yourfile.pypil").

The file is read with pypillometry.io.read_file(), so fname can also be an HTTP(S) or SSH URL. Files written by older versions of pypillometry are upgraded to the current version. Pickle files can run arbitrary code when they are read: only read them from sources you trust (HDF5 files do not run code).

Parameters:

fname (str) – filename (or URL)
**kwargs – passed to pypillometry.io.read_file() (e.g., cache_file, cache_dir, cache_layout, autodelete, session)

Return type:

EyeData

Returns:

the object stored in the file (its class is the one that was stored, independent of the class this method is called on)

add_events(events, inplace=None)[source]#

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)

add_to_history(event)[source]#

Add event to history.

Usually called by the keephistory decorator.

Parameters:: event (dict) – description of the operation with keys “funcstring” (printable call) and “funcname” (method name)

blink_stats(eyes=[], units='ms')[source]#

Return statistics on blink durations.

Uses the blinks stored for the “pupil” variable of each eye; a shortcut for the rows "blink" of layer_stats(), as a dict.

Parameters:

eyes (list) – eye(s) to consider; if empty, all available eyes
units (str) – Units for statistics: “ms”, “sec”, “min”, or “h”. Default “ms”.

Return type:

dict

Returns:

stats dict (number, mean, sd, min, max and total duration of blinks; number 0 and NaN without blinks) for each eye with pupil data, with keys like “left_pupil”

clear_layer(name, eyes=[], variables=[], inplace=None)[source]#

Clear a mask layer (e.g., "blink") for the selected channels.

Clearing "blink" removes the blinks and their mask (e.g., to undo d.pupil.blinks_detect()). "excluded" is a recording-wide layer: clearing it removes the excluded periods (eyes and variables are ignored).

Parameters:

name (str) – name of the layer
eyes (str | list) – eye(s); if empty, all available eyes
variables (str | list) – variable(s); if empty, all available variables
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 without the layer (self or a copy, depending on inplace)

copy(new_name=None)[source]#

Make and return a deep-copy of the eyedata object.

Parameters:: new_name (Optional[str]) – New name for the copy. If None, “_copy” is appended to the original name.
Return type:: EyeData
Returns:: deep copy of the object (same class as the original)

crop(start=-inf, end=inf, units='ms', inplace=None)[source]#

Crop the data to the time range from start to end.

The result contains all data (and events) between start and end (inclusive), e.g. d.crop(3*u.min, 5*u.min) or d.crop("3 min", "5 min"). start and end refer to the values of the time-vector (not to the time since the start of the recording). Masks are kept; stored blinks (in sample indices) are shifted and cut to the new range.

Parameters:

start (float) – start for new dataset; default: beginning of the data
end (float) – end of new dataset; default: end of the data
units (str) – time units of start and end if they are plain numbers (one of “ms”, “sec”, “min”, “h”); default “ms” (the units of the time vector).
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 shortened object (self or a copy, depending on inplace)

Raises:

ValueError – if start is after end or there are no samples between them

See also

remove_intervals: remove periods (e.g., breaks) and join the rest

downsample(fsd, dsfac=False, policy='default', inplace=None)[source]#

Simple downsampling scheme using mean within the downsampling window.

All data fields and the time-vector are downsampled simultaneously. See pypillometry.signal.baseline.downsample(). The samples that are unusable under the mask policy are left out of the window means (by default, interpolated samples are used, see mask()). A layer is kept for a new sample if it covers more than half of its window. A new sample whose window has no usable sample holds the mean of the stored values (NaN only if they are NaN) and stays unusable.

The new sampling rate is fs/factor, the rate of the decimated data. It differs from fsd if fs/fsd is not an integer (e.g., 1000 Hz with fsd=300 gives factor 3 and 333.3 Hz).

Parameters:

fsd (float) – new sampling-rate (in Hz) or decimate-factor
dsfac (bool) – if False (default), fsd is the requested sampling rate (the decimate factor is int(fs/fsd); a warning is logged if fs/fsd is not an integer); if True, fsd is the decimate factor (a positive integer)
policy (str, MaskPolicy or list of str) – mask policy that decides which samples are used for the window means (see mask()); default "default"
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 downsampled object (self or a copy, depending on inplace)

Raises:

TypeError – if fsd is not a number
ValueError – if the sampling rate fsd is not above 0 and at most fs, or the decimate factor is not a positive integer

drop_data(eyes=[], variables=[], inplace=None)[source]#

Drop specified eyes and/or variables from the data.

All data of the given eyes and all data of the given variables are dropped (together with their mask layers). Everything else is kept (events, excluded periods, parameters, history, experimental setup, calibration); the class of the object does not change.

Parameters:

eyes (list) – Eyes to drop (e.g., [‘left’] or [‘right’] or [‘left’, ‘right’]); if empty, no eye is dropped
variables (list) – Variables to drop (e.g., [‘pupil’] or [‘x’, ‘y’]); if empty, no variable is dropped
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 without the specified data (self or a copy, depending on inplace)

Raises:

KeyError – If an eye or variable does not exist.
ValueError – If dropping would result in no data remaining.

Examples

>>> import pypillometry as pp
>>> d = pp.get_example_data("rlmw_002_short")
>>> # Drop left eye data
>>> right_only = d.drop_data(eyes=["left"], inplace=False)
>>> right_only.eyes
['right']
>>> # Drop pupil data, keep only gaze
>>> gaze_only = d.drop_data(variables=["pupil"], inplace=False)
>>> # Drop right eye and pupil data
>>> left_gaze = d.drop_data(eyes=["right"], variables=["pupil"], inplace=False)
>>> sorted(left_gaze.data.keys())
['left_x', 'left_y']

drop_original(inplace=None)[source]#

Drop original dataset from record (e.g., to save space).

Sets the original attribute (stored when the object was created with keep_orig=True) to None.

Parameters:: 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 without the original data (self or a copy, depending on inplace)

exclude_intervals(intervals, inplace=None)[source]#

Exclude periods that are not part of the analysis (e.g., breaks or the calibration at the start).

The periods are stored with the object as the recording-wide "excluded" layer (see get_excluded()), which masks all variables (also those added later), so that functions that ignore masked data (e.g., scale(), get_segments()) also ignore the excluded periods. Unlike other masked data (blinks, artifacts), excluded periods are not treated as missing data: blink detection cuts blinks at them, and blinks that end in an excluded period are not interpolated. Blinks detected before keep their layer.

The layer moves with the samples (crop(), downsample(), remove_intervals(), …). Calling the method again adds to the excluded periods; clear_layer("excluded") removes them.

Parameters:

intervals (Intervals, Epochs or list of tuple) – the periods to exclude: an Intervals object (e.g., from get_intervals(); in time units or sample indices), Epochs or a list of (start, end) tuples (in ms, or with units, e.g., [(0, 2 * u.min)]; "<start>" and "<end>" stand for the start and end of the recording, e.g., [(10 * u.min, "<end>")]); ends are exclusive
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 excluded periods (self or a copy, depending on inplace)

See also

keep_intervals: exclude everything outside the given periods

Examples

>>> breaks = d.get_intervals(start="break_start", end="break_end", units="ms")
>>> d = d.exclude_intervals(breaks)
>>> d = d.exclude_intervals([(0, 2 * u.min)])

excluded_duration(units='ms')[source]#

Total duration of the excluded periods within the data.

Parameters:: units (str) – units of the result (“ms” (default), “sec”, “min”, “h” or “samples”)
Return type:: float
Returns:: the excluded time (number of excluded samples / sampling rate)

fill_time_discontinuities(yval=nan, print_info=True, inplace=None)[source]#

Find gaps in the time-vector and fill them in.

A gap is a step between consecutive time points that is larger than twice the median step. New time points are inserted into each gap at the median step size and all data variables are set to yval at these new time points; they are masked as missing. Existing masks are kept and stored blinks (in sample indices) are moved to the new sample positions. This is called by the constructor when fill_time_discontinuities=True.

Parameters:

yval (float, optional) – value used for the data in the filled-in gaps; default NaN, so the filled-in samples are masked as missing data (other values: masked by the "user" layer)
print_info (bool, optional) – if True (default), log the number of gaps that are filled in
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 without gaps (self or a copy, depending on inplace)

get_blinks(eyes=[], variables=[], units='ms')[source]#

Get blinks as a dict of Intervals (one per eye/variable).

The blinks are the runs of the "blink" layer (blinks that overlap or touch are one blink), also those in or next to an excluded period (see exclude_intervals()). If no blinks are stored for an eye/variable, an empty Intervals object is returned for it.

Parameters:

eyes (str | list) – Eye(s) to get blinks for; if empty, all available eyes.
variables (str | list) – Variable(s) to get blinks for; if empty, all available variables.
units (str) – Units for intervals: “ms” (default), “sec”, “min”, “h”, or “samples” for sample indices

Return type:

dict

Returns:

one Intervals object per existing eye/variable combination, keys like “left_pupil” (also for a single eye and variable)

Raises:

KeyError – if a requested eye/variable combination does not exist (see select())

Examples

>>> import pypillometry as pp
>>> d = pp.get_example_data("rlmw_002_short").pupil.blinks_detect()
>>> blinks = d.get_blinks("left", "pupil")["left_pupil"]
>>> blinks_sec = d.get_blinks("left", "pupil", units="sec")["left_pupil"]
>>> blinks_dict = d.get_blinks(["left", "right"], "pupil")
>>> list(blinks_dict)
['left_pupil', 'right_pupil']
>>> blinks_idx = blinks.to_units("indices", d)

get_duration(units='ms')[source]#

Return duration of the dataset in units specified.

Parameters:: units (str, optional) – unit one of “ms” (default), “sec”, “min”, “h” or “samples”
Return type:: float
Returns:: duration of dataset in specified units

get_epochs(event_select, window, units=UNSET, label=None, exact=False, **kwargs)[source]#

Return the time windows around events (Epochs).

Selects events, e.g., all stimuli, and one time window around each of them, e.g., from 200 ms before to 1000 ms after the stimulus. The result is the input of get_segments() (event-related pupil dilations) and can be used wherever intervals are taken (e.g., stat_per_event(), mask_intervals()). For spans between two different events (e.g., from trial start to response), use get_intervals().

Parameters:

event_select (str, function or Events) –
which events to select:
- str: all events whose label contains the string (or is equal to it, if exact is True); "<start>" and "<end>" stand for the start and the end of the recording
- function: applied to all labels, the events where it returns True are used
- Events: the events of this Events object (e.g., d.events.filter(cond="easy"))
window (tuple (min, max) or Quantity) – time window relative to the event onset (0 is the onset; negative numbers are before it), e.g. (-200, 800) * u.ms or ("-0.2 sec", "0.8 sec"). Plain numbers are in units.
units (str) – units of plain numbers in window (“ms”, “sec”, “min”, “h”, or “samples” for sample indices, converted to ms with the sampling rate); default: the units of window, or “ms” for plain numbers
label (str | None) – label of the Epochs; if None, it is taken from event_select
exact (bool) – if True, a string selector matches only labels that are equal to it; if False (default), labels that contain it
**kwargs – passed on to the event_select function; an error is raised if it is not a function

Return type:

Epochs

Returns:

the selected events (onsets in ms, labels and metadata, see Events) and the window (in ms). Windows that extend beyond the data are not clipped.

Examples

>>> import pypillometry as pp
>>> from pypillometry import u
>>> d = pp.EyeData(time=range(10000), left_pupil=range(10000),
...                event_onsets=[2000, 6000], event_labels=["stim", "stim"])
>>> d.get_epochs("stim", (-200, 800) * u.ms)
Epochs 'stim' | 2 epochs, window (-200, 800) ms

get_excluded(units='ms')[source]#

Return the excluded periods (see exclude_intervals()).

The periods are the runs of samples of the "excluded" layer (from the time of their first sample to the time of the sample after the last one).

Parameters:: units (str) – units of the returned intervals (“ms” (default), “sec”, “min”, “h”, or “samples” for sample indices)
Return type:: Intervals
Returns:: the excluded periods (empty if there are none)

get_included(units='ms')[source]#

Return the periods that are not excluded (see exclude_intervals()).

These are the contiguous runs of samples outside the excluded periods (the whole recording if nothing is excluded).

Parameters:: units (str) – units of the returned intervals (“ms” (default), “sec”, “min”, “h”, or “samples” for sample indices)
Return type:: Intervals
Returns:: the included periods (end-exclusive)

get_interpolated(eyes=[], variables=[], units='ms')[source]#

Get the interpolated stretches as a dict of Intervals (one per eye/variable).

These are the runs of the "interpolated" layer, set by d.pupil.blinks_interpolate() (interpolated blinks) and by interpolate_intervals() (any intervals). Interpolated blinks may differ from the detected blinks (get_blinks()) because:

Blink boundaries are refined using velocity thresholds
Some blinks may be skipped if they’re too short to interpolate

If nothing was interpolated for an eye/variable, an empty Intervals object is returned for it.

Parameters:

eyes (str | list) – Eye(s) to get interpolated stretches for; if empty, all available eyes.
variables (str | list) – Variable(s) to get interpolated stretches for; if empty, all available variables.
units (str) – Units for intervals: “ms” (default), “sec”, “min”, “h”, or “samples” for sample indices

Return type:

dict

Returns:

one Intervals object per existing eye/variable combination, keys like “left_pupil” (also for a single eye and variable)

Raises:

KeyError – if a requested eye/variable combination does not exist (see select())

See also

get_blinks: Get detected blinks
get_layer_intervals: Get the runs of any mask layer
pypillometry.eyedata.pupil.PupilNamespace.blinks_interpolate: Interpolate blinks

get_intervals(*, start, end, window=(0, 0), units=UNSET, label=None, exact=False, **kwargs)[source]#

Return the spans between two kinds of events (Intervals).

For example, the time from each trial start to the response, or the breaks between blocks. For one time window around single events (e.g., stimuli), use get_epochs().

Each start event is paired with the next end event after it (an end event at the same time does not count). If several start events come before the same end event, the last of them is used. Events without a partner are skipped with a warning that lists them (not for "<start>" and "<end>", which are paired with the first or last event only).

Parameters:

start (str or function) –
the events at the start and at the end of the spans:
- str: all events whose label contains the string (or is equal to it, if exact is True); "<start>" and "<end>" stand for the start and the end of the recording (the first sample and one sample past the last one, as intervals are end-exclusive)
- function: applied to all labels, the events where it returns True are used
For example, start="End Block", end="Start Block" gives the breaks between blocks and start="<start>", end="Start Block" the time before the first block.
end (str or function) –
the events at the start and at the end of the spans:
- str: all events whose label contains the string (or is equal to it, if exact is True); "<start>" and "<end>" stand for the start and the end of the recording (the first sample and one sample past the last one, as intervals are end-exclusive)
- function: applied to all labels, the events where it returns True are used
For example, start="End Block", end="Start Block" gives the breaks between blocks and start="<start>", end="Start Block" the time before the first block.
window (tuple or Quantity, optional) – window[0] is added to the start events and window[1] to the end events; default (0, 0): exactly the spans between them. Plain numbers are in units.
units (str) – units of plain numbers in window and of the returned Intervals (“ms”, “sec”, “min”, “h”, or “samples” for sample indices: each event is placed at the first sample at or after its onset); default: the units of window, or “ms”
label (str | None) – label of the Intervals; if None, "<start> to <end>" (for two strings)
exact (bool) – if True, string selectors match only labels that are equal to them; if False (default), labels that contain them
**kwargs – passed on to the selector functions; an error is raised if no selector is a function

Return type:

Intervals

Returns:

the spans (in units) with, per interval, the label "<start label> to <end label>", the onset of the start event and its metadata (those of the end event if start is "<start>"). Intervals that extend beyond the data are not clipped.

Examples

>>> import pypillometry as pp
>>> d = pp.EyeData(time=range(10000), left_pupil=range(10000),
...                event_onsets=[1000, 3000, 5000, 8000],
...                event_labels=["trial", "resp", "trial", "resp"])
>>> d.get_intervals(start="trial", end="resp").intervals
[(1000.0, 3000.0), (5000.0, 8000.0)]

get_layer_intervals(name, eyes=[], variables=[], units='ms')[source]#

Get the runs of a mask layer (e.g., "offscreen") as a dict of Intervals.

Each contiguous run of samples in which the layer is set becomes one interval. See get_blinks() for the blinks and get_excluded() for the excluded periods.

Parameters:

name (str) – name of the layer (e.g., "blink", "interpolated", "offscreen", "divergence", "user")
eyes (str | list) – eye(s); if empty, all available eyes
variables (str | list) – variable(s); if empty, all available variables
units (str) – units of the intervals: “ms” (default), “sec”, “min”, “h”, or “samples” for sample indices

Return type:

dict

Returns:

one Intervals object per existing eye/variable combination, keys like “left_x” (empty Intervals where the layer is not set)

Examples

>>> d = d.gaze.mask_offscreen()
>>> d.get_layer_intervals("offscreen", variables="x")

get_segments(epochs, channels=None, name=None, policy='default', eyes=[], variables=[])[source]#

Cut the data around events into segments of equal length.

Creates a SegmentedEyeData object with the segments of one or several channels (by default, all), cut at the same epochs; trials are selected for all channels at once (e.g., seg.filter(cond="easy")).

Parameters:

epochs (Epochs or Intervals) – the segments to extract: Epochs (from get_epochs(); length and time axis window[0] + arange(n) * 1000/fs from the window, parts outside the data masked) or Intervals that all have the same length (time axis from 0 at their starts)
channels (str or list of str, optional) – channels to extract (e.g., "left_pupil" or ["left_x", "left_y"]); if None, those of eyes and variables
name (str) – Name for the segmented dataset. If None, uses the label of epochs or “segments”
policy (str, MaskPolicy or list of str) – mask policy of the segments: the samples that are unusable under it are masked (see mask()); default "default" (interpolated samples are used)
eyes (str or list of str, optional) – eyes to extract if channels is None (default: all)
variables (str or list of str, optional) – variables to extract if channels is None (e.g., "pupil"; default: all)

Return type:

SegmentedEyeData

Returns:

Object containing the extracted segments with mask information

Raises:

ValueError – if epochs are Intervals of different lengths (e.g., between two events), or both channels and eyes/variables are given
KeyError – if a channel, eye or variable does not exist

See also

get_epochs: Windows around events (Epochs)
SegmentedEyeData: Class holding segmented data

Examples

>>> import pypillometry as pp
>>> d = pp.get_example_data("rlmw_002_short")
>>> epochs = d.get_epochs("F_", window=(-200, 800), units="ms")
>>> # all channels (pupil and gaze of both eyes)
>>> seg = d.get_segments(epochs)
>>> # pupil segments around the feedback events
>>> erpd = d.get_segments(epochs, variables="pupil")
>>> erpd.channels
['left_pupil', 'right_pupil']
>>> erpd.pupil.plot()

>>> # Apply baseline correction
>>> erpd_bc = erpd.pupil.baseline_correct(window=(-200, 0))

get_size()[source]#

Return the size of the object in bytes.

Return type:: ByteSize
Returns:: Total size of the object, including data and all attributes.

get_values(eye, var=None, policy='default')[source]#

Values of a channel with NaN where the sample is unusable under policy.

Parameters:

eye (str) – see mask()
var (str | None) – see mask()
policy – see mask()

Return type:

ndarray

Returns:

copy of the values (float), NaN where mask() is True

interpolate_intervals(intervals, eyes=[], variables=[], method='linear', margin=(-20, 20), store_as_suffix=None, policy='default', inplace=None)[source]#

Interpolate data within specified intervals.

This function replaces data within the specified intervals with interpolated values based on boundary points outside each interval. The interpolated samples get the "interpolated" layer (see get_interpolated()), so they are used under the default mask policy and masked under the "strict" one (see mask()). Intervals without usable boundary points on both sides are skipped with a warning.

Parameters:

intervals (Intervals, Epochs, list of tuple or dict) –
Either:
- A single Intervals (or Epochs) object or a list of (start, end) tuples (in ms, or with units): applied to all specified eyes/variables
- A dict of Intervals (or Epochs): keys like “left_pupil”, “right_x”, etc. When dict is provided, eyes and variables are ignored.
eyes (str or list of str, optional) – eye(s) to interpolate; if empty, all available eyes. Ignored if intervals is a dict.
variables (str or list of str, optional) – variable(s) to interpolate; if empty, all available variables. Ignored if intervals is a dict.
method (str, default "linear") – Interpolation method. Options: “linear”, “nearest”, “zero”, “slinear”, “quadratic”, “cubic”, “previous”, “next”. Passed to scipy.interpolate.interp1d.
margin (tuple, default (-20, 20)) – Time window (in ms) before and after the interval to collect boundary points for interpolation, relative to the start and end of each interval: points are taken from start + margin[0] to the start and from the end to end + margin[1], so margin[0] must be <= 0 and margin[1] >= 0. Samples that are unusable under policy (masked or NaN) are not used. For higher-order methods like “cubic” or “quadratic”, more boundary points from this margin are used to fit the interpolation curve.
store_as_suffix (str or None, default None) – If None, replace the original data. If a string, store interpolated data in a new variable with this suffix (e.g., “_interp” creates “left_pupil_interp”).
policy (str, MaskPolicy or list of str) – mask policy that decides which boundary points are usable (see mask()); default "default"
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 interpolated data (self or a copy, depending on inplace).

See also

mask_intervals: Apply intervals as masks without interpolation
get_blinks: Retrieve stored blink intervals

Examples

Interpolate blinks for left eye pupil data:

>>> import pypillometry as pp
>>> d = pp.get_example_data("rlmw_002_short").pupil.blinks_detect()
>>> blinks = d.get_blinks(eyes="left", variables="pupil")["left_pupil"]
>>> d1 = d.interpolate_intervals(blinks, eyes=["left"], variables=["pupil"],
...                              inplace=False)

Interpolate using a dict of intervals:

>>> blinks = d.get_blinks()  # returns dict
>>> d2 = d.interpolate_intervals(blinks, inplace=False)

Store interpolated data in a new variable:

>>> d3 = d.interpolate_intervals(blinks, store_as_suffix="_interp",
...                              inplace=False)
>>> "left_pupil_interp" in d3.data
True

Use cubic interpolation with wider margin:

>>> d4 = d.interpolate_intervals(blinks, method="cubic", margin=(-50, 50),
...                              inplace=False)

keep_intervals(intervals, inplace=None)[source]#

Exclude everything outside the given periods (e.g., keep only the task blocks or the fMRI run).

Same as exclude_intervals(intervals.complement(d)): the time before, between and after the periods is excluded (see exclude_intervals()). Periods that are already excluded stay excluded, also if they are within intervals.

Parameters:

intervals (Intervals, Epochs or list of tuple) – the periods to keep: an Intervals object (e.g., from get_intervals(); in time units or sample indices), Epochs or a list of (start, end) tuples (in ms, or with units; "<start>" and "<end>" stand for the start and end of the recording); ends are exclusive
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 excluded periods (self or a copy, depending on inplace)

Examples

>>> run = d.get_intervals(start="rsfMRI_ONSET", end="rsfMRI_END", units="ms")
>>> d = d.keep_intervals(run)

layer_stats(layers=None, eyes=[], variables=[], units='ms', policy='default')[source]#

Statistics of the mask layers: how often and how long each channel is marked by each layer.

For each channel and layer: the number of stretches (runs of marked samples), their mean, SD, minimum, maximum and total duration, and the percentage of the samples that are marked. The entry "masked" of a channel counts all samples that are unusable under policy (all layers together, and NaN; a sample can be in several layers, so the percentages of the layers do not add up to it).

Stretches and percentages refer to the included time (excluded periods left out), as in the quality report (quality_report()). The excluded periods themselves are described by d.get_excluded().stats() and excluded_duration().

Parameters:

layers (str or list of str, optional) – layers to describe (e.g., "blink", ["offscreen", "masked"]); default: all layers that are set on a channel (a pupil channel has no "offscreen" entry, for example) and "masked"
eyes (str | list) – eyes to consider; if empty, all available eyes
variables (str | list) – variables to consider; if empty, all available variables
units (str) – units of the durations: “ms” (default), “sec”, “min”, “h” or “samples”
policy (str, MaskPolicy or list of str, optional) – mask policy of the entry "masked" (see mask()); default "default"

Return type:

RecordDict

Returns:

channel -> layer -> statistics (n, mean, sd, min, max, total_duration and units of the stretches, percent of the samples), e.g. stats["left_pupil"]["blink"]["n"]; displayed as a table with one row per channel and layer (see RecordDict)

Raises:

ValueError – if layers contains "excluded" (see above)

See also

blink_stats: the statistics of the blinks only
get_layer_intervals: the stretches of a layer as Intervals
plot.PlotNamespace.plot_masked: plot of the unusable stretches

Examples

>>> import pypillometry as pp
>>> d = pp.get_example_data("rlmw_002_short")
>>> d = d | pp.pupil.blinks_detect() | pp.gaze.mask_offscreen()
>>> stats = d.layer_stats(eyes="left")
>>> {ch: list(layers) for ch, layers in stats.items()}
{'left_x': ['offscreen', 'masked'], 'left_y': ['offscreen', 'masked'], 'left_pupil': ['blink', 'masked']}
>>> stats["left_pupil"]["blink"]["n"]
14

mask(eye, var=None, policy='default')[source]#

Mask of a channel under a mask policy (True: unusable sample).

A sample is unusable if its value is NaN or if one of the layers of the policy is set (see MaskPolicy). By default, blinks, off-screen gaze, eye divergences, user masks and excluded periods are masked, interpolated samples are not.

Parameters:

eye (str) – eye (e.g., “left”) or the key of the channel (e.g., “left_pupil”)
var (str | None) – variable (e.g., “pupil”); None if eye is the key
policy (str, MaskPolicy or list of str) – "default", "strict" (interpolated samples are masked too), "raw" (nothing is masked), a MaskPolicy or a list of layers

Return type:

ndarray

Returns:

boolean array, one value per sample

Examples

>>> d.mask("left", "pupil")
>>> d.mask("left_pupil", policy="strict")
>>> d.mask("left", "pupil", policy=["blink"])

mask_as_intervals(eyes=[], variables=[], units='ms', label=None, policy='default')[source]#

Convert masks to Intervals objects.

Each contiguous run of masked samples (unusable under the mask policy, see mask()) becomes one interval.

Parameters:

eyes (str | list) – Eye(s) to get masks for; if empty, all available eyes.
variables (str | list) – Variable(s) to get masks for; if empty, all available variables (combinations not present in the data are left out).
units (str) – Units for intervals: “ms” (default), “sec”, “min”, “h”, or “samples” for sample indices.
label (str | None) – Descriptive label for the intervals. Default is None.
policy (str, MaskPolicy or list of str) – mask policy (see mask()); default "default"

Return type:

dict

Returns:

one Intervals object per existing eye/variable combination, keys like “left_pupil” (also for a single eye and variable)

Raises:

KeyError – if a requested eye/variable combination does not exist (see select())

Examples

>>> import pypillometry as pp
>>> d = pp.get_example_data("rlmw_002_short").pupil.blinks_detect()
>>> masked = d.mask_as_intervals("left", "pupil")["left_pupil"]
>>> masked_sec = d.mask_as_intervals("left", "pupil", units="sec")["left_pupil"]
>>> mask_dict = d.mask_as_intervals(["left", "right"], "pupil")
>>> list(mask_dict)
['left_pupil', 'right_pupil']

mask_intervals(intervals, eyes=[], variables=[], inplace=None)[source]#

Apply Intervals as masks to selected data.

Takes detected intervals (e.g., blinks, artifacts) and applies them as masks to specified eyes and variables: they are added to the "user" layer (existing masks are kept).

Parameters:

intervals (Intervals, Epochs, list of tuple or dict) –
Either:
- A single Intervals (or Epochs) object or a list of (start, end) tuples (in ms, or with units): applied to all specified eyes/variables
- A dict of Intervals (or Epochs): keys like “left_pupil”, “right_x”, etc. When dict is provided, eyes and variables are ignored.
eyes (str or list of str, optional) – eye(s) to apply mask to (e.g., ["left", "right"]); if empty, all available eyes. Ignored if intervals is a dict.
variables (str or list of str, optional) – variable(s) to apply mask to (e.g., ["pupil", "x", "y"]); if empty, all available variables. Ignored if intervals is a dict.
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 masks applied (self or a copy, depending on inplace).

See also

pypillometry.eyedata.pupil.PupilNamespace.blinks_detect: Detect blinks
get_blinks: Retrieve stored blink intervals

Examples

Apply blinks from a single Intervals object to left eye pupil data:

>>> import pypillometry as pp
>>> d = pp.get_example_data("rlmw_002_short").pupil.blinks_detect()
>>> blinks = d.get_blinks()
>>> d = d.mask_intervals(blinks["left_pupil"], eyes=["left"], variables=["pupil"])

Apply a dict of intervals (one per eye/variable):

>>> d = d.mask_intervals(blinks)  # eyes and variables ignored

Chain with other operations:

>>> d = d.mask_intervals(blinks).pupil.lowpass_filter(cutoff=5)

merge_eyes(eyes=[], variables=[], method='mean', keep_eyes=True, policy='default', name='mean', inplace=None)[source]#

Merge data from both eyes into a single variable.

The merged data is stored under the eye name name (default “mean”, e.g., obj["mean", "pupil"]). Each sample is the mean over the eyes in which it is usable under the mask policy (see mask()), where recorded samples come first: an interpolated sample is used only if no eye has a recorded one there. A sample is masked in the merged data only if it is unusable in all merged eyes (it then holds the mean of the stored values; NaN only if they are NaN). The merged data get the layers that are set in all eyes that went into a sample (e.g., "interpolated" where all of them were interpolated, or "blink" where all eyes are masked by a blink); masked samples without such a common layer get the "user" layer. Each variable is merged over the selected eyes that have data for it.

Parameters:

eyes (str or list of str, optional) – eye(s) to merge; if empty, all available eyes
variables (str or list of str, optional) – variable(s) to merge; if empty, all available variables
method (str, optional) – which method to use for merging; currently only “mean” is implemented, by default “mean”
keep_eyes (bool, optional) – keep original eye data (True, default) or drop it together with its stored blinks (False)
policy (str, MaskPolicy or list of str) – mask policy that decides which samples are usable (see mask()); default "default"
name (str, optional) – name of the new eye; default "mean" (as in d.pupil.merge_eyes())
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 merged data (self or a copy, depending on inplace)

merge_masks(inplace=None)[source]#

Merge masks of all variables into a single joint mask.

This function creates a joint mask by taking the logical OR of all individual masks (under the default mask policy, see get_mask()), then applies this joint mask to all variables (the newly masked samples get the "user" layer).

Parameters:: 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 merged masks (self or a copy, depending on inplace)

nevents()[source]#

Return number of events in data.

Return type:: int

print_history()[source]#: Pretty-print the history of the current dataset (which manipulations where done on it).

quality_report(thresholds=None, eyes=[], policy='default')[source]#

Report the quality of the data.

Measures that need no preprocessing are always computed (on the stored values, where missing samples are NaN):

pupil (if available): missing data, dropouts (periods of missing data) and high-frequency noise
gaze (if available): missing data, off-screen samples (needs the screen resolution) and precision (in degrees if screen size and eye distance are set in the experimental setup, else in pixels)
both eyes: correlation of the pupils and disparity of the gaze

Further measures are added if available: blinks (after d.pupil.blinks_detect()), masked and interpolated data (after preprocessing; masked: unusable under the mask policy, see mask()) and calibration/validation errors (e.g., when read from an Eyelink file).

Where it makes sense, each measure is labeled as “good”, “ok”, “poor” or “bad”. The overall label is the worst of all labels.

Excluded periods (see exclude_intervals()) are left out: all measures refer to the included time, and dropouts and sample-to-sample differences end at their boundaries.

Parameters:

thresholds (Optional[dict]) – thresholds for the labels, overriding the defaults in pypillometry.quality.DEFAULT_QUALITY_THRESHOLDS. Keys are "<section>.<metric>" (e.g., "pupil.missing_pct"), values are three bounds (good, ok, poor). Increasing bounds mean that lower values are better, decreasing bounds that higher values are better. None turns the label off.
eyes (str | list) – eye(s) to report; if empty, all available eyes
policy (str, MaskPolicy or list of str) – mask policy for the masked data (see mask()); default "default" (interpolated samples are not masked)

Return type:

QualityReport

Returns:

the report; print it for a text version, display it in a notebook for an HTML version or use to_dict() to get a dict

Examples

>>> import pypillometry as pp
>>> d = pp.get_rlmw_002_short()
>>> print(d.quality_report())
>>> d.quality_report(thresholds={"pupil.missing_pct": (2, 10, 20)})

remove_intervals(intervals, inplace=None)[source]#

Remove the data in the given periods (e.g., breaks) and join the rest.

The samples in the periods are deleted. Gaps between the remaining data are closed: the data after a removed period are shifted back in time, so that they continue where the removed period started (the time vector has no gap). Removing data at the beginning or end does not change the times, so removing everything before start and after end is the same as crop(). Event onsets are shifted with the data; events within removed periods are deleted. Stored blinks and excluded periods are moved to the new positions. The removed periods are added to params["removed_intervals"], in the original time (the time before any periods were removed; a period across a gap closed by an earlier call is split at the gap). params["removed_shifts"] holds the shifts between the current and the original time.

To remove the periods marked with exclude_intervals(), use d.remove_intervals(d.get_excluded()).

Filters or interpolation applied after joining treat the data on both sides of a removed period as neighbors; apply them before, or use split_excluded() to process the parts separately.

Parameters:

intervals (Intervals, Epochs or list of tuple) – the periods to remove: an Intervals object (in time units or sample indices), Epochs or a list of (start, end) tuples (in ms, or with units, e.g., [(10 * u.min, 12 * u.min)]; "<start>" and "<end>" stand for the start and end of the recording); ends are exclusive
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 without the removed periods (self or a copy, depending on inplace)

Raises:

ValueError – if all samples would be removed

See also

crop: keep only the data between two times
split_excluded: split the data at the excluded periods

Examples

>>> breaks = d.get_intervals(start="break_start", end="break_end", units="ms")
>>> d = d.remove_intervals(breaks)
>>> d = d.remove_intervals(d.get_excluded())

reset_time(t0=None, inplace=None)[source]#

Resets time so that time t0 becomes time zero.

t0 is subtracted from the time-vector, the event onsets and the periods in params["removed_intervals"] (see remove_intervals()).

Parameters:

t0 (float | None) – time (in ms) that becomes the new time zero; if None, use the first time point (so that the time-vector starts at zero)
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 shifted time (self or a copy, depending on inplace)

scale(variables=[], method='z', center=None, scale=None, eyes=[], policy='default', inplace=None)[source]#

Scale the signal: subtract center and divide by scale.

method says how center and scale are computed from the usable samples of each channel (under policy) if they are not given:

"z" (default): mean and standard deviation (z-scores)
"robust": median and median absolute deviation (MAD; the raw MAD, not multiplied by 1.4826), so the result is in units of the MAD and outliers (e.g., artefacts) have little influence
"minmax": minimum and range (max - min), so the result lies between 0 and 1
"percent": mean and mean / 100, so the result is the change in % of the mean (for a percent change relative to a baseline before each event, see SegmentedEyeData.pupil.baseline_correct)

Parameters:

variables (str or list of str, optional) – variables to scale; can be “pupil”, “x”,”y”, “baseline”, “response” or any other variable that is available in the dataset; either a string or a list of strings; available variables can be checked with obj.variables; empty list means all variables
method (str) – how center and scale are computed if they are None: "z" (default), "robust", "minmax" or "percent" (see above)
center (Union[float, dict, None]) – value to subtract; if None, computed with method; a number (same for all eyes and variables) or one per channel as {"left_pupil": value, ...}
scale (Union[float, dict, None]) – value to divide by; if None, computed with method; a number or one per channel as {"left_pupil": value, ...}
eyes (str or list of str, optional) – eye(s) to consider; if empty, all available eyes
policy (str, MaskPolicy or list of str) – mask policy that decides which samples are used for center and scale (see mask()); default "default" (interpolated samples are used)
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 scaled object (self or a copy, depending on inplace)

Raises:

ValueError – if method is unknown, or scale is 0 or not finite for a channel (e.g., a constant signal, or a MAD of 0)

Notes

The scaling parameters are stored in params["scale"] ({"center": {"left_pupil": ...}, "scale": {...}, "method": {...}}) and used by unscale(). Scaling a variable again combines the parameters, so that unscale() restores the values before the first scale.

Examples

>>> import pypillometry as pp
>>> d = pp.get_example_data("rlmw_002_short")
>>> z = d.scale("pupil", inplace=False)                     # z-scores
>>> r = d.scale("pupil", method="robust", inplace=False)    # units of the MAD
>>> p = d.scale("pupil", method="minmax", inplace=False)
>>> bool(p["left_pupil"].min() == 0 and p["left_pupil"].max() == 1)
True

set_blinks(intervals, eyes=[], variables=[])[source]#

Set blinks for specified eyes and variables (in-place).

The blinks replace the "blink" layer of the selected variables (and the mask of the blinks set before). Blinks are masked under the mask policies (see mask()).

Parameters:

intervals (Intervals, dict or None) –
Either:
- a single Intervals object: stored for all specified eyes/variables;
- a dict of Intervals (or None) with keys like “left_pupil”, “right_x”, etc.; when a dict is provided, eyes and variables are ignored;
- None: remove the blinks for the specified eyes/variables (and their mask).
eyes (str or list of str, optional) – eye(s) to set blinks for (e.g., ["left", "right"]); if empty, all available eyes. Ignored if intervals is a dict.
variables (str or list of str, optional) – variable(s) to set blinks for (e.g., ["pupil", "x", "y"]); if empty, all available variables. Ignored if intervals is a dict.

Return type:

EyeData

Returns:

the object itself (always modified in-place)

set_events(events)[source]#

Replace the events of the dataset (in-place).

The onsets are converted to ms (the internal storage format) if needed. The time range of the data is not stored with the events. A warning is given for events that are marked as being on another clock (needs_sync, see sync_clocks()).

Parameters:

events (Events) – the new events (onsets, labels and metadata)

Return type:

EyeData

Returns:

the object itself, with the new events (use d.copy() first to keep the old events)

Raises:

TypeError – if events is not an Events object
ValueError – if an onset is outside the time range of the data

See also

events: the events of the dataset
add_events: add events to the existing ones

Examples

>>> d = d.set_events(d.events.filter("stim"))
>>> d = d.set_events(d.events.parse_labels(r"_(?P<trial>\d+)"))

set_experimental_setup(**kwargs)[source]#

Set or update the experimental setup geometry (in-place).

Creates a new ExperimentalSetup or updates the existing one with the provided parameters (parameters that are not given are taken from the existing setup). All parameters are passed through to the ExperimentalSetup constructor.

Parameters:

**kwargs (dict) –

Any parameters accepted by ExperimentalSetup:

screen_resolution: tuple (width, height) in pixels
physical_screen_size: tuple (width, height) with units
eye_to_screen_center: distance from the eye to the screen center
screen_offset: tuple (delta_x, delta_y) - offset of screen center from eye
screen_pitch: tilt angle (alpha_tilt)
screen_yaw: tilt angle (beta_tilt)
camera_offset: tuple (x, y, z) in eye-centric frame
camera_spherical: tuple (theta, phi, r)
ipd: inter-pupillary distance

Return type:

EyeData

Returns:

the object itself (always modified in-place)

Examples

>>> import pypillometry as pp
>>> d = pp.get_example_data("rlmw_002_short")
>>> d = d.set_experimental_setup(
...     screen_resolution=(1920, 1080),
...     physical_screen_size=("52 cm", "29 cm"),
...     eye_to_screen_center="65 cm",
... )

split_excluded()[source]#

Split the data at the excluded periods (see exclude_intervals()).

Returns one object per included period (see get_included()), each with the samples, masks, blinks and events of that period and the original time vector. The objects are copies; self is not changed.

Return type:: list
Returns:: the parts of the recording between the excluded periods

See also

remove_intervals: remove periods and join the rest, e.g., d.remove_intervals(d.get_excluded())

stat_per_event(intervals=None, window=None, event_select=None, eyes=[], variables=[], statfct=<function mean>, units='ms', policy='default', **kwargs)[source]#

Return result of applying a statistical function to data in a given interval relative to event-onsets. For example, extract mean pupil-size in interval before trial onset.

Parameters:

intervals (Intervals or Epochs, optional) – Intervals object (in any time units or in sample indices, e.g., from get_intervals()) or Epochs (e.g., from get_epochs()). If provided, window and event_select are ignored.
window (Tuple[float, float]) – time-window relative to event-onset (0 is event-onset), e.g. (-200, 0) * u.ms; plain numbers are in units given by units. Required if intervals is not provided.
event_select (str, function or Events, optional) – the events to select (see get_epochs()); required if intervals is not provided
eyes (str | list) – eye(s) to consider; if empty, all available eyes
variables (str | list) – variable(s) to consider; if empty, all available variables
statfct (Callable) – function mapping a masked array to a single number; it must ignore masked samples (e.g., np.mean (default) or np.ma.median, but not np.median; a warning is logged otherwise). Intervals where all samples are masked give NaN.
units (str) – units for plain numbers in window (if used); default “ms”
policy (str, MaskPolicy or list of str) – mask policy: the samples that are unusable under it are masked (see mask()); default "default" (interpolated samples are used)
**kwargs – passed onto the event_select function

Return type:

dict

Returns:

one array per eye/variable (keys like “left_pupil”), with one value per interval/event

summary()[source]#

Return a summary of the dataset as a dictionary.

Return type:: : dict
Returns:: A dictionary summarizing the dataset.

unscale(variables=[], center=None, scale=None, eyes=[], inplace=None)[source]#

Scale back to original values using either values provided as arguments or the values stored in params[“scale”] by scale().

The signal is multiplied by scale and center is added. The stored parameters of the unscaled channels are removed.

Parameters:

variables (str or list of str, optional) – variables to unscale; can be “pupil”, “x”,”y”, “baseline”, “response” or any other variable that is available in the dataset; either a string or a list of strings; available variables can be checked with obj.variables; empty list means all variables
center (None, float or dict, optional) – value to add to the signal; a number (same for all eyes and variables) or {"left_pupil": value, ...}; if None, use the value stored by scale()
scale (None, float or dict, optional) – value to multiply the signal with; a number (same for all eyes and variables) or {"left_pupil": value, ...}; if None, use the value stored by scale()
eyes (str or list of str, optional) – eye(s) to consider; if empty, all available eyes
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 unscaled object (self or a copy, depending on inplace)

write_file(fname, compress=True)[source]#

Save to file (using write_file()).

The format follows from the extension: HDF5 for .h5 and .hdf5, pickle otherwise (e.g., .pypil).

Parameters:

fname (str) – str: filename
compress (bool) – bool: compress the file (default True; pickle: zstd, HDF5: gzip)

property blinks#

Return blinks (intervals) for all eyes.

Return type:: dict
Returns:: dictionary with blinks (Intervals in ms) for each eye/variable, keys like “left_pupil” (same as get_blinks())

property events: Events#

The events of the data (onsets in ms).

An Events object. Events are immutable: their methods (e.g., filter(), parse_labels()) return new Events, which are stored with set_events(). Operations on the data that change the time (e.g., crop(), remove_intervals(), reset_time()) move the events with it.

Examples

>>> d.events.filter("stim")
>>> d = d.set_events(d.events.parse_labels(r"_(?P<trial>\d+)"))

property eyes: List[str]#: Return a list of available eyes in the dataset.

property variables: List[str]#: Return a list of available variables in the dataset.