actverse <a href = "https://danielvartan.github.io/brandr/"><img src = "man/figures/logo.svg" align="right" width="120" /></a>

<!-- quarto render --> <!-- badges: start -->

<!-- badges: end -->

Overview

actverse is an R package that offers a comprehensive toolkit for processing, analyzing, and visualizing actigraphy data. It is designed to support sleep and chronobiology researchers by streamlining workflows and enhancing reproducibility in actigraphy research.

The package is built on tidyverse principles and integrates seamlessly with the tidyverse ecosystem, ensuring a consistent and user-friendly experience for data manipulation and analysis.

If you find this project useful, please consider giving it a star!  

The continuous development of actverse depends on community support. If you find this project useful, and can afford to do so, please consider becoming a sponsor.  

Installation

You can install actverse using the remotes package:

# install.packages("remotes")
remotes::install_github("danielvartan/actverse")

Usage

The R ecosystem offers a wide variety of time series standards, and selecting the right one was an important decision in developing actverse. A consistent standard for time objects is essential, as time can be represented in many ways and may be based on different numerical systems. For packages that follow tidyverse principles, we believe the tsibble package provides the best time series standard. As its name suggests, tsibble extends the tidyverse tibble object for time series data.

Most actverse functions require your data to be in the tsibble format. Converting your data is straightforward and can significantly improve your experience working with time series in R. Please refer to the tsibble documentation for guidance on adapting your data.

library(actverse)

Read/Write

• read_acttrust(): Read, tidy, and validate an ActTrust file.
• write_acttrust(): Write a tsibble to a readable ActTrust file.

Example:

file <- get_from_zenodo(
  doi = "10.5281/zenodo.4898822",
  dir = tempdir(),
  file = "processed.txt"
)

data <- file |> read_acttrust(tz = "America/Sao_Paulo")

library(dplyr)

data |> glimpse()
#> Rows: 51,806
#> Columns: 17
#> $ timestamp            <dttm> 2021-04-24 04:14:00, 2021-04-24 04:15:00, 202…
#> $ pim                  <dbl> 7815, 2661, 3402, 4580, 2624, 3929, 5812, 3182…
#> $ tat                  <dbl> 608, 160, 243, 317, 255, 246, 369, 270, 373, 1…
#> $ zcm                  <dbl> 228, 64, 80, 125, 33, 105, 171, 54, 189, 64, 6…
#> $ orientation          <dbl> 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0…
#> $ wrist_temperature    <dbl> 26.87, 27.18, 27.68, 27.86, 28.04, 28.13, 28.2…
#> $ external_temperature <dbl> 24.62, 25.06, 25.50, 25.75, 25.94, 26.06, 26.3…
#> $ light                <dbl> 3.58, 5.23, 3.93, 4.14, 3.16, 3.63, 11.53, 2.4…
#> $ ambient_light        <dbl> 1.45, 2.12, 1.59, 1.68, 1.28, 1.47, 4.67, 0.97…
#> $ red_light            <dbl> 0.57, 0.86, 0.64, 0.67, 0.51, 0.56, 3.22, 0.37…
#> $ green_light          <dbl> 0.66, 0.95, 0.71, 0.75, 0.57, 0.68, 3.49, 0.44…
#> $ blue_light           <dbl> 0.24, 0.36, 0.26, 0.28, 0.21, 0.30, 1.48, 0.20…
#> $ ir_light             <dbl> 0.17, 0.25, 0.20, 0.20, 0.16, 0.18, 1.00, 0.13…
#> $ uva_light            <dbl> 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0…
#> $ uvb_light            <dbl> 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0…
#> $ event                <dbl> 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0…
#> $ state                <dbl> 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0…

Sleep Statistics

• sri(): Compute Phillips et al. Sleep Regularity Index (SRI).
• state_prop(): Compute the proportion of time spent in a specific state (e.g., Sleeping, Awake).

Example:

Compare the results with the actogram plot shown in the following sections.

sri_data <- data |> sri()

