Movatterモバイル変換


[0]ホーム

URL:


Title:Manage Competition Results
Version:0.2.7
Description:Tools for storing and managing competition results. Competition is understood as a set of games in which players gain some abstract scores. There are two ways for storing results: in long (one row per game-player) and wide (one row per game with fixed amount of players) formats. This package provides functions for creation and conversion between them. Also there are functions for computing their summary and Head-to-Head values for players. They leverage grammar of data manipulation from 'dplyr'.
License:MIT + file LICENSE
URL:https://github.com/echasnovski/comperes
BugReports:https://github.com/echasnovski/comperes/issues
Depends:R (≥ 3.4.0)
Imports:dplyr (≥ 0.7.0), magrittr, rlang (≥ 0.1.2), tibble, tidyr(≥ 0.7.0)
Suggests:covr, knitr, rmarkdown, testthat
VignetteBuilder:knitr
Encoding:UTF-8
LazyData:true
RoxygenNote:7.2.3
NeedsCompilation:no
Packaged:2023-02-28 18:36:57 UTC; evgeni
Author:Evgeni ChasnovskiORCID iD [aut, cre]
Maintainer:Evgeni Chasnovski <evgeni.chasnovski@gmail.com>
Repository:CRAN
Date/Publication:2023-02-28 19:42:30 UTC

comperes: Manage Competition Results

Description

comperes offers a set of tools for storing and managing competitionresults.Competition is understood as a set ofgames (abstract event)in whichplayers (abstract entity) gain some abstractscores. Themost natural example is sport results, however not the only one. For example,product rating can be considered as a competition between products as"players". Here a "game" is a customer that reviews a set of products byrating them with numerical "score" (stars, points, etc.).

Details

This package provides the following functionality:

To learn more aboutcomperes browse vignettes withbrowseVignettes(package = "comperes").

Author(s)

Maintainer: Evgeni Chasnovskievgeni.chasnovski@gmail.com (ORCID)

See Also

Useful links:


Pipe operator

Description

Seemagrittr::%>% for details.

Usage

lhs %>% rhs

Convert between long pair-value data and matrix

Description

Functions for conversion between long pair-value data (data frame withcolumns for pair identifiers and value column) and matrix.

Usage

long_to_mat(tbl, row_key, col_key, value = NULL, fill = NULL,  silent = FALSE)mat_to_long(mat, row_key, col_key, value, drop = FALSE)

Arguments

tbl

Data frame with pair-value data.

row_key

String name of column for first key in pair.

col_key

String name of column for second key in pair.

value

String name of column for value (orNULL forlong_to_mat()).

fill

Value to fill for missing pairs.

silent

UseTRUE to omit message about guessed value column (seeDetails).

mat

Matrix with pair-value data.

drop

UseTRUE to drop rows with missing value (see Details).

Details

Pair-value data is commonly used in description of pairs of objects.Pair is described by two keys (usually integer or character) and value is anobject of arbitrary nature.

Inlong format there are at least three columns: for first key in pair,for second key and for value (might be more). Inmatrix format pair-valuedata is represented as matrix of values with row names as characterrepresentation of first key, column names - second key.

long_to_mat() works as follows:

mat_to_long() basically performs inverse operation tolong_to_mat() butpair identifiers are always character. Ifdrop = TRUE it drops rows withvalues (but not keys) being missing.

Value

long_to_mat() returns a matrix with selected values where row namesindicate first key in pair, col names - second.

mat_to_long() returns atibble with three columns: theone for first key in pair, the one for second, and the one for value.

Examples

long_data <- data.frame(  key_1 = c("a", "a", "b"),  key_2 = c("c", "d", "c"),  val = 1:3,  stringsAsFactors = FALSE)mat_data <- long_data %>% long_to_mat("key_1", "key_2", "val")print(mat_data)# Converts to tibblemat_data %>% mat_to_long("new_key_1", "new_key_2", "new_val")# Drops rows with valuus missingmat_data %>% mat_to_long("new_key_1", "new_key_2", "new_val", drop = TRUE)

Get matchups from competition results

Description

This function powers computing Head-to-Head values (bothlong andmatrix).

Usage

get_matchups(cr_data)

Arguments

cr_data

Competition results ready foras_longcr().

