For the 2023 season, our team has been looking to improve our scouting system. Part of this system involves sending requests to TBA for data verification. However, sending requests to TBA and dealing with each response body proved tedious. Looking for ways to get past this obstacle, numerous TBA API wrappers were readily available at our usage. However, we couldn’t find one that fit our needs. Thus, we set out to develop a Pythonic API Wrapper for TBA-related data that was easy to use for everyone, not just us.
Our main goal for FalconAlliance was usability. We strived to achieve usability by wrapping around TBA and attempting to go above and beyond by adding different features to make the coder’s experience more convenient.
Documentation
Documentation is a crucial part of usability. Without documentation, finding how to use a particular method or learning how to use a key feature would be much more challenging. However, just an API reference as the documentation wouldn’t be helpful to learning, so we included examples, explanations of features, and the API reference itself when making our documentation. In-code documentation is crucial too, and for every method, we wrote docstrings and type hints for each parameter to ensure a lack of documentation doesn’t impede the coder’s experience.
If you want to visit our documentation, you can check it out here
Speed
Speed was a crucial part of FalconAlliance because, without speed, bottleneck requests would likely bring your code to a halt. We used asynchronous requests in the background of FalconAlliance, with bottleneck requests like getting all teams that played during a season to experience speed-ups with asynchronous requests. The premise of asynchronous requests is that when the program is waiting for a request, it can initiate another request rather than wait for one request to finish to start another. In addition, you can also use caching to speed up your requests and lower the impact on TBA’s API. Caching headers are as simple as passing in use_caching=True into any method that wraps around a TBA endpoint. If you don’t want it to raise a NotModifiedError, you can pass in silent=True, which will return an empty body rather than raising an error letting you know that there are no new versions of the data you’re trying to retrieve.
Extended Functionality
FalconAlliance has extended functionality beyond just being a wrapper around FRC data sources to provide for many different usecases of FalconAlliance. Examples of our extended functionality include:
- Get the minimum/maximum match score for a team during a season or an event
- Get the minimum/maximum OPR/DPR/CCWM for a team during a season
- Get the average match score for a team during a season or event
- Get the average OPR/DPR/CCWM for a team during a season
- Find the latitude & longitude of a team based on their city/state/country
- Get the minimum/maximum match score for an event
- Get the minimum/maximum OPR/DPR/CCWM for an event
- Get the average match score for an event
- Get the average OPR/DPR/CCWM for an event
Plotting
Visualizing data can be complicated sometimes, however with FalconAlliance, a few lines of code can build you a full-fledged plot. The in-built plotting tool wrapps around matplotlib and supports six different plot types:
- Line plots
- Scatter plots
- Violin plots
- Bar plots
- Histograms
- Pie charts
The example below generates a violin plot visualizing Team 4099’s match scores over the years, showing how concise & versatile the plotting feature is:
Code
import falcon_alliance
with falcon_alliance.ApiClient():
team4099 = falcon_alliance.Team(4099)
plotter = falcon_alliance.Plotter()
# Positions (X Data)
years = range(2012, 2023)
# Data (Y Data, the "violins")
yearly_matches = falcon_alliance.apply(team4099.matches, year=years)
yearly_match_scores = yearly_matches.for_each(lambda match: match.alliance_of(team4099).score)
plotter.violin_plot(yearly_match_scores, years, title="Team 4099 Distribution of Match Scores (2012-2022)")
Output
You can read more about the plotting feature and what specific functions do here.
Bugs
We use testing to ensure that FalconAlliance is covered and safe from bugs which can be a hindrance to your code. Currently, we have 100% code coverage, keeping bugs to a minimum and providing the best experience when using FalconAlliance! If you find a bug, feel free to report it by opening an issue here.
If you have any questions about FalconAlliance, whether it be technical questions, suggestions, etc., feel free to ask them!