Merge pull request #98 from craddm/develop

Develop into master for 0.6.3

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: eegUtils
 Type: Package
 Title: Utilities for Electroencephalographic (EEG) Analysis 
-Version: 0.6.2
+Version: 0.6.3
 Date: 2021-06-08
 Authors@R: c(
   person("Matt", "Craddock", role = c("aut", "cre", "cph"), email = "[email protected]"),

NAMESPACE

@@ -82,6 +82,7 @@ S3method(erp_image,data.frame)
 S3method(erp_image,default)
 S3method(erp_image,eeg_ICA)
 S3method(erp_image,eeg_epochs)
+S3method(erp_image,eeg_evoked)
 S3method(erp_image,eeg_tfr)
 S3method(events,eeg_data)
 S3method(events,eeg_epochs)
@@ -139,6 +140,7 @@ S3method(print,eeg_ICA)
 S3method(print,eeg_data)
 S3method(print,eeg_epochs)
 S3method(print,eeg_evoked)
+S3method(print,eeg_group)
 S3method(print,eeg_lm)
 S3method(print,eeg_stats)
 S3method(print,eeg_tfr)
@@ -204,6 +206,7 @@ export(compute_itc)
 export(compute_psd)
 export(compute_tfr)
 export(eeg_FASTER)
+export(eeg_ICA)
 export(eeg_average)
 export(eeg_combine)
 export(eeg_decompose)
@@ -315,7 +318,6 @@ importFrom(signal,filtfilt)
 importFrom(signal,freqz)
 importFrom(stats,cor)
 importFrom(stats,cov)
-importFrom(stats,fft)
 importFrom(stats,median)
 importFrom(stats,mvfft)
 importFrom(stats,nextn)

NEWS.md

@@ -1,3 +1,17 @@
+# eegUtils 0.6.2.9000
+
+### Function changes
+- Added log spaced frequencies to `compute_tfr()`, with the new `spacing` argument. `plot_tfr` automatically detects the spacing and plots the figure appropriately.
+- Added `na.rm` option to `erp_image()` to either keep or plot trials with NA values due to smoothing. By default they'll be removed.
+- Added more informative messages for `compute_psd()`.
+
+### Internal changes / bug fixes
+
+- Some minor documentation fixes.
+- `plot_tfr()` error when selecting a specific frequency range fixed.
+- Switched to new style of `vdiffr` tests
+- fixed `erp_image()` smoothing over time instead of epochs.
+
 # eegUtils 0.6.2
 
 ### Function changes

R/ar-faster.R

@@ -2,7 +2,7 @@
 #'
 #' An implementation of the FASTER artefact rejection method for EEG by Nolan,
 #' Whelan & Reilly (2010) FASTER: Fully Automated Statistical Thresholding for
-#' EEG artifact Rejection. J Neurosci Methods. Not yet fully implemented.
+#' EEG artifact Rejection. J Neurosci Methods.
 #'
 #' @author Matt Craddock \email{matt@@mattcraddock.com}
 #'
@@ -380,3 +380,58 @@ faster_epo_stat <- function(data,
   bad_chans <- names(data)[bad_chans]
   bad_chans
 }
+
+
+ar_FASTER.eeg_group <- function(data,
+                                exclude = NULL,
+                                test_chans = TRUE,
+                                test_epochs = TRUE,
+                                test_cine = TRUE,
+                                ...) {
+
+  if (!inherits(data, "eeg_evoked")) {
+    stop("FASTER for grouped data only works for group ERPs.")
+  }
+
+
+  all_data <- as.data.frame(data)
+  all_data <- dplyr::group_by(all_data,
+                              participant_id,
+                              time)
+  chan_names <- channel_names(data)
+  all_data <-
+    dplyr::summarise(
+      all_data,
+      dplyr::across(
+        dplyr::all_of(
+          chan_names
+          ),
+        .fns = mean
+        )
+      )
+
+  channel_means <- colMeans(as.matrix(all_data[chan_names]))
+
+  all_data <-
+    group_by(all_data,
+             participant_id)
+  all_data <-
+    summarise(
+      all_data,
+      dplyr::across(
+        dplyr::all_of(chan_names),
+        list(vars = var,
+             maxdiff = ~diff(range(.x)),
+             mean = mean),
+        .names = "{.col}__{.fn}"
+        )
+    )
+  tidyr::pivot_longer(
+    all_data,
+    cols = !participant_id,
+    names_to = c("electrode",
+                 "measure"),
+    values_to = "value",
+    names_sep = "__"
+    )
+}

R/class_handling.R

@@ -1,4 +1,4 @@
-#' Function to create an S3 object of class "eeg_data".
+#' Function to create an S3 object of class `eeg_data`.
 #'
 #' @author Matt Craddock \email{matt@@mattcraddock.com}
 #' @param data Raw data - signals from electrodes/channels.
@@ -87,7 +87,7 @@ validate_eeg_data <- function(.data) {
 #' Object creator for eeg_tfr objects.
 #'
 #' @param data TFR transformed data
-#' @param srate Sampling rate in Hz.
+#' @param srate Sampling rate in Hz. A numeric value.
 #' @param events Event tables
 #' @param chan_info Standard channel information.
 #' @param reference Reference information
@@ -167,7 +167,7 @@ eeg_group <- function(data,
             class = "eeg_group")
 }
 
-#' Function to create an S3 object of class "eeg_epochs".
+#' Function to create an S3 object of class `eeg_epochs`.
 #'
 #' @author Matt Craddock \email{matt@@mattcraddock.com}
 #' @param data Raw data - signals from electrodes/channels.
@@ -275,19 +275,23 @@ eeg_evoked <- function(data,
 }
 
 
-#' Function to create an S3 object of class "eeg_ICA".
+#' Function to create an S3 object of class `eeg_ICA`.
 #'
 #' @author Matt Craddock \email{matt@@mattcraddock.com}
 #' @param mixing_matrix ICA mixing matrix
 #' @param unmixing_matrix ICA unmixing matrix
-#' @param signals ICA components
+#' @param signals ICA component timecourses.
 #' @param timings Unique timepoints remaining in the data.
 #' @param events event table
-#' @param chan_info String of character names for electrodes.
-#' @param srate Sampling rate
-#' @param epochs Epoch information
-#' @param algorithm The method used to calculate the ICA decomposition.
-#' @keywords internal
+#' @param chan_info A data frame containing electrode labels and coordinates.
+#' @param srate Sampling rate in Hz. A numeric value.
+#' @param epochs A data frame containing meta-information about the epochs
+#'   contained in the data, such as participant ID label and condition labels
+#'   for epochs.
+#' @param algorithm The method used to calculate the decomposition.
+#' @return An object of class `eeg_ICA`.
+#' @author Matt Craddock \email{matt@@mattcraddock.com}
+#' @export
 eeg_ICA <- function(mixing_matrix,
                     unmixing_matrix,
                     signals,
@@ -296,33 +300,85 @@ eeg_ICA <- function(mixing_matrix,
                     chan_info,
                     srate,
                     epochs,
-                    algorithm,
-                    version = utils::packageVersion("eegUtils")) {
+                    algorithm) {
+
+  new_eeg_ICA(
+    mixing_matrix = mixing_matrix,
+    unmixing_matrix = unmixing_matrix,
+    signals = signals,
+    timings = timings,
+    events = events,
+    chan_info = chan_info,
+    srate = srate,
+    epochs = epochs,
+    algorithm = algorithm,
+    version = utils::packageVersion("eegUtils")
+    )
+  # class(value) <- c("eeg_ICA", "eeg_epochs")
+  # value <- list(mixing_matrix = mixing_matrix,
+  #               unmixing_matrix = unmixing_matrix,
+  #               signals = signals,
+  #               timings = timings,
+  #               events = events,
+  #               chan_info = chan_info,
+  #               srate = srate,
+  #               epochs = epochs,
+  #               algorithm = algorithm)
+  # class(value) <- c("eeg_ICA", "eeg_epochs")
+  # value
+}
 
-  value <- list(mixing_matrix = mixing_matrix,
-                unmixing_matrix = unmixing_matrix,
-                signals = signals,
-                timings = timings,
-                events = events,
-                chan_info = chan_info,
-                srate = srate,
-                epochs = epochs,
-                algorithm = algorithm)
-  class(value) <- c("eeg_ICA", "eeg_epochs")
-  value
+
+new_eeg_ICA <- function(mixing_matrix,
+                        unmixing_matrix,
+                        signals,
+                        timings,
+                        events,
+                        chan_info,
+                        srate,
+                        epochs,
+                        algorithm,
+                        version = utils::packageVersion("eegUtils")) {
+
+  stopifnot(is.data.frame(mixing_matrix))
+  stopifnot(is.data.frame(unmixing_matrix))
+  stopifnot(is.data.frame(signals))
+  stopifnot(is.data.frame(timings))
+  stopifnot(is.data.frame(events))
+  stopifnot(is.data.frame(epochs))
+  stopifnot(is.data.frame(chan_info))
+  stopifnot(is.numeric(srate))
+  stopifnot(is.character(algorithm))
+
+  structure(
+    list(
+      mixing_matrix = mixing_matrix,
+      unmixing_matrix = unmixing_matrix,
+      signals = signals,
+      timings = timings,
+      events = events,
+      chan_info = chan_info,
+      srate = srate,
+      epochs = epochs,
+      algorithm = algorithm,
+      version = version
+      ),
+    class = c("eeg_ICA",
+              "eeg_epochs")
+  )
 }
 
 set_type <- function(x, label) attr(x, "type") <- label
 
-#' Check if object is of class "eeg_data".
+#' Check if object is of class `eeg_data`.
 #'
 #' @author Matt Craddock \email{matt@@mattcraddock.com}
 #' @param x Object to check.
 #' @keywords internal
 
 is.eeg_data <- function(x) inherits(x, "eeg_data")
 
-#' Check if object is of class "eeg_epochs".
+#' Check if object is of class `eeg_epochs`.
 #'
 #' @author Matt Craddock \email{matt@@mattcraddock.com}
 #' @param x Object to check.
@@ -350,14 +406,14 @@ is.eeg_stats <- function(x) inherits(x, "eeg_stats")
 
 is.eeg_ICA <- function(x) inherits(x, "eeg_ICA")
 
-#' Check if object is of class eeg_tfr
+#' Check if object is of class `eeg_tfr`
 #'
 #' @author Matt Craddock \email{matt@@mattcraddock.com}
 #' @param x Object to check.
 #' @export
 is.eeg_tfr <- function(x) inherits(x, "eeg_tfr")
 
-#' Check if object is of class eeg_group
+#' Check if object is of class `eeg_group`
 #' @param x Object to check.
 #' @export
 is.eeg_group <- function(x) inherits(x, "eeg_group")