# Data Format

## Purpose
This document explains the CSV inputs expected by the public `La Liga Score Predictor` bundle.

There are two kinds of CSV files in the bundle:
1. `sample_history.csv`
   - historical match data used by `predict_match(...)`
2. `sample_fixtures.csv`
   - upcoming fixtures used by `predict_batch.py`

The included public samples are synthetic and are meant for:
- onboarding
- smoke testing
- demo predictions
- understanding the expected schema

They are not meant to be treated as a production historical archive.

## Minimum History CSV Requirements
To use:
- `predict_match(...)`
- `predict_match_simple(...)`

your history CSV must contain at least these columns:
- `date`
- `home_team`
- `away_team`
- `home_goals`
- `away_goals`

### Expected meanings
- `date`
  - match date in a parseable date format
- `home_team`
  - home team name
- `away_team`
  - away team name
- `home_goals`
  - final home goals
- `away_goals`
  - final away goals

## Better Optional Columns
Prediction quality is better if your history CSV also includes:
- `home_team_id`
- `away_team_id`
- `home_elo_pre`
- `away_elo_pre`
- `elo_diff_pre`
- `home_tactic_id`
- `away_tactic_id`
- `home_coach_id`
- `away_coach_id`
- `home_player_minutes_total_prev5`
- `away_player_minutes_total_prev5`
- `home_player_goals_total_prev5`
- `away_player_goals_total_prev5`
- `home_player_assists_total_prev5`
- `away_player_assists_total_prev5`
- `home_player_yellow_cards_total_prev5`
- `away_player_yellow_cards_total_prev5`
- `home_player_red_cards_total_prev5`
- `away_player_red_cards_total_prev5`
- `home_player_starters_count_prev5`
- `away_player_starters_count_prev5`
- `home_player_used_count_prev5`
- `away_player_used_count_prev5`
- `home_player_injured_count_prev5`
- `away_player_injured_count_prev5`
- `home_player_suspended_count_prev5`
- `away_player_suspended_count_prev5`
- `home_tactic_stability_last5`
- `away_tactic_stability_last5`

These optional fields help the wrapper compute richer features with fewer fallbacks.

## Sample History CSV Shape
Example header from the included synthetic sample:

```csv
match_id,date,home_team,away_team,home_goals,away_goals,home_team_id,away_team_id,home_elo_pre,away_elo_pre,elo_diff_pre,home_tactic_id,away_tactic_id,home_coach_id,away_coach_id
```

The bundled synthetic history currently includes:
- `120` rows
- `20` La Liga team names
- `35` columns
- enough depth for rolling-form demo calculations
- richer optional context columns for better demonstration quality

## Fixture CSV Requirements
For `predict_batch.py`, the fixtures CSV should contain:
- `home_team`
- `away_team`
- `match_date`

Example:

```csv
home_team,away_team,match_date
Athletic,Osasuna,2026-04-21
Girona FC,Real Betis,2026-04-21
Mallorca,Valencia,2026-04-21
```

The bundled synthetic fixtures currently include:
- `10` upcoming sample fixtures

## Team Name Normalization
The public wrapper performs team-name normalization so common formatting differences are easier to handle.

Examples of tolerated variations include:
- `Atletico Madrid` and `Atlético de Madrid`
- `Mallorca` and `Real Mallorca`
- case differences such as `girona fc` and `Girona FC`

Still, best practice is:
- keep one stable team naming style in your dataset
- keep the same team naming style in fixture inputs

## What Happens If Optional Columns Are Missing
The wrapper falls back to dataset-level defaults for richer fields it cannot derive directly.

That keeps the interface usable, but it also means:
- predictions may be weaker than the full internal training environment
- richer tactical and identity context may be partially approximated

## Developer Expectation
This public package is designed so developers can do two things:

1. use the included synthetic samples to understand the integration flow
2. replace those samples with their own compatible historical data for real use

If you keep using only the synthetic sample files:
- the package will run correctly
- the methods will behave correctly
- but the predictions should be treated as demonstration-quality, not production-quality

## Why The Model Can Use 48 Signals Even If The CSV Has Fewer Columns
The trained model expects `48` numeric input signals at inference time.

Those signals are produced in three ways:
1. directly from columns already present in the history CSV
2. derived by the wrapper from past match rows
3. filled by fallback defaults when richer optional context is missing

So the public rule is:
- the CSV does not need to contain all `48` final model inputs as raw columns
- but a richer CSV allows the wrapper to produce a stronger feature row

## What Not To Publish
Do not publish large internal historical CSVs unless redistribution rights are explicit.

Safer public release options are:
- synthetic sample CSVs
- schema documentation
- notebooks that expect users to provide their own history CSV

That is why this bundle includes only small synthetic examples.