% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/scores_nt_fitbit.R
\name{compute_fitbit_sleep_table_ext}
\alias{compute_fitbit_sleep_table_ext}
\title{Computes episode-based daily sleep summary measures.}
\usage{
compute_fitbit_sleep_table_ext(
  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,
  main_duration = 180,
  gap = 90
)
}
\arguments{
\item{data_activity}{tbl. Epoch-level activity data used to derive heart rate
exclusion flags.}

\item{data_sleep_combined}{tbl. 30-second sleep epoch data containing sleep
stage and timestamp information.}

\item{data_daily}{tbl. Daily Fitbit summary data including resting heart
rate.}

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

\item{hr_high}{numeric or NULL. Optional upper threshold for valid heart rate
values.}

\item{hr_rep_day}{numeric. Threshold (number of epochs) for repeated heart
rate detection in daytime activity.}

\item{hr_rep_sleep}{numeric. Threshold (number of epochs) for repeated heart
rate detection in sleep.}

\item{bin_minutes}{numeric. Number of minutes used to bin data.}

\item{offset}{character. Time-of-day cutoff used to define sleep-day
boundaries.}

\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.}

\item{main_duration}{numeric. Minumum duration in minutes for a sleep episode
to be qualify as a main sleep episode.}

\item{gap}{numeric. Maximum allowed gap (in minutes) between consecutive
sleep epochs before a new sleep episode is defined.}
}
\value{
tbl. A daily-level extended sleep summary table containing:

\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}: Sleep-aligned date
\item \code{dt_day}: Day of week
\item \code{dt_wknd}: Weekend indicator
}

\strong{Sleep timing and block structure:}
\itemize{
\item \code{dtt_start_bed}, \code{dtt_end_bed}
\item \code{dtt_start_slp}, \code{dtt_end_slp}
}

\strong{Sleep duration metrics:}
\itemize{
\item \code{min_total_slp}, \code{min_asleep_slp}, \code{min_restless_slp},
\code{min_light_slp}, \code{min_deep_slp}, \code{min_rem_slp}, \code{min_nap_slp}
\item \code{min_waso}, \code{min_wake}, \code{n_waso}
}

\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}, \code{hrate_rest_fitb}
}

\strong{Heart rate exclusion metrics:}
\itemize{
\item \code{excl_min_total_slp}, \code{excl_min_lowhrate_slp}
\item \code{excl_min_nohrate_slp}, \code{excl_min_highhrate_slp}
\item \code{excl_min_repeathrate_slp}, \code{min_extra_nohrate_slp}
}

\strong{Quality control flags:}
\itemize{
\item \code{qc_300min}: Indicator for >= 300 minutes of sleep
\item \code{flg_slp}: Flag for implausible sleep structure
\item \code{flg_any}: Indicator for any valid sleep data
}
}
\description{
This function extends the standard sleep pipeline by grouping 30-second sleep
epochs into continuous sleep blocks based on a configurable gap threshold,
and redefining main sleep periods based on block duration. Heart rate
exclusion logic is applied both prior to and after block construction to
ensure consistency across raw and reconstructed sleep structures.
}
\details{
This extended pipeline differs from the standard sleep table by introducing a
episode-based reconstruction step. Sleep epochs are grouped into continuous
episodes using a configurable gap threshold, and episode duration is used to
define main sleep.
}
\note{
\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
}
}
