Skip to content

About

Forecast first international cricket appearances and two-year match counts from dated player histories

Resources

Stars

1 star

Watchers

1 watching

Forks

Repository files navigation

National selection

Forecasts and documentation · Player tables

Forecast whether an uncapped IPL player will make a recorded senior international appearance in the next H months, across countries. Forecasts update monthly; the main horizon is 12 months, with 6- and 24-month comparisons. Exact match dates determine which performances can enter each forecast.

Backtest results report how well the models predict, against historical entry-rate and country/calendar baselines. The sample covers the IPL pathway, not every country's domestic player pool. Most overseas IPL players have already played internationally; see country coverage. International archive gaps mean this is recorded entry, not a certified census of debuts.

X and Y

One row is a player × forecast date, identified by Cricsheet's player UUID. Previously capped players leave the risk set. Return selection is a separate task.

Component Definition
Main Y: selected At least one recorded Test, ODI or T20I appearance during [cutoff, cutoff + H months), for any national side. Actual participation, rather than squad nomination.
Secondary Y: n_matches Recorded appearances in that interval, including zero. Measures opportunity and persistence, not performance quality.
Performance Xs Matches, runs, balls faced, dismissals, wickets, legal balls bowled, runs conceded, batting average, strike rate, bowling average and economy. Each is computed for the observed IPL career and trailing 24 months.
Other performance Xs Days since last IPL appearance and days since first observed IPL appearance.
Context Xs Country affiliation known at cutoff and calendar month, in context-only and combined models.
Excluded from X Names, IDs, future performance or schedules, region and caste. Age, role, first-class statistics and WAR are not yet included.

A June 1, 2023 forecast uses completed matches through May 31, 2023. Its 12-month Y covers June 1, 2023 through May 31, 2024. Parameters were fitted on January 1, 2023 using only training outcomes whose entire window had already finished. Inputs update monthly; fitted parameters update each January.

Monthly forecasts retain inactive candidates under the existing two-year activity rule and avoid making forecast frequency depend on how often someone plays. The builder also accepts arbitrary dates. For a forecast after a match, use the following day; match-day timestamps are not sufficiently precise for intraday use. The reported accuracy evaluates month starts, not every possible post-match date.

Backtesting

  • Validate on monthly forecasts in 2017–2019; choose models by validation log loss.
  • Test on mature monthly forecasts in 2022–2024. The 24-month horizon has follow-up only through the January 2024 cutoff. Never label incomplete recent windows zero.
  • Compare horizons on the shared January 2022–January 2024 period, against each horizon's own baseline. Raw scores differ with horizon prevalence.
  • Compare monthly-trained and January-only procedures on identical January test candidates. Report family-by-family results and independently chosen policies.
  • Report log loss, Brier, average precision, ROC AUC, calibration, and within-country top-10 rankings; use MAE and Poisson deviance for match counts. Show unique players and entrants as well as repeated snapshots, and equal-player-weighted scores.

This is an exploratory temporal backtest. Data corrections were made during project development; these years are not an untouched confirmation sample. Repeated players and overlapping horizons are dependent. More monthly rows do not create more independent evidence. Overseas samples remain small. No discrimination estimates are made, and these data cannot address the 1970s or 1980s.

Organization

src/national_selection/
  data.py             Import archives, link IDs, audit coverage
  features.py         Build dated risk sets, Xs and configurable-horizon Ys
  models.py           Annual fits, dated evaluation and forecasts
  backtest.py         Matched January and common-horizon comparisons
  cli.py              Command-line entry points
  site.py             Forecast tables and rendered publication checks
  refresh.py          Monthly acquisition and dated forecast publication
  coverage.py         Player exclusions and country counts
  reference/          Reviewed identity links and verified appearance evidence
data/build/
  panel_6m.csv         Monthly panel with six-month labels
  panel_12m.csv        Monthly panel with twelve-month labels
  panel_24m.csv        Monthly panel with twenty-four-month labels
  ...                 Normalized inputs and linkage/coverage audits
docs/                 Design, protocol and identity decisions
out/
  report.md           Cross-horizon and cadence comparison
  monthly_12m/        Primary backtest, calibration and forecasts
  monthly_6m/         Shorter-horizon comparison
  monthly_24m/        Longer-horizon comparison
  annual_*m/         January-only benchmark at each horizon
data/current/         Updated inputs, separate from the frozen benchmark
out/current/          Most recent dated forecasts
out/history/          Preserved forecast snapshots and source receipts
tests/                Timing, accounting, identity and evaluation tests

Run

Use Python 3.12 or newer:

python3 -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'
make check
make prepare evaluate forecast

Included normalized data make these commands independent of sibling checkouts. make import rebuilds them from ../ipl_auction, ../war and ../side_order. make all imports, prepares, evaluates and forecasts. make ci-docker runs checks in a standard Python image. GitHub CI runs tests and the complete backtest from included inputs.

make site builds the Quarto website from the saved results, verifies forecast metadata and checks the rendered links and downloadable files. The overview includes this README, so its documentation stays synchronized. See publication and updates and the sibling-data inventory.

For a single horizon or a historical forecast date:

national-selection prepare --horizons 12
national-selection evaluate --horizons 12
national-selection forecast --horizons 12 --cutoff 2024-06-01

The frozen benchmark defaults to January 1, 2026, using data through December 2025. make refresh creates current forecasts from updated match feeds. The monthly GitHub action runs on the 2nd at 08:23 UTC, retains earlier forecasts, and publishes the validated site. The actual cutoff follows source coverage; forecast history records each publication. The fit_date and cutoff_date are exported separately. Horizon-specific selection metadata must exist before forecasting that horizon. Forecasts are rejected if the policy was unavailable at the annual fit date, or if the requested cutoff exceeds documented input coverage plus one day.

Results and audits

The main key is Cricsheet's player UUID; names never enter prediction. Auction nationality is a dated proxy for affiliation, not certified eligibility. Unsupported countries and unknown identities are excluded explicitly. Independent horizon models need not produce monotone probabilities; consistency violations are reported, not silently repaired.

Data originate from sibling projects and their Cricsheet/auction sources. The code's MIT license does not replace source data terms. See the manifest and Cricsheet licensing.

About

Forecast first international cricket appearances and two-year match counts from dated player histories

Resources

Stars

1 star

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages