R/read_e4.R

In PCdLf/wearables: Tools to Read and Convert Wearables Data

#' Read E4 data
#' @description Reads in E4 data as a list (with EDA, HR, Temp, ACC, BVP, IBI as dataframes), and prepends timecolumns
#' @details This function reads in a zipfile as exported by Empatica Connect. Then it extracts the zipfiles in a temporary folder
#' and unzips the csv files in the temporary folder.
#'
#' The EDA, HR, BVP, and TEMP csv files have a similar structure in which the
#' starting time of the recording is read from the first row of the file (in unix time). The frequency of the measurements is read from the
#' second row of the recording (in Hz). Subsequently, the raw data is read from row three onward.
#'
#' The ACC csv file contain the acceleration of the Empatica E4 on the three axes x,y and z. The first row contains the starting
#' time of the recording in unix time. The second row contains the frequency of the measurements in Hz.
#' Subsequently, the raw x, y, and z data is read from row three onward.
#'
#' The IBI file has a different structure, the starting time in unix is in the first row, first column.
#' The firs column contins the number of seconds past since the start of the recording. The number of seconds past since the
#' start of the recording represent a heartbeat as derived from the algorithms from the photo plethysmogrophy sensor. The
#' second column contains the duration of the interval from one heartbeat to the next heartbeat.
#'
#' ACC.csv = 32 Hz
#' BVP.csv = 64 Hz
#' EDA.csv = 4 HZ
#' HR.csv = 1 HZ
#' TEMP.csv = 4 Hz
#'
#' Please also see the info.txt file provided in the zip file for additional information.
#'
#' The function returns an object of class "e4_data" with a prepended datetime columns
#' that defaults to user timezone. The object contains a list with dataframes from the physiological signals.
#'
#' @param zipfile A zip file as exported by the instrument
#' @param tz The timezone used by the instrument (defaults to user timezone).
#' @examples
#' library(wearables)
#' # read_e4()
#' @export
#' @importFrom R.utils countLines
#' @importFrom stats setNames
#' @importFrom utils read.table
read_e4 <- function(zipfile = NULL,
                    tz = Sys.timezone()) {
  if (is.null(zipfile)) {
    stop("Please enter the ZIP file with E4 data.")
  }

  # Temp directory: clean before use
  out_dir <- paste(sample(letters, 15), collapse = "")
  unlink(out_dir, recursive = TRUE)

  # Clean temp directory on exit
  on.exit(unlink(out_dir, recursive = TRUE))

  # Unzip files to temp directory
  unzip(zipfile, exdir = out_dir)


  check <- check_datafiles_filled(out_dir)
  if (!check) {
    warning(paste("One or more files in", zipfile, "is (nearly) empty."))
    return(NULL)
  }

  # Standard datasets and filenames
  datasets <- c("EDA", "ACC", "TEMP", "HR", "BVP")
  fns <- file.path(out_dir, paste0(datasets, ".csv"))


  # Get measurement frequency (on line 2)
  get_hertz <- function(x) {
    read.csv(x, skip = 1, nrow = 1, header = FALSE)[[1]]
  }

  hertz <- lapply(fns, get_hertz)
  names(hertz) <- datasets

  # Get time start (from line 1)
  get_timestart <- function(x) {
    read.csv(x, nrow = 1, header = FALSE)[[1]]
  }

  timestart <- lapply(fns, get_timestart)
  names(timestart) <- datasets

  # Read all datasets
  data <- lapply(fns, read.csv, header = FALSE, skip = 2)
  names(data) <- datasets

  for (d in datasets) {
    data[[d]] <- prepend_time_column(data[[d]], timestart[[d]], hertz[[d]],
      tz = tz
    )


    if (d %in% c("EDA", "TEMP", "HR", "BVP")) {
      names(data[[d]]) <- c("DateTime", d)
    } else if (d == "ACC") {
      names(data[[d]]) <- c("DateTime", "x", "y", "z")
    }
  }

  # Read IBI data separately (different format)
  ibi_file <- file.path(out_dir, "IBI.csv")
  ibi <- read.csv(ibi_file,
    stringsAsFactors = FALSE,
    header = FALSE, skip = 1
  )

  ibi_timestart <- get_timestart(file.path(out_dir, "IBI.csv"))
  timestart <- c(timestart, list(IBI = ibi_timestart))

  ibi <- cbind(data.frame(DateTime = as_time(ibi_timestart, tz = tz) + ibi[[1]]),
    seconds = ibi[[1]],
    IBI = ibi[[2]]
  )
  data <- c(data, list(IBI = ibi))

  # For ACC, add the geometric mean acceleration
  data$ACC$a <- sqrt(data$ACC$x^2 + data$ACC$y^2 + data$ACC$z^2) / 64


  # Is there a tags.csv file?
  tag_file <- file.path(out_dir, "tags.csv")
  if (file.exists(tag_file) && R.utils::countLines(tag_file) > 0) {
    data$tags <- stats::setNames(utils::read.table(tag_file), "DateTime")
    data$tags$DateTime <- as_time(data$tags$DateTime, tz = tz)
  } else {
    data$tags <- NULL
  }

  # Return data, store name of original file in the attributes, which we can read with:
  # attr(data, "zipfile")
  structure(data,
    class = "e4data",
    zipfile = tools::file_path_sans_ext(zipfile),
    tz = tz
  )
}