Package 'slumbR'

List available questionnaire instruments

Description

List available questionnaire instruments

Usage

available_instruments()

Value

A character vector of instrument IDs supported by score_questionnaire().

---

Compute derived sleep variables from raw morning diary answers

Description

Given a morning-entry data frame row (as produced internally by read_export()), returns additional computed columns:

Usage

compute_sleep_vars(df)

Arguments

df	A data frame with morning-entry columns (output of diary_long()).

Details

Variable	Definition
tib_min	Time in bed (rise_time − bed_time), minutes
tst_min	Total sleep time (TIB − SOL − WASO), minutes
se_pct	Sleep efficiency (TST / TIB × 100), %
sol_flag	TRUE if SOL > 30 min (clinically significant)
se_flag	TRUE if SE < 85% (below healthy threshold)
waso_flag	TRUE if WASO > 30 min (clinically significant)
tst_flag	TRUE if TST < 7 h (below recommended)

Clock-time fields (bed_time, rise_time) are decimal hours. Overnight wrap is handled by adding 24 when rise_time ≤ bed_time.

Value

The same data frame with additional computed columns appended.

---

Extract the long-format diary data frame from a study or export

Description

A convenience accessor that returns the diary data frame from a slumbr_study or slumbr_export object. For a plain data frame it is returned unchanged.

Usage

diary_long(x)

## S3 method for class 'slumbr_study'
diary_long(x)

## S3 method for class 'slumbr_export'
diary_long(x)

## S3 method for class 'data.frame'
diary_long(x)

Arguments

x	A slumbr_study, slumbr_export, or plain data frame.

Details

The long-format frame has one row per diary entry (morning or evening). Morning rows carry sleep timing and quality variables; evening rows carry daytime behaviour variables. Most analyses will want diary_wide() to merge them into one row per night.

Value

A data frame with one row per diary entry.

---

Pivot diary entries to wide format — one row per participant per night

Description

Merges matching morning and evening entries for the same participant and date into a single row, prefixing morning columns with m_ and evening columns with e_.

Usage

diary_wide(x)

Arguments

x	A slumbr_study, slumbr_export, or plain long-format data frame.

Value

A data frame with one row per participant x date.

See Also

diary_long(), read_study()

Examples

## Not run: 
study <- read_study("exports/")
wide  <- diary_wide(study)
head(wide)

## End(Not run)

---

Read a single Sleep Diaries JSON export

Description

Parses one participant's JSON export file as produced by the Sleep Diaries app and returns a structured list with raw entries, parsed diary data, and questionnaire results.

Usage

read_export(path, participant_id = NULL, compute_vars = TRUE)

Arguments

path	Path to a .json file exported from the Sleep Diaries app.
participant_id	Optional character string used as the participant_id column value. If NULL (default), uses the researchCode field from the JSON, falling back to the participant name field, then to the filename.
compute_vars	Logical. If TRUE (default), adds derived sleep variables (TIB, TST, SE, flags) to morning entries via compute_sleep_vars().

Value

A named list with class "slumbr_export":

participant_id

Character. The resolved participant identifier.

participant_name

Character. Raw name from JSON.

research_code

Character or NA. Research code from JSON.

exported_at

POSIXct. Export timestamp.

diary

Data frame. One row per diary entry (morning or evening), with all parsed answer columns.

questionnaires

Data frame. One row per completed questionnaire, with raw answers in a list-column and computed scores.

raw

List. The full parsed JSON, for debugging.

See Also

read_study(), diary_long(), diary_wide()

Examples

## Not run: 
p <- read_export("exports/P001.json")
p$diary
p$questionnaires

## End(Not run)

---

Read a directory of Sleep Diaries JSON exports into a study object

Description

Reads all .json files in a directory (one per participant) and assembles them into a slumbr_study object containing combined long and wide data frames plus questionnaire scores.

Usage

read_study(
  dir,
  pattern = "\\.json$",
  participant_id_from = c("code", "name", "filename"),
  compute_vars = TRUE,
  verbose = TRUE
)

