| Title: | Plot Soccer Event Data |
|---|---|
| Description: | The 'ggplot2' package provides a powerful set of tools for visualising and investigating data. The 'ggsoccer' package provides a set of functions for elegantly displaying and exploring soccer event data with 'ggplot2'. Providing extensible layers and themes, it is designed to work smoothly with a variety of popular sports data providers. |
| Authors: | Ben Torvaney [aut, cre] |
| Maintainer: | Ben Torvaney <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.2.0 |
| Built: | 2024-12-06 06:54:24 UTC |
| Source: | CRAN |
Adds soccer pitch markings as a layer for use in a ggplot plot.
annotate_pitch( colour = "dimgray", fill = "white", limits = TRUE, dimensions = pitch_opta, goals = goals_box, linewidth = 0.5, alpha = 1, linetype = "solid" )annotate_pitch( colour = "dimgray", fill = "white", limits = TRUE, dimensions = pitch_opta, goals = goals_box, linewidth = 0.5, alpha = 1, linetype = "solid" )
colour |
Colour of pitch outline. |
fill |
Colour of pitch fill. |
limits |
Whether to adjust the plot limits to display the whole pitch. |
dimensions |
A list containing the pitch dimensions to draw. See |
goals |
A function for generating goal markings. Defaults to |
linewidth |
The linewidth of the pitch markings |
alpha |
The transparency of the pitch markings and fill |
linetype |
The linetype of the pitch markings (e.g. "dotted") |
list of ggplot geoms to be added to a ggplot plot
library(ggplot2) shots_data <- data.frame(x = c(90, 85, 82, 78, 83), y = c(43, 40, 52, 56, 44)) ggplot(shots_data, aes(x = x, y = y)) + annotate_pitch() + geom_point()library(ggplot2) shots_data <- data.frame(x = c(90, 85, 82, 78, 83), y = c(43, 40, 52, 56, 44)) ggplot(shots_data, aes(x = x, y = y)) + annotate_pitch() + geom_point()
Adds an arrow indicating the direction of play to a ggplot plot
direction_label( x_label = 50, y_label = -3, label_length = 20, colour = "dimgray", linewidth = 0.5, linetype = "solid", text_size = 3 )direction_label( x_label = 50, y_label = -3, label_length = 20, colour = "dimgray", linewidth = 0.5, linetype = "solid", text_size = 3 )
x_label |
x position of the centre of the arrow on the plot |
y_label |
y position of the arrow on the plot |
label_length |
length of arrow (in x axis units) |
colour |
colour of the arrow and text |
linewidth |
thickness of the arrow |
linetype |
linetype of the arrow |
text_size |
size of label text (passed onto |
list of ggplot layers to be added to a ggplot plot
library(ggplot2) shots_data <- data.frame(x = c(90, 85, 82, 78, 83), y = c(43, 40, 52, 56, 44)) p <- ggplot(shots_data, aes(x = x, y = y)) + annotate_pitch() + geom_point() # Add direction of play label p + direction_label()library(ggplot2) shots_data <- data.frame(x = c(90, 85, 82, 78, 83), y = c(43, 40, 52, 56, 44)) p <- ggplot(shots_data, aes(x = x, y = y)) + annotate_pitch() + geom_point() # Add direction of play label p + direction_label()
Various functions can be supplied to annotate_pitch to specify the appearance
of goals in the resulting plot.
goals_box( colour, fill, dimensions, linewidth = 1, alpha = 1, linetype = "solid", offset = 2, ... ) goals_strip( colour, fill, dimensions, linewidth = 1, alpha = 1, linetype = "solid", offset = 1, lineend = "round", ... ) goals_line( colour, fill, dimensions, ..., linewidth = 1, linetype = NULL, relative_width = 3 )goals_box( colour, fill, dimensions, linewidth = 1, alpha = 1, linetype = "solid", offset = 2, ... ) goals_strip( colour, fill, dimensions, linewidth = 1, alpha = 1, linetype = "solid", offset = 1, lineend = "round", ... ) goals_line( colour, fill, dimensions, ..., linewidth = 1, linetype = NULL, relative_width = 3 )
colour |
Colour of pitch outline. |
fill |
Colour of pitch fill. |
dimensions |
A list containing the pitch dimensions to draw. See |
linewidth |
Determines line thickness in |
alpha |
Determines alpha in |
linetype |
Determines linetype in |
offset |
Determines how deep the goal extends. |
... |
Passed onto underlying |
lineend |
Determines lineend in |
relative_width |
Determines relative width of the goal marking to the pitch markings in |
Each function takes colour, fill, and dimensions arguments. User-defined
functions with the same arguments can also be used
list of ggplot geoms to be added to a ggplot plot
library(ggplot2) shots_data <- data.frame(x = c(90, 85, 82, 78, 83), y = c(43, 40, 52, 56, 44)) # Default ggplot(shots_data, aes(x = x, y = y)) + annotate_pitch(goals = goals_box) + geom_point() # Other goals markings ggplot(shots_data, aes(x = x, y = y)) + annotate_pitch(goals = goals_strip) + geom_point() # Partial functions can be used to customise further ggplot(shots_data, aes(x = x, y = y)) + annotate_pitch(goals = ~ goals_box(..., offset = 4)) + geom_point()library(ggplot2) shots_data <- data.frame(x = c(90, 85, 82, 78, 83), y = c(43, 40, 52, 56, 44)) # Default ggplot(shots_data, aes(x = x, y = y)) + annotate_pitch(goals = goals_box) + geom_point() # Other goals markings ggplot(shots_data, aes(x = x, y = y)) + annotate_pitch(goals = goals_strip) + geom_point() # Partial functions can be used to customise further ggplot(shots_data, aes(x = x, y = y)) + annotate_pitch(goals = ~ goals_box(..., offset = 4)) + geom_point()
When the actual length and width of a pitch are known,
for example from Tracab file metadata, make_pitch_tracab can be
used to replace the 105m x 68m defaults hardcoded in pitch_tracab.
The remaining pitch markings are taken from the
UEFA Category 4 standard (pitch_international).
make_pitch_tracab(length = 105, width = 68)make_pitch_tracab(length = 105, width = 68)
length |
Length of the pitch in metres |
width |
Width of the pitch in metres |
A named list of pitch marking coordinates.
pitch_tracab
library(ggplot2) library(ggsoccer) ggplot() + annotate_pitch(dimensions = make_pitch_tracab(110, 70)) + theme_pitch()library(ggplot2) library(ggsoccer) ggplot() + annotate_pitch(dimensions = make_pitch_tracab(110, 70)) + theme_pitch()
The coordinate system used to generate pitch markings in
can be customised by supplying a pitch specification to the dimensions
argument of annotate_pitch.
ggsoccer provides pitch specifications for a few popular data providers by default. However, user-defined specifications can also be used.
pitch_opta pitch_statsperform pitch_statsbomb pitch_wyscout pitch_international pitch_tracab pitch_impectpitch_opta pitch_statsperform pitch_statsbomb pitch_wyscout pitch_international pitch_tracab pitch_impect
An object of class list of length 10.
An object of class list of length 10.
An object of class list of length 11.
An object of class list of length 10.
An object of class list of length 11.
An object of class list of length 11.
An object of class list of length 11.
A "pitch specification" is simply a list of dimensions that define a coordinate system. The required dimensions are:
"length": The length of the pitch from one goal to the other (x axis)
"width": The width of the pitch from touchline to the other (y axis)
"penalty_box_length": The distance from the goalline to the edge of the penalty area
"penalty_box_width": The width of the penalty area
"six_yard_box_length": The distance from the goalline to the edge of the six-yard box
"six_yard_box_width": The width of the six-yard box
"penalty_spot_distance": The distance from the goalline to the penalty spot
"goal_width": The distance from one goal post to the other
"origin_x": The minimum x coordinate of the pitch
"origin_y": The minimum y coordinate of the pitch
"penalty_arc_radius": The radius of the arc above the penalty box (Optional). Defaults to penalty_spot_distance
The following pitch dimensions are provided:
"pitch_statsperform": For StatsPerform/Opta f24 data
"pitch_opta": Alias for "pitch_statsperform"
"pitch_statsbomb": For Statsbomb data
"pitch_wyscout": For Wyscout data
"pitch_international": As per UEFA Category 4 stadium regulations
"pitch_tracab": "For ChyronHego Tracab, using the 105m x 68m default size"
"pitch_impect": For IMPECT data
make_pitch_tracab
library(ggplot2) library(ggsoccer) ggplot() + annotate_pitch(dimensions = pitch_statsbomb) + theme_pitch()library(ggplot2) library(ggsoccer) ggplot() + annotate_pitch(dimensions = pitch_statsbomb) + theme_pitch()
Returns a list containing 2 functions to translate x and y coordinates, from one set of pitch dimensions (i.e. data provider) to another.
Any x or y coordinate is rescaled linearly between the nearest two pitch markings. For example, the edge of the penalty box and the half way-line.
rescale_coordinates(from, to) rescale_international(from)rescale_coordinates(from, to) rescale_international(from)
from |
The dimensions to convert from (see |
to |
The dimensions to convert to (see |
pitch_international creates a rescaler to pitch_international
coordinates.
opta_to_wyscout <- rescale_coordinates( from = pitch_opta, to = pitch_wyscout ) opta_xs <- c(10, 22, 55, 78) opta_ys <- c(10, 22, 55, 78) opta_to_wyscout$x(opta_xs) #> c(9.75000, 21.15152, 55.15152, 78.84848) opta_to_wyscout$y(opta_ys) #> c(9.004739, 20.031847, 55.172414, 79.968153)opta_to_wyscout <- rescale_coordinates( from = pitch_opta, to = pitch_wyscout ) opta_xs <- c(10, 22, 55, 78) opta_ys <- c(10, 22, 55, 78) opta_to_wyscout$x(opta_xs) #> c(9.75000, 21.15152, 55.15152, 78.84848) opta_to_wyscout$y(opta_ys) #> c(9.004739, 20.031847, 55.172414, 79.968153)
Functionally very similar to ggplot2::theme_void.
theme_pitch(aspect_ratio = 68/105)theme_pitch(aspect_ratio = 68/105)
aspect_ratio |
Aspect ratio ( |
list of ggplot themes to be added to a ggplot plot
library(ggplot2) shots_data <- data.frame(x = c(90, 85, 82, 78, 83), y = c(43, 40, 52, 56, 44)) p <- ggplot(shots_data, aes(x = x, y = y)) + annotate_pitch() + geom_point() # Pitch fixed to 68/105 by default p + theme_pitch() # Free aspect p + theme_pitch(aspect_ratio = NULL)library(ggplot2) shots_data <- data.frame(x = c(90, 85, 82, 78, 83), y = c(43, 40, 52, 56, 44)) p <- ggplot(shots_data, aes(x = x, y = y)) + annotate_pitch() + geom_point() # Pitch fixed to 68/105 by default p + theme_pitch() # Free aspect p + theme_pitch(aspect_ratio = NULL)