Skip to contents

Create a Withings Sleep Analysis Object

Source: R/withings-sleep.R
withings_sleep.Rd

Constructs a withings_sleep object from Withings sleep data for analysis, reporting, and export. Can work with epoch data alone (for SRI calculation) or with both summary and epoch data (for full reporting).

Usage

withings_sleep(
  summary = NULL,
  epoch,
  id_cols = c("w_id", "sleep_id", "id"),
  tz_cols = c("w_timezone", "timezone")
)

Arguments

summary

Optional. A data frame or tibble containing sleep summary data with one row per sleep session. If NULL, only epoch-based analyses (like SRI) will be available. Expected columns include:

  • ID column: One of w_id, sleep_id, or id to match with epoch data

  • Timezone: One of w_timezone or timezone (e.g., "America/New_York", "UTC")

  • Sleep metrics (optional): w_total_sleep_time, w_sleep_efficiency, w_sleep_latency, w_waso, w_apnea_hypopnea_index, w_snoring

  • Timestamps: w_startdate_utc, w_enddate_utc as POSIXct

epoch

A data frame or tibble containing minute-by-minute sleep epoch data. Required columns:

  • timestamp: Unix timestamp (seconds since 1970-01-01 00:00:00 UTC)

  • state: Sleep state code (0 = awake, 1 = light sleep, 2 = deep sleep, 3 = REM)

  • ID column: One of w_id, sleep_id, or id to match with summary

Optional columns for enhanced analysis:

  • hr: Heart rate (beats per minute)

  • rr: Respiratory rate (breaths per minute)

  • snoring: Snoring intensity

  • mvt_score: Movement score (used as acceleration proxy for GGIR)

id_cols

Character vector of candidate ID column names to try for matching summary and epoch data. Default: c("w_id", "sleep_id", "id")

tz_cols

Character vector of candidate timezone column names in summary data. Default: c("w_timezone", "timezone")

Value

An S3 object of class withings_sleep with components:

summary

Processed summary data (NULL if not provided)

epoch

Processed epoch data with added datetime columns

$report()

Method to generate HTML/PDF report (requires summary data)

$reformat()

Method to export data in various formats (e.g., GGIR)

$sri()

Method to calculate Sleep Regularity Index from epoch data

Details

The function is flexible and can handle different input scenarios:

Epoch-only mode (summary = NULL):

  • Only $sri() and $reformat() methods will work

  • Useful when you only have raw epoch data and want to calculate sleep regularity

  • $report() will fail with an informative error

Full mode (both summary and epoch):

  • All methods available including interactive HTML reports

  • Data are automatically combined and aligned by ID

  • Datetime columns added to epoch data for plotting

See also

withings_sleep_report for summary statistics, reformat.withings_sleep for data export, withings_sleep_report_render for HTML/PDF report generation

Examples

if (FALSE) { # \dontrun{
# Load data from CSV files
summary <- read.csv("withings_summary.csv")
epoch <- read.csv("withings_epoch.csv")

# Full analysis with both summary and epoch
wsleep <- withings_sleep(summary, epoch)
wsleep$report(output = "html", file = "sleep_report.html")
wsleep$sri()

# Epoch-only analysis (e.g., for SRI calculation)
wsleep_minimal <- withings_sleep(summary = NULL, epoch = epoch)
sri_result <- wsleep_minimal$sri()
cat(sri_result$report)

# Export to GGIR format for external analysis
ggir_data <- wsleep$reformat(type = "ggir")
write.csv(ggir_data, "sleep_for_ggir.csv", row.names = FALSE)
} # }