Details

get_matchups() returns atibble of allmatchups (pairs of players from one game)actually present incr_data(including matchups of players with themselves).It has following columns:

Important notes:

Value

Awidecr for games with two players.

See Also

Long format of Head-to-Head values.

Matrix format of Head-to-Head values.

Examples

get_matchups(ncaa2005)

Common Head-to-Head functions

Description

List of commonly used functions for computing Head-to-Head values.

Usage

h2h_funs

Format

An object of classlist of length 9.

Details

h2h_funs is a named list ofexpressionsrepresenting commonly used expressions of Head-to-Head functions forcomputing Head-to-Head values withh2h_long() orh2h_mat(). Names of theelements will be used as Head-to-Head value names. To use them insideh2h_long() orh2h_mat() useunquoting mechanismfrom rlang package.

Currently present functions:

Note that it is generally better to subseth2h_funs using namesrather than indices because the order of elements might change in futureversions.

See Also

Long format of Head-to-Head values.

Matrix format of Head-to-Head values.

Examples

ncaa2005 %>% h2h_long(!!!h2h_funs)ncaa2005 %>% h2h_mat(!!!h2h_funs["num_wins2"])

Compute long format of Head-to-Head values

Description

Functions to compute Head-to-Head values in long pair-value format.

Usage

h2h_long(cr_data, ..., fill = list())to_h2h_long(mat, value = "h2h_value", drop = FALSE)## S3 method for class 'h2h_long'as_tibble(x, ...)

Arguments

cr_data

Competition results ready foras_longcr().

...

Name-value pairs of Head-to-Head functions (see Details).

fill

