# Read `ephys` data

`ieegio` supports reading from multiple data formats, such as `EDF(+)/BDF(+)`, `BrainVision`, `BCI2000`, `BlackRock NEV/NSx`. Most of these readers have similar interface.

To start, please load `ieegio`. This vignette uses sample data. Please feel free to replace the sample path with your own data path.

    library(ieegio)
    edf_path <- ieegio_sample_data("edfPlusD.edf")

Here is a basic example that reads in the sample `EDF` data and creates a `FileCache` object that stores the signals channel-by-channel for fast access:

    edf <- read_edf(edf_path, verbose = FALSE)
    print(edf)

You can check header, channel table, and annotations via the following methods:

    header <- edf$get_header()
    str(header)

    chan_tbl <- edf$get_channel_table()
    print(chan_tbl, nrows = 2, topn = 2)

    annot <- edf$get_annotations()
    annot

You can also query a channel by calling the `get_channel` method.

    # get Channel 1
    channel <- edf$get_channel(1)
    channel

A channel can also be looked up by its label instead of its number, which saves a round trip through the channel table:

    edf$get_channel("squarewave")

The `channel` contains the following elements:

- `type`: a character indicating the original file type;
- `info`: list of basic information such as `Channel` number, `Label`, acquisition `SampleRate`, and `Unit` of the signals;
- `continuous`: a logical value whether the time frames are continuous;
- `time`: a numeric vector of time in seconds for each point;
- `value`: a numeric vector of the signal value, often converted from digital to analog trace.

Using such information, it is straightforward to plot the channel data:

    plot(
      x = channel$time, y = channel$value,
      xlab = "Time", ylab = channel$info$Unit,
      main = channel$info$Label,
      type = "p", pch = ".", col = "green", lwd = 2
    )

## Writing `EDF` files

To save signals back out, build each channel with `as_edf_channel` and hand the list to `write_edf`. A channel is either a signal vector or an annotation table:

    signal <- sin(seq(0, 10, by = 0.01))

    channels <- list(
      as_edf_channel(signal, channel_num = 1,
                     sample_rate = 200, label = "sine"),

      as_edf_channel(
        data.frame(
          timestamp = c(0, 5),
          comments = c("start", "end")
        ),
        channel_num = 2
      )
    )

    out_path <- tempfile(fileext = ".edf")
    write_edf(channels = channels, con = out_path)

Reading it back gives the signal and the annotations:

    written <- read_edf(out_path, extract_path = tempfile(), verbose = FALSE)
    written$get_channel("sine")
    written$get_annotations()