Merge pull request #135 from pbulsink/readme-fix

SCasanova · Jul 21, 2023 · f98573b · f98573b
2 parents 95a72ce + ee3796c
commit f98573b
Show file tree

Hide file tree

Showing 3 changed files with 128 additions and 98 deletions.
diff --git a/README.Rmd b/README.Rmd
@@ -21,11 +21,12 @@ options(
   tibble.print_max = 5,
   pillar.min_title_width = 5
 )
+library(f1dataR)
 ```
 
 # f1dataR <img src='man/figures/logo.png' align="right" width="25%" min-width="120px"/>
 
-An R package to access Formula 1 Data from the Ergast API and the official F1 data stream via the fastf1 python library.
+An R package to access Formula 1 Data from the Ergast API and the official F1 data stream via the fastf1 Python library.
 
 <!-- badges: start -->
 
@@ -41,6 +42,7 @@ An R package to access Formula 1 Data from the Ergast API and the official F1 da
 ```{r eval = FALSE}
 if (!require("remotes")) install.packages("remotes")
 remotes::install_github("SCasanova/f1dataR")
+library(f1dataR)
 ```
 
 ## Data Sources
@@ -53,72 +55,84 @@ Data is pulled from:
 ## Functions
 
 ### Load Lap Times
-`load_laps(season = 'current', race = 'last')`
+> `load_laps(season = "current", race = "last")`
+
 This function loads lap-by-lap time data for all drivers in a given season
 and round. Round refers to race number. The defaults are current season and last race. Lap data is limited to 1996-present.
 
 **Example:**
 ```{r load_laps}
-library(f1dataR)
 load_laps()
 ```
 
 or
 
 ```{r load_specific_laps}
-load_laps(2021, 15)
+load_laps(season = 2021, round = 15)
 ```
 
 
 ### Driver Telemetry
-`load_driver_telemetry(season = 'current', race = 'last', session = 'R', driver, laps = "all")`
+> `load_driver_telemetry(season = "current", race = "last", session = "R", driver, laps = "all")`
 
 When the parameters for season (four digit year), round (number or GP name), session (FP1. FP2, FP3, Q, S, SS, or R), and driver code (three letter code) are entered, the function will load all data for a session and the pull the info for the selected driver. The first time a session is called, loading times will be relatively long but in subsequent calls this will improve to only a couple of seconds
 
-<<<<<<< HEAD
 ```{r load_telemetries}
-load_driver_telemetry(2022, round = 4, driver = "PER")
+load_driver_telemetry(season = 2022, round = 4, driver = "PER")
 
-load_driver_telemetry(2018, round = 7, "Q", "HAM", laps = "fastest")
+load_driver_telemetry(season = 2018, round = 7, "Q", "HAM", laps = "fastest")
 ```
 
 ### Lap-by-Lap information
+> `load_session_laps(season = "current", race = "last", session = "R", add_weather = FALSE)`
 
 This function will give us detailed information of lap and sector times, tyres, weather (optional), and more for every lap of the GP and driver.
 
 
 ```{r load_session_laps}
-load_session_laps(season = 2023, round = 4, add_weather = T)
+load_session_laps(season = 2023, round = 4, add_weather = TRUE)
 ```
 
+### Plotting
+> `plot_fastest(season = "current", round = "last", session = "R", driver, color = "gear")`
+
+A built in plotting function that plots the circuit and a driver's fastest laps' `speed` or `gear` exists.
+
+```{r plot, echo=FALSE, message=FALSE, warning=FALSE}
+plot_fastest(season = 2023, round = 1, session = "R", driver = "VER", color = "gear")
+```
+
+
 ### Cache information
 
 The cache directory for sessions can be set manually with the options function
 
-```{r cache_example, eval = F}
+```{r cache_example, eval = FALSE}
 options(f1dataR.cache = "path/to/directory")
 ```
 
-
-
 ### Other functions
-* `load_pitstops(season = 'current', round  ='last')`
-* `load_drivers(season = 2022)`
-* `load_circuits(season = 2022)`
-* `load_schedule(season = 2022)`
-* `load_standings(season = 'current', round = 'last', type = c('driver', 'constructor'))`
-* `load_results(season = 'current', round = 'last')`
-* `load_quali(season = 'current', round = 'last')`
-* `plot_fastest(season = 'current', round = 'last', driver, color = 'gear')`
 
