API reference

The public entry points. Session is the one to hold on to: it keeps the cache, the assumption registry and every model it has fitted.

athletevalue.api.Session

One cache, one registry, and the models fitted with them.

Fitted seasons are keyed on the season, the penalty settings, the prior, the prior's training cap, the registry digest and the model version; economics models on the last season, the registry digest and the model version. The least recently used entries are dropped beyond max_seasons and max_economics; a season model for a full year holds a few hundred megabytes.

clear()

Forget fitted models (files on disk are untouched).

fit_season(season, *, lam=None, choose_lambda_by_cv=False, prior=None, last_available_season=None)

Download (or reuse) one season's inputs and fit ratings, team ratings and win models.

prior defaults to the registry's mbb.prior.use_box_prior. The prior is fit on seasons before season only; last_available_season can lower that cap further (for example to reproduce what was knowable at an earlier date). The first season with data has no earlier season and is fitted without a prior.

fit_economics(last_season)

Fit the revenue and tournament-bid models on every season through last_season.

validate(model, *, use_torvik=True, extended=False, economics=True)

Compare a fitted season with the SportsDataverse RAPM and Torvik team ratings.

extended adds the gates above the ratings (validate.extended_gates): it fits the previous season for the returning-player check and, with economics, the revenue and bid models through this season.

fit_market(deals=None, *, labels=None, fitted=None, economics=None)

Fit the roster-market model on disclosed men's basketball deals.

Raises InsufficientLabelsError when the labels do not meet the registry minimums; the valuation then keeps the allocation as the price.

value_player(name, season, *, team=None, sport='mbb', labels=None, economics=True, seed=0, last_available_season=None, model=None, economics_model=None)

Value one player-season: impact, wins, program value, market price and surplus.

The price comes from, in order: disclosed pay for this player-season, the fitted market model when it passes its gates, then the roster-budget allocation. model and economics_model reuse models fitted elsewhere; economics set to False skips program value.

value_team(team, season, *, economics=True, seed=0, model=None, economics_model=None)

Value-vs-price table (medians) for every player on team.

athletevalue.api.fit_season(season, *, cache=None, registry=None, lam=None, choose_lambda_by_cv=False, prior=None, last_available_season=None)

See Session.fit_season.

athletevalue.api.validate(model, *, cache=None, registry=None, use_torvik=True, extended=False, economics=True)

See Session.validate.

athletevalue.api.fit_economics(last_season, *, cache=None, registry=None)

See Session.fit_economics.

athletevalue.api.fit_market(deals=None, *, labels=None, cache=None, registry=None, fitted=None, economics=None)

See Session.fit_market.

athletevalue.api.value_player(name, season, *, team=None, sport='mbb', labels=None, cache=None, registry=None, economics=True, seed=0, last_available_season=None, model=None, economics_model=None)

See Session.value_player.

athletevalue.api.value_team(team, season, *, cache=None, registry=None, economics=True, seed=0, model=None, economics_model=None)

See Session.value_team.

athletevalue.api.load_deals(labels=None)

Deals from the packaged registry, plus a user CSV in the same schema if given.

athletevalue.valuation.result.PlayerValuation

Bases: BaseModel

Separate estimates of impact, value to the program and market price for one player-season.

war_sensitivity instance-attribute

Median WAR under each replacement definition, keyed by definition name.

program_value instance-attribute

Revenue this season from the player's wins and bid, under EADA accounting.

program_value_two_season = None class-attribute instance-attribute

The same plus next season's carry-over, which accrues whether or not the player stays.

allocated_market_value = None class-attribute instance-attribute

The role-and-impact allocation, kept when the fitted model sets the market value.

athletevalue.valuation.validate.ValidationReport dataclass

athletevalue.sources.cache.ArtifactCache

Downloads files once, checks them against pins, and remembers where they came from.

fetch(url, *, relative_path, license_tag, refresh=False, max_age=None)

Return the cached artifact, downloading it first if needed.

A cached copy older than max_age is downloaded again when online; if that download fails, the older copy is returned.

read_derived(relative_path)

The derived frame, or None when absent, altered, or built from other inputs.

write_derived(relative_path, frame, *, sources, settings=None)

Write frame and record the inputs, model version and settings behind it.

verify()

Hash every recorded file and report what no longer matches.

clear(*, derived_only=False)

Delete cached files (only derived ones if asked). Returns the number removed.