-
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathREADME.qmd
More file actions
330 lines (242 loc) · 9.9 KB
/
README.qmd
File metadata and controls
330 lines (242 loc) · 9.9 KB
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
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
# actverse <a href = "https://danielvartan.github.io/brandr/"><img src = "man/figures/logo.svg" align="right" width="120" /></a>
<!-- quarto render -->
```{r}
#| label: setup
#| include: false
library(actverse)
library(badger)
library(dplyr)
library(here)
library(rutils) # github.com/danielvartan/rutils
source(here("R", ".setup.R"))
```
<!-- badges: start -->
```{r}
#| echo: false
#| output: asis
cat(
badge_repostatus("active"),
badge_github_actions(action = "R-CMD-check.yaml"),
badge_codecov() |> shush(),
badge_license(
license = "GPLv3",
color = "bd0000",
url = "https://www.gnu.org/licenses/gpl-3.0"
),
badge_custom(
x = "Contributor%20Covenant",
y = "3.0",
color = "4baaaa",
url = "https://www.contributor-covenant.org/version/3/0/code_of_conduct/",
alt = "Contributor Covenant 3.0 Code of Conduct"
)
)
```
<!-- badges: end -->
## Overview
`actverse` is an R package that offers a comprehensive toolkit for processing, analyzing, and visualizing [actigraphy](https://en.wikipedia.org/wiki/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](https://tidyverse.tidyverse.org/articles/manifesto.html) and integrates seamlessly with the [tidyverse ecosystem](https://www.tidyverse.org/), ensuring a consistent and user-friendly experience for data manipulation and analysis.
> If you find this project useful, please consider giving it a star! [](https://github.com/danielvartan/actverse/)
> 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. [](https://github.com/sponsors/danielvartan)
## Installation
You can install `actverse` using the [`remotes`](https://github.com/r-lib/remotes) package:
```r
# install.packages("remotes")
remotes::install_github("danielvartan/actverse")
```
## Usage
The R ecosystem offers a [wide variety](https://cran.r-project.org/view=TimeSeries) 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](https://youtu.be/eelVqfm8vVc) and may be based on different numerical systems. For packages that follow [tidyverse principles](https://tidyverse.tidyverse.org/articles/manifesto.html), we believe the [`tsibble`](https://tsibble.tidyverts.org/index.html) package provides the best time series standard. As its name suggests, `tsibble` extends the [tidyverse](https://www.tidyverse.org/) [`tibble`](https://tibble.tidyverse.org/) object for time series data.
Most `actverse` functions require your data to be in the [`tsibble`](https://tsibble.tidyverts.org/index.html) format. Converting your data is straightforward and can significantly improve your experience working with time series in R. Please refer to the [`tsibble`](https://tsibble.tidyverts.org/index.html) documentation for guidance on adapting your data.
```{r}
library(actverse)
```
### Read/Write
- [`read_acttrust()`](https://danielvartan.github.io/actverse/reference/read_acttrust.html): Read, tidy, and validate an [ActTrust](https://condorinst.com/en/) file.
- [`write_acttrust()`](https://danielvartan.github.io/actverse/reference/write_acttrust.html): Write a `tsibble` to a readable [ActTrust](https://condorinst.com/en/) file.
Example:
```{r}
#| message: false
#| warning: false
file <- get_from_zenodo(
doi = "10.5281/zenodo.4898822",
dir = tempdir(),
file = "processed.txt"
)
```
```{r}
#| message: false
#| warning: false
data <- file |> read_acttrust(tz = "America/Sao_Paulo")
```
```{r}
#| message: false
#| warning: false
library(dplyr)
data |> glimpse()
```
### Sleep Statistics
- [`sri()`](https://danielvartan.github.io/actverse/reference/sri.html): Compute Phillips et al. Sleep Regularity Index ([SRI](https://doi.org/10.1038/s41598-017-03171-4)).
- [`state_prop()`](https://danielvartan.github.io/actverse/reference/state_prop.html): 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.
```{r}
#| message: false
#| warning: false
sri_data <- data |> sri()
sri_data
```
```{r}
library(rutils) # github.com/danielvartan/rutils
sri_data |>
stats_summary("sri") |>
print(n = Inf)
```
```{r}
#| label: readme-sri
#| message: false
#| warning: false
#| fig-width: 9
#| fig-height: 6.75
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()`](https://danielvartan.github.io/actverse/reference/periodogram.html): Compute Sokolove & Bushell's $\chi^{2}$ periodogram.
- [`spectrogram()`](https://danielvartan.github.io/actverse/reference/spectrogram.html): Create a spectrogram plot based on Sokolove & Bushell's $\chi^{2}$ periodogram.
Example:
```{r}
#| label: readme-periodogram
#| message: false
#| warning: false
#| fig-width: 9
#| fig-height: 6.75
data |> periodogram("pim")
```
```{r}
#| label: readme-spectrogram
#| message: false
#| warning: false
#| fig-width: 9
#| fig-height: 6.75
data |> spectrogram("pim")
```
### Data Visualization
We strongly recommend using the [`ragg`](https://ragg.r-lib.org/) package as your backend graphics device for complex data visualizations. It is faster and produces higher quality images than R default graphics device.
- [`actogram()`](https://danielvartan.github.io/actverse/reference/actogram.html): Create an actogram plot from actigraphy data.
```{r}
#| label: readme-actogram
#| message: false
#| warning: false
#| fig-width: 10
#| fig-height: 10
data |>
actogram(
col = "pim",
days = 18,
latitude = -23.55065,
longitude = -46.63338
)
```
### Data Interpolation
- [`na_approx()`](https://danielvartan.github.io/actverse/reference/na_approx.html) `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:
```{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)
```
```{r}
#| label: readme-na-approx
#| message: false
#| warning: false
#| fig-width: 9
#| fig-height: 6.75
na_plot(x, index, na_approx(x, index, fill_na_tips = TRUE))
```
### API Clients
* [`get_from_zenodo()`](https://danielvartan.github.io/actverse/reference/get_from_zenodo.html): Get data from a Zenodo record.
* [`get_sun_stats()`](https://danielvartan.github.io/actverse/reference/get_sun_stats.html): Get sun related statistics from different APIs.
Example:
```{r}
#| message: false
#| warning: false
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)
```
### Other Features
`actverse` also comes with many utility functions and provides actigraphy datasets for testing and learning purposes.
All functions are thoroughly documented, with detailed explanations of the underlying methodologies and computational guidelines. For a complete list of available functions and their documentation, click [here](https://danielvartan.github.io/actverse/).
Example:
```{r}
#| message: false
#| warning: false
file |>
read_acttrust(regularize = FALSE) |>
find_epoch()
```
## How to Cite
```{r}
citation("actverse")
```
## License
```{r}
#| echo: false
#| output: asis
cat(
badge_license(
license = "GPLv3",
color = "bd0000",
url = "https://www.gnu.org/licenses/gpl-3.0"
)
)
```
```text
Copyright (C) 2025 Daniel Vartanian
actverse is free software: you can redistribute it and/or modify it under the
terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with
this program. If not, see <https://www.gnu.org/licenses/>.
```
## Contributing
```{r}
#| echo: false
#| output: asis
cat(
badge_custom(
x = "Contributor%20Covenant",
y = "3.0",
color = "4baaaa",
url = "https://www.contributor-covenant.org/version/3/0/code_of_conduct/",
alt = "Contributor Covenant 3.0 Code of Conduct"
)
)
```
Contributions are always welcome! Whether you want to report bugs, suggest new features, or help improve the code or documentation, your input makes a difference. Before opening a new issue, please take a moment to review our [Guidelines for Contributing](https://danielvartan.github.io/actverse/CONTRIBUTING.html) and check the [issues tab](https://github.com/danielvartan/actverse/issues) to see if your topic has already been reported.
[](https://github.com/sponsors/danielvartan)
You can also support the development of `actverse` by becoming a sponsor. Click [here](https://github.com/sponsors/danielvartan) to make a donation. Please mention `actverse` in your donation message.