Author: Shanshan Chen
Date: 2025-11-08

# CircaCP: Getting Started

#### Shanshan Chen

#### 2025-11-08

    #Load required packages
    library(CircaCP)
    library(ggplot2)

## Read in the example actigraphy data, specify column names for Date, Time and Activity

    csv <- system.file("extdata", "NHANES_11111.csv", package = "CircaCP")

    df <- import_acti_file(csv, "Date", "Time", "MIMS")

    head(df)
    #> # A tibble: 6 × 4
    #>   id           Date   Time     Activity
    #>   <chr>        <chr>  <chr>       <dbl>
    #> 1 NHANES_11111 9/1/13 21:30:00     6.08
    #> 2 NHANES_11111 9/1/13 21:31:00    17.5
    #> 3 NHANES_11111 9/1/13 21:32:00     8.12
    #> 4 NHANES_11111 9/1/13 21:33:00    11.4
    #> 5 NHANES_11111 9/1/13 21:34:00    12.1
    #> 6 NHANES_11111 9/1/13 21:35:00    27.8

## screening actigraphy data to check minumum wearing days and continuous wearing

    screen_fun <- if (exists("screen_wear", mode = "function")) {
      screen_wear
    } else {
      stop("No screening function (screen_wear*) found in CircaCP.")
    }

    out <- screen_fun(
      df,
      min_days     = 5,
      max_zero_run = 200
    )

    out$status
    #> [1] "ok"

## apply consinor fitting

    stopifnot(exists("sleep_cos", mode = "function"))
    clean_df = out$clean_df
    cos_df <- sleep_cos(clean_df, thr = 0.4)
    cos_df$cos_para
    #> [1]  14.47712 -12.47072 360.83514
    cos_df$RMSE
    #> [1] 15.25192

## apply circacp algorithm

    stopifnot(exists("sleep_detection", mode = "function"))
    clean_df = out$clean_df
    newdf <- sleep_detection(clean_df, thr = 0.4, dist = "ZAG")
    head(newdf)
    #>             id   Date     Time Activity label.cos label.sw   cosinor
    #> 1 NHANES_11111 9/1/13 21:30:00    6.075         1        1 0.4996403
    #> 2 NHANES_11111 9/1/13 21:31:00   17.457         1        1 0.4974587
    #> 3 NHANES_11111 9/1/13 21:32:00    8.117         1        1 0.4952771
    #> 4 NHANES_11111 9/1/13 21:33:00   11.413         1        1 0.4930956
    #> 5 NHANES_11111 9/1/13 21:34:00   12.149         1        1 0.4909142
    #> 6 NHANES_11111 9/1/13 21:35:00   27.817         1        1 0.4887330
    #>   Activity_norm
    #> 1    0.03745492
    #> 2    0.10762970
    #> 3    0.05004470
    #> 4    0.07036592
    #> 5    0.07490367
    #> 6    0.17150344

# plot estimated cosinor fitting and circadian cycles

    ggplot2::ggplot(newdf, ggplot2::aes(x = seq_along(Activity))) +
        ggplot2::geom_line(ggplot2::aes(y = Activity_norm), alpha = 0.4) +
        ggplot2::geom_line(ggplot2::aes(y = cosinor/2), alpha = 0.4, color = "magenta") +
        ggplot2::geom_line(ggplot2::aes(y = label.cos), color = "blue") +
        ggplot2::labs(x = "Minute", y = "Activity", title = unique(newdf$id)) +
        ggplot2::scale_color_manual(
                name = NULL,
               values = c(
               "Activity (norm)" = "grey40",
               "Cosinor"     = "magenta",
                "Cosinor label"   = "blue"))+
      ggplot2::theme_bw(12)
    #> Warning: No shared levels found between `names(values)` of the manual scale and the
    #> data's colour values.

