{"id":21304524,"url":"https://github.com/bnicenboim/eeguana","last_synced_at":"2025-07-11T21:30:33.305Z","repository":{"id":34155855,"uuid":"153299577","full_name":"bnicenboim/eeguana","owner":"bnicenboim","description":"A package for manipulating  EEG data in R.","archived":false,"fork":false,"pushed_at":"2025-05-07T16:46:32.000Z","size":503671,"stargazers_count":24,"open_issues_count":38,"forks_count":9,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-07-07T22:11:05.618Z","etag":null,"topics":["dplyr","eeg","eeg-analysis","eeg-data","eeg-signals","r","tidyverse"],"latest_commit_sha":null,"homepage":"https://bnicenboim.github.io/eeguana/","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bnicenboim.png","metadata":{"files":{"readme":"README.Rmd","changelog":"NEWS.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":"codemeta.json","zenodo":null}},"created_at":"2018-10-16T14:26:07.000Z","updated_at":"2025-06-12T16:31:28.000Z","dependencies_parsed_at":"2023-01-15T05:01:11.878Z","dependency_job_id":"8db8b064-54bb-413a-9ced-4704405a0796","html_url":"https://github.com/bnicenboim/eeguana","commit_stats":{"total_commits":770,"total_committers":6,"mean_commits":"128.33333333333334","dds":0.04935064935064937,"last_synced_commit":"d140feaec178a08d355def603ed4ad4fcf1c3092"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/bnicenboim/eeguana","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bnicenboim%2Feeguana","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bnicenboim%2Feeguana/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bnicenboim%2Feeguana/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bnicenboim%2Feeguana/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bnicenboim","download_url":"https://codeload.github.com/bnicenboim/eeguana/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bnicenboim%2Feeguana/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264901933,"owners_count":23680957,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dplyr","eeg","eeg-analysis","eeg-data","eeg-signals","r","tidyverse"],"created_at":"2024-11-21T16:08:45.296Z","updated_at":"2025-07-11T21:30:30.253Z","avatar_url":"https://github.com/bnicenboim.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\nbibliography: papers.bib\noutput: github_document\n---\n [![R build status](https://github.com/bnicenboim/eeguana/workflows/R-CMD-check/badge.svg)](https://github.com/bnicenboim/eeguana/actions)\n[![Codecov test coverage](https://codecov.io/gh/bnicenboim/eeguana/branch/master/graph/badge.svg)](https://codecov.io/gh/bnicenboim/eeguana?branch=master) \n[![DOI](https://zenodo.org/badge/153299577.svg)](https://zenodo.org/badge/latestdoi/153299577)  [![lifecycle](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://www.tidyverse.org/lifecycle/#experimental)\n[![Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip)\n\n\n\n```{r setup, include = FALSE}\nknitr::opts_chunk$set(\n  collapse = TRUE,\n  comment = \"#\u003e\",\n  fig.path = \"man/figures/README-\",\n  out.width = \"100%\"\n)\n```\n\n# eeguana \u003cimg src=\"man/figures/logo.png\" align=\"right\" style=\"width: 20vw; min-width: 25px;\"/\u003e\n\n## Overview\n\nA package for flexible manipulation of EEG data. `eeguana` provides a `data.table` powered framework through `tidytable` for manipulating EEG data with *dplyr*-like functions (e.g., `eeg_mutate`, `eeg_filter`, `eeg_summarize`) extended to a new class `eeg_lst`,  other EEG-specialized functions, and `ggplot` wrapper functions.  The new class is inspired by tidyverse principles but it's not really \"tidy\" (due to space considerations), it's a list of (i) a wide *data table* (`signal_tbl`) that contains the signal amplitudes at every sample point of the EEG,  (ii) an events *data table* with information about markers (or triggers), blinks and other exported information, and (iii) a long table with experimental information, such as participant number (`.recording`), conditions, etc.  \n\n*eeguana* can do only basic pre-processing for now, more complete packages exist for Matlab ([FieldTrip](http://www.fieldtriptoolbox.org/) and [EEGLAB](https://sccn.ucsd.edu/eeglab/index.php)) and python ([MNE](https://martinos.org/mne/stable/index.html)).\n\nSee [Reference](https://bnicenboim.github.io/eeguana/reference/index.html) for more information about the functions of *eeguana*.\n\n**NOTE: Changes in dependencies that broke the package are now fixed!**\n\n## Installation\n\nThere is still **no** released version of *eeguana*.  The package is in the early stages of development, and it **will** be subject to a lot of changes. To install the latest version from github use:\n\n\n``` r\ndevtools::install_github(\"bnicenboim/eeguana\")\n```\n\n## Example\n\nHere, I exemplify the use of *eeguana* with (pre-processed) EEG data from BrainVision 2.0. The data belong to a simple experiment  where a participant was presented 100 faces and 100 assorted images in random order. The task of the experiment was to mentally count the number of faces.\n\nFirst we download the data:\n\n```{r downloading, results='hide', eval = any(!file.exists(\"faces.vhdr\",\"faces.vmrk\",\"faces.dat\"))}\n# Run the following or just download the files from brain_vision folder in https://osf.io/tbwvz/\nlibrary(httr)\nGET(\"https://osf.io/q6b7x//?action=download\",\n  write_disk(\"./faces.vhdr\", overwrite = TRUE),\n  progress()\n)\nGET(\"https://osf.io/ft5ge//?action=download\",\n  write_disk(\"./faces.vmrk\", overwrite = TRUE),\n  progress()\n)\nGET(\"https://osf.io/85dgj//?action=download\",\n  write_disk(\"./faces.dat\", overwrite = TRUE),\n  progress()\n)\n```\n\nBrainVision 2.0 exports three files: `faces.vhdr`, `faces.vmrk`, and\n`faces.dat`. The file `faces.vhdr` contains the metadata and links to the other\ntwo files, `faces.vmrk` contains the triggers and other events in the samples,\nand `faces.dat` contains the signals at every sample for every channel recorded.\n\n\n```{r libs, message = FALSE}\nlibrary(eeguana)\n```\n\nWe first need to read the data:\n\n```{r}\nfaces \u003c- read_vhdr(\"faces.vhdr\")\n```\n\nThe function `read_vhdr()` creates a list with data frames for the signal, events,\nsegments information, and incorporates in its attributes generic EEG information.\n\n```{r}\nfaces\n```\n\nSome intervals were marked as \"bad\" by BrainVision, and so we'll remove them\nfrom the data. We'll also segment and baseline the data. In this experiment, the\ntrigger \"s70\" was used for faces and \"s71\" for no faces. We'll segment the data\nusing these two triggers.\n\n```{r}\nfaces_segs \u003c- faces |\u003e\n  eeg_segment(.description %in% c(\"s70\", \"s71\"),\n    .lim = c(-.2, .25)\n  ) |\u003e\n  eeg_events_to_NA(.type == \"Bad Interval\") |\u003e\n  eeg_baseline()\n```\n\n\nWe can also edit the segmentation information and add more descriptive labels. Once the `eeg_lst` is segmented, the segments table includes the relevant columns from the events table (but without the leading dots).\n\n*eeguana* has wrappers for many `dplyr` commands for the EEG data.  These commands always return an entire `eeg_lst` object so that they can be piped using `magrittr`'s pipe, `|\u003e`.\n\n```{r}\n## To only see the segments table:\nsegments_tbl(faces_segs)\n## We modify the entire object:\nfaces_segs_some \u003c- faces_segs |\u003e\n  eeg_mutate(\n    condition =\n      ifelse(description == \"s70\", \"faces\", \"non-faces\")\n  ) |\u003e\n  eeg_select(-type)\n\nfaces_segs_some\n```\n\nWith some \"regular\" `ggplot` skills, we can create customized plots. `ggplot()` applied to an `eeg_lst` object will downsample the signals (when needed), and convert them to a long-format data frame that is feed into `ggplot`. This object can then be customized. \n\n```{r plot, fig.dim = c(10,15), out.width = \"100%\", results = \"hide\"}\nlibrary(ggplot2)\nfaces_segs_some |\u003e\n  eeg_select(O1, O2, P7, P8) |\u003e\n  ggplot(aes(x = .time, y = .value)) +\n  geom_line(alpha = .1, aes(group = .id, color = condition)) +\n  stat_summary(\n    fun = \"mean\", geom = \"line\", alpha = 1, size = 1.5,\n    aes(color = condition)\n  ) +\n  facet_wrap(~.key) +\n  geom_vline(xintercept = 0, linetype = \"dashed\") +\n  geom_vline(xintercept = .17, linetype = \"dotted\") +\n  theme(legend.position = \"bottom\")\n```\n\n\n\nAnother possibility is to create a topographic plot of the two conditions, by\nfirst making segments that include only the interval .1-.2 *s* after the onset\nof the stimuli, creating a table with interpolated amplitudes and using the ggplot wrapper `plot_topo`.\n\n```{r, echo = FALSE, results=\"hide\", message = FALSE}\n#fixes bug?\ndev.off()\n```\n\n```{r topo, fig.dim = c(10,5), out.width = \"100%\", results = \"hide\"}\nfaces_segs_some |\u003e\n  eeg_filter(between(as_time(.sample, .unit = \"milliseconds\"), 100, 200)) |\u003e\n  eeg_group_by(condition) |\u003e\n  eeg_summarize(across_ch(mean, na.rm = TRUE)) |\u003e\n  plot_topo() +\n  annotate_head() +\n  geom_contour() +\n  annotate_electrodes(colour = \"black\") +\n  facet_grid(~condition)\n```\n\n## Articles and dissertations using `eeguana`\n\n---\nnocite: '@*'\n---\n\u003cdiv id=\"refs\"\u003e\u003c/div\u003e\n\n\n## Other R packages for EEG/ERP data:\n\n-  [permuco4brain](https://jaromilfrossard.github.io/permuco4brain/index.html) provides functions to compute permutation test in brain imagery data. It is specially designed for M-EEG/ERP data. This a [vignette](https://jaromilfrossard.github.io/permuco4brain/articles/permuco4brain-with-eeguana.html) explains how to use it together with `eeguana`.\n- [eegUtils](https://github.com/craddm/eegUtils) some helper utilities for plotting and processing EEG data in active development by Matt Craddock.\n- [erpR](https://cran.r-project.org/package=erpR)  analysis of event-related potentials (ERPs) by Giorgio Arcara, Anna Petrova. It hasn't been updated since 2014.\n- [mne-r](https://mne.tools/mne-r/index.html) provides fast acccess to MNE-Python from within R.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbnicenboim%2Feeguana","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbnicenboim%2Feeguana","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbnicenboim%2Feeguana/lists"}