Tutorials
=========

The tutorials are Jupyter notebooks that show how to do specific tasks
from start to finish. Each page has a link to the notebook on GitHub and a
Binder link |binder| that opens it in your browser, so you can run it
without installing anything.

.. |binder| image:: https://mybinder.org/badge_logo.svg

If you are new to :mod:`pypillometry`, start with the
:doc:`/getting_started/quickstart`.


Reading data
------------

.. grid:: 1 2 3 3
   :gutter: 3

   .. grid-item-card:: Eyelink EDF files
      :link: /notebooks/importdata_edf
      :link-type: doc

      Read an EDF file, including events and calibration data.

   .. grid-item-card:: Text files (ASC)
      :link: /notebooks/importdata_asc
      :link-type: doc

      Read text files with pandas and build a data object from arrays.

   .. grid-item-card:: Events from a behaviour log
      :link: /notebooks/importdata_behaviour
      :link-type: doc

      Add events from the log of the experiment software and synchronize
      its clock with the eye tracker.

   .. grid-item-card:: Example datasets
      :link: /notebooks/example_datasets
      :link-type: doc

      The datasets that come with the package.


Working with data objects
-------------------------

.. grid:: 1 2 3 3
   :gutter: 3

   .. grid-item-card:: Pipelines and history
      :link: /notebooks/pipes
      :link-type: doc

      Chain processing steps, keep a record of them, and decide between
      in-place changes and copies.

   .. grid-item-card:: Eyes and variables
      :link: /notebooks/eyes_and_variables
      :link-type: doc

      Monocular and binocular data, selecting and combining eyes, adding
      variables.

   .. grid-item-card:: Summarizing data
      :link: /notebooks/summary
      :link-type: doc

      Summaries of one or many datasets: contents, data quality, masked
      data and one value per trial, as tables.


Preprocessing and plotting
--------------------------

.. grid:: 1 2 3 3
   :gutter: 3

   .. grid-item-card:: Blinks
      :link: /notebooks/blinks
      :link-type: doc

      Detect, check and interpolate blinks.

   .. grid-item-card:: Missing data
      :link: /notebooks/missing_data
      :link-type: doc

      Mask layers and policies on a real recording: blinks, off-screen
      gaze, excluded periods, interpolation and their effect on analyses.

   .. grid-item-card:: Plotting
      :link: /notebooks/plotting
      :link-type: doc

      Plot pupil and gaze data for exploration and quality checks.


Events and event-related analyses
---------------------------------

.. grid:: 1 2 3 3
   :gutter: 3

   .. grid-item-card:: Events
      :link: /notebooks/events
      :link-type: doc

      Select, filter, convert and change the events of a recording.

   .. grid-item-card:: Event metadata
      :link: /notebooks/event_metadata
      :link-type: doc

      Trial, condition or reaction time for each event, from the trigger
      labels or a behaviour log; select events by them.

   .. grid-item-card:: Intervals
      :link: /notebooks/intervals
      :link-type: doc

      Time windows around events, blinks and artifacts: create, combine
      and use them.

   .. grid-item-card:: Event-related pupil dilation
      :link: /notebooks/erpds
      :link-type: doc

      Average pupil responses per condition and across participants.

   .. grid-item-card:: Gaze in regions of interest
      :link: /notebooks/rois
      :link-type: doc

      Where participants look after an event: fixation curves, dwell
      time and first entry per trial, combined with the pupil.


Modeling and complete analyses
------------------------------

.. grid:: 1 2 3 3
   :gutter: 3

   .. grid-item-card:: Modeling the pupil signal
      :link: /notebooks/modeling
      :link-type: doc

      Separate the signal into tonic baseline and phasic responses.

   .. grid-item-card:: A complete study
      :link: /notebooks/preproc_example_pavlov
      :link-type: doc

      Preprocess a full study with many participants.

   .. grid-item-card:: Case study: an N-back task
      :link: /notebooks/case_study_nback
      :link-type: doc

      One recording from start to end: behavioural log as event
      metadata, preprocessing, tonic pupil and ERPDs.

More examples for the experimental features are in
:doc:`/experimental/index`.

.. toctree::
   :hidden:
   :caption: Reading data

   /notebooks/importdata_edf
   /notebooks/importdata_asc
   /notebooks/importdata_behaviour
   /notebooks/example_datasets

.. toctree::
   :hidden:
   :caption: Working with data objects

   /notebooks/pipes
   /notebooks/eyes_and_variables
   /notebooks/summary

.. toctree::
   :hidden:
   :caption: Preprocessing and plotting

   /notebooks/blinks
   /notebooks/missing_data
   /notebooks/plotting

.. toctree::
   :hidden:
   :caption: Events and event-related analyses

   /notebooks/events
   /notebooks/event_metadata
   /notebooks/intervals
   /notebooks/erpds
   /notebooks/rois

.. toctree::
   :hidden:
   :caption: Modeling and complete analyses

   /notebooks/modeling
   /notebooks/preproc_example_pavlov
   /notebooks/case_study_nback