https://github.com/sportsdataverse/sportyR

R package for drawing regulation playing surfaces for several sports

https://github.com/sportsdataverse/sportyR

Keywords

Repository

R package for drawing regulation playing surfaces for several sports

README.Rmd

---
output: github_document
editor_options: 
  markdown: 
    wrap: 72
---



```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  cache = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%",
  dpi = 600
)
```

# sportyR 


[![CRAN
version](https://img.shields.io/badge/dynamic/json?style=flat&color=ff552e&label=CRAN version&prefix=v&query=%24.Version&url=https%3A%2F%2Fcrandb.r-pkg.org%2FsportyR)](https://CRAN.R-project.org/package=sportyR)
[![CRAN
downloads](https://img.shields.io/badge/dynamic/json?style=flat&color=ff552e&label=Downloads&query=%24[0].downloads&url=https%3A%2F%2Fcranlogs.r-pkg.org%2Fdownloads%2Ftotal%2F2021-10-26%3Alast-day%2FsportyR)](https://CRAN.R-project.org/package=sportyR)
[![Version-Number](https://img.shields.io/github/r-package/v/sportsdataverse/sportyR?label=sportyR&logo=R&style=flat&color=ff552e&logoColor=1d9bf0)](https://github.com/sportsdataverse/sportyR/)
[![R-CMD-check](https://img.shields.io/github/workflow/status/sportsdataverse/sportyR/R-CMD-check?label=R-CMD-Check&logo=R&&style=flat&logoColor=1d9bf0)](https://github.com/sportsdataverse/sportyR/actions/workflows/R-CMD-check.yaml)
[![codecov](https://img.shields.io/codecov/c/github/sportsdataverse/sportyR?color=ff552e&label=codecov&logo=codecov)](https://codecov.io/gh/sportsdataverse/sportyR)
[![Lifecycle:maturing](https://img.shields.io/badge/lifecycle-maturing-blue.svg?style=flat&logo=github&color=ff552e)](https://github.com/sportsdataverse/sportyR/)
[![Twitter
Follow](https://img.shields.io/twitter/follow/sportyR_pkg?&label=%40sportyR_pkg&logo=twitter&style=flat&color=ff552e)](https://twitter.com/sportyR_pkg)
[![Twitter
Follow](https://img.shields.io/twitter/follow/sportsdataverse?&label=%40sportsdataverse&logo=twitter&style=flat&color=ff552e)](https://twitter.com/sportsdataverse)



As the field of sports analytics evolve, there's a growing need for
methods to both track and visualize players throughout the game. This
package aims to make this easy regardless of sport needed to be plotted.

This repository contains code necessary to draw scale versions of playing surfaces to visualize play-by-play data for baseball, basketball, curling, football, hockey, soccer, and tennis in **R**. For the **Python** version of this package, click [here](https://github.com/sportsdataverse/sportypy).


## Installation

The most recent release of `sportyR` is available on
[CRAN](https://cran.r-project.org/web/packages/sportyR/index.html), and
it can be installed directly via:

```{r readme-install-package-cran, eval = FALSE}
# Install released version from CRAN
install.packages("sportyR")
```

The development version of `sportyR` can be installed from
[GitHub](https://github.com/sportsdataverse/sportyR) with:

```{r readme-install-package-github, eval = FALSE}
# Install development version from GitHub
devtools::install_github("sportsdataverse/sportyR")
```

Once the library is installed, be sure to load it into the working
environment.

```{r readme-load-sportyR}
# Required to use package
library(sportyR)
```

## Plotting Functions {#plotting-functions}

All plotting functions in this library are named as `geom_{sport}()`,
and take the following arguments:

-   `league`: the league code for the sport. In all functions, this will
    ***NOT*** have a default value. The supplied league is
    **case-insensitive**. Future iterations of this package may allow
    the full league name to be supplied if desired (e.g.
    `league = 'National Basketball Associaton'` instead of
    `league = 'NBA'`), but this feature is not currently available.

-   `display_range`: This automatically "zooms" in on the area of the
    plot you're interested in. Valid ranges here vary by sport, but can
    be found by calling `?geom_{sport}` and reading about the display
    ranges

-   `x_trans` and `y_trans`: By default, the origin of the coordinate
    system *always* lies at the center of the plot. For example,
    `(0, 0)` on a basketball court lies along the division line and on
    the line that connects the center of each basket. If you want to
    shift the origin (and therefore the entire plot), use `x_trans` and
    `y_trans` to do so

-   `{surface_type}_updates`: A list of updates to the parameters that
    define the surface. I'll demo how to use this to change a hockey
    rink in a different vignette, but I'll call this out here

-   `color_updates`: A list that contains updates to the features'
    colors on the plot. These are named by what the feature is, using
    `snake_case` to specify the names. To get the list of color names
    you can change, try running `cani_color_league_features()` with your
    desired league

-   `rotation`: An angle (in degrees) that you'd like to rotate the plot
    by, where +\theta is counterclockwise

-   `xlims` and `ylims`: Any limits you'd like to put on the plot in the
    x and y direction. These will overwrite anything set by the
    `display_range` parameter

-   `{surface}_units`: If your data is in units that are different than
    how the rule book of the league specifies the units (e.g. you've got
    NHL data in inches, but the rule book describes the rink in feet),
    change this parameter to match the units you've got your data in.
    You're welcome to change the units of the data as well, but this is
    provided for convenience

## TV View and Display Ranges

### TV View

All of the `geom_{sport}()` functions, by default, will draw the surface
in what can be considered "TV view", or the way that the surface would
typically be displayed on a television broadcast. This typically means
the action moves from left to right across the screen (a basketball game
that has the baskets on the left and right end of the court). As
mentioned above, it is possible to change this to be in any orientation
through the `rotation` parameter to each `geom_{sport}()` function.

There are a few exceptions to this:

-   `geom_baseball()` is displayed from the high-home view by default,
    as baseball coordinates typically have the `+y` axis extending from
    the back tip of home plate towards center field

-   `geom_tennis()` is displayed with the court diagrammed from the
    perspective of the chair umpire

### Display Ranges

Related to the idea of custom displays of the plot is the concept of the
`display_range` parameter in the `geom_{sport}()` function. This is
unique to each sport, but globally supported across the package. This
parameter allows the specification of a designated region of the surface
to display. As an example, if you're trying to limit the analysis of NFL
data to being inside of the red zone, you may want to do something
similar to the following:

```{r readme-display-range-demo, dev = "png"}
# Display only the red zone of the football field
geom_football("nfl", display_range = "red zone")
```


Another use case would be to make the data you're viewing easier to see. Say you wanted to look at curling data, but only cared about stone positions in the house (and not the path as to how the stones got there). You might do this:

```{r readme-display-range-curling-demo, dev = "png"}
# Display only the house on a curling sheet
geom_curling("wcf", display_range = "house")
```

## Plot Units

Each plot function has a standardized unit of measure in which the plot
is created, and is standardized by the primary units specified in their
respective rule books. They are as follows (and any explanation is in
parentheses):

```{r readme-plot-units-table, echo = FALSE}
units_df <- data.frame(
  sport = c(
    rep("Baseball", 6),
    rep("Basketball", 6),
    rep("Curling", 1),
    rep("Football", 7),
    rep("Hockey", 11),
    rep("Lacrosse", 7),
    rep("Soccer", 5),
    rep("Tennis", 6),
    rep("Volleyball", 3)
  ),
  league = c(
    # Baseball
    "Little League",
    "MiLB",
    "MLB",
    "NCAA",
    "NFHS (High School)",
    "Pony",
    # Basketball
    "FIBA",
    "NBA",
    "NBA G League",
    "NCAA",
    "NFHS",
    "WNBA",
    # Curling
    "WCF (World Curling Federation)",
    # Football
    "CFL",
    "NCAA",
    "NFHS11 (High School, 11 players)",
    "NFHS6 (High School, 6 players)",
    "NFHS8 (High School, 8 players)",
    "NFHS9 (High School, 9 players)",
    "NFL",
    # Hockey
    "AHL",
    "ECHL",
    "IIHF",
    "NCAA",
    "NHL",
    "NWHL",
    "OHL",
    "PHF",
    "PWHL",
    "QMJHL",
    "USHL",
    # Lacrosse
    "NCAAM",
    "NCAAW",
    "NLL",
    "PLL",
    "USA Men's",
    "USA Women's",
    "World Lacrosse",
    # Soccer
    "EPL",
    "FIFA",
    "MLS",
    "NCAA",
    "NWSL",
    # Tennis
    "ATP",
    "ITA",
    "ITF",
    "NCAA",
    "USTA",
    "WTA",
    # Volleyball
    "FIVB",
    "NCAA",
    "USA Volleyball"
  ),
  primary_unit = c(
    rep("`ft`", 6),
    rep("`m`", 1),
    rep("`ft`", 5),
    rep("`ft`", 1),
    rep("`yd`", 7),
    rep("`ft`", 2),
    rep("`m`", 1),
    rep("`ft`", 8),
    rep("`yd`", 1),
    rep("`m`", 1),
    rep("`ft`", 1),
    rep("`yd`", 2),
    rep("`m`", 1),
    rep("`ft`", 1),
    rep("`m`", 2),
    rep("`yd`", 3),
    rep("`ft`", 6),
    rep("`m`", 3)
  )
)

names(units_df) <- c("Sport", "League", "Primary Plotting Unit")

knitr::kable(units_df, align = "c")
```

However, since the data that is supplied may come in various units of
measure, the plots are able to be generated in the data's units. This is
done via the `unit` argument in `geom_{sport}()`. The features
themselves will look visually identical, but the underlying coordinate
grid will change.

Additionally, the `convert_units()` function can be called on a data
frame to convert from the data's arguments to the plot's. For example,
if soccer data is given in yards, but is desirable to be plotted in
meters, calling
`convert_units(tracking_data, 'yd', 'm', conversion_columns = c('x', 'y'))`
will convert the x and y coordinates from yards to meters.

As mentioned [above](#plotting-functions), the `geom_{sport}()` family
of functions allow for rotations of surfaces via the `rotation`
argument. To make this easy, `sportyR` also allows for the rotation of
data frames' coordinates ***so long as they contain an*** `x` ***and***
`y` ***column*** via the `rotate_coords()` function. Reflection is also
possible through `reflect()`.

## Surface Examples

Most playing surfaces are standard in size, so they can be rendered via
a call to the proper `geom_{sport}()` function like so:

```{r readme-mlb-example}
# Draw a basic MLB infield plot
geom_baseball("mlb", display_range = "infield")
```

```{r readme-fifa-example}
# Create a 100m by 75m FIFA pitch
geom_soccer(
  "fifa",
  pitch_updates = list(
    pitch_length = 100,
    pitch_width = 75
  )
)
```

It's also possible to plot partial surfaces and rotated surfaces:

```{r readme-nhl-example}
# Draw half of a rotated NBA court
geom_basketball("nba", display_range = "offense", rotation = 270)
```

## License

This package is released under the [GPL 3.0
License](https://github.com/sportsdataverse/sportyR/blob/master/LICENSE.md).

## Contributions

### League Office

The package maintainers and functional engineers

-   [Ross Drucker](https://github.com/rossdrucker) - `sportyR`
    Commissioner

### General Managers

Contribute by adding a new sport and become its general manager. Current
general managers (and their sports) are:

-   [Ross Drucker](https://github.com/rossdrucker) - Baseball
-   [Ross Drucker](https://github.com/rossdrucker) - Basketball
-   [Ross Drucker](https://github.com/rossdrucker) - Curling
-   [Ross Drucker](https://github.com/rossdrucker) - Football
-   [Ross Drucker](https://github.com/rossdrucker) - Hockey
-   [Ross Drucker](https://github.com/rossdrucker) - Soccer
-   [Ross Drucker](https://github.com/rossdrucker) - Tennis
-   [Ross Drucker](https://github.com/rossdrucker) - Volleyball

### Coaching Staffs

Notice something for a sport that already exists, but isn't quite right?
Join that sport's coaching staff!

### Scout Team

By regularly reporting issues, making very slight modifications, fixing
typos, or just helping others navigate their own issues, you're able to
join the Scout Team!

### Acknowledgements

Much of the underling code structure in `sportyR`, beginning with
`v2.0.0`, was influenced by [The
Bucketless](https://github.com/the-bucketless)'s work on the
[hockey_rink](https://github.com/the-bucketless/hockey_rink) package for
Python.

### `sportyR`tist

The `sportyR` logo was created by Lindsey Kelso. Check her out on
[Instagram](http://Instagram.com/kelsokreationsbylindsey) or her [online
shop](http://kelsokreationsbylindsey.bigcartel.com)!

Owner

GitHub Events

Committers

Last synced: 9 months ago

Issues and Pull Requests

Last synced: 6 months ago

Packages