| Title: | Functions to Extract, Clean and Analyse Online Chess Game Data |
|---|---|
| Description: | A set of functions to enable users to extract chess game data from popular chess sites, including 'Lichess'<https://lichess.org/> and 'Chess.com' <https://www.chess.com/> and then perform analysis on that game data. |
| Authors: | Jason Zivkovic [aut, cre], Jonathan Carroll [ctb] (ORCID: <https://orcid.org/0000-0002-1404-5264>), Dan Wakeling [ctb] |
| Maintainer: | Jason Zivkovic <[email protected]> |
| License: | GPL-3 |
| Version: | 1.5.5 |
| Built: | 2026-09-19 01:45:48 UTC |
| Source: | https://github.com/JaseZiv/chessR |
Check Status function
check_status(res)check_status(res)
res |
Response from API |
This function takes in one parameter, the game_type, and returns a data frame of the top 50 players on chess.com.
chessdotcom_leaderboard(game_type = "daily")chessdotcom_leaderboard(game_type = "daily")
game_type |
A valid chess.com game type to return the leaderboard for |
The leaderboard options (games) include:
"daily", "daily960", "live_rapid", "live_blitz", "live_bullet", "live_bughouse", "live_blitz960", "live_threecheck" , "live_crazyhouse", "live_kingofthehill", "lessons", "tactics"
a dataframe of the chess.com top 50 players based on game_type selected
## Not run: chessdotcom_leaderboard(game_type = "daily") ## End(Not run)## Not run: chessdotcom_leaderboard(game_type = "daily") ## End(Not run)
This package is designed to aid in the extraction and analysis of game data from the popular chess.com
Maintainer: Jason Zivkovic [email protected]
Other contributors:
Jonathan Carroll [email protected] (ORCID) [contributor]
Dan Wakeling [email protected] [contributor]
Useful links:
Extract moves from a game as a data.frame
extract_moves(moves_string)extract_moves(moves_string)
moves_string |
string containing moves built by 'chessR' (e.g. from https://www.chess.com/) or the filename of a PGN file |
cleaned moves as a data.frame
Extract moves and create 'chess' game
extract_moves_as_game(game)extract_moves_as_game(game)
game |
a single row of a 'data.frame' provided by 'chessR' containing move information or the filename of a PGN file |
a [chess::game()] game object
get_each_player returns a dataframe of all of the games played by one player
get_each_player(username)get_each_player(username)
username |
A string value of a player's name |
This function will take in a single player's username and return the data on all the games they have played on chess.com
This function returns the raw json data for a player's chess.com data as a data frame
get_each_player_chessdotcom(username, year_month)get_each_player_chessdotcom(username, year_month)
username |
A valid username from chess.com |
year_month |
An integer of YYYYMM |
a dataframe of chess.com data
get_game_data returns a dataframe of game data for either a single user
or a list of usernames
get_game_data(usernames)get_game_data(usernames)
usernames |
A character vector of player usernames from chess.com |
This function will take in a list of player usernames and return a dataframe of game metadata
a dataframe of chess.com data plus additional analysis columns
## Not run: chess_analysis_single <- get_game_data(usernames = "JaseZiv") chess_analysis_multiple <- get_game_data(usernames = c("JaseZiv", "Smudgy1")) ## End(Not run)## Not run: chess_analysis_single <- get_game_data(usernames = "JaseZiv") chess_analysis_multiple <- get_game_data(usernames = c("JaseZiv", "Smudgy1")) ## End(Not run)
This function returns a character vector of how the game ended from chess.dom.
get_game_ending(termination_string, white, black)get_game_ending(termination_string, white, black)
termination_string |
A character vector in the chess.com extracted data frame called 'Termination' |
white |
A character vector in the chess.com extracted data frame called 'White' for the player on white |
black |
A character vector in the chess.com extracted data frame called 'Black' for the player on black |
A character vector of the game ending for each game
## Not run: get_game_ending(termination_string = df$Termination, df$White, df$Black) ## End(Not run)## Not run: get_game_ending(termination_string = df$Termination, df$White, df$Black) ## End(Not run)
This function returns the raw json data for a player's or list of players' chess.com data as a data frame, for all or select months played
get_raw_chessdotcom(usernames, year_month = NA_integer_)get_raw_chessdotcom(usernames, year_month = NA_integer_)
usernames |
A vector of a valid username or usernames from chess.com |
year_month |
An integer of YYYYMM |
a dataframe of chessdotcom data
## Not run: get_raw_chessdotcom(usernames = "JaseZiv") get_raw_chessdotcom(usernames = "JaseZiv", year_month = c(202112:202201)) get_raw_chessdotcom(usernames = c("JaseZiv", "Smudgy1"), year_month = 202201) ## End(Not run)## Not run: get_raw_chessdotcom(usernames = "JaseZiv") get_raw_chessdotcom(usernames = "JaseZiv", year_month = c(202112:202201)) get_raw_chessdotcom(usernames = c("JaseZiv", "Smudgy1"), year_month = 202201) ## End(Not run)
This function returns the raw json data for a player's or list of players' Lichess data as a data frame
get_raw_lichess(player_names, since = NULL, until = NULL)get_raw_lichess(player_names, since = NULL, until = NULL)
player_names |
A vector of a valid username or usernames from Lichess |
since |
Games played since this date. An object of class 'Date' or a string of the form '"yyyy-mm-dd"'. If 'NULL', defaults to account creation date. |
until |
Games played until this date. An object of class 'Date' or a string of the form '"yyyy-mm-dd"'. If 'NULL', defaults to now. |
a dataframe of lichess data
## Not run: georges_data <- get_raw_lichess(player_names = "Georges") the_knife_data <- get_raw_lichess("the_knife", since = "2023-08-13", until = "2023-08-14") ## End(Not run)## Not run: georges_data <- get_raw_lichess(player_names = "Georges") the_knife_data <- get_raw_lichess("the_knife", since = "2023-08-13", until = "2023-08-14") ## End(Not run)
This function returns a character vector of the usernames of the game winners
get_winner(result_column, white, black)get_winner(result_column, white, black)
result_column |
A character vector in the extracted data frame called 'Result' |
white |
A character vector in the extracted data frame called 'White' for the player on white |
black |
A character vector in the extracted data frame called 'Black' for the player on black |
A character vector of the game ending for each game
## Not run: get_winner(df$Result, df$White, df$Black) ## End(Not run)## Not run: get_winner(df$Result, df$White, df$Black) ## End(Not run)
This function returns a data frame of Lichess data with clock and move times
lichess_clock_move_time(games_list)lichess_clock_move_time(games_list)
games_list |
A data frame of lichess data which can be generated from chessR::get_raw_lichess("username") |
a data frame of lichess data with move time, clock time, and move numbers
## Not run: lordy_leroy_data <- get_raw_lichess(player_names = "LordyLeroy") lordy_leroy_data_with_times <- lichess_clock_move_time(games_list = lordy_leroy_data) ## End(Not run)## Not run: lordy_leroy_data <- get_raw_lichess(player_names = "LordyLeroy") lordy_leroy_data_with_times <- lichess_clock_move_time(games_list = lordy_leroy_data) ## End(Not run)
This function takes in two parameters; how many players you want returned (max 200) and the speed variant. The result is a data frame for each game type
lichess_leaderboard(top_n_players, speed_variant)lichess_leaderboard(top_n_players, speed_variant)
top_n_players |
The number of players (up to 200) you want returned |
speed_variant |
A valid lichess speed variant to return the leaderboard for |
The leaderboard speed variant options include:
"ultraBullet", "bullet", "blitz", "rapid", "classical", "chess960", "crazyhouse", "antichess" , "atomic", "horde", "kingOfTheHill", "racingKings", "threeCheck"
a dataframe of the lichess top players based on speed_variant and top_n_players selected
## Not run: top10_blitz <- lichess_leaderboard(top_n_players = 10, speed_variant = "blitz") leaderboards <- purrr::map2_df(top_n_players = 10, c("ultraBullet", "bullet"), lichess_leaderboard) ## End(Not run)## Not run: top10_blitz <- lichess_leaderboard(top_n_players = 10, speed_variant = "blitz") leaderboards <- purrr::map2_df(top_n_players = 10, c("ultraBullet", "bullet"), lichess_leaderboard) ## End(Not run)
Plot a game
plot_moves(game, interactive = TRUE, sleep = 1)plot_moves(game, interactive = TRUE, sleep = 1)
game |
a [chess::game()] object, likely with moves identified |
interactive |
wait for 'Enter' after each move? Turn off to use in a gif |
sleep |
how long to wait between moves |
'NULL', (invisibly) - called for the side-effect of plotting
## Not run: hikaru <- get_each_player_chessdotcom("hikaru", "202112") m <- extract_moves_as_game(hikaru[11, ]) plot_moves(m) ## End(Not run)## Not run: hikaru <- get_each_player_chessdotcom("hikaru", "202112") m <- extract_moves_as_game(hikaru[11, ]) plot_moves(m) ## End(Not run)
This function returns the number of moves played in each game. The function accepts a vector of chess Moves data in PGN notation, usually called 'Moves'
return_num_moves(moves_string)return_num_moves(moves_string)
moves_string |
A character vector of chess Moves data in PGN notation usually called 'Moves' in extracted data |
A numeric vector of the number of moves in each game
## Not run: return_num_moves(moves_string = df$Moves) ## End(Not run)## Not run: return_num_moves(moves_string = df$Moves) ## End(Not run)