-
-
Notifications
You must be signed in to change notification settings - Fork 5
/
README.Rmd
303 lines (177 loc) · 14.4 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
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
---
output: github_document
---
[](https://github.com/mlampros/fitbitViz/actions)
[](https://codecov.io/github/mlampros/fitbitViz?branch=master)
[](http://cran.r-project.org/package=fitbitViz)
[](http://www.r-pkg.org/pkg/fitbitViz)
<a href="https://www.buymeacoffee.com/VY0x8snyh" target="_blank"><img src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png" alt="Buy Me A Coffee" height="21px" ></a>
[](https://hub.docker.com/r/mlampros/fitbitviz)
[](https://cran.r-project.org/package=fitbitViz)
## fitbitViz
<br>
The **fitbitViz** R package allows the extraction of data and the visualization of *‘ggplot2’*, *‘Leaflet’* and *3-dimensionsal ‘Rayshader’ Maps* using the [Fitbit Web API](https://dev.fitbit.com/build/reference/web-api/). If you own any of the **Fitbit activity trackers** you can take advantage of this package. A detailed explanation of the functionality can be found both in the Vignette and in the [blog post](http://mlampros.github.io/2021/05/20/fitbitViz_package/).
The 3-dimensional Rayshader Map requires the installation of the [CopernicusDEM](https://github.com/mlampros/CopernicusDEM) R package which includes the **30- and 90-meter elevation data**.
<br>
```{r setup, include = FALSE}
knitr::opts_chunk$set(fig.path = 'man/figures/',
out.width = "100%")
```
### Requirements:
<br>
To make use of this R package you have first to **register an Application** in <https://dev.fitbit.com/>. By registering an application you will receive the Fitbit **token** which besides your existing [user-id](https://community.fitbit.com/t5/Web-API-Development/Where-do-I-find-my-User-ID/m-p/1138667/highlight/true#M4375) is required so that you can take advantage of the **fitbitViz** functions.
There are many resources on the web on how to setup a Fitbit application. The [Fitbit web API documenation](https://dev.fitbit.com/build/reference/web-api/) includes more details. The next images and comments explain the whole process,
* Go to https://dev.fitbit.com/ and click on **Manage > Register an App**
**Login with your Fitbit credentials** and follow the prompts. I used as URL in the Registration Page **my Fitbit user-id** url, **`https://www.fitbit.com/user/USER_ID`**. You have to replace the **USER_ID** in the url with [your specific user-id](https://community.fitbit.com/t5/Web-API-Development/Where-do-I-find-my-User-ID/m-p/1138667/highlight/true#M4375). Then in the **Redirect URL** field use **`https://localhost`**. Tick the remaining options as in the next image, *read and agree to the terms of service* and click **Register** to register the application.
* Once the app is created, click on the 'OAuth 2.0 Tutorial' weblink near the bottom of the screen:
* In the 'Fitbit OAuth 2.0 Tutorial' website the **Client ID** already exists and we have to copy-paste the **Client Secret** from the previous web page
* then we scroll down to the 'Getting an Access Token' section and click to the two "Generate" buttons to generate the required codes,
* In the next section 'Step 2: Display Authorization Page' we click to the already created URL which will open a new tab to our web browser,
* in this new web page tick the **Allow All** and click the **Allow** button
* After clicking *Allow*, the browser tab redirects to the callback URL. Although this might seem like an "Unable to connect" web page the important thing here is to just copy the URL of the web page as follows,
* and paste it to the section "Step 3: Handle the Redirect" where the "Authorization code" and "State" will be created,
* finally in section "Step 4: Get Tokens" we just click to the **SUBMIT REQUEST** button to receive the token in the **Response** field,
<br>
The **parsed response** looks as follows,
<br>
You now have your **Access Token** and can start using the **fitbitViz** R package to access and visualize your data.
Keep in mind that the *Access token* is **valid for 8 hours**. Based on the documentation of the fitbit API
*"After the Access Token expiration time has passed your requests will receive a 401 HTTP error. When this happens, your app should use the Refresh Token to get a new pair of tokens"*.
To refresh the token the user of the *fitbitViz* R package can use the ***refresh_token_app()*** function, which requires the **client id**, **client secret** and **refresh token** of your registered Fitbit application, in the following way:
<br>
```R
require(fitbitViz)
#..............................................
# Refresh token once it expires (after 8 hours)
#..............................................
client_id = 'xxxxxx'
client_secret = 'xxxxxxxxxxxxxxxxxx'
refresh_token = 'xxxxxxxxxxxxxxxxxxxxxxxx'
# refresh the token
new_token = refresh_token_app(client_id = client_id,
client_secret = client_secret,
refresh_token = refresh_token)
# a named list that includes the new 'access_token' and 'refresh_token'
str(new_token)
```
<br>
### Keep track of your activities using 'fitbitViz', 'Blogdown' and 'Github Actions'
<br>
**UPDATE 26-12-2022**: The registration of an Application of the *fitbit web API* has changed and it seems that users have to refresh the token every **8 hours**. The following instructions were meant to be used with a registered application that wouldn't require to refresh the token after **1 year**.
<br>
The functions of the **fitbitViz** R package can be used in an automatic way so that the user can keep track of the **Visualizations** and **data** over time.
From the first moment I've started implementing the **fitbitViz** R package this is what I actually had in my mind. You can have a look to [my Fitbit Visualizations website](https://mlampros.github.io/fitbitVizBlog/). The following steps explain in detail how this can be achieved:
* Fork the [fitbitVizBlog](https://github.com/mlampros/fitbitVizBlog) repository ( **!!! Not this repository but the one that includes the blog posts !!!** )
* Create the following **secrets** required for the [.github/workflows/gh_fitbit_blog.yaml](https://github.com/mlampros/fitbitVizBlog/blob/master/.github/workflows/gh_fitbit_blog.yaml) file by navigating to **Settings** >> **secrets** (*be aware that the **AWS_ACCESS_KEY_ID** and **AWS_SECRET_ACCESS_KEY** are optional and required only if you want to receive the **3-dimensional** Rayshader Visualization*)
* **USER_ID**: click on 'New repository secret' and use **USER_ID** as **Name** and your Fitbit [user-id](https://community.fitbit.com/t5/Web-API-Development/Where-do-I-find-my-User-ID/m-p/1138667/highlight/true#M4375) as **Value**
* **FITBIT_TOKEN**: click on 'New repository secret' and use **FITBIT_TOKEN** as **Name** and the **token** you received from your previously registered Fitbit application as **Value**
* **GH_PAT**: First create a [Personal Access Token](https://github.com/settings/tokens) by giving as **Note** a name and then ticking in **Select scopes** the **workflow** (Update GitHub Action workflows) scope and lastly click on **Generate Token**. Then click on 'New repository secret' and use **GH_PAT** as **Name** and the copied **Generated Token** as **Value**
* **EMAIL**: click on 'New repository secret' and use **EMAIL** as **Name** and the **e-mail** you use on Github as **Value**
* **AWS_ACCESS_KEY_ID**: click on 'New repository secret' and use **AWS_ACCESS_KEY_ID** as **Name** and insert your **aws access key id** in the **Value** field ( the aws credentials are required for the Copernicus Elevation Data, this [guide explains how to receive the aws credentials](https://supsystic.com/documentation/id-secret-access-key-amazon-s3/) )
* **AWS_SECRET_ACCESS_KEY**: click on 'New repository secret' and use **AWS_SECRET_ACCESS_KEY** as **Name** and insert your **aws secret access key** in the **Value** field
What it remains is to modify the [.github/workflows/gh_fitbit_blog.yaml](https://github.com/mlampros/fitbitVizBlog/blob/master/.github/workflows/gh_fitbit_blog.yaml) file to adjust the
* current **cron-job** settings which runs every Sunday at 23:00 pm
* 
* current **fitbitViz** parameters
* 
Regarding the **fitbitViz** parameters ([.github/workflows/gh_fitbit_blog.yaml](https://github.com/mlampros/fitbitVizBlog/blob/master/.github/workflows/gh_fitbit_blog.yaml) file) at it's current state the application takes:
* **DATE**: this parameter corresponds to the current Date ( the Date that the **Cron-Job** runs ). You can set this parameter also to a character string such as **DATE="2021-05-16";** if you want to use as the end Date this specific date. **Be Aware** this parameter is defined in a separate github action step.
* **previous_n_days**: this parameter specifies the number of days before the current **DATE** for which the Fitbit data will be downloaded (I've set it to **6** to visualize and access data of the **last** week)
* **sleep_time_begins**: this is your scheduled sleep time in form of a **lubridate::hms("00H 40M 0S")** object (adjust the input depending on your sleep time)
* **sleep_time_ends**: this is your scheduled wake up time in form of a **lubridate::hms("08H 00M 0S")** object (adjust the input depending on your wake up time)
* **asc_desc_linestring**: this parameter is related to the GPS data of the **3-dimensional** map especially if you keep track of your outdoor activities. There are **3 options** but before making use of the **2nd. option make sure** that there is an ascending and descending route, otherwise it will give an error:
1. by specifying **asc_desc_linestring="";** a single LINESTRING will be created based on the GPS data using a single color
2. by specifying **asc_desc_linestring="TRUE";** the LINESTRING of the GPS data will be split into 2 parts using the highest elevation location as a split point (**blue** color for the ascending part and **red** color for the descending part)
3. by specifying **asc_desc_linestring="17H 5M 0S";** the GPS data will be split into 2 parts using this input time as split point (adjust the time based on your data)
* **time_zone**: your current time zone as specified in **lubridate::ymd_hms(tz = ..)** function (it defaults to my current time zone which is **Europe/Athens**)
* **buffer_meters**: this parameter extends the 3-dimensional map by **N-meters** (the current default value is **1500** meters)
* **resolution_dem**: this parameter takes either **30** or **90** and corresponds to the resolution of the Copernicus elevation data (the current default value is **30** meters)
* **verbose_Rmd**: this last parameter is just for debugging in case you want to enable verbosity in the output **.Rmd** file (it defaults to "FALSE" and it takes also "TRUE" as input)
<br>
The order to *modify*, *debug* or *include new code / functions* to the files of this Github Repository is the following:
* first modify the **gh_fitbit_blog.yaml** file
* then modify the *R code* of the **R_templates/data_template.R** file
* and finally modify the *Rmd code* of the **R_templates/functions_template.Rmd** file
<br>
One **important** thing to keep in mind is that besides the Visualizations the user has access also to the pre-processed Fitbit data by clicking to a **CSV** button as shown in the next image,
<br>
<br>
* **References**:
* https://registry.opendata.aws/copernicus-dem/
* https://dev.fitbit.com/build/reference/web-api/
* https://github.com/orchid00/actions_sandbox/issues/41#issuecomment-816970613
<br>
### Docker Image:
<br>
**Docker images** of the *fitbitViz* package are available to download from my [dockerhub](https://hub.docker.com/r/mlampros/fitbitviz) account. The images come with *Rstudio* and the *R-development* version (latest) installed. The whole process was tested on Ubuntu 18.04. To **pull** & **run** the image do the following,
<br>
```R
docker pull mlampros/fitbitviz:rstudiodev
docker run -d --name rstudio_dev -e USER=rstudio -e PASSWORD=give_here_your_password --rm -p 8787:8787 mlampros/fitbitviz:rstudiodev
```
<br>
The user can also **bind** a home directory / folder to the image to use its files by specifying the **-v** command,
<br>
```R
docker run -d --name rstudio_dev -e USER=rstudio -e PASSWORD=give_here_your_password --rm -p 8787:8787 -v /home/YOUR_DIR:/home/rstudio/YOUR_DIR mlampros/fitbitviz:rstudiodev
```
<br>
In the latter case you might have first give permission privileges for write access to **YOUR_DIR** directory (not necessarily) using,
<br>
```R
chmod -R 777 /home/YOUR_DIR
```
<br>
The **USER** defaults to *rstudio* but you have to give your **PASSWORD** of preference (see [www.rocker-project.org](https://rocker-project.org/) for more information).
<br>
Open your web-browser and depending where the docker image was *build / run* give,
<br>
**1st. Option** on your personal computer,
<br>
```R
http://0.0.0.0:8787
```
<br>
**2nd. Option** on a cloud instance,
<br>
```R
http://Public DNS:8787
```
<br>
to access the Rstudio console in order to give your username and password.
<br>
### Package Installation & Citation:
<br>
To install the package from CRAN use,
```R
install.packages("fitbitViz")
```
<br>
and to download the latest version of the package from Github,
```{r, echo = TRUE, eval = FALSE }
remotes::install_github('mlampros/fitbitViz')
```
<br>
If you use the **fitbitViz** R package in your paper or research please cite `https://CRAN.R-project.org/package=fitbitViz`:
<br>
```R
@Manual{,
title = {{fitbitViz}: Fitbit Visualizations},
author = {Lampros Mouselimis},
year = {2022},
note = {R package version 1.0.6},
url = {https://CRAN.R-project.org/package=fitbitViz},
}
```
<br>