+Many other functions exist, and are flexible enough to call the current `season` with the string `"current"` or use the year as a numeric value. Similarly, `round` can be `"last"` or a round number (from 1 to the total number of races in a season).
+
+* `load_constructors()`
+* `load_drivers(season = "current")`
+* `load_circuits(season = "current")`
+* `load_pitstops(season = "current", round = "last")`
+* `load_quali(season = "current", round = "last")`
+* `load_results(season = "current", round = "last")`
+* `load_schedule(season = ``r get_current_season()``)`
+* `load_sprint(season = "current", round = "last")`
+* `load_standings(season = "current", round = "last", type = c("driver", "constructor"))`
 
 ### Clear F1 Cache
-`clear_f1_cache()`
+> `clear_f1_cache()`
+
 Clears the cache for all functions in the package.
 
 ## Loaded Data
 
-The package also includes a static data frame for all current drivers and their respective constructors. Complete with team colors, logo and driver number logo.
+The package also includes a static data frame for all current drivers and their respective constructors. Complete with team colors, and links to team logos.
 
 ```{r constructor_example}
 constructor_data %>% colnames()

diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 # f1dataR <img src='man/figures/logo.png' align="right" width="25%" min-width="120px"/>
 
 An R package to access Formula 1 Data from the Ergast API and the
-official F1 data stream via the fastf1 python library.
+official F1 data stream via the fastf1 Python library.
 
 <!-- badges: start -->
 
@@ -21,6 +21,7 @@ status](https://www.r-pkg.org/badges/version/f1dataR)](https://CRAN.R-project.or
 ``` r
 if (!require("remotes")) install.packages("remotes")
 remotes::install_github("SCasanova/f1dataR")
+library(f1dataR)
 ```
 
 ## Data Sources
@@ -36,16 +37,15 @@ Data is pulled from:
 
 ### Load Lap Times
 
-`load_laps(season = 'current', race = 'last')` This function loads
-lap-by-lap time data for all drivers in a given season and round. Round
-refers to race number. The defaults are current season and last race.
-Lap data is limited to 1996-present.
+> `load_laps(season = "current", race = "last")`
+
+This function loads lap-by-lap time data for all drivers in a given
+season and round. Round refers to race number. The defaults are current
+season and last race. Lap data is limited to 1996-present.
 
 **Example:**
 
 ``` r
-library(f1dataR)
-#> Loading required package: reticulate
 load_laps()
 #> # A tibble: 970 × 6
 #>    driver_id      position time       lap time_sec season
@@ -60,13 +60,13 @@ load_laps()
 #>  8 hamilton       8        1:40.664     1    101.    2023
 #>  9 gasly          9        1:41.014     1    101.    2023
 #> 10 albon          10       1:41.364     1    101.    2023
-#> # … with 960 more rows
+#> # ℹ 960 more rows
 ```
 
 or
 
 ``` r
-load_laps(2021, 15)
+load_laps(season = 2021, round = 15)
 #> # A tibble: 1,025 × 6
 #>    driver_id position time       lap time_sec season
 #>    <chr>     <chr>    <chr>    <int>    <dbl>  <dbl>
@@ -80,12 +80,12 @@ load_laps(2021, 15)
 #>  8 perez     8        1:50.617     1     111.   2021
 #>  9 ocon      9        1:51.098     1     111.   2021
 #> 10 raikkonen 10       1:51.778     1     112.   2021
-#> # … with 1,015 more rows
+#> # ℹ 1,015 more rows
 ```
 
 ### Driver Telemetry
 
-`load_driver_telemetry(season = 'current', race = 'last', session = 'R', driver, laps = "all")`
+> `load_driver_telemetry(season = "current", race = "last", session = "R", driver, laps = "all")`
 
 When the parameters for season (four digit year), round (number or GP
 name), session (FP1. FP2, FP3, Q, S, SS, or R), and driver code (three
@@ -94,76 +94,84 @@ and the pull the info for the selected driver. The first time a session
 is called, loading times will be relatively long but in subsequent calls
 this will improve to only a couple of seconds
 
-\<\<\<\<\<\<\< HEAD
-
 ``` r
