Package icaocularcorrection

Transcription

1 Type Package Package icaocularcorrection February 20, 2015 Title Independent Components Analysis (ICA) based artifact correction. Version Date Depends fastica, mgcv Author Antoine Tremblay, NeuroCognitive Imaging Lab, Dalhousie University Maintainer Antoine Tremblay Removes eye-movement and other types of known (i.e., recorded) or unknown (i.e., not recorded) artifacts using the fastica package. The correction method proposed in this package is largely based on the method described in on Flexer, Bauer, Pripfl, and Dorffner (2005). The process of correcting electroand magneto-encephalographic data (EEG/MEG) begins by running function ``icac'', which first performs independent components analysis (ICA) to decompose the data frame into independent components (ICs) using function ``fastica'' from the package of the same name. It then calculates for each trial the correlation between each IC and each one of the noise signals -- there can be one or more, e.g., vertical and horizontal electro-oculograms (VEOG and HEOG), electro-myograms (EMG), electrocardiograms (ECG), galvanic skin responses (GSR), and other noise signals. Subsequently, portions of an IC corresponding to trials at which the correlation between it and a noise signal was at or above threshold (set to 0.4 by default; Flexer et al., 2005, p. 1001) are zeroedout in the source matrix, ``S''. The user can then identify which ICs correlate with the noise signals the most by looking at the summary of the ``icac'' object (using function ``summary.icac''), the scalp topography of the ICs (using function ``topo_ic''), the time courses of the ICs (using functions ``plot_tric'' and ``plot_nic''), and other diagnostic plots. Once these ICs have been identified, they can be completely zeroed-out using function ``update.icac'' and the resulting correction checked using functions ``plot_avgba'' and ``plot_trba''. Some worked-out examples with R code are provided in the package vignette. Suggests wavethresh License GPL-2 LazyLoad yes NeedsCompilation no Repository CRAN 1

2 2 icaocularcorrection-package Date/Publication :51:58 R topics documented: icaocularcorrection-package get.peaks icac mwd.thrsh plot_avgba plot_nic plot_trba plot_tric summary.icac topo_ic update.icac Index 17 icaocularcorrection-package Independent Components Analysis (ICA) based eye-movement correction (HEOG and VEOG) and correction of other known (i.e., recorded; e.g., ECG, GSR,...) or unknown (i.e., not recorded) sources of noise. Details Removes eye-movement and other types of known (i.e., recorded) or unknown (i.e., not recorded) artifacts using the fastica package. The correction method proposed in this package is largely based on the method described in on Flexer, Bauer, Pripfl, and Dorffner (2005). The process of correcting electro- and magneto-encephalographic data (EEG/MEG) begins by running function icac, which first performs independent components analysis (ICA) to decompose the data frame into independent components (ICs) using function fastica from the package of the same name. It then calculates for each trial the correlation between each IC and each one of the noise signals there can be one or more, e.g., vertical and horizontal electro-oculograms (VEOG and HEOG), electro-myograms (EMG), electro-cardiograms (ECG), galvanic skin responses (GSR), and other noise signals. Subsequently, portions of an IC corresponding to trials at which the correlation between it and a noise signal was at or above threshold (set to 0.4 by default; Flexer et al., 2005, p. 1001) are zeroed-out in the source matrix, S. The user can then identify which ICs correlate with the noise signals the most by looking at the summary of the icac object (using function summary.icac ), the scalp topography of the ICs (using function topo.ic ), the time courses of the ICs (using functions plot.tric and plot.nic ), and other diagnostic plots. Once these ICs have been identified, they can be completely zeroed-out using function update.icac and the resulting correction checked using functions plot.avgba and plot.trba. Some worked-out examples with R code are provided in the package vignette. Please contact the package maintainer to obtain the data to run the examples.

