-
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
158 lines (103 loc) · 6.93 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
library(actverse)
library(dplyr)
library(lubridate)
library(hms)
```
# actverse
<!-- badges: start -->
[](https://www.repostatus.org/#wip)
[](https://lifecycle.r-lib.org/articles/stages.html)
[](https://github.com/giperbio/actverse/actions)
[](https://app.codecov.io/gh/giperbio/actverse?branch=main)
[](https://choosealicense.com/licenses/mit/)
[](https://giperbio.github.io/actverse/CODE_OF_CONDUCT.html)
<!-- badges: end -->
## 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](https://tidyverse.tidyverse.org/articles/manifesto.html) and integrates with the [tidyverse ecosystem](https://www.tidyverse.org/).
## Prerequisites
You need to have some familiarity with the [R programming language](https://www.r-project.org/) and with the [`tsibble`](https://tsibble.tidyverts.org/index.html) 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](https://r4ds.had.co.nz/) and the Coursera course from John Hopkins University [Data Science: Foundations using R](https://www.coursera.org/specializations/data-science-foundations-r) (free for audit students).
Please refer to the [`tsibble`](https://tsibble.tidyverts.org/index.html) 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](https://r4ds.had.co.nz/dates-and-times.html) chapter from Wickham & Grolemund's book [R for Data Science](https://r4ds.had.co.nz/) and the [tsibble objects](https://otexts.com/fpp3/tsibbles.html) subchapter from Rob J. Hyndman & George Athanasopoulos' book [Forecasting: Principles and Practice](https://otexts.com/fpp3/).
## 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 message = FALSE, warning = FALSE}
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:
```{r message = FALSE, warning = FALSE}
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:
```{r message = FALSE, warning = FALSE}
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:
```{r message = FALSE, warning = FALSE}
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](https://giperbio.github.io/actverse/) to see a list of them.
Example:
```{r message = FALSE, warning = FALSE}
# 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.
```{r}
citation("actverse")
```
## Contributing
We welcome contributions, including bug reports.
Take a moment to review our [Guidelines for Contributing](https://giperbio.github.io/actverse/CONTRIBUTING.html).
## Acknowledgments
The initial development of `actverse` was supported by three scholarships provided by the [University of Sao Paulo (USP)](http://usp.br/) (❤️).
<br>
Become an `actverse` supporter!
Click [here](https://github.com/sponsors/danielvartan) to make a donation. Please indicate the `actverse` package in your donation message.