In telaroz/handbaloner: Utilities for handball data analysis.

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)

handbaloner

Documentación en español

The handbaloner package has useful function for the visualization of handball data.

Package installation

The development version can be installed from GitHub with:

# install.packages("devtools")
devtools::install_github("telaroz/handbaloner")

Also, the plot_paces function has as dependency the package ggflags, which is not in CRAN. So in order to use that function, that dependency should be installed (not needed to use the rest of the functions)

install.packages("ggflags", repos = c(
  "https://jimjam-slam.r-universe.dev",
  "https://cloud.r-project.org"))

Court visualization examples

In this example, we can draw a basic court.

library(handbaloner)

court()

We can change the colours, rotate vertically and mirror the court with the functions' parameters

court(vertical = TRUE, flip = TRUE, court_color = "orange", 
      area_color = "#3431A2", lines_color = "black")

As the plots are generated with ggplot, we can describe the colours with their HEX code, rgb, number or by its name in english; see: use of colours in ggplot2

We can also draw half a court

half_court(vertical = TRUE, court_color = colors()[36], 
      area_color = rgb(red = 0.2, green = 0.4, blue = 0.6), 
      lines_color = "yellow")

Another useful function is distance_to_goal which measures the distance from a point of the field to its closest goal, given some coordinates ([-40, 40] in the x axis and [-20, 20] in the y axis):

distance_to_goal(x = 10, y = 3)

Also, as this is a ggplot, we can add some additional layers. For example, let's generate a data.frame with some coordinates of shots and whether they were goals or not. We will add the distance to goal as a column and plot in green and red if the shots were goal or not.

shots <- dplyr::tibble(x = c(-13, -12, 11, -11, 9.5),
                       y = c(2, 5, -3, -1, 0),
                       goal = c(1, 0, 1, 1, 0)) |> 
  dplyr::mutate(goal = as.character(goal)) 

dplyr::mutate(shots, distance_to_goal = distance_to_goal(x, y))

court() +
  ggplot2::geom_point(data = shots, ggplot2::aes(x, y, color = goal),
                      size = 4) +
  ggplot2::scale_color_manual(values = c("0" = "red", "1" = "green"))

Goal visualization examples

In this example, we can draw a handball goal.

library(handbaloner)

draw_goal()

We can change the colour of the goal. It is red by default.

library(handbaloner)

draw_goal("blue")

Now, let's draw some shots, just as we did with the court:

goal_shots <- dplyr::tibble(x = c(-2, -1, 0.5, 0.7, 1.4),
                       y = c(0.2, 2, -0.5, 0.3, 0.9),
                       goal = c(0, 0, 1, 1, 1)) |> 
  dplyr::mutate(goal = as.character(goal)) 

draw_goal() +
  ggplot2::geom_point(data = goal_shots, ggplot2::aes(x, y, color = goal),
                      size = 4) +
  ggplot2::scale_color_manual(values = c("0" = "red", "1" = "green"))

Generate Play by Play tidy data from IHF files

First, you need to download the PBP pdf file. You can use the scrape_from_ihf function to do so. Find the link for the match information and set the folder to download the file.

For the first match of the 2023 World Men's Handball Championship, you can download all PDFs as follows:

scrape_from_ihf(link = "https://www.ihf.info/competitions/men/308/28th-ihf-men039s-world-championship-2023-polandsweden/101253/match-center/118963",
                folder = "ejemplo")

Now, use the generate_tidy_pbp to generate a data.frame in a tidy format.

tidy <- generate_tidy_pbp("ejemplo/47PBP.PDF")
tidy

Plot paces of both teams throughout the game

To plot the paces of both teams in 5 minute intervals, we just need to have the play by play data in a tidy format generated by the generate_tidy_pbp. The plot_paces function takes the data and the match ID we want to visualize and returns the plot.