data-sources
Choose public sports data sources for a modeling question across NFL, NBA, MLB, NHL, college sports, soccer, and more. Use before acquisition code or whenever source coverage, grain, licensing, or historical depth is unclear.
WalrusQuant · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add WalrusQuant/sports-analytic-skills --skill data-sources技能说明
name: data-sources description: > Choose public sports data sources for a modeling question across NFL, NBA, MLB, NHL, college sports, soccer, and more. Use before acquisition code or whenever source coverage, grain, licensing, or historical depth is unclear. license: MIT metadata: version: "0.12.0"
Data Sources
When to Use This Skill
Use when:
- the user needs a public sports data source and is not sure which one;
- choosing grain (game, team-game, player-game, play/event) before loading;
- comparing nflverse / sportsdataverse / pybaseball / other public options;
- writing a source plan with provenance, snapshot, and first-load checks.
Do not use this skill when:
- the user already has a usable table and wants EDA or modeling;
- they explicitly want the optional repository toolkit panels/CLI →
sports-ds-bridge; - they already chose a loader and just need that loader skill.
| Need | Go instead |
|---|---|
| NFL loader details | nflreadpy |
| Multi-sport SDV details | sportsdataverse-py |
| MLB / Statcast details | pybaseball |
| Optional toolkit bridge | sports-ds-bridge |
| EDA after load | eda-sports |
Outcome
Produce a source plan naming the required grain, decision-time fields, primary source, fallback, coverage risks, terms, snapshot rule, and first-load checks. Source choice does not create predictive validity; it determines whether the question can be answered reproducibly and legally.
Use this skill before acquisition code or whenever coverage, field semantics, historical depth, IDs, latency, or licensing are uncertain. If the source is already chosen and a loader fails, use its package skill instead.
Required inputs
- sport, competition, question, target, and analytical population;
- analytical grain and natural key: season, game, team-game, player-game, possession, play, pitch, or event;
- each candidate source's native grain and the aggregation/join contract needed to reach the analytical grain;
- historical depth, expected volume, refresh cadence, and completion latency;
- exact prediction decision time T and fields that must be known by then;
- stable identifiers and cross-source joins required;
- license, attribution, redistribution, authentication, and rate constraints;
- required raw and derived artifact formats.
Candidate guide
These are ecosystems to investigate, not durable rankings. Confirm current coverage, access, and terms in upstream documentation at selection time.
| Need | Candidate ecosystem | Verify before committing |
|---|---|---|
| NFL schedules, PBP, rosters, weekly data | nflverse / nflreadpy | table-specific grain, season coverage, schema drift |
| Basketball, hockey, college, soccer | maintained league/public modules, including SportsDataverse where applicable | competition/table support and field definitions |
| MLB Statcast/pitch or season tables | public MLB data tooling such as pybaseball | query-specific grain, bounded dates, field availability |
| Detailed event/possession data | public league-specific event provider | event IDs, ordering, correction policy |
| Cross-source enrichment | sources with stable IDs and timestamps | join coverage and as-of legality |
Read the source matrix while shortlisting ecosystems, the terms notes before acquisition or redistribution, and the sanity checks before accepting the first pull.
Choose a source whose native records contain the facts required for the analytical grain, and write the aggregation contract when the grains differ. For example, play data may be aggregated to team-game only after event ordering, completion, and key rules are explicit. A season aggregate cannot manufacture play-level detail or historical publication vintages it never contained.
Source comparison rubric
Compare at least two plausible sources on:
| Dimension | Questions |
|---|---|
| Coverage | Which competitions, seasons, phases, and entities exist? |
| Grain | What is one native record and its key? If it differs from the analytical grain, is the transformation explicit and valid? |
| Semantics | Are fields, units, ties, overtime, and completion states defined? |
| Time | Event, publication, update, and revision timestamps available? |
| Identity | Stable event/team/player IDs across seasons and sources? |
| Reliability | Bulk releases, versioning, uptime, schema-change notices? |
| Access | Terms, license, attribution, auth, rate and redistribution limits? |
| Reproducibility | Can responses be snapshotted and checksummed? |
| Cost/volume | Can the bounded request fit time, memory, storage, and quotas? |
Do not treat “popular” or “easy to import” as sufficient evidence.
Workflow
- Lock question, analytical grain/key, target, population, and T.
- List only the minimum required raw fields and stable identifiers.
- Shortlist and compare a primary and fallback source with the rubric.
- Read upstream documentation and record field/time semantics and terms.
- Estimate request count and data volume; bound event-level pulls by dates/IDs.
- Pull the smallest representative sample spanning relevant eras/statuses.
- Validate keys, row counts, periods, outcomes, entities, timestamps, and nulls.
- Test required joins on a small sample and quantify unmatched/many-to-many rows.
- Save the untouched raw response or immutable snapshot with retrieval metadata.
- Document fallback triggers, known gaps, and the EDA handoff.
First-load diagnostics
- nonzero rows and requested competitions/seasons are present;
- natural keys are unique at the claimed grain;
- scheduled, live, completed, canceled, and postponed records are distinguishable;
- completed events have plausible outcomes and nonconstant score distributions;
- team-game overall win rate is near its paired identity and home-only rates are plausible;
- identifiers remain stable or have a documented crosswalk;