# The `mpib_ecomp_sourcedata` dataset

This dataset contains the `sourcedata` from the eComp experiment,
conducted at the Max Planck Institute for Human Development (MPIB)
in 2021, by Stefan Appelhoff and colleagues.

It is hosted on GIN: https://gin.g-node.org/sappelhoff/mpib_ecomp_sourcedata/

Note that all recording dates have been anonymized.

All important details are reported in the original paper for the
project:

- preprint: [10.1101/2022.03.31.486560](https://doi.org/10.1101/2022.03.31.486560)
- journal article: forthcoming

The raw data organized in Brain Imaging Data Structure
(BIDS; https://bids.neuroimaging.io/)
format are available here:

- repository: https://gin.g-node.org/sappelhoff/mpib_ecomp_dataset/
- doi: forthcoming

Derived data are available here:

- repository: https://gin.g-node.org/sappelhoff/mpib_ecomp_derivatives/
- doi: forthcoming

The experiment code used during data collection can be found here:

- repository: https://github.com/sappelhoff/ecomp_experiment/
- doi: [10.5281/zenodo.6411313](https://doi.org/10.5281/zenodo.6411313)

The analysis code for this project can be found here:

- repository: https://github.com/sappelhoff/ecomp_analysis/
- doi: [10.5281/zenodo.6411287](https://doi.org/10.5281/zenodo.6411287)

# Overview

This is a very condensed overview of the data.
For a full understanding, please see the materials linked above,
and contact the author in case of doubt.

Each subject folder contains the following files:

- Two `*_info.json` files: One for each task condition
  (called "stream": `single` and `dual`) with general participant information
- Two directories: "single" and "dual", containing the following data
  for the two task conditions respectively:
- EEG data: `.eeg`, `.vhdr`. `.vmrk` BrainVision files
    - The information about TTL markers can be found in the
      [experiment code](https://github.com/sappelhoff/ecomp_experiment/blob/66ac231bcb18bb136c1c0de3433a1c9a749485e8/ecomp_experiment/define_ttl.py#L24-L91)
- Behavior data: `.tsv` file
    - This is a very brief description of the columns:
        - `trial`: the trial index (integers starting with 0)
        - `direction`: did participant press "left" or "right" button;
          is "n/a" if no response (strings)
        - `choice`: in single --> "lower" vs "higher";
          in dual --> "red" vs "blue"; is "n/a" if no response (strings)
        - `ambiguous`: True/False whether the mean was exactly 5 (single),
          or the mean difference was exactly 0 (dual) --> in those cases,
          participants received random feedback (booleans)
        - `rt`: reaction time in seconds (floats),
          is "n/a" if no response (string) -->
          so in this column there may be floats and strings
        - `validity` : True/False --> is False,
          if there was a timeout in the choice. Happened rarely -->
          6 times over all subjs and trials. If True, "direction", "choice",
          "rt", and "correct" are "n/a" as a value
        - `iti`: The inter trial interval for this trial in ms
        - `correct`: True/False whether the choice was correct
          (this is random in ambiguous trials; booleans);
          is "n/a" if no response (string)
          --> so in this column there may be booleans and strings
        - `stream`: The stream that this data was produced in:
          "single" or "dual" (strings)
        - `state`: 0 or 1, used for presenting the response options one way
          or the other way around (integers), irrelevant for analysis,
          because this is already more accessible encoded in
          "direction"+"choice"
        - `sample1` ... `sample10`: the 1st, 2nd, ... 10th sample in this trial:
          Integer between 1 and 9 with either positive or negative sign,
          mapping to blue or red color respectively
- Eyetracking data: `.edf` EyeLink file
  (this is *NOT* the "European Data Format", but the "Eyelink Data format")
    - Event markers have the same meaning as in the EEG data

# Download

The full data can be downloaded using one of these two methods:

1. Via [datalad](https://www.datalad.org/)
    1. install: http://handbook.datalad.org/en/latest/intro/installation.html
    1. clone: `datalad clone https://gin.g-node.org/sappelhoff/mpib_ecomp_sourcedata`
    1. go to root of dataset: `cd mpib_ecomp_sourcedata`
    1. get all data: `datalad get *`
    1. if you want to work on the files or edit them, you may need to run
       `datalad unlock *`
1. Via the [GIN client](https://github.com/G-Node/gin-cli)
    1. install: https://gin.g-node.org/G-Node/Info/wiki/GIN+CLI+Setup
    1. clone: `gin get sappelhoff/mpib_ecomp_sourcedata`
    1. go to root of dataset: `cd mpib_ecomp_sourcedata`
    1. get all data: `gin download --content`
    1. if you want to work on the files or edit them, you may need to run
       `gin unlock *`

Or click on the small "download icon" on the right side above the list of
files in the repository overview on GIN.
This will allow you to see the GIN documentation on how to download data.

# Using this dataset

If you use this dataset in your work, please consider citing it
as well as the references describing it.

See the LICENSE below, as well as the [`datacite.yml`](./datacite.yml) file.

# License

This data is made available under the Public Domain Dedication and License v1.0
whose full text can be found at: http://opendatacommons.org/licenses/pddl/1.0/

See also the human readable summary at:
https://opendatacommons.org/licenses/pddl/summary/

Please see the [LICENSE](./LICENSE) file for details.

# Contact

- [Stefan Appelhoff](mailto:mailto:appelhoff@mpib-berlin.mpg.de)