% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/scores_nt_fitbit.R
\name{add_sleep_flags}
\alias{add_sleep_flags}
\title{Append Sleep Episode Metadata to Epoch-Level Data}
\usage{
add_sleep_flags(data, blocks, main_duration)
}
\arguments{
\item{data}{tbl. Data frame with epoch-level sleep data that contains
\itemize{
\item \code{participant_id}: Participant identifier.
\item \code{dtt}: POSIXct epoch timestamp.
\item \code{is_slp}: Logical. Original sleep flag prior to block-based revision.
\item \code{hr_exc_night}: Logical. Indicates whether the epoch occurred on a
heart-rate-excluded night.
}}

\item{blocks}{tbl.  A \code{tbl} or \code{data.frame} of sleep block ranges,
typically the output of \code{create_block_ranges()}. Must contain
\code{participant_id}, \code{block_start}, \code{block_end}, \code{main_block}, and
\code{duration_min}.}

\item{main_duration}{Positive numeric. Minimum duration in minutes required
for a block to be considered main sleep. Blocks shorter than this threshold
will not be classified as main sleep even if main block contains main sleep.}
}
\value{
The input \code{data} with all columns from \code{blocks} appended via
temporal overlap join, plus two derived columns:
\itemize{
\item \code{is_slp}: Revised sleep flag, overwriting the original. \code{TRUE} if the
epoch falls within a detected sleep block or was originally flagged as
sleep on a heart-rate-excluded night.
\item \code{main_slp}: \code{TRUE} if the epoch's block has \code{main_block == TRUE} and
\code{duration_min >= main_duration}. \code{FALSE} otherwise, including unmatched
epochs.
}
}
\description{
Joins sleep block metadata onto epoch-level data via a temporal overlap join,
then derives two flags: a revised \code{is_slp} indicator and a \code{main_slp}
indicator. Epochs are considered sleep if they fall within a detected sleep
block or were originally flagged as sleep during a heart-rate-excluded night.
}
\note{
\code{is_slp} and \code{main_slp} are present in \code{data} on entry but are both
overwritten. \code{is_slp} is revised using block membership and the
\code{hr_exc_night} flag; \code{main_slp} is recomputed entirely from the joined
block metadata. Neither original value is retained in the output.
}
\keyword{internal}
