Adds soccer pitch markings as a layer for use in a ggplot plot.

Description

Adds soccer pitch markings as a layer for use in a ggplot plot.

Usage

annotate_pitch(
  colour = "dimgray",
  fill = "white",
  limits = TRUE,
  dimensions = pitch_opta,
  goals = goals_box,
  linewidth = 0.5,
  alpha = 1,
  linetype = "solid"
)

Arguments

Value

list of ggplot geoms to be added to a ggplot plot

Examples

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

Description

Adds an arrow indicating the direction of play to a ggplot plot

Usage

direction_label(
  x_label = 50,
  y_label = -3,
  label_length = 20,
  colour = "dimgray",
  linewidth = 0.5,
  linetype = "solid",
  text_size = 3
)

Arguments

Value

list of ggplot layers to be added to a ggplot plot

Examples

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()

Goals markings

Description

Various functions can be supplied to annotate_pitch to specify the appearance of goals in the resulting plot.

Usage

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
)

Arguments

Details

Each function takes colour, fill, and dimensions arguments. User-defined functions with the same arguments can also be used

Value

list of ggplot geoms to be added to a ggplot plot

Examples

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()

Create Tracab dimensions object from pitch length and width

Description

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).

Usage

make_pitch_tracab(length = 105, width = 68)

Arguments

Value

A named list of pitch marking coordinates.

See Also

pitch_tracab

Examples

library(ggplot2)
library(ggsoccer)

ggplot() +
  annotate_pitch(dimensions = make_pitch_tracab(110, 70)) +
  theme_pitch()

Pitch dimensions

Description

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.

Usage

pitch_opta

pitch_statsperform

pitch_statsbomb

pitch_wyscout

pitch_international

pitch_tracab

pitch_impect

Format

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.

Details

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

See Also

make_pitch_tracab

Examples

library(ggplot2)
library(ggsoccer)

ggplot() +
  annotate_pitch(dimensions = pitch_statsbomb) +
  theme_pitch()

Rescale x-y coordinates

Description

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.

Usage

rescale_coordinates(from, to)

rescale_international(from)

Arguments

Details

pitch_international creates a rescaler to pitch_international coordinates.

Examples

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)

Removes background and axes details from a ggplot plot.

Description

Functionally very similar to ggplot2::theme_void.

Usage

theme_pitch(aspect_ratio = 68/105)

Arguments

Value

list of ggplot themes to be added to a ggplot plot

Examples

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)