README.Rmd

---
output:
  github_document:
    html_preview: true
---
# teamcolors <img src='man/figures/logo.png' align="right" height="139" />

<!-- badges: start -->
[![R-CMD-check](https://github.com/beanumber/teamcolors/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/beanumber/teamcolors/actions/workflows/R-CMD-check.yaml)
[![CRAN status](https://www.r-pkg.org/badges/version/teamcolors)](https://cran.r-project.org/package=teamcolors)
<!-- badges: end -->


An R package providing color palettes for pro and amateur sports teams. The palettes are provided by [Jim Neilsen's Team Colors website](http://jim-nielsen.com/teamcolors/) and offered with only minimal alterations. NCAA colors come from [teamcolorcodes.com](https://teamcolorcodes.com/), via the [ncaahoopR](https://github.com/lbenz730/ncaahoopR) package.
Other sports include the [Women's National Basketball Association](https://wnba.com), [National Women's Soccer League](https://nwsl.com), and the [Canadian Football League](https://cfl.com).

## Install

To install the CRAN version, use:

```{r, eval=FALSE}
install.packages(teamcolors)
```

To install the development version from GitHub, use:

```{r, eval=FALSE}
devtools::install_github("beanumber/teamcolors")
```

## Load

```{r}
library(teamcolors)
head(teamcolors)
```

## Show palettes

Sometimes you need to work with a named vector of colors. Other times you can use the built-in `scale_color_teams()` and `scale_color_fill()` functions. 

```{r palettes}
league_pal("nba")
```

## Plot

In baseball, [Pythagorean expectation](https://en.wikipedia.org/wiki/Pythagorean_expectation) relates expected winning percentage to runs allowed and runs scored. How well does it work? 

```{r pythag, message=FALSE}
library(Lahman)
library(tidyverse)
pythag <- Teams %>%
  filter(yearID == 2016) %>%
  select(name, teamID, yearID, W, L, R, RA) %>%
  mutate(
    wpct = W / (W + L), exp_wpct = 1 / (1 + (RA / R)^2),
    # note name discrepancy!
    name = ifelse(name == "Los Angeles Angels of Anaheim", "Los Angeles Angels", name)
  )
```

### `ggplot2`

```{r ggplot}
ggplot(pythag, aes(x = wpct, y = exp_wpct, color = name, fill = name)) +
  geom_abline(slope = 1, intercept = 0, linetype = 3) +
  geom_point(shape = 21, size = 3) +
  scale_fill_teams(guide = FALSE) +
  scale_color_teams(2, guide = FALSE) +
  ggrepel::geom_text_repel(aes(label = teamID)) +
  scale_x_continuous("Winning Percentage", limits = c(0.3, 0.7)) +
  scale_y_continuous("Expected Winning Percentage", limits = c(0.3, 0.7)) +
  theme_light() +
  labs(
    title = "Real and Pythagorean winning % by team",
    subtitle = paste(first(pull(pythag, yearID)), "MLB Season", sep = " "),
    caption = "Source: Lahman baseball database. Using teamcolors R pkg"
  ) +
  coord_equal()
```

### Base R

```{r base-r, message=FALSE}
pythag <- pythag %>%
  left_join(teamcolors, by = "name")
with(pythag, plot(wpct, exp_wpct, bg = primary, col = secondary, pch = 21, cex = 3))
```


## Key

You can see the color palettes using existing functionality from the [scales](https://github.com/r-lib/scales) package, but it won't show the names of the teams. 

```{r show_col}
scales::show_col(league_pal("mlb"), borders = league_pal("mlb", 2))
```

So, instead, use `show_team_col()`. Note that this only shows color palettes for non-NCAA teams.

```{r teamcolors, fig.height=10, fig.width=10}
show_team_col()
```


To view color palettes for college teams, use the `show_ncaa_col()` function.

```{r ncaacolors, fig.height=10, fig.width=20}
show_ncaa_col()
```


## Logos

Links to team logos are provided by (http://www.sportslogos.net/).

```{r logos}
teamcolors %>%
  filter(grepl("New Y", name)) %>%
  pull(logo) %>%
  knitr::include_graphics()
```

Note that we don't have any coverage for the EPL.

```{r}
teamcolors %>%
  group_by(league) %>%
  summarize(
    num_teams = n(),
    num_logos = sum(!is.na(logo))
  )
```

## References

For more examples see: 

- Lopez, M.J., Matthews, G.J., Baumer, B.S., "How often does the best team win? A unified approach to understanding randomness in North American sport," *The Annals of Applied Statistics*, vol. 12, no. 4, 2018, pp. 2483--2516. URL (https://doi.org/10.1214/18-AOAS1165)

To cite this package in your work, see:

```{r, eval=FALSE}
citation("teamcolors")
```

## Notes