In gipso/actverse: Tools for Actigraphy Data Analysis

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)

library(actverse)
library(dplyr)
library(lubridate)
library(hms)

actverse

Overview

actverse is an R package that provides a complete toolkit to process, analyze and visualize actigraphy data. Its aim is to facilitate the work of sleep and chronobiology scientists with actigraphy data and to improve reproducibility in research.

actverse adheres to the tidyverse principles and integrates with the tidyverse ecosystem.

Prerequisites

You need to have some familiarity with the R programming language and with the tsibble package to use actverse main functions.

If you don't feel comfortable with R, we strongly recommend checking Hadley Wickham and Garrett Grolemund's free and online book R for Data Science and the Coursera course from John Hopkins University Data Science: Foundations using R (free for audit students).

Please refer to the tsibble package documentation to learn more about it. tsibble is an essential package to deal with time series in R. We also recommend that you read the Dates and times chapter from Wickham & Grolemund's book R for Data Science and the tsibble objects subchapter from Rob J. Hyndman & George Athanasopoulos' book Forecasting: Principles and Practice.

Installation

You can install actverse with:

``` {r, eval = FALSE}

install.packages("remotes")

remotes::install_github("giperbio/actverse")

## Usage

The R ecosystem has a [vast number](https://cran.r-project.org/view=TimeSeries) of time series standards and we had to choose one of them while developing `actverse`. A standard for time objects is a must, because [time can have many representations](https://youtu.be/eelVqfm8vVc) and can be rooted in  different numerical systems. We believe that the best time series standard available for packages that adheres to the [tidyverse principles](https://tidyverse.tidyverse.org/articles/manifesto.html) is the [`tsibble`](https://tsibble.tidyverts.org/index.html). As the name suggests, `tsibble` is an adaptation for time series of the [tidyverse](https://www.tidyverse.org/) [`tibble`](https://tibble.tidyverse.org/) object.

Most `actverse` functions will require that your data be in the [`tsibble`](https://tsibble.tidyverts.org/index.html) standard. Adapting your data is a simple process and can make a big difference when dealing with time series in R. Please refer to [`tsibble`](https://tsibble.tidyverts.org/index.html) documentation to learn how to do this.

We also recommend seeing the [`tsbox`](https://www.tsbox.help/) package, an R
package that propose to be an "universal translator" (🖖) for R time series standards.

### Read/Write

* `read_acttrust()`: Read, tidy, and validate an [ActTrust](https://condorinst.com/en/acttrust-actigraph/) file.
* `write_acttrust()`: Adapt and write a `tsibble` to a readable [ActTrust](https://condorinst.com/en/acttrust-actigraph/) file.

Example:

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

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

data

Period functions

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

Example:

per <- periodogram(data, "pim")

spec <- spectrogram(data, "pim")

Data interpolation

• na_approx() na_locf() na_overall_mean() na_overall_median() na_overall_mode() na_spline() na_weekly_mean() na_zero() na_plot(): Replace NA by interpolation.

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)
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:

get_sun_stats(lat = -23.5489, lon = -46.6388, tz = "America/Sao_Paulo") %>%
    dplyr::as_tibble() %>% 
    t()

Other features

actverse also comes with many utility functions and provides free actigraphy datasets for testing and learning purposes.

All functions are properly documented, showing all the guidelines behind the computations. Click here to see a list of them.

Example:

# Find the epochs/periodicities in a 'tsibble'
read_acttrust(file, regularize = FALSE) %>%
    find_epoch()

Citation

If you use actverse in your research, please consider citing it. We put a lot of work to build and maintain a free and open-source R package. You can find the citation below.

citation("actverse")

Contributing

We welcome contributions, including bug reports.

Take a moment to review our Guidelines for Contributing.

Acknowledgments

The initial development of actverse was supported by three scholarships provided by the University of Sao Paulo (USP) (❤️).

Become an actverse supporter!

Click here to make a donation. Please indicate the actverse package in your donation message.

gipso/actverse documentation built on Sept. 29, 2023, 10:46 a.m.