# plot estimated cosinor fitting and slee-wake cycles

    ggplot2::ggplot(newdf, ggplot2::aes(x = seq_along(Activity))) +
        ggplot2::geom_line(ggplot2::aes(y = Activity_norm), alpha = 0.4) +
        ggplot2::geom_line(ggplot2::aes(y = cosinor/2), alpha = 0.4, color = "magenta") +
        ggplot2::geom_line(ggplot2::aes(y = label.sw), color = "forestgreen") +
        ggplot2::labs(x = "Minute", y = "Activity", title = unique(newdf$id)) +
        ggplot2::scale_color_manual(
                name = NULL,
               values = c(
               "Activity (norm)" = "grey40",
               "Cosinor / 2"     = "magenta",
                "Cosinor label"   = "blue",
                "Sleep/Wake"      = "forestgreen"))+
      ggplot2::theme_bw(12)
    #> Warning: No shared levels found between `names(values)` of the manual scale and the
    #> data's colour values.

## Non-parametric metrics for circadian rhythsm

    np <- extract_nonparametric_metrics(newdf, L_window = 300, M_window=600)
    head(np)
    #> $L5_mean
    #> [1] 0.9231071
    #>
    #> $L5_start_min
    #> [1] 79
    #>
    #> $M10_mean
    #> [1] 24.64013
    #>
    #> $M10_start_min
    #> [1] 664
    #>
    #> $RA
    #> [1] 0.9277785
    #>
    #> $IS
    #> [1] 0.30567

## Extract all sleep and circadian rhythm related metrics

    if (exists("extract_sleep_metrics_df", mode = "function")) {
      metrics_df <- extract_sleep_metrics_df(newdf)
    } else if (exists("extract_sleep_metrics", mode = "function")) {
      metrics_df <- extract_sleep_metrics(newdf)  # may be a list
    } else {
      stop("No extract_sleep_metrics* function found.")
    }
    head(metrics_df)
    #>             id period_type       timestamp clock_min duration_hours       SRI
    #> 1 NHANES_11111       sleep 9/1/13 22:14:00      1334       8.300000 0.8856151
    #> 2 NHANES_11111       sleep 9/2/13 21:58:00      1318       8.333333 0.8856151
    #> 3 NHANES_11111       sleep 9/3/13 23:25:00      1405       7.350000 0.8856151
    #> 4 NHANES_11111       sleep 9/4/13 22:34:00      1354       8.583333 0.8856151
    #> 5 NHANES_11111       sleep 9/5/13 23:28:00      1408       9.866667 0.8856151
    #> 6 NHANES_11111       sleep  9/7/13 2:27:00       147       8.450000 0.8856151
    #>      Mesor Amplitude Acrophase_min DN_Ratio        RA      IS        IV
    #> 1 14.47712  12.47072      1080.835 185.4051 0.9277785 0.30567 0.4460329
    #> 2 14.47712  12.47072      1080.835 185.4051 0.9277785 0.30567 0.4460329
    #> 3 14.47712  12.47072      1080.835 185.4051 0.9277785 0.30567 0.4460329
    #> 4 14.47712  12.47072      1080.835 185.4051 0.9277785 0.30567 0.4460329
    #> 5 14.47712  12.47072      1080.835 185.4051 0.9277785 0.30567 0.4460329
    #> 6 14.47712  12.47072      1080.835 185.4051 0.9277785 0.30567 0.4460329
    #>     L5_mean L5_start_min M10_mean M10_start_min SleepTimeSD_hours
    #> 1 0.9231071           79 24.64013           664          1.330825
    #> 2 0.9231071           79 24.64013           664          1.330825
    #> 3 0.9231071           79 24.64013           664          1.330825
    #> 4 0.9231071           79 24.64013           664          1.330825
    #> 5 0.9231071           79 24.64013           664          1.330825
    #> 6 0.9231071           79 24.64013           664          1.330825
    #>   WakeTimeSD_hours
    #> 1         1.585032
    #> 2         1.585032
    #> 3         1.585032
    #> 4         1.585032
    #> 5         1.585032
    #> 6         1.585032