---
title: "Pi Ratings"
author: "Lars Van Cutsem"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{README}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

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

<!-- badges: start -->
<!-- badges: end -->

The goal of piratings is to calculate dynamic performance ratings for association football teams in a competitive match setting. The pi rating system takes into account the team's performance in recent matches, the well-known home advantage effect and, the fact that a win is more important than increasing the score difference. The dynamic rating system has proven to obtain superior results in predicting the outcome of association football matches.


The pi rating system was developed by Constantinou and Fenton in the research paper "Determining the level of ability of football teams by dynamic ratings based on the relative discrepancies in scores between adversaries".  

The paper can be found [here](<http://www.constantinou.info/downloads/papers/pi-ratings.pdf>) 


## Installation

You can install the released version of piratings from [CRAN](<https://CRAN.R-project.org>) with:

``` r
install.packages("piratings")
```


## Example

```{r setup, include = FALSE}
knitr::opts_chunk$set(echo = T,
                      results = "hide")
install.packages("ggplot2", repos = "http://cran.us.r-project.org")
```

This is a basic example which shows you how to use the package:

```{r echo = T, results = "markup"}
library(piratings)

## example data from the European Soccer Dataset
## for the English Premier League during the seasons
## 2008/2009 to 2015/2016

data("EPL2008_2015")
head(EPL2008_2015)
```

We prepare the function arguments:

``` {r echo = T, results = "hide", message = F}
## prepare the function arguments:
teams <- as.matrix(EPL2008_2015[, c("home_team", "away_team")])
outcomes <- as.matrix(EPL2008_2015[, c("home_goals", "away_goals")])

grid <- optimize_pi_ratings(teams, outcomes, seq(0.04, 0.08, 0.005), seq(0.3, 0.7, 0.05))
```

Finally, we can plot the result of the grid optimization using ggplot2:

```{r echo = T, results = "markup", warning = F}
## we plot this grid using the ggplot2 library
library(ggplot2)

ggplot(data = grid, aes(x = lambda, y = gamma, fill = mean.squared.error)) + 
  geom_tile() + scale_fill_gradient2(low = "blue", mid = "white", high = "red", midpoint = 2.668) + 
  labs(x = "lambda", y = "gamma", title = "grid optimization", fill = "Mean \nsquared \nerror") + 
  theme(plot.title = element_text(hjust = 0.5))

## we find the optimal parameter settings to be
## lambda = 0.06 and gamma = 0.6

piratings <- calculate_pi_ratings(teams, outcomes, 0.06, 0.6)
tail(piratings)
```

## Data
Contains information from the European Soccer Database, which is made available
    [here](<https://www.kaggle.com/hugomathien/soccer>) under the [Open Database License](<https://opendatacommons.org/licenses/odbl/1.0/>) (ODbL) .