---
title: "A guide to eegUtils data structures"
author: "Matt Craddock"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{A guide to eegUtils data structures}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
library(eegUtils)
```

## eegUtils

`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 used for continuous data. When raw data is imported, the output is this class. 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 numeric value 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 NULL on import, since BDF and CNT do not contain (usable) 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 
        ```{r}
        head(eegUtils:::electrodeLocs)
        ```
        
* `timings`
    + A data.frame containing a description of each row in time (s) and sample numbers (samples)


* `epochs`
    + A data.frame containing information about the epochs in the data, more relevant for epoched data.


* `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

`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*
        
    ```{r}
    events(demo_epochs)
    ```
    
* `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.
    ```{r}
    head(demo_epochs$timings)
    ```
    
    
* `epochs`
    + A data.frame containing information about the participant, and labels applied to any epochs
    ```{r}
    epochs(demo_epochs)
    ```
    
## eeg_tfr

`eeg_tfr` objects hold time-frequency representations of `eeg_epochs` objects.

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

## eeg_ICA

`eeg_ICA` objects contain the results of either an ICA or an SSD decomposition applied to an `eeg_epochs` object.

* `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