% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/scores_nt_fitbit.R
\name{summarize_sleep}
\alias{summarize_sleep}
\title{Computes weekly summary sleep metrics}
\usage{
summarize_sleep(data)
}
\arguments{
\item{data}{tbl. Sleep dataset containing at daily-level sleep summary
scores.}
}
\value{
tbl. A weekly aggregated dataset with the following summaries:

Time-based summaries:
\itemize{
\item \code{mean_t_start_bed}: Circular mean bed start time.
\item \code{mean_t_end_bed}: Circular mean bed end time.
\item \code{mean_t_start_slp}: Circular mean sleep onset time.
\item \code{mean_t_end_slp}: Circular mean sleep end time.
}

Total sleep metrics:
\itemize{
\item \code{sum_min_total_slp}, \code{sum_min_asleep_slp}, \code{sum_min_restless_slp},
\code{sum_min_light_slp}, \code{sum_min_deep_slp}, \code{sum_min_rem_slp},
\code{sum_min_nap_slp}, \code{sum_min_wake_slp}, \code{sum_min_waso}
}

Mean sleep metrics:
\itemize{
\item \code{mean_min_slp_total}, \code{mean_min_asleep_slp}, \code{mean_min_restless},
\code{mean_min_slp_light}, \code{mean_min_slp_deep}, \code{mean_min_slp_rem},
\code{mean_min_wake}, \code{mean_min_waso}
}

Heart rate–weighted metrics:
\itemize{
\item \code{hrate_awake_slp}: Mean HR during awake periods (weighted by minutes awake)
\item \code{hrate_restless_slp}: Mean HR during restless sleep
\item \code{hrate_asleep_slp}: Mean HR during asleep periods
\item \code{hrate_light_slp}: Mean HR during light sleep
\item \code{hrate_deep_slp}: Mean HR during deep sleep
\item \code{hrate_rem_slp}: Mean HR during REM sleep
}

Wake fragmentation:
\itemize{
\item \code{sum_n_waso}: Total number of wake-after-sleep-onset events
\item \code{mean_n_waso}: Mean number of WASO events per day
}
}
\description{
Computes weekly summary sleep metrics at the participant-session-week level.

Aggregates daily-level sleep measures into weekly summaries, including
totals, means, circular time averages, and heart rate metrics.
}
\details{
Heart rate–weighted metrics are computed using duration-weighted averages,
ensuring that longer stage durations contribute proportionally more to the
final estimate. All mean-based outputs are rounded to one decimal place.

Circular time variables are computed using circular statistics to correctly
handle times near midnight.
}
\keyword{internal}