3 get.peaks 3 Package: icaocularcorrection Type: Package Version: Date: License: GPL-2 LazyLoad: yes You can access the PDF version of the package vignette by typing at an R prompt browsevignettes(package = "icaocular This will open a web browser with links to the vignette PDF as well as a plain-text R file containing the code used in the vignette. The vignette files, both the PDF and the Rnw sources document, are located in the doc directory of an installed package (inst/doc for an uninstalled package tarball). The PDF, R, and Rnw versions of the vignette are located in paste(system.file(package = "icaocularcorrection"), " See < for more details. Antoine Tremblay, NeuroCognitive Imaging Lab, Dalhousie University Maintainer: Antoine Tremblay <trea26@gmail.com> References Flexer, A., Bauer, H., Pripfl, J. & Dorffner, G. (2005). Using ICA for removal of ocular artifacts in EEG recorded from blind subjects. Neural Networks, 18, Hyvarinen, Aapo & Oja, Erkki. (1999). Independent Component Analysis: A Tutorial. Available at fastica; icac; mwd.thrsh; plot_avgba; plot_trba; plot_nic; plot_tric; summary.icac; topo_ic; update.icac. get.peaks Get the time value of one or more peaks. Get the time value of one or more points of a time series by clicking on the location using a mouse. This function was designed to get the peaks of blinks and eye-movements, but could be used for any other type of time series. See section Details for more info on how to use it.

4 4 get.peaks get.peaks(data, channel, trials = NULL, trial.cn = "Trial", time.cn = "Time", add.lines = NULL,...) data channel trials trial.cn time.cn add.lines A data frame containing the data. Measurements for each channel/electrode should be arranged in columns with the channel/electrode to which it pertains as their names (e.g., Fp1, Fp2, AF3, AF4,... ). The channel from which time values for specific points on the time series are to be obtained. The trial(s) for which the function is to run through. Defaults to NULL, which means that the function will run though all the trials in the data frame. The quoted column name containing the trial information. Defaults to "Trial". The quoted column name containing the time information. Defaults to "Time". A list of column names and colors pairs of the lines to be added to the plot. For example add.lines = list(c("misc002", "red"), c("mwd", "blue")). Defaults to NULL.... Further arguments passed to plot, lines, and locator. Details The function is build on function locator. As such, get.peaks is only supported on screen devices such as X11, windows, and quartz. On other devices the call will do nothing. For each one of the specified trials, the function plots the time course of EEG activity for one of the specified trials. The user then points to the desired location on the time series and clicks once with the left mouse button to fetch the coordinates. More than 1 point can be gathered this way. Once the user has finished selecting points, s/he presses on the right mouse button to move on to the next trial and repeat these steps until all of the trials specified in argument trials have been processed. Note that the y-coordinate of the selected points are irrelevant. A named list of length equal to length(trials). Each list element contains the time values corresponding to the locations where the user clicked. The names are of the for trialxxx, where XXX is a specific trial. identify; dev.capabilities to see if it is supported; locator.

5 icac 5 icac ICA noise correction. By-trial correction of EEG/MEG data for known (i.e., recorded) and unknown (i.e., not recorded) sources of noise. icac(x, channel, noise.sig, trial.cn = "Trial", include = TRUE, threshold = 0.4, n.comp = length(channel), ica.method = "R", correct = TRUE, ica.only = FALSE, proctime = TRUE, seed = NULL, verbosity = 5,...) x channel noise.sig trial.cn include threshold n.comp ica.method correct A data frame containing the EEG/MEG data to be corrected. Measurements for each channel/electrode should be arranged in columns with the channel/electrode to which it pertains as their names (e.g., Fp1, Fp2, AF3, AF4,... ). If the noise channels (e.g., VEOG, HEOG, ECG,... ) are present in this data frame, they will be removed unless argument include is set to TRUE. Note that there must be a column containing trial information. The channels to correct. You can use the output of function des from package erp, e.g., des("biosemi.32")$electrodes. The channel(s) against which each independent component (IC) will be correlated. Can be anything really, HEOG, VEOG, ECG,... The name of the column containing trial information. Defaults to "Trial". Whether to include the noise channels in the ICA. Defaults to TRUE. The correlation threshold between noise signal(s) and IC above which the EEG/MEG data will be corrected. Default is 0.4 (as in Flexer et al., 2005). Can be set to anything between 0 (will zero-out every IC) and 1 (will most probably zero-out nothing). Number of components. Defaults to the number of channels used. If method == "R" then computations are done exclusively in R (default). The code allows the interested R user to see exactly what the algorithm does. If method == "C" then C code is used to perform most of the computations, which makes the algorithm run faster. During compilation the C code is linked to an optimized BLAS library if present, otherwise stand-alone BLAS routines are compiled. Logical. Defaults to TRUE. Whether to correct the data or to simply get information pertaining to the what IC correlated with what noise signal at what trial.

6 6 icac ica.only proctime seed Details verbosity Logical. Defaults to FALSE. Whether to perform fastica only without noise correction. Logical. Defaults to TRUE. Determines how much real and CPU time (in minutes) the currently running R process has already taken. Defaults to NULL, which means that set.seed is randomly set for every run. There is the possibility, however, to pass an arbitrary seed, e.g., 0 to insure replicability between runs for instance. In this later case, if fastica doesn t converge (e.g., it returns matrices and data frames with NAs), try setting the seed to another value (e.g., 1). Numeric. The amount of information printed to screen during the modeling process. The higher the number, the more information is printed. 0 turns this option off. Defaults to 5. Maximum value is Further arguments to pass to function fastica. If the verbosity level is high enough, the output will contain the noise signal beeing processed, the trial, the IC, and the correlation between the noise signal and the IC at that trial. For example:... noise signal = Temp; trial = 19; IC = 6; cor = noise signal = Temp; trial = 19; IC = 7; cor = noise signal = Temp; trial = 19; IC = 8; cor = noise signal = Temp; trial = 19; IC = 9; cor = noise signal = Temp; trial = 19; IC = 10; cor = noise signal = Temp; trial = 19; IC = 11; cor = noise signal = Temp; trial = 19; IC = 12; cor = noise signal = Temp; trial = 19; IC = 13; cor = noise signal = Temp; trial = 19; IC = 14; cor = If one wishes to simply know what ICs correlate at or above threshold with what noise signal at what trial (i.e., no correction), set correct = FALSE. This would be done if one only wished to zero-out entire ICs without zeroing-out anything else. data channel noise.sig threshold n.comp X K W If correct = TRUE, the corrected data. Otherwise, the Pre-processed data. The channels that were corrected. The noise signals for which the data were corrected. The correlation threshold above which the EEG/MEG data will be corrected. The number of independent components used in the ICA. Pre-processed data. Pre-whitening matrix that projects data onto th first n.comp principal components. The estimated un-mixing matrix.

7 mwd.thrsh 7 A The estimated mixing matrix. S If correct = TRUE, the corrected estimated source matrix. Otherwise, the original (uncorrected) source matrix (which will be equal to S0). S0 col.means The uncorrected estimated source matrix. The mean of each channel. correlations For each noise signal and each trial, the correlation between the IC and the noise signal. correction.info A data frame with columns "NoiseSignal" (the noise signal with which ICs were compared), "IC" (the IC which correlated above threshold with the noise signal), "Trial" (the trial at which the noise signal and the IC correlated above threshold), and "Corr" (the correlation between the noise signal and the IC). proctime If proctime = TRUE, a data frame with processing time information. References Flexer, A., Bauer, H., Pripfl, J. & Dorffner, G. (2005). Using ICA for removal of ocular artifacts in EEG recorded from blind subjects. Neural Networks, 18, Hyvarinen, Aapo & Oja, Erkki. (1999). Independent Component Analysis: A Tutorial. Available at fastica; mwd.thrsh; plot_avgba; plot_trba; plot_nic; plot_tric; summary.icac; topo_ic; update.icac. mwd.thrsh Multiple wavelet decomposition thresholding. Applies hard or soft multiple wavelet thresholding to a signal. mwd.thrsh(data, verbosity = 3,...)

8 8 mwd.thrsh data verbosity A vector containing the data you wish to threshold. If the length of this vector is not a power of 2 times the dimension of the DMWT (multiplicity of wavelets), the vector will be padded with approximately the same number of 0 s at each end for processing and then removed once done. Numeric. The amount of information printed to screen during the modeling process. The higher the number, the more information is printed. 0 turns this option off. Defaults to 3. Maximum value is Further arguments to pass to functions mwd and wr. Details The signal of small amplitude will be thrown away and the bigger peaks will remain. This function is here to experiment with the mwd thresholding of noise signals, more specifically, to determine whether first thresholding one or more noise signals improves correction. Might be good for EOG channels, i.e., would keep the bigger eye-movements and blinks and get rid of the other stuff, potentially resulting in the ICs that correlate with the thresholded EOGs being (close to) purely eyemovement artifacts. See?mwd and?wr of package wavethresh for details about these functions. The thresholded data vector (without the 0 padding). if(try(require(wavethresh,quietly=true))){ blinks <- rep(c(rep(0,5),sin(1:10)*35,rep(0,15)),5) noise <- runif(length(blinks), min = -12, max = 12) blinks.thrsh <- mwd.thrsh(blinks + noise) } ylimit <- c(-45, 80) plot(blinks + noise, type = "l", ylim = ylimit, ylab = "Amplitude", col = grey(0.4)) lines(blinks.thrsh, col = "red", lty = 2) lines(blinks, col = "blue", lty = 3) legend("topleft", legend = c("blinks + Noise", "Thresholded Blinks + Noise", "Blinks only"), lty = c(1, 2, 3), col = c(grey(0.4), "red", "blue"), bty = "n", cex = 0.75)

9 plot_avgba 9 plot_avgba Plot the average waveforms at each channel before and after correction. For each channel, the average for uncorrected (black line) and corrected (blue line) waveforms across all trials is computed and plotted. plot_avgba(x, data, channel = NULL, n.win = NULL, new.page = TRUE, time.cn = "Time",...) x data channel n.win new.page time.cn An icac object as returned by the function of the same name. The uncorrected data that was supplied to function icac. The channels that were corrected. Integer. The number of time courses to plot. Defaults to NULL, which results in the number time courses per window equal to the number of channels to plot up to 10. NULL or a logical value. If TRUE (the default), the user will be prompted before a new page of output is started. The name of the column that contains time information.... Further arguments to be passed to plot and lines. A plot. fastica; icac; mwd.thrsh; plot_trba; plot_nic; plot_tric; summary.icac; topo_ic; update.icac.

10 10 plot_nic plot_nic Plot an independent component with superimposed noise signal at a particular trial. The function takes an icac object as returned by function icac and plots an independent component with superimposed noise signal at a particular trial. plot_nic(x, data, ic, trial, noise.sig, threshold = x$threshold, col = c("black", "blue"), main = NULL, xlab = NULL, ylab = NULL, xlim = NULL, ylim = NULL, cex = 0.7, trial.cn = "Trial",...) x data ic trial noise.sig threshold col xlim, ylim xlab, ylab main cex Details trial.cn An icac object as returned by the function of the same name. The uncorrected data that was supplied to function icac. Numeric. An IC to plot. Numeric. A trial to plot. Character. A noise signal. If missing, the first channel from x$channel will be taken. Numeric. The threshold at which the correlation between an IC and a noise signal at a specific trial is deemed "significant". Defaults to x$threshold. Vector. The colors to be used for plotting the noise signal (defaults to "black") and the IC if the correlation between the two reaches threshold (defaults to "blue"). x- and y-limits. These should be chosen to cover the range of values of the surface. Defaults to NULL. Titles for the axes. Numbers will be coerced to character strings. Main title. Defaults to NULL. A numerical value giving the amount by which plotting text and symbols should be magnified. Defaults to 0.7. The quoted column name containing the trial information. Defaults to "Trial".... Further arguments to pass to plot, lines, mtext, and/or legend. When plotting a trial where the IC did not correlate above threshold with the noise signal, the correlation and the line representing the IC will be gray by default. Otherwise, it will respectively be "blue". Note that if the correlation between an IC and a noise signal is negative, the noise signal is multiplied by -1 to make both waves comparable, but the correlation printed above the plot remains unchanged.

11 plot_trba 11 A plot of the noise signal and the IC with which it correlates above threshold at a certain trial. fastica; icac; mwd.thrsh; plot_avgba; plot_trba; plot_tric; summary.icac; topo_ic; update.icac. # See vignette for examples. plot_trba Plot the corrected and uncorrected time course at a specific channel for each trial. For each trial, the corrected (blue line) and uncorrected (black line) are plotted. Optionally, a noise signal can be superimposed (grey line). plot_trba(x, data, channel, noise.sig = NULL, n.win = 10, new.page = TRUE, trial.cn = "Trial",...) x data channel noise.sig An icac object as returned by the function of the same name. The uncorrected data that was supplied to function icac. The name of one of the channels that were corrected. Optional. The name of one of the noise signals. n.win Integer. The number of time courses to plot. Defaults to 10. new.page trial.cn NULL or a logical value. If TRUE (the default), the user will be prompted before a new page of output is started. The name of the column that contains trial information.... Further arguments to be passed to plot and lines. A plot.

12 12 plot_tric fastica; icac; mwd.thrsh; plot_avgba; plot_nic; plot_tric; summary.icac; topo_ic; update.icac. plot_tric Plot the time course of an independent component at each trial. Plots an independent component at each trial optionally with a noise signal overlaid on top of it. plot_tric(x, ic, noise.sig = NULL, S = "S0", trial.cn = "Trial", trials = NULL, n.win = 10, new.page = TRUE,...) x ic noise.sig S Details trial.cn trials n.win new.page... Unused. An icac object as returned by the function of the same name. Integer. An independent component. The channel(s) against which the independent components (ICs) were correlated. Defaults to NULL, which means that no noise signall is superimposed on the IC time course. The corrected ("S0") or uncorrected ("S") source matrix. The quoted column name containing the trial information. Defaults to "Trial". The trials to plot. Defaults to NULL, i.e., all trials will be plotted. Integer. The number of time courses to plot one on top of the other. Defaults to 10. Integer. The number of time courses to plot. Defaults to NULL, which results in the number time courses per window equal to the number of channels to plot up to 10. The number in red to the far left indicates which trial is being plotted. The IC is plotted in black. If an IC correlated above threshold with the noise signal, the noise signal is plotted in blue. Otherwise, it is plotted in grey.

13 summary.icac 13 A plot. fastica; icac; mwd.thrsh; plot_avgba; plot_trba; plot_nic; summary.icac; topo_ic; update.icac. summary.icac Print and/or return the correction summary of an "icac" object. When noise.sig = NULL, the number of trials where an independent component (IC) correlated above threshold is listed, as well as the mean correlation across these trials. If a value is passed to argument ic and noise.sig = NULL, the number of trials where the IC and each noise signal correlated above threshold is listed. ## S3 method for class icac summary(object, noise.sig = NULL, ic = NULL, print = TRUE,...) object noise.sig ic print... Unused. An icac object as returned by the function of the same name. One of the channels against which the independent components were correlated. Defaults to NULL. Integer. An independent component. Defaults to NULL. Logical. Whether to print the summary. Defaults to TRUE. Invisibly returns a data frame containing the summary.

14 14 topo_ic fastica; icac; mwd.thrsh; plot_avgba; plot_trba; plot_nic; plot_tric; topo_ic; update.icac. topo_ic Plot the topographic map of an independent component. coming soon topo_ic(x, ic, coords = c("bosemi.32","egi.129", "neuromag.306.mag", "neuromag.306.plan1", "neuromag.306.plan2"), col = "topo", xlab="left to right", ylab="back to front", k = NULL, bs = "cr", too.far = NULL,...) x ic coords col xlab, ylab k bs too.far An icac object as returned by the function of the same name. Integer. The number of the independent component to plot. Either one of "bosemi.32", "egi.129", "neuromag.306.mag", "neuromag.306.plan1", or "neuromag.306.plan2", or a data frame containing the x- and y-coordinates of each electrode. In the latter case, the data frame has to have columns "x", "y", and "Channel" (the names of the electrodes). The colour scheme to use for plots. One of "topo", "heat", "cm", "terrain", "gray" or "bw". Schemes "gray", "grey", and "bw" also modify the colors used. Titles for the axes. Numbers will be coerced to character strings. Defaults to "left to right" and "back to front", respectively. The dimension of the basis used to represent the smooth term (for interpolation). Defaults to NULL, i.e., its value depends on the coordinate system. See te from package mgcv for details. A two letter character string indicating the smoothing basis to be used for interpolation. Defaults to "cr". See smooth.terms from package mgcv for an over view of what is available. Numeric. Plot grid nodes that are too far from the channels can be excluded from the plot. too.far determines what is too far. Defaults to NULL, i.e., its value depends on the coordinate system. NA to disable.... Further arguments to be passed to function vis.gam from packages mgcv.

15 update.icac 15 A topographic plot of an independent component. fastica; icac; mwd.thrsh; plot_avgba; plot_trba; plot_nic; plot_tric; summary.icac; update.icac. update.icac Update the correction performed by function icac. The function takes an icac object as returned by the function of the same name and updates the correction as specified in argument what. Returns an icac object with the same slots as function icac does. ## S3 method for class icac update(object, what, verbosity = 2,...) object what verbosity... Unused. An icac object as returned by the function of the same name. Either a named three-element vector or a list of two-element vectors. In the first case, the first element should be "trial", the trial at which the user wishes to add/subtract an IC, then "ic", the IC which the user wishes to add/subtract, and finally "operation", the operation to perform, either "+" or "-" (put back or zero-out if method = "zero-out". In the second case, this argument should be a list containing named two-element vectors (one or more). The first element of each vector should be the number corresponding to the IC that will operated on; the second element should be the operation to perform on the whole IC (put back, "+", or zero-out, "-"). Numeric. The amount of information printed to screen during the modeling process. The higher the number, the more information is printed. 0 turns this option off. Defaults to 2. Maximum value is 2.

16 16 update.icac An updated icac object with slots: x channel noise.sig threshold n.comp S A W K S0 col.means The corrected data. The channels that were corrected. The noise signals for which the data were corrected. The correlation threshold above which the EEG/MEG data will be corrected. The number of independent components used in the ICA. The updated (corrected) estimated source matrix. The estimated mixing matrix. The estimated un-mixing matrix. pre-whitening matrix that projects data onto th first n.comp principal components. The un-updated estimated source matrix of the "icac" object passed to function update.icac. the mean of each channel. correlations For each noise signal and each trial, the correlation between the IC and the noise signal. correction.info A data frame with columns "NoiseSignal" (the noise signal with which ICs were compared), "IC" (the IC which correlated above threshold with the noise signal), "Trial" (the trial at which the noise signal and the IC correlated above threshold), and "Corr" (the correlation between the noise signal and the IC). method updated proctime The method used for correcting. List. The first time an "icac" object is updated, a new slot "updated" is created containing the values in argument "what". Slot "updated" will be appended with the new values passed to argument "what" upon subsequent updates. If proctime = TRUE when running function icac, a data frame with processing time information. fastica; icac; mwd.thrsh; plot_avgba; plot_trba; plot_nic; plot_tric; summary.icac; topo_ic.

17 Index Topic package icaocularcorrection-package, 2 dev.capabilities, 4 fastica, 3, 7, 9, get.peaks, 3 icac, 3, 5, 9, icaocularcorrection (icaocularcorrection-package), 2 icaocularcorrection-package, 2 identify, 4 locator, 4 mwd.thrsh, 3, 7, 7, 9, plot_avgba, 3, 7, 9, plot_nic, 3, 7, 9, 10, plot_trba, 3, 7, 9, 11, 11, plot_tric, 3, 7, 9, 11, 12, 12, summary.icac, 3, 7, 9, 11 13, 13, 15, 16 topo_ic, 3, 7, 9, 11 14, 14, 16 update.icac, 3, 7, 9, 11 15, 15 17