---
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 2025:

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). For the calculation, you can adjust the magnitude of the ELO change per race (`k`) and the scaling factor (`d`).

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

The different names that the same F1 team has had over the years will be collapsed into the last used in the dataset, for example: Toro Rosso (2019) \rightarrow AlphaTauri (2020-2023) \rightarrow RB (2024) \rightarrow 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 for 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,1) -> pitplot_pitdata

pitplot_pitdata
```

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

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

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

pitplot_pitdata_title_edit
```

# Citations

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"))`
