-
Notifications
You must be signed in to change notification settings - Fork 7
/
README.Rmd
152 lines (98 loc) · 5.73 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
---
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%"
)
options(tibble.print_min = 5, tibble.print_max = 5)
```
# chessR <a href='https://jaseziv.github.io/chessR/'><img src='man/figures/logo.png' align="right" height="219.5" /></a>
<!-- badges: start -->
[)](https://github.com/JaseZiv/chessR/)
[](https://github.com/JaseZiv/chessR/actions)
[](https://app.codecov.io/gh/JaseZiv/chessR)
[](https://CRAN.R-project.org/package=chessR)
[](https://CRAN.R-project.org/package=chessR)
[](https://cran.r-project.org/package=chessR)
<!-- badges: end -->
## Overview
This package is designed to allow users to extract game data from popular online chess platforms. The platforms currently supported in this package include:
* [chess.com](https://www.chess.com/)
* [Lichess](https://lichess.org/)
These websites offer a very convenient set of APIs to be able to access data and documentation to these can be found [here for chess.com](https://www.chess.com/news/view/published-data-api) and [here for Lichess](https://lichess.org/api).
## Installation
You can install the CRAN version of [**```chessR```** ](https://CRAN.R-project.org/package=chessR) with:
```{r cran-installation, eval=FALSE}
install.packages("chessR")
```
You can install the released version of [**```chessR```**](https://github.com/JaseZiv/chessR/) from [GitHub](https://github.com/JaseZiv/worldfootballR) with:
```{r gh-installation, eval=FALSE}
# install.packages("devtools")
devtools::install_github("JaseZiv/chessR")
```
```{r load_libs, warning=FALSE, message=FALSE}
library(chessR)
```
***
## Usage
The functions available in this package are designed to enable the extraction of chess game data.
### Data Extraction
The functions detailed below relate to extracting data from the chess gaming sites currently supported in this package.
#### Raw Game Data
The game extraction functions can take a vector of either single or multiple usernames. It will output a data frame with all the games played by that user.
The functions are below.
**Note:**
These functions query an API, which is rate limited. The limiting rates for chess.com are unknown. For Lichess, the limit is throttled to 15 games per second. Queries could therefore take a few minutes if you're querying a lot of games.
```{r get_raw, eval = FALSE}
# function to extract chess.com game data
chessdotcom_game_data_all_months <- get_raw_chessdotcom(usernames = "JaseZiv")
chessdotcom_hikaru_recent <- get_raw_chessdotcom(usernames = "Hikaru", year_month = c(202104:202105))
# function to extract lichess game data
lichess_game_data <- get_raw_lichess("Georges")
```
#### Analysis Data
The following function will extract the same data that the `get_raw_chessdotcom()` function will, however this function will also include additional columns to make analysing data easier.
The function can be used either on a single player, or a character vector of multiple players.
**Note:**
This is only available for chess.com extracts
```{r get_analysis, eval=FALSE}
chess_analysis_single <- get_game_data("JaseZiv")
chess_analysis_multiple <- get_game_data(c("JaseZiv", "Smudgy1"))
```
### Leaderboards
The leaderboards of each game platform can be extracted for a number of different games available on each platform. Each are discussed below:
#### Chess.com
The below function allows the user to extract the top 50 players of each game type specified. Game types available include:
> *"daily","daily960", "live_rapid", "live_blitz", "live_bullet", "live_bughouse", "live_blitz960", "live_threecheck", "live_crazyhouse", "live_kingofthehill", "lessons", "tactics"*
The usernames that are contained in the results can then be passed to `get_raw_chessdotcom` outlined above.
```{r get_leaders, eval=FALSE}
chessdotcom_leaders <- chessdotcom_leaderboard(game_type = "daily")
```
#### Lichess
The `lichess_leaderboard()` function takes in two parameters; how many players you want returned (with a max of 200 being returned) and the speed variant. Speed variants include;
> *"ultraBullet", "bullet", "blitz", "rapid", "classical", "chess960", "crazyhouse", "antichess", "atomic", "horde", "kingOfTheHill", "racingKings", "threeCheck"*
```{r get_lichess_leaders, eval=FALSE}
lichess_leaders <- lichess_leaderboard(top_n_players = 10, speed_variant = "blitz")
```
#### Visualising games
With the additional [`{chess}`](https://cran.r-project.org/package=chess) package, you can visualise a game. For example, a recent Hikaru Nakamura vs Daniel Naroditsky game on chess.com:
```{r, eval = FALSE}
# extract just one year-month of Hikaru's games from chess.com
hikaru <- chessR:::get_each_player_chessdotcom("hikaru", "202112")
# convert to {chess} 'game' format
m <- extract_moves_as_game(hikaru[11, ])
# plot each move and save all as a gif
# set sleep = 0 so the rendering doesn't happen in realtime
gifski::save_gif({
plot_moves(m, interactive = FALSE, sleep = 0)
},
gif_file = "~/Hikaru_Naroditsky.gif",
delay = 1)
```
For a detailed guide to using the package and the functions for analysis, see the package [vignette](https://jaseziv.github.io/chessR/articles/using_chessR_package.html)