.. currentmodule:: pypillometry Overview ======== The package is divided into separate sub-modules that solve specific subtasks (pre-processing, baseline estimation etc). The functions in these modules operate on plain :py:mod:`numpy.array`'s or standard Python-structures. While these functions can be used directly, an easier approach is to use the class :py:class:`~pypillometry.pupildata.PupilData` which wraps these functions in a convenient way. Each object of class :py:class:`~pypillometry.pupildata.PupilData` represents one dataset of pupillometric data, including time, signal and external events (trial onsets, stimulus presentations, responses, etc). By calling the member functions of such an object, the corresponding function from one of the sub-modules is called using the appropriate arguments. .. currentmodule:: pypillometry.eyedata .. autosummary:: EyeDataDict GenericEyeData .. toctree:: :maxdepth: 2 :local: :caption: Contents: usage Reading/writing pupillometric data ---------------------------------- So far, reading in data is not part of the :py:mod:`pypillometry`-package. This is because the format of the eyetracker-files will vary depending on the setup of the eyetracker (there are many ways to represent event-triggers) and the actual model of the eyetracker. Python provides excellent functionality to parse text-based datafiles and we therefore give guidance how to use these tools rather than trying to implement that functionality in our package. There are many ways in which pupillometric data can be read into Python. For example, Eyelink's `ASC-format `_ generated by the EDF2ASC conversion tool outputs space-separated data that can be easily loaded using the `I/O functionality of the pandas package `_ . Data is input into :mod:`pypillometry` using the :func:`constructor ` of the :class:`~pypillometry.pupildata.PupilData` object. However, data that has been converted into :class:`PupilData`-objects can be easily saved and restored (using :mod:`shelve`). .. code-block:: python d=PupilData(...) # create PupilData object after manually loading data # save the dataset into a shelve-file d.write_file("dataset.pd") # load it from the file d2=PupilData.from_file("dataset.pd") :ref:`An example for importing data from Eyelink EDF-files ` Pipeline-based processing ------------------------- :py:mod:`pypillometry` implements a pipeline-like approach where each operation executed on a :class:`~pypillometry.pupildata.PupilData`-object returns a copy of the (modified) object. This enables the "chaining" of commands as follows: .. code-block:: python d=PupilData.from_file("data/test.pd").blinks_detect().blinks_merge().lowpass_filter(3).downsample(50) This command loads a data-file (`test.pd`), applies a 3Hz low-pass filter to it, downsamples the signal to 50 Hz, detects blinks in the signal and merges short, successive blinks together. The final result of this processing-pipeline is stored in object `d`. This object stores also the complete history of the operations applied to the dataset and allows to transfer it to a new dataset. See the following page more on this: :ref:`Pipeline-based processing in pypillometry ` Pre-processing data ------------------- Assuming you have generated a :class:`~pypillometry.pupildata.PupilData` object, a range of pre-processing functions are available. The main pre-processing issues with pupillometric data are: - artifacts and missing data due to blinks (these can usually be corrected/interpolated) - missing data/artifacts from other sources (e.g., looking away, eyetracker losing pupil for other reasons) - smoothing/downsampling to get rid of high-freq low-amp noise Handling Blinks ^^^^^^^^^^^^^^^ Pupillometric data usually contain blinks which show up as missing data in the signal where the eyetracker is unable to record the size of the pupil. A range of functions are available for detecting and interpolating blinks. More details and an example can be found in the notebook: :ref:`An example for how to handle blinks ` A fully worked-out example of a real study can be found in this notebook: :ref:`Preprocessing of a full dataset with multiple subjects ` The following is a list of functions for that purpose. Note that the functions take multiple arguments that control the algorithms behaviour. It is often crucial to adjust the parameters on an individual level since the artifacts tend to be quite dissimilar between subjects (but usually stable within-subject). All arguments are documented in the :ref:`API-docs `. .. autosummary:: PupilData.blinks_detect PupilData.blinks_interpolate PupilData.blinks_interp_mahot PupilData.blinks_merge PupilData.blinks_plot Smoothing/low-pass filtering ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In most cases, pupillometric data should be low-pass filtered (e.g., using a cutoff of 4 Hz `Jackson & Sirois, 2009 `_) or smoothed in other ways (e.g., with a running-window). Tge following is a list of functions for smoothing: .. autosummary:: PupilData.lowpass_filter PupilData.smooth_window PupilData.downsample Changing/Slicing data ^^^^^^^^^^^^^^^^^^^^^ Often, pupillometric data needs to be trimmed, e.g., to remove pre-experiment recordings or to remove unusable parts of the data (:func:`PupilData.sub_slice`). The timing should usually be realigned to the start of the experiment (:func:`PupilData.reset_time`). Furthermore, a scaling (e.g., Z-transform) of the pupil-data can be useful for comparing multiple subjects (:func:`PupilData.scale`). The following is a list of available functions for these purposes: .. autosummary:: PupilData.sub_slice PupilData.copy PupilData.scale PupilData.unscale PupilData.reset_time Plotting/Summarizing Data ------------------------- Plotting ^^^^^^^^ It is crucial to validate preprocessing steps by visually inspecting the results using plots. Therefore, :mod:`pypillometry` implements several plotting facilities that encourage active exploration of the dataset. Please see the tutorial :ref:`Plotting of pupillometric data ` for more details. .. autosummary:: PupilData.plot PupilData.plot_segments PupilData.blinks_plot plotpd plotpd_ia PupilData.get_erpd Inspecting/Summarizing ^^^^^^^^^^^^^^^^^^^^^^ The package also provides several functions for summarizing datasets. Simply `print()`ing a :class:`PupilData` object gives a readable summary of the main properties of the dataset and also prints the complete history of the results. By calling :func:`PupilData.summary`, summary data can be arranged and summarized in tabular form. See the notebook :ref:`Summarizing pupillometric data ` for more details. .. autosummary:: PupilData.summary PupilData.stat_per_event PupilData.get_erpd Event-Related Pupil Dilation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The average pupillometric signal, timelocked to repeating events during the experiment, is referred to as "Event-related pupil dilation" or ERPD. In :mod:`pypillometry`, the functionality for this is implemented in the class :class:`pypillometry.erpd.ERPD`. Running :func:`PupilData.get_erpd` returns an Object of class :class:`ERPDSingleSubject`. This object has functions for plotting and summarising the event-related pupillary dilation. :ref:`Here is an example notebook for for how to work with ERPDs `. .. autosummary:: PupilData.get_erpd .. currentmodule:: pypillometry.erpd .. autosummary:: group_erpd ERPD.summary ERPD.plot Modeling the pupillometric signal --------------------------------- For some applications, it is interesting to model the full pupillometric signal as consisting of a (tonic) baseline and a (phasic) response component. The package implements novel algorithms developed in our lab and documentation will become available here. More details are availabel in this notebook: :ref:`Modeling the pupillometric signal `. .. currentmodule:: pypillometry.pupildata .. autosummary:: PupilData.estimate_baseline PupilData.estimate_response PupilData.stat_per_event Artificial Data --------------- For validation and testing purposes, it can be useful to generate artificial datasets. The package implements a :class:`FakePupilData` as inheriting from regular :class:`PupilData` and therefore shares all its functionality. In addition to that, :class:`FakePupilData` stores "ground-truth" data and parameters that was used while creating the artificial data. The function :func:`create_fake_pupildata` allows to quickly create datasets generating according to a provided experimental structure (see the functions documentation for an overview over the many available options). .. autosummary:: FakePupilData create_fake_pupildata