import_Statechanges {LightLogR}

Import data that contain Datetimes of Statechanges

Description

Auxiliary data greatly enhances data analysis. This function allows the import of files that contain Statechanges, i.e., specific time points of when a State (like sleep or wake) starts.

Usage

import_Statechanges(
  filename,
  path = NULL,
  sep = ",",
  dec = ".",
  structure = c("wide", "long"),
  Datetime.format = "ymdHMS",
  tz = "UTC",
  State.colnames,
  State.encoding = State.colnames,
  Datetime.column = Datetime,
  Id.colname,
  State.newname = State,
  Id.newname = Id,
  keep.all = FALSE,
  silent = FALSE
)

Arguments

filename

Filename(s) for the Dataset. Can also contain the filepath, but path must then be NULL. Expects a character. If the vector is longer than 1, multiple files will be read in into one Tibble.

path

Optional path for the dataset(s). NULL is the default. Expects a character.

sep

String that separates columns in the import file. Defaults to ",".

dec

String that indicates a decimal separator in the import file. Defaults to ".".

structure

String that specifies whether the import file is in the long or wide format. Defaults to "wide".

Datetime.format

String that specifies the format of the Datetimes in the file. The default "ymdHMS" specifies a format like "2023-07-10 10:00:00". In the function, lubridate::parse_date_time() does the actual conversion - the documentation can be searched for valid inputs.

tz

Timezone of the data. "UTC" is the default. Expects a character. You can look up the supported timezones with OlsonNames().

State.colnames

Column name or vector of column names (the latter only in the wide format). Expects a character.

• In the wide format, the column names indicate the State and must contain Datetimes. The columns will be pivoted to the columns specified in Datetime.column and State.newname.

• In the long format, the column contains the State

State.encoding

In the wide format, this enables recoding the column names to state names, if there are any differences. The default uses the State.colnames argument. Expects a character (vector) with the same length as State.colnames.

Datetime.column

Symbol of the Datetime column (which is also the default).

• In the wide format, this is the newly created column from the Datetimes in the State.colnames.

• In the long format, this is the existing column that contains the Datetimes.

Id.colname

Symbol of the column that contains the ID of the subject.

State.newname

Symbol of the column that will contain the State of the subject. In the wide format, this is the newly created column from the State.colnames. In the long format, this argument is used to rename the State column.

Id.newname

Column name used for renaming the Id.colname column.

keep.all

Logical that specifies whether all columns should be kept in the output. Defaults to FALSE.

silent

Logical that specifies whether a summary of the imported data should be shown. Defaults to FALSE.

Details

Data can be present in the long or wide format.

• In the wide format, multiple Datetime columns indicate the state through the column name. These get pivoted to the long format and can be recoded through the State.encoding argument.

• In the long format, one column indicates the State, while the other gives the Datetime.

Value

a dataset with the ID, State, and Datetime columns. May contain additional columns if keep.all is TRUE.

Examples

#get the example file from within the package
path <- system.file("extdata/",
package = "LightLogR")
file.sleep <- "205_sleepdiary_all_20230904.csv"

#import Data in the wide format (sleep/wake times)
import_Statechanges(file.sleep, path,
Datetime.format = "dmyHM",
State.colnames = c("sleep", "offset"),
State.encoding = c("sleep", "wake"),
Id.colname = record_id,
sep = ";",
dec = ",")

#import in the long format (Comments on sleep)
import_Statechanges(file.sleep, path,
                   Datetime.format = "dmyHM",
                   State.colnames = "comments",
                   Datetime.column = sleep,
                   Id.colname = record_id,
                   sep = ";",
                   dec = ",", structure = "long")