Arguments

dir	Path to a directory containing .json export files.
pattern	Regex pattern to match filenames. Default "\\.json$".
participant_id_from	One of "code" (use researchCode field, fallback to name then filename), "name" (use the participant name field), or "filename" (always use the filename without extension).
compute_vars	Logical. Passed to read_export().
verbose	Logical. Print a progress summary. Default TRUE.

Value

A named list with class "slumbr_study":

diary

Long-format data frame. All participants, all entries.

wide

Wide-format data frame. One row per participant-night, morning and evening columns merged side by side.

scores

Data frame. Questionnaire scores, one row per participant × instrument.

participants

Character vector of resolved participant IDs.

exports

Named list of individual slumbr_export objects.

See Also

read_export(), diary_long(), diary_wide()

Examples

## Not run: 
study <- read_study("exports/")
study$diary
study$wide
study$scores

## End(Not run)

---

Re-score all questionnaires in a study or export

Description

Takes the questionnaire data frame (as returned in ⁠$questionnaires⁠ from read_export() or read_study()) and adds re-computed score_r and label_r columns using the R scoring functions. Useful for validation or when raw answers were imported without scores.

Usage

score_all_questionnaires(x)

Arguments

x	A slumbr_study, slumbr_export, or a data frame with columns questionnaire and answers (list-column).

Value

The questionnaire data frame with two additional columns: score_r (re-computed score) and label_r (interpretation label).

Examples

## Not run: 
study <- read_study("exports/")
score_all_questionnaires(study)

## End(Not run)

---

Score a Sleep Diaries questionnaire from raw answers

Description

Re-scores any of the eight validated instruments included in the Sleep Diaries app. Scoring algorithms exactly match the app's JavaScript implementation.

Usage

score_questionnaire(instrument, answers)

Arguments

instrument	Character. One of "ess", "isi", "dbas16", "meq", "psqi", "rusated", "stopbang", "mctq".
answers	Named list of answers keyed by item ID (e.g. list(ess1 = 2, ess2 = 1, ...)). Clock-time items (PSQI, MCTQ) expect list(hour = H, minute = M) sub-lists, matching the JSON export format.

Value

A named list with at minimum:

score

Numeric. The computed total or mean score (for MCTQ: a list with msf_sc and sjl).

label

Character. The clinical interpretation label.

reference

Character. Citation for the instrument.

PSQI additionally returns components (a named vector of the 7 component scores). MCTQ additionally returns msf_sc and sjl as top-level fields.

See Also

score_all_questionnaires()

Examples

# ESS
score_questionnaire("ess", answers = list(
  ess1 = 2, ess2 = 1, ess3 = 0, ess4 = 3,
  ess5 = 1, ess6 = 0, ess7 = 2, ess8 = 1
))

# MCTQ (free-day mid-sleep and social jetlag)
score_questionnaire("mctq", answers = list(
  mctq_wd   = 5,
  mctq_bt_w = list(hour = 23, minute = 0),
  mctq_sl_w = 15,
  mctq_wt_w = list(hour = 7,  minute = 0),
  mctq_bt_f = list(hour = 0,  minute = 30),
  mctq_sl_f = 20,
  mctq_wt_f = list(hour = 9,  minute = 0)
))

---

Summarise a study's diary data at the participant level

Description

Summarise a study's diary data at the participant level

Usage

study_summary(x, na.rm = TRUE)

Arguments

x	A slumbr_study, slumbr_export, or long-format data frame.
na.rm	Logical. Remove NAs before computing means. Default TRUE.

Value

A data frame with one row per participant and columns: participant_id, n_morning, n_evening, n_nights, mean_tst_h, mean_se_pct, mean_sol_min, mean_waso_min, mean_quality, mean_restedness, pct_early_waking.

Examples

## Not run: 
study <- read_study("exports/")
study_summary(study)

## End(Not run)

---