forked from fawda123/rStrava
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.Rmd
149 lines (111 loc) · 6.44 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
---
output:
html_document:
keep_md: yes
toc: no
self_contained: yes
---
# rStrava
##### *Marcus W. Beck, [email protected], Pedro Villarroel, [email protected], Daniel Padfield, [email protected], Lorenzo Gaborini, [email protected]*
Linux: [](https://travis-ci.org/fawda123/rStrava)
Windows: [](https://ci.appveyor.com/project/fawda123/rStrava)
[](https://zenodo.org/badge/latestdoi/23404183)
### Overview and installation
This is the development repository for rStrava, an R package to access data from the Strava API. The package can be installed and loaded as follows:
```{r eval = F}
install.packages('devtools')
devtools::install_github('fawda123/rStrava')
```
### Issues and suggestions
Please report any issues and suggestions on the [issues link](https://github.com/fawda123/rStrava/issues) for the repository.
### Package overview
The functions are in two categories depending on mode of use. The first category of functions scrape data from the public Strava website and the second category uses the API functions or relies on data from the API functions. The second category requires an authentication token. The help files for each category can be viewed using ```help.search```:
```{r eval = F}
help.search('notoken', package = 'rStrava')
help.search('token', package = 'rStrava')
```
### Scraping functions (no token)
An example using the scraping functions:
```{r echo = FALSE, message = FALSE, cache = F}
devtools::load_all('.')
```
```{r message = FALSE}
# get athlete data
athl_fun(2837007, trace = FALSE)
```
### API functions (token)
#### Setup
These functions require a Strava account and a personal API, both of which can be obtained on the Strava website. The user account can be created by following instructions on the [Strava homepage](https://www.strava.com/). After the account is created, a personal API can be created under API tab of [profile settings](https://www.strava.com/settings/api). The user must have an application name (chosen by the user), client id (different from the athlete id), and an application secret to create the authentication token. Additional information about the personal API can be found [here](https://strava.github.io/api/). Every API retrieval function in the rStrava package requires an authentication token (called `stoken` in the help documents). The following is a suggested workflow for using the API functions with rStrava.
First, create the authentication token using your personal information from your API. Replace the `app_name`, `app_client_id`, and `app_secret` objects with the relevant info from your account.
```{r, eval = FALSE}
app_name <- 'myappname' # chosen by user
app_client_id <- 'myid' # an integer, assigned by Strava
app_secret <- 'xxxxxxxx' # an alphanumeric secret, assigned by Strava
# create the authentication token
stoken <- httr::config(token = strava_oauth(app_name, app_client_id, app_secret))
```
Setting `cache = TRUE` for `strava_oauth` will create an authentication file in the working directory. This can be used in later sessions as follows:
```{r, eval = FALSE}
stoken <- httr::config(token = readRDS('.httr-oauth')[[1]])
```
Finally, the `get_heat_map` and `get_elev_prof` functions optionally retrieve elevation data from the Google Maps Elevation API. To use these features, an additional authentication key is required. Follow the instructions [here](https://developers.google.com/maps/documentation/elevation/#api_key). The key can be added to the R environment file for later use:
```{r eval = FALSE}
# save the key, do only once
cat("google_key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n",
file=file.path(normalizePath("~/"), ".Renviron"),
append=TRUE)
# retrieve the key, restart R if not found
mykey <- Sys.getenv("google_key")
```
#### Using the functions
The API retrieval functions are used with the token.
```{r echo = FALSE, message = FALSE}
source('extra.R')
```
```{r}
myinfo <- get_athlete(stoken, id = '2837007')
head(myinfo)
```
An example creating a heat map of activities:
```{r message = F, fig.height = 5.5, fig.width = 7, cache = TRUE}
# get activities, get activities by location, plot
my_acts <- get_activity_list(stoken)
acts <- lapply(my_acts, function(x) x$location_city) %in% c('Pensacola', 'Pensacola Beach', 'Milton')
get_heat_map(my_acts, acts = which(acts), col = 'darkgreen', size = 2, dist = F, f = 0.5)
```
Plotting elevation and grade for a single ride:
```{r}
# plot elevation along a single ride
get_heat_map(my_acts, acts = 1, alpha = 1, add_elev = T, f = 0.3, key = mykey, size = 2, col = 'Spectral', maptype = 'satellite', units = 'imperial')
# plot % gradient along a single ride
get_heat_map(my_acts, acts = 1, alpha = 1, add_elev = T, f = 0.3, as_grad = T, key = mykey, size = 2, col = 'Spectral', expand = 5, maptype = 'satellite', units = 'imperial')
```
Get elevation profiles for activities:
```{r message = F, fig.height = 3, fig.width = 9, cache = TRUE}
# get activities
my_acts <- get_activity_list(stoken)
get_elev_prof(my_acts, acts = 1, key = mykey, units = 'imperial')
get_elev_prof(my_acts, acts = 1, key = mykey, units = 'imperial', total = T)
```
Plot average speed per split (km or mile) for an activity:
```{r message = F, fig.height = 3, fig.width = 9, cache = TRUE}
# plots for most recent activity
plot_spdsplits(my_acts, stoken, acts = 1, units = 'imperial')
```
Additional functions are provided to get "stream" information for individual activities. Streams provide detailed information about location, time, speed, elevation, gradient, cadence, watts, temperature, and moving status (yes/no) for an individual activity.
Use `get_activity_streams` for detailed info about activites:
```{r, fig.height = 4, fig.with = 4}
# get streams for the first activity in my_acts
strms_data <- get_activity_streams(my_acts, stoken, acts = 1)
head(strms_data)
# make a plot
library(ggplot2)
ggplot(strms_data, aes(x = lng, y = lat, group = id, col = velocity_smooth)) +
geom_path(size = 2) +
coord_equal() +
theme_void() +
scale_colour_distiller('Speed (km/hr)', palette = 'Spectral')
```
### License
This package is released in the public domain under the creative commons license [CC0](https://tldrlegal.com/license/creative-commons-cc0-1.0-universal).