Package — additional Python functions
Hand-written wrappers, loaders, and helpers in sportsdataverse
not covered by the generated API-endpoint reference above.
Other
cache_stats() -> 'Dict[str, Any]'
Return a snapshot of the cache for debugging / inspection.
Returns a dict with mode, entries, and disk_bytes (only
populated when mode=filesystem). Cheap — doesn't read the cached
bodies, just counts + sizes.
college_baseball_re24(seasons: 'Union[int, List[int], None]' = None, *, state: 'Optional[pl.DataFrame]' = None, return_as_pandas: 'bool' = False) -> "Union[pl.DataFrame, 'pd.DataFrame']"
sportsdataverse.baseball.college_run_expectancy.college_baseball_re24 fixed to league="college_baseball".
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
seasons | Union[int, List[int], None] | None | See the core function. |
state | Optional[DataFrame] | None | See the core function. |
return_as_pandas | bool | False | Return pandas.DataFrame instead of polars. |
Returns
see the core function's Returns table.
Example
from sportsdataverse.baseball.college_baseball.college_baseball_re import college_baseball_state, college_baseball_re24
state = college_baseball_state(raw)
matrix = college_baseball_re24(state=state)
college_baseball_state(plays: 'Dict[str, Any]') -> 'pl.DataFrame'
sportsdataverse.baseball.college_run_expectancy.college_baseball_state fixed to league="college_baseball".
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
plays | Dict[str, Any] | Raw payload from espn_college_baseball_game_plays(event_id, return_parsed=False). |
Returns
see the core function's Returns table.
Example
from sportsdataverse.baseball.college_baseball.college_baseball_re import college_baseball_state
state = college_baseball_state(raw)
college_baseball_wpa(seasons: 'Union[int, List[int], None]' = None, *, state: 'Optional[pl.DataFrame]' = None, results: 'Optional[pl.DataFrame]' = None, return_as_pandas: 'bool' = False) -> "Union[pl.DataFrame, 'pd.DataFrame']"
sportsdataverse.baseball.college_run_expectancy.college_baseball_wpa fixed to league="college_baseball".
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
seasons | Union[int, List[int], None] | None | See the core function. |
state | Optional[DataFrame] | None | See the core function. |
results | Optional[DataFrame] | None | See the core function. |
return_as_pandas | bool | False | Return pandas.DataFrame instead of polars. |
Returns
see the core function's Returns table.
Example
from sportsdataverse.baseball.college_baseball.college_baseball_re import college_baseball_wpa
wpa = college_baseball_wpa(state=state, results=results)
college_softball_re24(seasons: 'Union[int, List[int], None]' = None, *, state: 'Optional[pl.DataFrame]' = None, return_as_pandas: 'bool' = False) -> "Union[pl.DataFrame, 'pd.DataFrame']"
sportsdataverse.baseball.college_run_expectancy.college_baseball_re24 fixed to league="college_softball".
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
seasons | Union[int, List[int], None] | None | See the core function. |
state | Optional[DataFrame] | None | See the core function. |
return_as_pandas | bool | False | Return pandas.DataFrame instead of polars. |
Returns
see the core function's Returns table.
Example
from sportsdataverse.baseball.college_softball.college_softball_re import college_softball_state, college_softball_re24
state = college_softball_state(raw)
matrix = college_softball_re24(state=state)
college_softball_state(plays: 'Dict[str, Any]') -> 'pl.DataFrame'
sportsdataverse.baseball.college_run_expectancy.college_baseball_state fixed to league="college_softball".
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
plays | Dict[str, Any] | Raw payload from espn_college_softball_game_plays(event_id, return_parsed=False). |
Returns
see the core function's Returns table.
Example
from sportsdataverse.baseball.college_softball.college_softball_re import college_softball_state
state = college_softball_state(raw)
college_softball_wpa(seasons: 'Union[int, List[int], None]' = None, *, state: 'Optional[pl.DataFrame]' = None, results: 'Optional[pl.DataFrame]' = None, return_as_pandas: 'bool' = False) -> "Union[pl.DataFrame, 'pd.DataFrame']"
sportsdataverse.baseball.college_run_expectancy.college_baseball_wpa fixed to league="college_softball".
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
seasons | Union[int, List[int], None] | None | See the core function. |
state | Optional[DataFrame] | None | See the core function. |
results | Optional[DataFrame] | None | See the core function. |
return_as_pandas | bool | False | Return pandas.DataFrame instead of polars. |
Returns
see the core function's Returns table.
Example
from sportsdataverse.baseball.college_softball.college_softball_re import college_softball_wpa
wpa = college_softball_wpa(state=state, results=results)
cricket_expected_runs(state_wp: 'pl.DataFrame', *, return_as_pandas: 'bool' = False) -> 'pl.DataFrame | pd.DataFrame'
Expected remaining runs + run rate from a win-probability-scored state frame.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
state_wp | DataFrame | Output of ~sportsdataverse.cricket.cricket_win_prob.cricket_win_probability (must carry proj_final, runs, overs_left). | |
return_as_pandas | bool | False | When True, return a pandas.DataFrame. |
Returns
The input rows plus exp_runs_remaining:Float64 (proj_final - runs, floored at 0) and exp_run_rate:Float64 (per remaining over; null when no overs remain). A zero-row input returns the schema with both columns appended (all null).
Example
import polars as pl
from sportsdataverse.cricket.cricket_win_prob import cricket_win_probability
from sportsdataverse.cricket.cricket_wpa import cricket_expected_runs
scored = cricket_win_probability(state)
er = cricket_expected_runs(scored)
er.select("exp_runs_remaining", "exp_run_rate").head()
cricket_match_state(summary: 'dict', *, fmt: 'str', return_as_pandas: 'bool' = False) -> 'pl.DataFrame | pd.DataFrame'
Extract over-level match state from an ESPN cricket summary/scoreboard payload.
One row per innings with a parseable competitor score string. The batting
side that carries a target in its score is the second innings (chasing);
the other is the first innings (setting).
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
summary | dict | Raw ESPN cricket summary or scoreboard payload (dict). | |
fmt | str | Format slug ("t20" / "odi"); validated via ~sportsdataverse.cricket.cricket_model_constants.get_format. | |
return_as_pandas | bool | False | When True, return a pandas.DataFrame. |
Returns
A polars.DataFrame (or pandas) with the documented state schema; a zero-row frame when the payload is empty/malformed.
Example
from sportsdataverse.cricket import espn_cricket_summary
from sportsdataverse.cricket.cricket_win_prob import cricket_match_state
state = cricket_match_state(espn_cricket_summary(event="1385691", return_parsed=False), fmt="t20")
print(state.shape)
cricket_win_probability(state: 'pl.DataFrame', *, return_as_pandas: 'bool' = False) -> 'pl.DataFrame | pd.DataFrame'
In-play win probability for the batting/chasing team from match state.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
state | DataFrame | Over-level match state carrying the documented state schema (event_id, innings_number, batting_team_id, runs, wickets, balls_bowled, balls_total, target, fmt) — e.g. the output of cricket_match_state. | |
return_as_pandas | bool | False | When True, return a pandas.DataFrame. |
Returns
The input rows plus overs_left:Int64, wickets_left:Int64, resources_left:Float64, proj_final:Float64, win_prob_raw:Float64 (parametric core) and win_prob:Float64 (calibrated, the shipped estimate). A zero-row input returns the schema with these columns appended (all null).
Example
import polars as pl
from sportsdataverse.cricket.cricket_win_prob import cricket_win_probability
st = pl.DataFrame([{ "event_id": "M1", "innings_number": 2,
"batting_team_id": "A", "runs": 120, "wickets": 3,
"balls_bowled": 90, "balls_total": 120, "target": 160, "fmt": "t20"}])
cricket_win_probability(st).select("win_prob").item()
cricket_wpa(state_wp: 'pl.DataFrame', *, return_as_pandas: 'bool' = False) -> 'pl.DataFrame | pd.DataFrame'
Batting/bowling win-probability added per over/wicket transition.
wpa_batting is the change in the batting team's win probability since the
previous state within the same innings; wpa_bowling is its negation (the
bowling side gains exactly what the batting side loses). The lead is taken
.over(["event_id", "innings_number"]) so no change leaks across matches or
innings, and the first state of each innings has wpa_batting = 0.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
state_wp | DataFrame | Output of ~sportsdataverse.cricket.cricket_win_prob.cricket_win_probability (must carry event_id, innings_number, balls_bowled, win_prob). | |
return_as_pandas | bool | False | When True, return a pandas.DataFrame. |
Returns
The input rows (sorted by event_id, innings_number, balls_bowled) plus win_prob_before:Float64, wpa_batting:Float64 and wpa_bowling:Float64. A zero-row input returns the schema with those columns appended (all null).
Example
from sportsdataverse.cricket.cricket_win_prob import cricket_win_probability
from sportsdataverse.cricket.cricket_wpa import cricket_wpa
wpa = cricket_wpa(cricket_win_probability(state))
wpa.select("wpa_batting", "wpa_bowling").head()
get_cache_mode() -> 'str'
Return the current cache mode.
mch_ratings(dates: 'list[str]', *, return_as_pandas: 'bool' = False) -> 'pl.DataFrame | pd.DataFrame'
MCH opponent-adjusted goal-margin ratings over a set of scoreboard dates.
Fetches espn_mch_scoreboard for each date in dates, concatenates
the completed games, and adjusts with
sportsdataverse.hockey.college_hockey_ratings.college_hockey_ratings.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
dates | list[str] | YYYYMMDD date strings to fetch (ESPN has no single "whole season" scoreboard endpoint; the caller supplies the date sweep -- see dev/league_ports/capture_wch_and_scoreboards.py for the sweep used to build the committed oracle fixture). | |
return_as_pandas | bool | False | Return pandas instead of polars. |
Returns
One row per team: team_id, adj_off, adj_def, adj_net, raw_off, raw_def, games.
Example
from sportsdataverse.hockey.mch import mch_ratings
ratings = mch_ratings(["20250118", "20250201"])
ratings.sort("adj_net", descending=True).head()
set_cache_mode(mode: 'str') -> 'None'
Switch the global cache mode.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
mode | str | One of "off", "memory", "filesystem". |
set_default_ttl(ttl: 'Optional[Union[timedelta, int]]') -> 'None'
Override the default TTL for endpoints not matched by the tier rules.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
ttl | Optional[Union[timedelta, int]] | A timedelta, an integer (interpreted as seconds), or None to reset to the built-in DEFAULT_TTL (MODERATE = 1 hour). |
ufl_pbp(game_id: 'Union[str, int]', *, return_as_pandas: 'bool' = False) -> "Union[pl.DataFrame, 'pd.DataFrame']"
Enriched UFL play-by-play (EP/EPA/WP/WPA/CP/CPOE).
Same shared spring-football core as ~sportsdataverse.football.xfl.xfl_pbp
(see sportsdataverse.football.spring_football_ep_wp).
Capture finding: ESPN publishes no play-by-play for UFL games as of
this port -- verified empty (summary.drives AND the Core v2
.../plays endpoint) across every completed 2024 + 2025 UFL game. This
function returns a zero-row (contract-shaped) frame on today's real data
-- not a stub -- and will pick up real rows automatically once ESPN
backfills UFL play-by-play. See
tests/fixtures/league_ports/FEASIBILITY.md.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
game_id | Union[str, int] | ESPN UFL event id. | |
return_as_pandas | bool | False | When True, return a pandas.DataFrame. |
Returns
One row per play with ep/epa/wp/wpa/cp/cpoe and the other enrich_nfl_pbp output columns. Zero rows today for every UFL game (see capture finding above).
Example
from sportsdataverse.football.ufl import ufl_pbp
df = ufl_pbp("401638299")
print(df.height) # 0 today -- see the capture-finding note above
wch_ratings(dates: 'list[str]', *, return_as_pandas: 'bool' = False) -> 'pl.DataFrame | pd.DataFrame'
WCH opponent-adjusted goal-margin ratings over a set of scoreboard dates.
See the module docstring's coverage caveat -- ESPN's WCH scoreboard coverage observed during this port was tournament-only.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
dates | list[str] | YYYYMMDD date strings to fetch. | |
return_as_pandas | bool | False | Return pandas instead of polars. |
Returns
One row per team: team_id, adj_off, adj_def, adj_net, raw_off, raw_def, games.
Example
from sportsdataverse.hockey.wch import wch_ratings
ratings = wch_ratings(["20250315", "20250321", "20250322", "20250323"])
ratings.sort("adj_net", descending=True).head()
xfl_pbp(game_id: 'Union[str, int]', *, return_as_pandas: 'bool' = False) -> "Union[pl.DataFrame, 'pd.DataFrame']"
Enriched XFL play-by-play (EP/EPA/WP/WPA/CP/CPOE).
Fetches the ESPN game summary, unrolls its drives into an nflverse-shape
frame, and scores it with the same parity-validated NFL EP/WP pipeline
used league-wide (see
sportsdataverse.football.spring_football_ep_wp).
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
game_id | Union[str, int] | ESPN XFL event id. | |
return_as_pandas | bool | False | When True, return a pandas.DataFrame. |
Returns
One row per play with ep/epa/wp/wpa/cp/cpoe and the other enrich_nfl_pbp output columns. Zero rows for a game ESPN has no play-by-play for.
Example
from sportsdataverse.football.xfl import xfl_pbp
df = xfl_pbp("401517780")
print(df.select("play_id", "epa", "wp").head())