A named list that for each variable supplies a single value touse instead ofNA for missing pairs (see tidyr'scomplete()).

mat

Matrix of Head-to-Head values.

value

String name to be used for column with Head-to-Head value.

drop

UseTRUE to drop rows with missing Head-to-Head values (seeDetails).

x

Object to be converted totibble.

Details

h2h_long() computes Head-to-Head values inlong format. It allows computation of multipleHead-to-Head values at the same time by supplying multiple summary functionsin.... If no function is supplied in..., it returns all appropriatecombinations ofmatchups (see next paragraph).

After computing Head-to-Head values of actually present matchups, they arealigned with "levels" (seelevels2()) ofplayer vector (after applyingas_longcr()). This is a way to target function on fixed set of players byusing factor columns. The procedure is:

Usefill as incomplete() to control filling values. To drop those rowsuse tidyr'sdrop_na().

to_h2h_long() takesobject ofh2h_mat structure and convertsit intoh2h_long object with value column named as stored invalue. Usedrop = TRUE to remove rows with missing values in value column (but not inplayers').

Value

An object of classh2h_long which is atibblewith columnsplayer1,player2 and those, produced by Head-to-Headfunctions (forh2h_long() maybe none).

as_tibble() applied toh2h_long object dropsh2h_long class.

Head-to-Head value

Head-to-Head value is a summary statistic of direct confrontation between twoplayers. It is assumed that this value can be computed based only on theplayers'matchups. In other words, every game is convertedinto series of "subgames" between ordered pairs of players (includingselfplay) which is stored aswidecr object. After that, summary of item,defined by columnsplayer1 andplayer2, is computed usingsummarise_item().

That said, name-value pairs of Head-to-Head functions should be defined asforsummarise_item() applied to data with columnsgame,player1,score1,player2,score2.

See Also

Matrix format of Head-to-Head values.

Common Head-to-Head functions.

Examples

ncaa2005 %>%  h2h_long(    mean_score = mean(score1),    mean_abs_score = mean(abs(score1 - score2))  )ncaa2005[-(1:2), ] %>%  h2h_long(    mean_score = mean(score1),    fill = list(mean_score = 0)  )

Compute matrix format of Head-to-Head values

Description

Functions to compute Head-to-Head values in matrix pair-value format.

Usage

h2h_mat(cr_data, ..., fill = NULL)to_h2h_mat(tbl, value = NULL, fill = NULL)

Arguments

cr_data

Competition results ready foras_longcr().

...

Name-value pairs of Head-to-Head functions (see Details).

fill

A single value to use instead ofNA for missing pairs.

tbl

Data frame inlong format of Head-to-Head values.

value

String name for column with Head-to-Head value.

Details

h2h_mat() computes Head-to-Head values inmatrix format. It allows multiple Head-to-Headfunctions in... but only first (if present) will be used. Basically, ituses supplied function to compute long format of Head-to-Head values and thentransforms it naturally to matrix, filling missing valueswithfill.

to_h2h_mat() takesobject ofh2h_long structure and converts it intoh2h_mat using column with namevalue for values and filling data forimplicitly missing (not explicitly provided intbl) player pairs withfill. Ifvalue isNULL it takes first non-player column. If there is nosuch column, it will use vector of dummy values (NAs orfills).

Value

An object of classh2h_mat which is amatrix with row namesindicating first player in matchup, col names - second and values -Head-to-Head values.

Head-to-Head value

Head-to-Head value is a summary statistic of direct confrontation between twoplayers. It is assumed that this value can be computed based only on theplayers'matchups. In other words, every game is convertedinto series of "subgames" between ordered pairs of players (includingselfplay) which is stored aswidecr object. After that, summary of item,defined by columnsplayer1 andplayer2, is computed usingsummarise_item().

That said, name-value pairs of Head-to-Head functions should be defined asforsummarise_item() applied to data with columnsgame,player1,score1,player2,score2.

See Also

Long format of Head-to-Head values.

Common Head-to-Head functions.

Examples

# Only first function is usedncaa2005 %>%  h2h_mat(    mean_score = mean(score1),    mean_abs_score = mean(abs(score1 - score2))  )ncaa2005[-(1:2), ] %>%  h2h_mat(mean_score = mean(score1), fill = 0)

Results of Harry Potter Books Survey

Description

hp_survey contains results of the survey with a goal to collect data enoughto rate Harry Potter books.

Usage

hp_survey

Format

Atibble with answers from 182 respondents and thefollowing columns:

Rows are ordered by person and then by book identifier.

Details

Survey was done viaGoogle Forms service. Toparticipate in it, respondent is asked to log in into her/his Google account(to ensure that one person takes part only once). It was popularized mostlyamong R users viaR-bloggers andTwitter.

At the beginning of the survey, there was the following text:

This is a survey with goal to collect data enough to rate Harry Potter books.Data will be made public with complete anonymity of respondents. Please, takepart only if you have read all seven original J. K. Rowling Harry Potterbooks and are willing to give an honest feedback about your impressions.

Analyzed books were coded with the following names:

Survey had the following procedure:


Compute item summary

Description

Functions for computing item summary, i.e. some summary measurements (ofarbitrary nature) of item (one or more columns) present in data frame.

Usage

summarise_item(tbl, item, ..., .prefix = "")summarise_game(tbl, ..., .prefix = "")summarise_player(tbl, ..., .prefix = "")summarize_item(tbl, item, ..., .prefix = "")summarize_game(tbl, ..., .prefix = "")summarize_player(tbl, ..., .prefix = "")

Arguments

tbl

Data frame.

item

Character vector of columns to group by.

...

Name-value pairs of summary functions (as indplyr::summarise).

.prefix

A string to be added to all summary functions' names.

Details

Basically,summarise_item() performs the following steps:

summarise_game() andsummarise_player() are wrappers forsummarise_item() usingitem = "game" anditem = "player" respectively.

Value

Output ofsummarise() as not groupedtibble.

See Also

Common itemsummary functions for competitionresults.

Join item summary

Examples

ncaa2005 %>%  dplyr::mutate(game_type = game %% 2) %>%  summarise_item(c("game_type", "player"), mean_score = mean(score))ncaa2005 %>%  summarise_game(mean_score = mean(score), min_score = min(score))

Join item summary

Description

Functions for joining summary data to data frame. They perform respectivevariant ofsummarise item functions and thenleft join to the input its result (byitem columns).

Usage

join_item_summary(tbl, item, ..., .prefix = "")join_game_summary(tbl, ..., .prefix = "")join_player_summary(tbl, ..., .prefix = "")

Arguments

tbl

Data frame.

item

Character vector of columns to group by.

...

Name-value pairs of summary functions (as indplyr::summarise).

.prefix

A string to be added to all summary functions' names.

Details

join_game_summary() andjoin_player_summary() are wrappers forjoin_item_summary() usingitem = "game" anditem = "player"respectively.

Value

Result ofleft_join() to the input data frame.

See Also

Compute item summary

Common itemsummary functions for competition results.

Examples

ncaa2005 %>% join_player_summary(player_mean_score = mean(score))

Levels of vector

Description

Extension oflevels() function. Iflevels(x) is notNULL, it isreturned. Otherwise, character representation of unique sorted values isreturned (withNA treated based onna.last as insort()).

Usage

levels2(x, na.last = TRUE)

Arguments

x

An object of interest.

na.last

Argument for controlling the treatment ofNAs. Seesort().

Examples

fac_vec <- factor(c("a", "b"), levels = c("a", "b", "c"))levels2(fac_vec)levels2(c(10, 1, 2, NA, 11))

Long format of competition results

Description

Functions for dealing with competition results in long format.

Usage

is_longcr(cr_data)as_longcr(cr_data, repair = TRUE, ...)## S3 method for class 'longcr'as_tibble(x, ...)

Arguments

cr_data

Data of competition results (convertible to tabular).

repair

Whether to repair input.

...

Additional arguments to be passed to or from methods.

x

Object to be converted totibble.

Details

as_longcr() is S3 method for converting data tolongcr. Whenusingdefault method ifrepair isTRUE it also tries to fix possibleproblems (see "Repairing"). Ifrepair isFALSE it convertscr_data totibble and addslongcr class to it.

When applyingas_longcr() to proper (check viais_widecr() is made)widecr object, conversion is made:

For appropriatelongcr objectsas_longcr() returns its input andthrows error otherwise.

Value

is_longcr() returnsTRUE if its argument is appropriate object ofclasslongcr: it should inherit classeslongcr,tbl_df (in otherwords, to betibble) and have "game", "player", "score"among column names.

as_longcr() returns an object of classlongcr.

as_tibble() applied tolongcr object dropslongcrclass.

Long format of competition results

It is assumed that competition consists from multiple games (matches,comparisons, etc.). One game can consist fromvariable number ofplayers. Inside a game all players are treated equally.In every game every player has some score: the value of arbitrary naturethat fully characterizes player's performance in particular game (in mostcases it is some numeric value).

longcr inherits fromtibble. Data should have at least three columns withthe following names:

Extra columns are allowed.Note that if object is converted towidecr, they will be dropped. So it is better to storeextra information about "game"-"player" pair as list-column "score" whichwill stay untouched.

Repairing

Optionrepair = TRUE (default) inas_longcr() means that its result isgoing to be repaired with following actions:

See Also

Wide format

Examples

# Repairing examplecr_data <- data.frame(  playerscoregame_ID = rep(1:5, times = 2),  gameId = rep(1:5, each = 2),  scoreS = 31:40,  scoreSS = 41:50)cr_data_long <- as_longcr(cr_data, repair = TRUE)is_longcr(cr_data_long)as_tibble(cr_data_long)

Example competition results from 2005 NCAA football season

Description

ncaa2005 is an example competition results of an isolated group ofAtlantic Coast Conference teams provided in book "Who's #1" by Langville andMeyer.

Usage

ncaa2005

Format

An object of classlongcr containing informationabout 10 games.


Compute number of wins

Description

Function to accompanynum_wins andnum_wins2 inh2h_funs. May be usefulfor outer usage.

Usage

num_wins(score_1, score_2, half_for_draw = FALSE, na.rm = TRUE)

Arguments

score_1

Vector of scores for first player.

score_2

Vector of scores for second player.

half_for_draw

UseTRUE to add half the matchups with draws.

na.rm

UseTRUE to not count pair of scores with at least oneNA.


Competition results with games between two players

Description

Functions for competition results with games between two players.

Usage

to_pairgames(cr_data)is_pairgames(cr_data)

Arguments

cr_data

Competition results in format ready foras_longcr().

Details

Pairgames is a term for competition results with games between twoplayers.

to_pairgames() is a function that converts competition results intopairwise games: it drops games with one player and for every game with 3 andmore players this function transforms it into set of separate games betweenunordered pairs of players. In other words the result is a set of unorderedmatchups (as different games) between differentplayers.

Important notes:

Value

to_pairgames() returns a competition results of pairwise games aswidecr object with two players.

is_pairgames() returns a boolean value of whethercr_data contains onlygames between two players.

Examples

cr_data <- data.frame(  game = c(rep(1:5, each = 3), 6),  player = c(rep(1:5, times = 3), 1),  score = 101:116,  extraCol = -(1:16))to_pairgames(cr_data)# Missing valuescr_data_na <- data.frame(  game = rep(1L, 3),  player = c(1, NA, NA),  score = 1:3)to_pairgames(cr_data_na)# Checksis_pairgames(cr_data)is_pairgames(to_pairgames(cr_data))

Objects exported from other packages

Description

These objects are imported from other packages. Follow the linksbelow to see their documentation.

tibble

as_tibble


Common item summary functions

Description

List of commonly used functions for summarising competition results.

Usage

summary_funs

Format

An object of classlist of length 8.

Details

summary_funs is a named list ofexpressionsrepresenting commonly used expressions of summary functions for summarisingcompetition results withsummarise_item(). Names of the elements will beused as summary names. It is designed primarily to be used withlong format of competition results. To use them insidesummarise_item()useunquoting mechanism from rlang package.

Currently present functions:

Note that it is generally better to subsetsummary_funs using namesrather than indices because the order of elements might change in futureversions.

See Also

Compute item summary,Join item summary

Examples

ncaa2005 %>% summarise_game(!!!summary_funs, .prefix = "game_")

Tidy eval helpers

Description

These functions provide tidy eval-compatible ways to capture symbols(sym(),syms()), expressions (expr(),enexpr()), and quosures(quo(),enquo()).


Wide format of competition results

Description

Functions for dealing with competition results in wide format.

Usage

is_widecr(cr_data)as_widecr(cr_data, repair = TRUE, ...)## S3 method for class 'widecr'as_tibble(x, ...)

Arguments

cr_data

Data of competition results (convertible to tabular).

repair

Whether to repair input.

...

Additional arguments to be passed to or from methods.

x

Object to be converted totibble.

Details

as_widecr() is S3 method for converting data towidecr. Whenusingdefault method ifrepair isTRUE it also tries to fixpossible problems (see "Repairing"). Ifrepair isFALSE it convertscr_data totibble and addswidecr class to it.

When applyingas_widecr() to proper (check viais_longcr() is made)longcr object, conversion is made:

For appropriatewidecr objectsas_widecr returns its input andthrows error otherwise.

Value

is_widecr() returnsTRUE if its argument is appropriate objectof classwidecr: it should inherit classeswidecr,tbl_df (in otherwords, to betibble) and have complete pairs of"player"-"score" columns where pair is detected bydigits after strings"player" and "score" respectively. Columns of "player" and "score" typesshouldn't have any extra symbols except type name and digits after it. Allother columns are considered as "extra columns".

as_widecr() returns an object of classwidecr.

as_tibble() applied towidecr object dropswidecrclass.

Wide format of competition results

It is assumed that competition consists from multiple games (matches,comparisons, etc.). One game can consist only fromconstant numberof players. Inside a game all players are treated equally.In every game every player has some score: the value of arbitrary naturethat fully characterizes player's performance in particular game (in mostcases it is some numeric value).

widecr inherits fromtibble. Data should be organized in pairs of columns"player"-"score". Identifier of a pair should go after respective keyword andconsist only from digits. For example: player1, score1, player2, score2.Order doesn't matter. Extra columns are allowed.

To account for R standard string ordering, identifiers of pairs should beformatted with leading zeros (when appropriate). For example: player01,score01, ..., player10, score10.

Columngame for game identifier is optional. If present it will be used inconversion tolongcr format viaas_longcr().

Repairing

Optionrepair = TRUE (default) inas_widecr() means that its result isgoing to be repaired with following actions:

See Also

Long format

Examples

cr_data <- data.frame(  playerA = 1:10,  playerB = 2:11,  scoreC = 11:20,  scoreB = 12:21,  otherColumn = 101:110)cr_data_wide <- as_widecr(cr_data, repair = TRUE)is_widecr(cr_data_wide)as_tibble(cr_data_wide)

[8]ページ先頭

©2009-2025 Movatter.jp