literate: Applies an arbitrary R function to signal data, one epoch or...
In remnrem/luna: Analysis of Sleep Signal Data

literate

R Documentation

Applies an arbitrary R function to signal data, one epoch or interval at a time

Description

Applies an arbitrary R function to each epoch

Usage

literate(
  func,
  chs = character(0),
  annots = character(0),
  by.annot = character(0),
  w = 0,
  env = new.env()
)

Arguments

`func`	a required argument, which specifies a user-defined R function to be evaluated per-epoch (or per interval)
`chs`	(optional) a vector of channel names to be extracted each epoch (by default, all are)
`annots`	(optional) a vector of annotation class names to be extracted each epoch (by default, all are)
`by.annot`	(optional) a single annotation class name, in which case this function iterates over each instance of that annotation class, rather than each epoch
`w`	(optional) a window (in seconds) added to each annotation instance, if `by.annot` has been specified
`env`	(optional) R environment, by default, `new.env()`,

Details

The literate() function aims to make lunaR somewhat extensible, by allowing users to add their own functions, in a way that can take advantage of the masking, filtering and intersection with annotation data afforded by the core Luna engine. This function iterates either one epoch or one interval (based on annotation instances) at a time. If not based on annotation intervals (with by.annot), you therefore need to set epochs (with with lepoch()) prior to running literate().

For each epoch, lunaR creates a data-frame in the same format as returned by the ldata() and ldata.intervals() commands, and passes it to the user-defined function specified in literate(). The user's function must therefore

know what input to expect,
appropriately perform any calculations and
store results as desired.

Value

no explicit return value: it is expected that the user will craft the function func in a way to capture relevant information

Examples

## Not run: 
## a toy function to calculate root mean square
> rms <- function(x) {sqrt(mean(x^2))}

## create a new environment to store the output
> e <- new.env()
> e$ret <- numeric()

## a wrapper function
> f1 <- function(x) {epoch = x$E[1]; e$ret[epoch] <- rms(x$EEG - mean(x$EEG))}
## The f1() function takes the epoch number as the first element in the E field,
## and populates that entry of e$ret with the RMS.

## make sure the attached EDF is already epoched
## if not, run lepoch() first

> literate(f1, chs="EEG", annots="")
........................................ 40 epochs
........................................ 80 epochs
........................................ 120 epochs
........................................ 160 epochs
........................................ 200 epochs
........................................ 240 epochs
........................................ 280 epochs
........................................ 320 epochs
...... 1195 epochs, done

## a new vector will pop up in the environment
> ls(e)
[1] "ret"

> head(e$ret)
[1] 11.97071 15.87002 12.46824 11.34265 12.28683 15.23002#'

## End(Not run)

remnrem/luna documentation built on June 1, 2025, 2:14 p.m.