-load_driver_telemetry(2022, round = 4, driver = "PER")
+load_driver_telemetry(season = 2022, round = 4, driver = "PER")
 #> # A tibble: 592 × 19
-#>    date                session_time  time   rpm speed n_gear throt…¹ brake   drs
-#>    <dttm>                     <dbl> <dbl> <dbl> <dbl>  <dbl>   <dbl> <lgl> <dbl>
-#>  1 2022-04-24 09:19:27        8308. 0     11221   282      7     100 FALSE     0
-#>  2 2022-04-24 09:19:27        8308. 0.021 11221   283      7     100 FALSE     0
-#>  3 2022-04-24 09:19:28        8308. 0.278 11221   284      7     100 FALSE     0
-#>  4 2022-04-24 09:19:28        8308. 0.401 11279   285      7     100 FALSE     0
-#>  5 2022-04-24 09:19:28        8309. 0.678 11337   286      7     100 FALSE     0
-#>  6 2022-04-24 09:19:28        8309. 0.681 11376   287      7     100 FALSE     0
-#>  7 2022-04-24 09:19:28        8309. 0.86  11416   288      7     100 FALSE     0
-#>  8 2022-04-24 09:19:29        8309. 1.08  11456   289      7     100 FALSE     0
-#>  9 2022-04-24 09:19:29        8309. 1.18  11461   289      7     100 FALSE     0
-#> 10 2022-04-24 09:19:29        8309. 1.24  11467   290      7     100 FALSE     0
-#> # … with 582 more rows, 10 more variables: source <chr>,
-#> #   relative_distance <dbl>, status <chr>, x <dbl>, y <dbl>, z <dbl>,
-#> #   distance <dbl>, driver_ahead <chr>, distance_to_driver_ahead <dbl>,
-#> #   driver_code <chr>, and abbreviated variable name ¹throttle
-
-load_driver_telemetry(2018, round = 7,'Q', 'HAM', laps = "fastest")
+#>    date                session_time  time   rpm speed n_gear throttle brake
+#>    <dttm>                     <dbl> <dbl> <dbl> <dbl>  <dbl>    <dbl> <lgl>
+#>  1 2022-04-24 10:19:27        8308. 0     11221   282      7      100 FALSE
+#>  2 2022-04-24 10:19:27        8308. 0.021 11221   283      7      100 FALSE
+#>  3 2022-04-24 10:19:28        8308. 0.278 11221   284      7      100 FALSE
+#>  4 2022-04-24 10:19:28        8308. 0.401 11279   285      7      100 FALSE
+#>  5 2022-04-24 10:19:28        8309. 0.678 11337   286      7      100 FALSE
+#>  6 2022-04-24 10:19:28        8309. 0.681 11376   287      7      100 FALSE
+#>  7 2022-04-24 10:19:28        8309. 0.86  11416   288      7      100 FALSE
+#>  8 2022-04-24 10:19:29        8309. 1.08  11456   289      7      100 FALSE
+#>  9 2022-04-24 10:19:29        8309. 1.18  11461   289      7      100 FALSE
+#> 10 2022-04-24 10:19:29        8309. 1.24  11467   290      7      100 FALSE
+#> # ℹ 582 more rows
+#> # ℹ 11 more variables: drs <dbl>, source <chr>, relative_distance <dbl>,
+#> #   status <chr>, x <dbl>, y <dbl>, z <dbl>, distance <dbl>,
+#> #   driver_ahead <chr>, distance_to_driver_ahead <dbl>, …
+
+load_driver_telemetry(season = 2018, round = 7, "Q", "HAM", laps = "fastest")
 #> # A tibble: 534 × 19
