eegUtils uses S3 objects to store EEG data and associated information such as channel locations. Using different object classes for data structured in different ways ensures that the various plotting functions work consistently across different types of EEG data. For example, there are different classes for epoched (eeg_epochs) and continuous data (eeg_data), and for time-frequency representations of data (eeg_tfr).

eeg_data objects

eeg_data objects are the base class that all continuous data has. When raw data is imported, the output is this class. Currently, this class is a list constituting the following entries:

  • signals
    • A data frame containing the actual EEG data in wide format. Each column is data from a single electrode, each row from a single timepoint.
  • srate
    • A single integer giving the sampling rate of the data in Hz
  • events
    • A data.frame/tibble with 3 columns describing the events recorded in the data.
      • event_onset (in samples) relative to recording onset
      • event_time (in seconds) relative to recording onset
      • event_type (typically integer, others possible)
  • chan_info
    • Often NA on import, since BDF and CNT do not contain (useable) electrode locations.
    • A data.frame/tibble containing channel location information can be added. Currently similar to EEGLAB style, with the following columns (may change):
      • electrode - electrode names
      • radius - Spherical co-ordinates (Radius is typically normalized to 1)
      • theta - Spherical co-ordinates (theta)
      • phi - Spherical co-ordinates (theta)
      • cart_x - Cartesian 3D coordinates
      • cart_y - Cartesian 3D coordinates
      • cart_z - Cartesian 3D coordinates
      • x - 2D Stereographic projection of the spherical coordinates
      • y - 2D Stereographic projection of the spherical coordinates
  • timings
    • A data.frame containing a description of each row in time (s) and sample numbers (samples)
  • continuous
    • A logical variable indiciating if the data is continuous or epoched. To be phased out now that multiple classes exist.
  • reference
    • NA on loading, in the absence of a recorded reference channel.
    • Once data is referenced, is a list consisting of two entries.
      • ref_chans - Labels for channels used to calculate the reference data. Can also be “average”.
      • excluded - Labels for any channels excluded from the reference data.


eeg_epochs objects share the same overall structure with eeg_data objects, but some of the internals currently differ, as described below.

  • events
    • The events table has two additional columns, epoch and time.
      • epoch gives the epoch number to which a given event belongs
      • time gives the time point at which the event occurs relative to the epoch onset
      • event_time still gives the time point at which the event occurs relative to the recording onset
  • timings
    • The timings table has one additional column, epoch.
      • epoch gives the epoch number to which a given datapoint belongs
      • sample still uniquely identifies each datapoint
      • time now gives the time relative to the zero-point of the epoch, i.e. the event on which the epoch is centred.


eeg_tfr objects hold time-frequency representations of eeg_epochs objects.

  • signals
    • a 4D matrix - time by electrode by frequency by epoch
  • dimensions
    • keeps track of which matrix dimension corresponds to which property.


eeg_ICA objects contain the results of an ICA decomposition applied to an eeg_epochs objects.

  • mixing_matrix
    • The weights that are used to convert the source data into the original data
  • unmixing_matrix
    • The weights that are used to convert the original data into source data
  • signals - individual component activations