sri_data
#> # A tsibble: 1,440 x 6 [1m]
#>   time   state      previous_state agreement    sri valid_data
#>   <time> <list>     <list>         <list>     <dbl>      <dbl>
#> 1 00'00" <fct [36]> <fct [36]>     <lgl [36]>  77.1          1
#> 2 01'00" <fct [36]> <fct [36]>     <lgl [36]>  77.1          1
#> 3 02'00" <fct [36]> <fct [36]>     <lgl [36]>  77.1          1
#> 4 03'00" <fct [36]> <fct [36]>     <lgl [36]>  77.1          1
#> 5 04'00" <fct [36]> <fct [36]>     <lgl [36]>  77.1          1
#> 6 05'00" <fct [36]> <fct [36]>     <lgl [36]>  77.1          1
#> # ℹ 1,434 more rows

library(rutils) # github.com/danielvartan/rutils

sri_data |>
  stats_summary("sri") |>
  print(n = Inf)
#> # A tibble: 16 × 2
#>    name     value
#>    <chr>    <chr>
#>  1 class    numeric
#>  2 n        1440
#>  3 n_rm_na  1440
#>  4 n_na     0
#>  5 mean     68.0758848246661
#>  6 var      515.005730939369
#>  7 sd       22.6937377031499
#>  8 min      -2.85714285714286
#>  9 q_1      60
#> 10 median   71.4285714285714
#> 11 q_3      86.6666666666667
#> 12 max      94.2857142857143
#> 13 iqr      26.6666666666667
#> 14 range    97.1428571428571
#> 15 skewness -1.06521803030843
#> 16 kurtosis 3.64135525938626

library(ggplot2)
library(scales)

sri_data |>
  ggplot(ggplot2::aes(x = time, y = sri)) +
  geom_smooth(color = "#FC2913") +
  labs(
    x = "Time of Day (Hour)",
    y = "Sleep Regularity Index (SRI)"
  ) +
  scale_x_time(
    breaks = breaks_width("6 hours"),
    labels = label_time("%-H") # Use "%#H" for Windows
  ) +
  scale_y_continuous(limits = c(0, NA)) +
  actverse:::get_actverse_theme()

Period Functions

• periodogram(): Compute Sokolove & Bushell’s $\chi^{2}$ periodogram.
• spectrogram(): Create a spectrogram plot based on Sokolove & Bushell’s $\chi^{2}$ periodogram.

Example:

data |> periodogram("pim")

data |> spectrogram("pim")

Data Visualization

We strongly recommend using the ragg package as your backend graphics device for complex data visualizations. It is faster and produces higher quality images than R default graphics device.

• actogram(): Create an actogram plot from actigraphy data.

data |>
  actogram(
    col = "pim",
    days = 18,
    latitude = -23.55065,
    longitude = -46.63338
  )

Data Interpolation

• na_approx() na_locf() na_overall_mean() na_overall_median() na_overall_mode() na_spline() na_weekly_mean() na_zero() na_plot(): Interpolate missing values in a numeric vector.

Example:

x <- c(NA, 1, 5, 10, NA, 5, 10, 1, NA, 10, 1, 5, NA, NA)
index <- seq(as.Date("2020-01-01"), as.Date("2020-01-14"), by = "day")

na_approx(x, index, fill_na_tips = TRUE)
#>  [1]  1.0  1.0  5.0 10.0  7.5  5.0 10.0  1.0  5.5 10.0  1.0  5.0  5.0  5.0

na_plot(x, index, na_approx(x, index, fill_na_tips = TRUE))

API Clients

• get_from_zenodo(): Get data from a Zenodo record.
• get_sun_stats(): Get sun related statistics from different APIs.

Example:

library(rutils) # github.com/danielvartan/rutils

get_sun_stats(
  latitude = -23.5489,
  longitude = -46.6388,
  tz = "America/Sao_Paulo"
) |>
  list_as_tibble() |>
  print(n = Inf)
#> # A tibble: 18 × 2
#>    name              value
#>    <chr>             <chr>
#>  1 date              2025-11-25
#>  2 latitude          -23.5489
#>  3 longitude         -46.6388
#>