-#>    date                session_time  time   rpm speed n_gear throt…¹ brake   drs
-#>    <dttm>                     <dbl> <dbl> <dbl> <dbl>  <dbl>   <dbl> <lgl> <dbl>
-#>  1 2018-06-09 13:59:18        3788. 0     10674   297      8     100 FALSE    12
-#>  2 2018-06-09 13:59:18        3788. 0.016 10704   298      8     100 FALSE    12
-#>  3 2018-06-09 13:59:18        3788. 0.043 10762   299      8     100 FALSE    12
-#>  4 2018-06-09 13:59:19        3788. 0.256 10820   301      8     100 FALSE    12
-#>  5 2018-06-09 13:59:19        3788. 0.343 10847   302      8     100 FALSE    12
-#>  6 2018-06-09 13:59:19        3788. 0.496 10875   303      8     100 FALSE    12
-#>  7 2018-06-09 13:59:19        3789. 0.643 10921   303      8     100 FALSE    12
-#>  8 2018-06-09 13:59:19        3789. 0.736 10967   304      8     100 FALSE    12
-#>  9 2018-06-09 13:59:19        3789. 0.943 10990   305      8     100 FALSE    12
-#> 10 2018-06-09 13:59:19        3789. 0.976 11014   306      8     100 FALSE    12
-#> # … with 524 more rows, 10 more variables: source <chr>,
-#> #   relative_distance <dbl>, status <chr>, x <dbl>, y <dbl>, z <dbl>,
-#> #   distance <dbl>, driver_ahead <chr>, distance_to_driver_ahead <dbl>,
-#> #   driver_code <chr>, and abbreviated variable name ¹throttle
+#>    date                session_time  time   rpm speed n_gear throttle brake
+#>    <dttm>                     <dbl> <dbl> <dbl> <dbl>  <dbl>    <dbl> <lgl>
+#>  1 2018-06-09 14:59:18        3788. 0     10674   297      8      100 FALSE
+#>  2 2018-06-09 14:59:18        3788. 0.016 10704   298      8      100 FALSE
+#>  3 2018-06-09 14:59:18        3788. 0.043 10762   299      8      100 FALSE
+#>  4 2018-06-09 14:59:19        3788. 0.256 10820   301      8      100 FALSE
+#>  5 2018-06-09 14:59:19        3788. 0.343 10847   302      8      100 FALSE
+#>  6 2018-06-09 14:59:19        3788. 0.496 10875   303      8      100 FALSE
+#>  7 2018-06-09 14:59:19        3789. 0.643 10921   303      8      100 FALSE
+#>  8 2018-06-09 14:59:19        3789. 0.736 10967   304      8      100 FALSE
+#>  9 2018-06-09 14:59:19        3789. 0.943 10990   305      8      100 FALSE
+#> 10 2018-06-09 14:59:19        3789. 0.976 11014   306      8      100 FALSE
+#> # ℹ 524 more rows
+#> # ℹ 11 more variables: drs <dbl>, source <chr>, relative_distance <dbl>,
+#> #   status <chr>, x <dbl>, y <dbl>, z <dbl>, distance <dbl>,
+#> #   driver_ahead <chr>, distance_to_driver_ahead <dbl>, …
 ```
 
 ### Lap-by-Lap information
 
+> `load_session_laps(season = "current", race = "last", session = "R", add_weather = FALSE)`
+
 This function will give us detailed information of lap and sector times,
 tyres, weather (optional), and more for every lap of the GP and driver.
 
 ``` r
-load_session_laps(season = 2023, round = 4, add_weather = T)
+load_session_laps(season = 2023, round = 4, add_weather = TRUE)
 #> # A tibble: 962 × 39
