Statbotics¶
Statbotics.io aims to modernize FRC data analytics through developing and distributing cutting-edge metrics and analysis. This Python API makes Expected Points Added (EPA) statistics just a few Python lines away! Currently we support queries on teams, years, events, and matches. Read below for usage and documentation.
Visit https://statbotics.io for more content!
Usage¶
With Python>=3.8 and pip installed, run
pip install statbotics==2.0.1
Then in a Python file, create a Statbotics object and get started!
import statbotics
sb = statbotics.Statbotics()
print(sb.get_team(254))
>> {'team': 254, 'name': 'The Cheesy Poofs', 'offseason': False, 'state': 'CA', 'country': 'USA', 'district': None, 'rookie_year': 1999, 'active': True, 'norm_epa': 1961.0, 'norm_epa_recent': 1956.0, 'norm_epa_mean': 1896.0, 'norm_epa_max': 2114.0, ... }
Read below for more methods!
API Reference¶
-
class
statbotics.main.
Statbotics
¶ Main Object for interfacing with the Statbotics API
-
get_team
(team: int, fields: List[str] = ['all']) → Dict[str, Any]¶ Function to retrieve information on an individual team
Parameters: - team – Team Number, integer
- fields – List of fields to return. The default is [“all”]
Returns: a dictionary with team metadata and EPA statistics
-
get_teams
(country: Optional[str] = None, state: Optional[str] = None, district: Optional[str] = None, active: Optional[bool] = True, metric: str = 'team', ascending: Optional[bool] = None, limit: int = 100, offset: int = 0, fields: List[str] = ['all']) → List[Dict[str, Any]]¶ Function to retrieve information on multiple teams
Parameters: - country – Restrict based on country (select country to include)
- state – US States and Canada provinces only. Can infer country.
- district – Use 2 or 3-letter key (ex: FIM, NE, etc)
- active – Restrict to active teams (played most recent season)
- metric – Order output by field (Ex: “-norm_epa”, “team”, etc). Default is “team”.
- ascending – Order output ascending or descending. Default varies by metric.
- limit – Limits the output length to speed up queries. Max 10,000
- offset – Skips the first (offset) items when returning
- fields – List of fields to return. Default is [“all”]
Returns: A list of dictionaries, each dictionary including team metadata and EPA statistics
-
get_year
(year: int, fields: List[str] = ['all']) → Dict[str, Any]¶ Function to retrieve information for a specific year
Parameters: - year – Year, integer
- fields – List of fields to return. The default is [“all”]
Returns: a dictionary with the year, match prediction statistics, and RP prediction statistics
-
get_years
(metric: str = 'year', ascending: Optional[bool] = None, limit: int = 100, offset: int = 0, fields: List[str] = ['all']) → List[Dict[str, Any]]¶ Function to retrieve information on multiple years
Parameters: - metric – Order output by field. (Ex: “epa_acc”, “epa_mse”, etc). Default “year”
- ascending – Order output ascending or descending. Default varies by metric.
- limit – Limits the output length to speed up queries. Max 10,000
- offset – Skips the first (offset) items when returning
- fields – List of fields to return. Default is [“all”]
Returns: A list of dictionaries, each dictionary including the year and match/RP prediction statistics
-
get_team_year
(team: int, year: int, fields: List[str] = ['all']) → Dict[str, Any]¶ Function to retrieve information for a specific team’s performance in a specific year
Parameters: - team – Team number, integer
- year – Year, integer
- fields – List of fields to return. The default is [“all”]
Returns: a dictionary with the team, year, and EPA statistics
-
get_team_years
(team: Optional[int] = None, year: Optional[int] = None, country: Optional[str] = None, state: Optional[str] = None, district: Optional[str] = None, metric: str = 'team', ascending: Optional[bool] = None, limit: int = 100, offset: int = 0, fields: List[str] = ['all']) → List[Dict[str, Any]]¶ Function to retrieve information on multiple (team, year) pairs
Parameters: - team – Restrict based on a specific team number
- country – Restrict based on country (select countries included)
- state – US States and Canada provinces only. Can infer country.
- district – Use 2 or 3-letter key (ex: FIM, NE, etc)
- metric – Order output by field. (Ex: “epa_end”, “team”, etc). Default “team”
- ascending – Order output ascending or descending. Default varies by metric.
- limit – Limits the output length to speed up queries. Max 10,000
- offset – Skips the first (offset) items when returning
- fields – List of fields to return. Default is [“all”]
Returns: A list of dictionaries, each dictionary including the team, year, and EPA statistics
-
get_event
(event: str, fields: List[str] = ['all']) → Dict[str, Any]¶ Function to retrieve information for a specific event
Parameters: - event – Event key, string (ex: “2019cur”)
- fields – List of fields to return. The default is [“all”]
Returns: a dictionary with the event and EPA statistics
-
get_events
(year: Optional[int] = None, country: Optional[str] = None, state: Optional[str] = None, district: Optional[str] = None, type: Union[str, int, None] = None, week: Optional[int] = None, metric: str = 'year', ascending: Optional[bool] = None, limit: int = 100, offset: int = 0, fields: List[str] = ['all']) → List[Dict[str, Any]]¶ Function to retrieve information on multiple events
Parameters: - year – Restrict by specific year, integer
- country – Restrict based on country (select countries included)
- state – US States and Canada provinces only. Can infer country.
- district – Use 2 or 3-letter key (ex: FIM, NE, etc)
- type – 0=regional, 1=district, 2=district champ, 3=champs, 4=einstein
- week – Week of play, generally between 0 and 8
- metric – Order output bu field. (Ex: “epa_pre_playoffs”, “epa_end”, etc). Default “year”
- ascending – Order output ascending or descending. Default varies by metric.
- limit – Limits the output length to speed up queries. Max 10,000
- offset – Skips the first (offset) items when returning
- fields – List of fields to return. Default is [“all”]
Returns: A list of dictionaries, each dictionary including the team, event and EPA statistics
-
get_team_event
(team: int, event: str, fields: List[str] = ['all']) → Dict[str, Any]¶ Function to retrieve information for a specific (team, event) pair
Parameters: - team – Team number, integer
- event – Event key, string (ex: “2019cur”)
- fields – List of fields to return. The default is [“all”]
Returns: a dictionary with the event and EPA statistics
-
get_team_events
(team: Optional[int] = None, year: Optional[int] = None, event: Optional[str] = None, country: Optional[str] = None, state: Optional[str] = None, district: Optional[str] = None, type: Union[str, int, None] = None, week: Optional[int] = None, metric: str = 'year', ascending: Optional[bool] = None, limit: int = 0, offset: int = 0, fields: List[str] = ['all']) → List[Dict[str, Any]]¶ Function to retrieve information on multiple (team, event) pairs
Parameters: - team – Restrict by team number, integer
- year – Restrict by specific year, integer
- country – Restrict based on country (select countries included)
- state – US States and Canada provinces only. Can infer country.
- district – Use 2 or 3-letter key (ex: FIM, NE, etc)
- type – 0=regional, 1=district, 2=district champ, 3=champs, 4=einstein
- week – Week of play, generally between 0 and 8
- metric – Order output by field. (Ex: “epa_pre_playoffs”, “epa_end”, etc). Default “year”
- ascending – Order output ascending or descending. Default varies by metric.
- limit – Limits the output length to speed up queries. Max 10,000
- offset – Skips the first (offset) items when returning
- fields – List of fields to return. Default is [“all”]
Returns: A list of dictionaries, each dictionary including the team, event and EPA statistics
-
get_match
(match: str, fields: List[str] = ['all']) → Dict[str, Any]¶ Function to retrieve information for a specific match
Parameters: - match – Match key, string (ex: “2019cur_qm1”, “2019cmptx_f1m3”)
- fields – List of fields to return. The default is [“all”]
Returns: a dictionary with the match, score breakdowns, and predictions
-
get_matches
(team: Optional[int] = None, year: Optional[int] = None, event: Optional[str] = None, week: Optional[int] = None, elims: Optional[bool] = None, metric: str = 'time', ascending: Optional[bool] = None, limit: int = 200, offset: int = 0, fields: List[str] = ['all']) → List[Dict[str, Any]]¶ Function to retrieve information on multiple matches
Parameters: - team – Restrict by team number, integer
- year – Restrict by specific year, integer
- event – Restrict by specific event key, string
- week – Week of play, generally between 0 and 8
- elims – Restrict to only elimination matches, default False
- metric – Order output by field. (Ex: “time”, “epa_pre_playoffs”, “epa_end”, etc). Default “time”
- ascending – Order output ascending or descending. Default varies by metric.
- limit – Limits the output length to speed up queries. Max 10,000
- offset – Skips the first (offset) items when returning
- fields – List of fields to return. Default is [“all”]
Returns: A list of dictionaries, each dictionary including the match, score breakdowns, and predictions
-
get_team_match
(team: int, match: str, fields: List[str] = ['all']) → Dict[str, Any]¶ Function to retrieve information for a specific (team, match) pair
Parameters: - team – Team number, integer
- match – Match key, string (ex: “2019cur_qm1”, “2019cmptx_f1m3”)
- fields – List of fields to return. The default is [“all”]
Returns: a dictionary with the team, match, alliance, and EPA statistics
-
get_team_matches
(team: Optional[int] = None, year: Optional[int] = None, event: Optional[str] = None, week: Optional[int] = None, match: Optional[str] = None, elims: Optional[bool] = None, metric: str = 'time', ascending: Optional[bool] = None, limit: int = 100, offset: int = 0, fields: List[str] = ['all']) → List[Dict[str, Any]]¶ Function to retrieve information on multiple (team, match) pairs
Parameters: - team – Restrict by team number, integer
- year – Restrict by specific year, integer
- event – Restrict by specific event key, string
- week – Week of play, generally between 0 and 8
- elims – Restrict to only elimination matches, default False
- metric – Order output by field. (Ex: “time”, “auto_epa”, etc). Default “time”
- ascending – Order output ascending or descending. Default varies by metric.
- limit – Limits the output length to speed up queries. Max 10,000
- offset – Skips the first (offset) items when returning
- fields – List of fields to return. Default is [“all”]
Returns: A list of dictionaries, each dictionary including the team, match, alliance, and then elo
-
Contribute¶
If you are interested in contributing, reach out to Abhijit Gupta (avgupta456@gmail.com). Source code is available at github.com/avgupta456/statbotics.
Support¶
If you are having issues, please let us know. We welcome issues and pull requests at github.com/avgupta456/statbotics.
License¶
The project is licensed under the MIT license.