---
title: "f1pits-intro"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{f1pits-intro}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 5,       # ancho en pulgadas
  fig.height = 2.5,       # alto en pulgadas
  dpi = 120             # resolution
)
```

```{r setup}
library(f1pits)
```

# Vignette Info. Introduction:

The `f1pits` package provides datasets of Formula 1 race pit stops (since 2019), extracted from [DHL website](https://inmotion.dhl/en/formula-1/fastest-pit-stop-award) and a function to visualize pit stop data.

This package can be considered complementary to the `f1dataR` package, which provides Formula 1 race data. You can download `f1pits` package in [GitHub](https://github.com/Jordan-Soria/f1pits).

# Exemple to use:

## Step 1: Pit Stops data

To extract the pit stop data for a specific race or an entire season, use the `pits()` function. Check the documentation for the different arguments of the function.

```{r message=TRUE, warning=TRUE}
# Accessing the data, for example, round 1, Australian GP 2026:

pits(1, 2026) -> pitdata

pitdata
```

The output generated is a tibble containing the columns:

**Pos.** (position according to pit stop time), **Team**, **Driver**, **Time (sec)** is the time (in seconds) of each pitstop, **Lap** (lap of the race; does NOT include sprint sessions), and **Points** (DHL points. If a driver makes more than one pit stop among the top 10 fastest, the second and subsequent pit stops by that driver do not receive points).

## Step 2: ELO team calculations

You can calculate ELO ratings of each team from a pit stop dataset, using a single race or multiple races from the one or different seasons with `pitelo()` function.

```{r message=TRUE, warning=TRUE}
pitelo(pitdata)
```

The ELO calculation is the *mean*, *median*, or *minimum* pit stop position of the teams in each race (see `stat_fun` argument). On the other hand, two methodologies can be applied for ELO calculation: *sequential* or *batch* (see `calc` argument).

Also you can adjust the magnitude of the ELO change per race (`k`) and the scaling factors (`c` and `d`). The default values in `pitelo()` are based on [Hvattum and Arntzen (2010)](https://doi.org/10.1016/j.ijforecast.2009.10.002).

```{r message=TRUE, warning=TRUE}
pitelo(pitdata, stat_fun = 3, calc = 2, k = 40, c = 20, d = 1000)
```

The different names that the same F1 team structure has had over the years will be collapsed by default into the last used in the dataset, for example: Toro Rosso (2019) → AlphaTauri (2020-2023) → RB (2024) → Racing Bulls (2025-2026).

```{r message=TRUE, warning=TRUE}
pits(1, 2024) -> pitdata24

pits(1, 2025) -> pitdata25

# Join datasets:
pitdata_multiple <- dplyr::bind_rows(pitdata, pitdata24, pitdata25)

# Show all teams in dataset:
unique(pitdata_multiple$Team)

pitelo(pitdata_multiple, fml = TRUE)

pitelo(pitdata_multiple, fml = FALSE)
```

Additionally, you can provide your own ELO rating to initialize the calculations in the function (MUST have the same structure type as in this example).

```{r message=TRUE, warning=TRUE}
# Create an ELO tibble with a starting value of 1000 for all teams, except Cadillac.
# As a new team it will be slightly penalized 
# because its team structure is completely new.

elo_data <- tibble::tibble(
    Team = c("Ferrari", "Red Bull", "Mercedes", "Racing Bulls", "McLaren",
             "Haas", "Alpine", "Williams", "Audi", "Aston Martin", "Cadillac"),
    Rating = c(1000, 1000, 1000, 1000, 1000,
               1000, 1000, 1000, 1000, 1000, 950))

elo_data

str(elo_data)

pitelo(pitdata, elo = elo_data)
```

## Step 3 (if you want): Plotting

The `f1pits` package includes the `pitplot()` function, which takes the data obtained from `pits()` and produces a ggplot object to visualize pit stop performance. Remember that if you want to provide your own data, the input must be a tibble (see the documentation of `pits()`). Check the documentation for the different arguments of `pitplot()` before using it.

```{r message=TRUE, warning=TRUE}
# Plotting the data:

pitplot(pitdata, 2) -> pitplot_pitdata

pitplot_pitdata
```

Finally, if you want a fun text for your plot, run the `pitart()` function in the `title_text` argument: 

```{r message=TRUE, warning=TRUE, fig.height=4}

pitplot(pitdata, 2, title_text = paste0(pitart(3), "    Pit Stop data")) -> pitplot_pitdata_title_edit

pitplot_pitdata_title_edit
```

# Citation

This package makes extensive use of **'dplyr'** for data manipulation and **'ggplot2'** for plotting the data. **'httr'** and **'jsonlite'** also to access my repository data. **'f1dataR'** has inspired me to create this package as a complement.

<hr>

`r format(citation("f1pits"))`