-#>     time driver driver_n…¹ lap_t…² lap_n…³ stint pit_o…⁴ pit_i…⁵ secto…⁶ secto…⁷
-#>    <dbl> <chr>  <chr>        <dbl>   <dbl> <dbl>   <dbl>   <dbl>   <dbl>   <dbl>
-#>  1 3892. VER    1             110.       1     1    697.    NaN    NaN      43.2
-#>  2 4000. VER    1             108.       2     1    NaN     NaN     38.4    43.6
-#>  3 4108. VER    1             108.       3     1    NaN     NaN     38.5    43.7
-#>  4 4215. VER    1             107.       4     1    NaN     NaN     37.9    43.4
-#>  5 4322. VER    1             107.       5     1    NaN     NaN     38.3    43.4
-#>  6 4430. VER    1             107.       6     1    NaN     NaN     38.3    43.2
-#>  7 4537. VER    1             107.       7     1    NaN     NaN     38.3    43.0
-#>  8 4643. VER    1             107.       8     1    NaN     NaN     38.0    43.0
-#>  9 4750. VER    1             107.       9     1    NaN     NaN     38.0    43.1
-#> 10 4861. VER    1             111.      10     1    NaN    4860.    37.9    43.4
-#> # … with 952 more rows, 29 more variables: sector3time <dbl>,
+#>     time driver driver_number lap_time lap_number stint pit_out_time pit_in_time
+#>    <dbl> <chr>  <chr>            <dbl>      <dbl> <dbl>        <dbl>       <dbl>
+#>  1 3892. VER    1                 110.          1     1         697.        NaN 
+#>  2 4000. VER    1                 108.          2     1         NaN         NaN 
+#>  3 4108. VER    1                 108.          3     1         NaN         NaN 
+#>  4 4215. VER    1                 107.          4     1         NaN         NaN 
+#>  5 4322. VER    1                 107.          5     1         NaN         NaN 
+#>  6 4430. VER    1                 107.          6     1         NaN         NaN 
+#>  7 4537. VER    1                 107.          7     1         NaN         NaN 
+#>  8 4643. VER    1                 107.          8     1         NaN         NaN 
+#>  9 4750. VER    1                 107.          9     1         NaN         NaN 
+#> 10 4861. VER    1                 111.         10     1         NaN        4860.
+#> # ℹ 952 more rows
+#> # ℹ 31 more variables: sector1time <dbl>, sector2time <dbl>, sector3time <dbl>,
 #> #   sector1session_time <dbl>, sector2session_time <dbl>,
 #> #   sector3session_time <dbl>, speed_i1 <dbl>, speed_i2 <dbl>, speed_fl <dbl>,
-#> #   speed_st <dbl>, is_personal_best <list>, compound <chr>, …, and abbreviated
-#> #   variable names ¹driver_number, ²lap_time, ³lap_number, ⁴pit_out_time,
-#> #   ⁵pit_in_time, ⁶sector1time, ⁷sector2time
+#> #   speed_st <dbl>, …
 ```
 
+### Plotting
+
+> `plot_fastest(season = "current", round = "last", session = "R", driver, color = "gear")`
+
+A built in plotting function that plots the circuit and a driver’s
+fastest laps’ `speed` or `gear` exists.
+
+<img src="man/figures/README-plot-1.png" width="100%" />
+
 ### Cache information
 
 The cache directory for sessions can be set manually with the options
@@ -175,24 +183,32 @@ options(f1dataR.cache = "path/to/directory")
 
 ### Other functions
 
-- `load_pitstops(season = 'current', round  ='last')`
-- `load_drivers(season = 2022)`
-- `load_circuits(season = 2022)`
-- `load_schedule(season = 2022)`
-- `load_standings(season = 'current', round = 'last', type = c('driver', 'constructor'))`
-- `load_results(season = 'current', round = 'last')`
-- `load_quali(season = 'current', round = 'last')`
-- `plot_fastest(season = 'current', round = 'last', driver, color = 'gear')`
+Many other functions exist, and are flexible enough to call the current
+`season` with the string `"current"` or use the year as a numeric value.
+Similarly, `round` can be `"last"` or a round number (from 1 to the
+total number of races in a season).
+
+- `load_constructors()`
+- `load_drivers(season = "current")`
+- `load_circuits(season = "current")`
+- `load_pitstops(season = "current", round = "last")`
+- `load_quali(season = "current", round = "last")`
+- `load_results(season = "current", round = "last")`
+- `load_schedule(season =`2023`)`
+- `load_sprint(season = "current", round = "last")`
+- `load_standings(season = "current", round = "last", type = c("driver", "constructor"))`
 
 ### Clear F1 Cache
 
-`clear_f1_cache()` Clears the cache for all functions in the package.
+> `clear_f1_cache()`
+
+Clears the cache for all functions in the package.
 
 ## Loaded Data
 
 The package also includes a static data frame for all current drivers
-and their respective constructors. Complete with team colors, logo and
-driver number logo.
+and their respective constructors. Complete with team colors, and links
+to team logos.
 
 ``` r
 constructor_data %>% colnames()

diff --git a/man/figures/README-plot-1.png b/man/figures/README-plot-1.png