scoutR is an R package that makes TheBlueAlliance (TBA) and Statbotics data easier for R users to access. The objective is to provide functions that allow a newcomer to R to write one line of code and retrieve exactly the right dataframe in a tidy format rather than as a JSON that needs massaging to be useful. scoutR also provides a number of quality-of-life utility functions for FRC data.

Setup - New User Checklist

Install R and RStudio on your machine. You can find them both on Posit’s website here: https://posit.co/download/rstudio-desktop/. scoutR assumes that you have R 4.3.0 or later.
Install pak by running install.packages("pak") in the R console
Install scoutR by running pak::pak("gkrotkov/scoutR") in the R console.
Introduce yourself to scoutR by running scoutR::initialize_scoutR(auth_key), with your TBA auth key. You can get a TBA auth key at this link.
To use scoutR functions in your R instance, call library(scoutR). This loads the functions from scoutR into your environment.

Now scoutR is installed on your version of R! Check out intro to scoutR for a walkthrough.

Function naming convention (“how do I guess what functions exist?”)

scoutR interface functions generally follow the naming convention that the first word is the input value and the second word is the return value. For example event_teams() takes an event key (ex. “2026chcmp”) and returns team IDs, and team_awards() takes a team ID and returns awards.

The scoutR interface also exposes single-word functions that mirror the TBA API. For example events() takes a year, and event() takes an event ID.

Why do I care about Tidy data? What even is it?

Tidy data has 3 features.

Each variable forms a column.
Each observation forms a row.
Each type of observational unit forms a separate table.

This is a pretty simple set of rules for data to follow, but following it enables powerful data manipulation libraries like the tidyverse. Tidy data streamlines visualization and analysis - it lets students skip annoying API interactions and get right to data science questions.

For collaborators

Roadmap to ScoutR

The below R files define functions that are the core engine of scoutR. R files like utils, data, and dependencies just make the proverbial trains run on time.

Name	Description	Input	Output	User Facing?
`scoutR`	Analysis functions for at-event usage.	Event codes or match data	Tidy dataframes	✅
`tba_interfaceR`	Provide a direct interface between the user and the TBA API	TBA-legal keys	Tidy dataframes	✅
`helpR`	“Under the hood” helper functions that make other functions easy to use.	Varies, but mostly dataframes of match objects	Varies	❌
`tba_readR`	Read data from the TBA API, helper library for `tba_interfaceR`	TBA-legal keys	JSON	❌
`tba_tidyR`	Reformat JSON data from TBA to Tidy format, helper library for `interfaceR`	JSON	Tidy dataframes	❌
`statbotics_readR`	Read JSON data from Statbotics to Tidy format	Statbotics endpoints	Tidy data frames	✅

Dependencies

scoutR manages dependencies with the renv package. This means we can resolve package issues by references the renv lockfile.