% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/scores_nt_fitbit.R
\name{compute_fitbit_sleep_table}
\alias{compute_fitbit_sleep_table}
\title{Compute daily sleep summaries}
\usage{
compute_fitbit_sleep_table(
  data_activity,
  data_sleep_combined,
  data_daily,
  hr_low = 50,
  hr_high = NULL,
  hr_rep_day = 10,
  hr_rep_sleep = 30,
  bin_minutes = NULL,
  offset = "12:00",
  min_slp_minutes = 300
)
}
\arguments{
\item{data_activity}{tbl. Data frame with the following columns with
minute-level epoch data with the following columns:
\itemize{
\item \code{participant_id}: Participant identifier
\item \code{session_id}: Session identifier
\item \code{dtt}: POSIXct epoch timestamp
\item \code{dtt} POSIXct epoch timestamp.
}}

\item{data_sleep_combined}{tbl. Data frame with the following columns in
30-second epoch level with the following columns:
\itemize{
\item \code{participant_id}: Participant identifier
\item \code{session_id}: Session identifier
\item \code{dtt}: POSIXct epoch timestamp
\item \code{stage}: Sleep stage classification (e.g., \code{"light"},  \code{"deep"}, \code{"rem"},
\code{"awake"}).
\item \code{main_slp}: logical. Indicates if epoch is associated with 'main' sleep.
}}

\item{data_daily}{tbl. Daily-level Fitbit-generated summary data containing:
\itemize{
\item \code{participant_id}: Participant identifier
\item \code{session_id}: Session identifier
\item \code{dt}: Calendar date
\item \code{hrate_rest_fitb}: Fitbit-reported resting heart rate in beats per
minute.
}}

\item{hr_low}{numeric. Lower bound threshold for valid heart rate values.}

\item{hr_high}{numeric or NULL. Optional upper bound threshold for valid
heart rate values. If NULL, no upper threshold is applied.}

\item{hr_rep_day}{numeric. Threshold (number of epochs) for identifying
repeated heart rate values during wake/activity periods.}

\item{hr_rep_sleep}{numeric. Threshold (number of epochs) for identifying
repeated heart rate values during sleep periods.}

\item{bin_minutes}{numeric. Number of minutes used to bin activity data when
computing intensity scores (e.g., 1440 for daily aggregation). Default is
NULL. When NULL, it uses \code{offset} to split days, which by default is
\code{12:00} (noon).}

\item{offset}{character. Time of day (HH:MM) used as the cutoff for defining
the sleep day. Timestamps occuring after this time are assigned to the next
day.}

\item{min_slp_minutes}{numeric. Minimum number of sleep minutes required
for a day to pass quality control. Used to create a \code{qc_Xmin} flag
column in the output.}
}
\value{
tbl.  A daily-level summarized data frame with the following
components:

\strong{Identifiers and time variables:}
\itemize{
\item \code{participant_id}, \code{session_id}
\item \code{wk}: Study week index
\item \code{day}: Study day index
\item \code{dt}: Calendar date
\item \code{dt_day}: Day of week (labeled)
\item \code{dt_wknd}: Indicator for weekend days
}

\strong{Sleep timing measures:}
\itemize{
\item \code{dtt_start_bed}, \code{dtt_end_bed}: Bed interval start and end times
\item \code{dtt_start_slp}, \code{dtt_end_slp}: Sleep interval start and end times
}

\strong{Sleep duration measures:}
\itemize{
\item \code{min_total_slp}: Total sleep duration
\item \code{min_asleep_slp}, \code{min_restless_slp}, \code{min_light_slp},
\code{min_deep_slp}, \code{min_rem_slp}: Stage-specific sleep durations
\item \code{min_nap_slp}: Nap sleep duration
\item \code{min_wake}: Wake minutes during sleep intervals
\item \code{min_waso}: Wake after sleep onset (WASO)
\item \code{n_waso}: Number of WASO episodes
}

\strong{Heart rate summaries by sleep stage:}
\itemize{
\item \code{hrate_awake_slp}, \code{hrate_restless_slp}, \code{hrate_asleep_slp}
\item \code{hrate_light_slp}, \code{hrate_deep_slp}, \code{hrate_rem_slp}
\item \code{hrate_nap_slp}: Mean heart rate during nap sleep
\item \code{hrate_rest_fitb}: Daily resting heart rate from Fitbit
}

\strong{Heart rate exclusion measures:}
\itemize{
\item \code{excl_min_total_slp}: Total excluded sleep minutes
\item \code{excl_min_lowhrate_slp}: Minutes excluded due to low heart rate
\item \code{excl_min_nohrate_slp}: Minutes excluded due to missing heart rate
\item \code{excl_min_highhrate_slp}: Minutes excluded due to high heart rate
\item \code{excl_min_repeathrate_slp}: Minutes excluded due to repeated heart rate
\item \code{min_extra_nohrate_slp}: Additional plausible sleep minutes excluded
}

\strong{Quality control and flags:}
\itemize{
\item \code{qc_300min}: Indicator for >= 300 minutes of valid sleep
\item \code{flg_slp}: Indicator for implausible sleep structure
\item \code{flg_any}: Indicator that any sleep data are present
}
}
\description{
Processes Fitbit minute-level data to generate daily sleep summary
scores. This function integrates multiple processing steps, including heart
rate-based exclusions and calculation of sleep measures, aggregated
at the day level.
}
\note{
\code{flg_slp}, sleep timing and WASO variables are only calculated when
\code{bin_minutes} is NULL. Calculations depend on offset dates and cannot operate
on binned intervals. Returns an empty columns otherwise.
\itemize{
\item \code{data_activity}: fitbit_raw_activity or fitbit_covid_raw_activity
\item \code{data_sleep_combined}: fitbit_raw_sleep or fitbit_covid_raw_sleep
\item \code{data_daily}: fitbit_raw_metrics or fitbit_covid_raw_metrics
}
}
