Split and Annotate Actigraphy Data into Daily Records

`Act2Daily` is used to split the actigraphy recording by the recording dates stored in Bdf (a BriefSum object).

Usage

Act2Daily(
  df,
  Bdf,
  TUnit = "hour",
  VAct = NULL,
  VTm = NULL,
  Incomplete = FALSE,
  Travel = TRUE
)

Arguments

df: A data.frame of raw actigraphy recording. Both time and activity count should be included in the df. See VAct and VTm for further detail.
Bdf: A BriefSum object containing per-day metadata for the recording. Note, if jet lag occurred during the recording, please, update the metadata using TAdjust before passing to this function.
TUnit: Character; time–unit for the x–axis of each day's timeline. Must be one of "day", "hour", "minute" or "second". Default is "hour".
VAct: Optional character. Name of the activity column in df. If NULL, defaults to the second column of df.
VTm: Optional character. Name of the date.time index column in df.If NULL, defaults to the first column of df.
Incomplete: Logical; if TRUE, days flagged `Incomplete Recording` (i.e. <24 h) are retained in the data list with recordings segmented by day. Default = FALSE (these days are removed).
Travel: Logical; if TRUE, days flagged `Travel` are retained although some data points from an earlier adjacent calendar day may be duplicated (a warning is issued). If FALSE, travel days and the day before/after are excluded. Default = TRUE.

Value

A data list that includes the adjusted recordings both in long format and as a nested list by day.

Details

Transforms a continuous actigraphy time-series into a day-by-day list of aligned epoch and produces a fully annotated data frame. Based on the summary table generated by either BriefSum or TAdjust, it re-organize and segment the raw recording data by each day. The function is designed to process incomplete recordings while accounting for travel and daylight-saving adjustments. All labels contained in the summary table (i.e., Bdf) will be assigned to the corresponding data points. This workflow ensures that each day's recording is bounded by its calendar date while accounts for travel–induced overlaps, and clearly documents any incomplete or unallocated points.

Note

When you cross into a time zone with a larger UTC offset (e.g., Montreal \(UTC-5\) to Taipei \(UTC+8\)), it will generate a small overlap of epochs between the day before travel and the day labeled "Travel Day" in the "Daily_df". Conversely,when you move into a time zone with a smaller UTC offset, a brief gap appears on "Travel Day", with labeling - "Unallocated", which represents "time lose".

Examples

if (FALSE) { # \dontrun{

# Import data
data (FlyEast)


# Create quick summary of the recording with adjustment for daylight saving.
BdfList <-
    BriefSum (
        df = FlyEast,
        SR = 1 / 60,
        Start = "2017-10-24 13:45:00"
    )


# Lets extract the quick summary of the recording
Bdf <- BdfList$Bdf

### Note that since the original data was affected by travel-induced time
### shift, the recordings would not be properly segmented from 2017-11-02.

## To avoid time shift due to travelling, we will keep only the first 8 days.
Bdf <- Bdf [1:8, ]
df <- BdfList$df

# Segment Data by Day
dfList <-
    Act2Daily (
        df = df,
        Bdf = Bdf,
        VAct = "Activity",
        VTm = "Time",
        Incomplete = TRUE,
        Travel = TRUE
    )

str (dfList) ### Look at the output structure
View (dfList)
} # }