README.Rmd

---
output: github_document
---

<!-- 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%"
)
options(tibble.print_min = 5, tibble.print_max = 5)
```

#worldfootballR

<!-- badges: start -->
[![Travis build status](https://travis-ci.org/JaseZiv/worldfootballR.svg?branch=main)](https://travis-ci.org/JaseZiv/worldfootballR)
<!-- badges: end -->

## Overview

This package is designed to allow users to extract various world football results and player statistics data from fbref.com


## Installation

You can install the `worldfootballR` package from github with:

```{r gh-installation, eval=FALSE}
# install.packages("devtools")
devtools::install_github("JaseZiv/worldfootballR")
```

```{r load_libs, warning=FALSE, message=FALSE}
library(worldfootballR)
library(tidyverse)
```


## Usage

The functions available in this package are designed to enable the extraction of world football data.

There are three main categories of data extract functions in this package:

* Match-level statistics (team and player)
* Season-level statistics (team and player)
* League / Team metadata

### Match-level statistics

#### Get match results

To get the match results (and additional metadata) for all games for a tier-1 league season, the following function can be used:

```{r get_match_results}
# function to extract chess.com game data
serieA_2020 <- get_match_results(country = "ITA", gender = "M", season_end_year = 2020)
glimpse(serieA_2020)
```

**More than one league season**

The `get_match_results` function can be used to get data for multiple seasons/leages/genders/etc also:

```{r get_match_results_multiple, eval=FALSE}
big_5_2020_results <- get_match_results(country = c("ENG", "ESP", "ITA", "GER", "FRA"),
                                        gender = "M", season_end_year = 2020)
```


#### Get match report

This function will return similar results to that of `get_match_results()`, however `get_match_report()` will provide some additional information. It will also only provide it for a single match, not the whole season:  

```{r get_match_report}
# function to extract chess.com game data
liv_mci_2020 <- get_match_report(match_url = "https://fbref.com/en/matches/47880eb7/Liverpool-Manchester-City-November-10-2019-Premier-League")
glimpse(liv_mci_2020)
```


#### Get advanced match statistics

The `get_advanced_match_stats` function allows the user to return a data frame of different stat types for matches played.

Note, some stats may not be available for all leagues. The big five European leagues should have all of these stats.

The following stat types can be selected:

* *summary*
* *passing*
* *passing_types*
* *defense*
* *possession*
* *misc*
* *keeper*

The function can be used for either all players individually:

```{r get_advanced_match_stats}
test_urls_multiple <- c("https://fbref.com/en/matches/c0996cac/Bordeaux-Nantes-August-21-2020-Ligue-1",
                        "https://fbref.com/en/matches/9cbccb37/Dijon-Angers-August-22-2020-Ligue-1",
                        "https://fbref.com/en/matches/f96cd5a0/Lorient-Strasbourg-August-23-2020-Ligue-1")

advanced_match_stats <- get_advanced_match_stats(match_url = test_urls_multiple, stat_type = "possession", team_or_player = "player")
glimpse(advanced_match_stats)
```


Or used for the team totals for each match:

```{r get_advanced_match_stats_team}
test_urls_multiple <- c("https://fbref.com/en/matches/c0996cac/Bordeaux-Nantes-August-21-2020-Ligue-1",
                        "https://fbref.com/en/matches/9cbccb37/Dijon-Angers-August-22-2020-Ligue-1",
                        "https://fbref.com/en/matches/f96cd5a0/Lorient-Strasbourg-August-23-2020-Ligue-1")

advanced_match_stats_team <- get_advanced_match_stats(match_url = test_urls_multiple, stat_type = "passing_types", team_or_player = "team")
glimpse(advanced_match_stats_team)
```


#### Get match lineups

This function will return a dataframe of all players listed for that match, including whether they started on the pitch, or on the bench.  

```{r get_match_lineups}
# function to extract chess.com game data
liv_mci_2020_lineups <- get_match_lineups(match_url = "https://fbref.com/en/matches/47880eb7/Liverpool-Manchester-City-November-10-2019-Premier-League")
glimpse(liv_mci_2020_lineups)
```

***

### Season-level statistics


#### Get Season Team Stats

The `get_season_team_stats` function allows the user to return a data frame of different stat types for all teams in tier-1 league seasons.

Note, some stats may not be available for all leagues. The big five European leagues should have all of these stats.

The following stat types can be selected:

* *league_table*
* *league_table_home_away*
* *standard*
* *keeper*
* *keeper_adv*
* *shooting*
* *passing*
* *passing_types*
* *goal_shot_creation*
* *defense*
* *possession*
* *playing_time*
* *misc*

```{r get_season_team_stats}
# function to extract season teams stats
prem_2020_shooting <- get_season_team_stats(country = "ENG", gender = "M", season_end_year = "2020", stat_type = "shooting")
glimpse(prem_2020_shooting)
```


**More than one league season**

The `get_season_team_stats` function can be used to get data for multiple seasons/leages/genders/etc.

Important to note, this function can only be used for one `stat-type` at a time, however all other parameters can have multiple values:

```{r get_season_team_stats_multiple, eval=FALSE}
big_5_2020_possessions <- get_season_team_stats(country = c("ENG", "ESP", "ITA", "GER", "FRA"),
                                        gender = "M", season_end_year = 2020, stat_type = "possession")
```

***

## Contributing

### Issues and Feature Requests

Issues, feature requests and improvement ideas are all welcome.

When reporting an issue, please include:

* Reproducible examples
* A brief description of what the expected results are
* If applicable, the fbref.com page the observed behaviour is occuring on

For feature requests, raise an issue with the following:

* The desired functionality
* Example inputs and desired output


### Pull Requests
Pull requests are also welcomed. Before doing so, please create an issue or email me with your idea.

Any new functions should follow the conventions established by the the package’s existing functions. Please ensure:

* Functions are sensibly named
* The intent of the contribution is clear
* At least one example is provided in the documentation