football-docs 0.1.2 → 0.2.0

package/docs/databallpy/usage.md

@@ -0,0 +1,280 @@
+# DataBallPy Usage Guide
+
+## Installation
+
+```bash
+pip install databallpy
+
+# With kloppy integration (expands provider support)
+pip install 'databallpy[kloppy]'
+
+# With dangerous accessible space metric
+pip install 'databallpy[accessible-space]'
+```
+
+## Loading Data
+
+### From Files with Native Parsers
+
+```python
+from databallpy import get_game
+
+# Tracab tracking + Opta events (most common combo)
+game = get_game(
+    tracking_data_loc="../data/tracking_data.dat",
+    tracking_metadata_loc="../data/tracking_metadata.xml",
+    tracking_data_provider="tracab",
+    event_data_loc="../data/event_data_f24.xml",
+    event_metadata_loc="../data/event_metadata_f7.xml",
+    event_data_provider="opta",
+)
+
+# StatsBomb events only (requires extra files)
+game = get_game(
+    event_data_loc="events.json",
+    event_match_loc="match.json",
+    event_lineup_loc="lineup.json",
+    event_data_provider="statsbomb",
+)
+
+# Metrica tracking + events
+game = get_game(
+    tracking_data_loc="tracking_home.csv",
+    tracking_metadata_loc="metadata.xml",
+    tracking_data_provider="metrica",
+    event_data_loc="events.json",
+    event_data_provider="metrica",
+)
+```
+
+### From Kloppy Datasets
+
+```python
+from kloppy import sportec
+from databallpy import get_game_from_kloppy
+
+tracking_dataset = sportec.load_open_tracking_data(match_id="J03WPY", only_alive=False)
+event_dataset = sportec.load_open_event_data(match_id="J03WPY")
+game = get_game_from_kloppy(
+    tracking_dataset=tracking_dataset,
+    event_dataset=event_dataset
+)
+```
+
+### Open Data (DFL/Bundesliga)
+
+```python
+from databallpy import get_open_game
+
+# 7 available matches (2 Bundesliga 1 + 5 Bundesliga 2)
+game = get_open_game(provider="sportec", game_id="J03WMX")  # Köln vs Bayern
+```
+
+### Save and Load Games
+
+```python
+# Save (creates parquet + JSON files)
+game.save_game(name="my_game", path="/data")
+
+# Load
+from databallpy import get_saved_game
+game = get_saved_game(name="my_game", path="/data")
+```
+
+## Accessing Data
+
+```python
+# DataFrames
+game.tracking_data   # TrackingData (custom DataFrame)
+game.event_data      # EventData (custom DataFrame)
+game.shot_events     # DataFrame of ShotEvent objects
+game.pass_events     # DataFrame of PassEvent objects
+game.dribble_events  # DataFrame of DribbleEvent objects
+
+# Player column IDs (for tracking data)
+home_col_ids = game.get_column_ids(team="home")
+defenders = game.get_column_ids(team="home", positions=["defender"])
+
+# Get specific frames
+frame_data = game.get_frames(12345, playing_direction="team_oriented")
+frame_data = game.get_frames(12345, playing_direction="possession_oriented")
+
+# Get event and its tracking frame
+event = game.get_event(event_id=42)
+frame = game.get_event_frame(event_id=42)
+
+# Match metadata
+game.home_team_name, game.away_team_name
+game.home_score, game.away_score
+game.home_formation, game.away_formation
+game.pitch_dimensions  # [length, width] in metres
+```
+
+## Synchronization
+
+Aligns tracking and event data using the Needleman-Wunsch algorithm. After sync, tracking data gets `event_id`, `databallpy_event`, `sync_certainty` columns; event data gets `tracking_frame`, `sync_certainty` columns.
+
+```python
+game.synchronise_tracking_and_event_data(
+    n_batches="smart",  # or int for manual batch count
+    verbose=True,
+    offset=1,           # seconds offset for alignment
+)
+
+# Check sync status
+game.is_synchronised  # bool
+```
+
+Quality checks must pass for sync to be allowed (kick-off near origin, ball alive >50% of game, player positions within bounds).
+
+## Preprocessing
+
+### Filtering Tracking Data
+
+```python
+game.tracking_data.filter_tracking_data(
+    column_ids=home_col_ids,
+    filter_type="savitzky_golay",
+    window_length=7,
+    polyorder=2,
+)
+```
+
+### Velocity and Acceleration
+
+```python
+# Add velocity columns (_vx, _vy)
+game.tracking_data.add_velocity(
+    column_ids=home_col_ids,
+    filter_type=None,          # optional smoothing
+    max_velocity=np.inf,
+)
+
+# Add acceleration columns (_ax, _ay)
+game.tracking_data.add_acceleration(
+    column_ids=home_col_ids,
+    filter_type=None,
+    max_acceleration=np.inf,
+)
+```
+
+## Analytics and Metrics
+
+### Covered Distance (by velocity/acceleration zones)
+
+```python
+result_df = game.tracking_data.get_covered_distance(
+    column_ids=home_col_ids,
+    velocity_intervals=((0, 5), (5, 20)),      # m/s
+    acceleration_intervals=((2, np.inf),),       # m/s²
+)
+```
+
+### Pressure (Herold & Kempe 2022)
+
+```python
+pressure = game.tracking_data.get_pressure_on_player(
+    index=12345,           # frame index
+    column_id="home_1",    # player to measure pressure on
+    pitch_size=game.pitch_dimensions,
+    d_front="variable",    # or float
+    d_back=3.0,
+    q=1.75,
+)
+```
+
+### Team Possession (from synchronized events)
+
+```python
+game.tracking_data.add_team_possession(game.event_data, game.home_team_id)
+```
+
+### Individual Player Possession (Vidal-Codina et al. 2022)
+
+```python
+game.tracking_data.add_individual_player_possession(
+    pz_radius=1.5,
+    bv_threshold=5.0,
+    ba_threshold=10.0,
+    min_frames_pz=0,
+)
+```
+
+### Pitch Control (Gaussian influence model)
+
+```python
+pitch_control = game.tracking_data.get_pitch_control(
+    pitch_dimensions=game.pitch_dimensions,
+    n_x_bins=106,
+    n_y_bins=68,
+)
+```
+
+### Voronoi Space Occupation
+
+```python
+distances, assigned = game.tracking_data.get_approximate_voronoi(
+    pitch_dimensions=game.pitch_dimensions,
+    n_x_bins=106,
+    n_y_bins=68,
+)
+```
+
+### Dangerous Accessible Space
+
+Requires `pip install 'databallpy[accessible-space]'`:
+
+```python
+game.tracking_data.add_dangerous_accessible_space(mask=None)
+```
+
+## Visualization
+
+```python
+from databallpy.visualize import (
+    plot_soccer_pitch, plot_tracking_data, plot_events, save_tracking_video
+)
+
+# Plot empty pitch
+fig, ax = plot_soccer_pitch(field_dimen=(106.0, 68.0), pitch_color="mediumseagreen")
+
+# Plot single tracking frame
+fig, ax = plot_tracking_data(
+    game, idx=12345,
+    team_colors=["green", "red"],
+    events=["pass", "shot"],
+    add_velocities=True,
+    add_player_possession=True,
+    heatmap_overlay=some_array,
+)
+
+# Plot events on pitch
+fig, ax = plot_events(game, events=["shot"], outcome=True, team_id=game.home_team_id)
+
+# Save video clip (requires ffmpeg)
+save_tracking_video(
+    game, start_idx=1000, end_idx=2000,
+    save_folder="./clips", title="goal_clip",
+    events=["shot"],
+)
+```
+
+## Video Analysis Export
+
+Export events to SportsCode/Longomatch-compatible XML:
+
+```python
+xml_str = game.event_data.to_video_analysis_xml(
+    databallpy_events=["shot", "pass"],
+    before_seconds=3.0,
+    after_seconds=3.0,
+)
+```
+
+## Long Format Conversion
+
+Convert tracking data from wide format (one column per player axis) to long format (one row per frame/player):
+
+```python
+long_df = game.tracking_data.to_long_format()
+```

package/docs/mplsoccer/overview.md

@@ -0,0 +1,25 @@
+# mplsoccer
+
+## Overview
+
+mplsoccer is a Python library for plotting soccer/football charts using Matplotlib and loading StatsBomb open data. Created by Andrew Rowlinson and Anmol Durgapal, licensed under MIT. Current version: 1.6.1.
+
+- **Install**: `pip install mplsoccer` or `conda install -c conda-forge mplsoccer`
+- **Dependencies**: matplotlib>=3.6, numpy, pandas, pillow, requests, scipy, seaborn
+
+## Key Features
+
+**Pitch-based visualizations**: scatter plots, heatmaps, hexbin, KDE plots, arrows (pass maps), comet lines, flow maps, Voronoi diagrams, Delaunay tessellation, convex hulls, polygons, goal angle visualization, pass networks, shot freeze frames, formations, Juego de Posición heatmaps, pass sonars, animations.
+
+**Non-pitch chart types**: radar charts (`Radar`), pizza/Nightingale charts (`PyPizza`), bumpy charts (`Bumpy`), turbine charts.
+
+**Utilities**: `FontManager` (Google Fonts), `Standardizer` (coordinate conversion), `add_image`/`inset_image`, `grid()`/`jointgrid()` layout helpers, `Sbopen`/`Sbapi`/`Sblocal` (StatsBomb data loading).
+
+## Limitations and Caveats
+
+- **Y-axis inversion varies by provider**: StatsBomb, Wyscout, and Metrica have inverted y-axes. mplsoccer handles this internally.
+- **Tracking data pitch types require explicit dimensions**: `tracab`, `metricasports`, `skillcorner`, `secondspectrum`, and `custom` all need `pitch_length` and `pitch_width`.
+- **Wyscout goal width discrepancy**: mplsoccer uses ggsoccer's 12 units (vs socceraction's 10 units).
+- **Opta vs Wyscout**: Both use 0-100 coordinates but Wyscout has inverted y-axis. Easy to mix up.
+- **Matplotlib-based**: Performance for very large datasets or interactive use can be limited.
+- **No built-in data fetching beyond StatsBomb**: For Opta, Wyscout, etc., load data yourself; mplsoccer only handles visualization and coordinate standardization.

package/docs/mplsoccer/pitch-types.md

@@ -0,0 +1,88 @@
+# mplsoccer Pitch Types and Coordinate Systems
+
+## Supported Pitch Types
+
+| Pitch Type | Provider | X Range | Y Range | Dimensions Required | Notes |
+|---|---|---|---|---|---|
+| `statsbomb` (default) | StatsBomb | 0-120 | 80-0 (inverted y) | No (fixed) | Default pitch type |
+| `opta` | Stats Perform / Opta | 0-100 | 0-100 | No (fixed) | Also used by Sofascore, WhoScored |
+| `wyscout` | Wyscout / Hudl | 0-100 | 0-100 (inverted y) | No (fixed) | Similar to Opta but y-inverted |
+| `tracab` | TRACAB / ChyronHego | Centered, cm | Centered, cm | Yes | Values in centimetres |
+| `uefa` | UEFA | 0-105 | 0-68 | No (fixed) | Standard 105m x 68m |
+| `metricasports` | Metrica Sports | 0-1 | 0-1 (inverted y) | Yes | Normalised coordinates |
+| `skillcorner` | SkillCorner | Centered, m | Centered, m | Yes | Values in metres |
+| `secondspectrum` | Second Spectrum | Centered, m | Centered, m | Yes | Values in metres |
+| `impect` | Impect | -52.5 to 52.5 | -34 to 34 | No (fixed) | Centered |
+| `custom` | Any | 0 to pitch_length | 0 to pitch_width | Yes | Fully configurable |
+
+Tracking data providers (`tracab`, `metricasports`, `skillcorner`, `secondspectrum`, `custom`) require explicit `pitch_length` and `pitch_width` (typically 105 and 68).
+
+## Pitch Constructor
+
+```python
+from mplsoccer import Pitch, VerticalPitch
+
+# Basic pitch
+pitch = Pitch(pitch_type='statsbomb')
+
+# Tracking data pitch (requires dimensions)
+pitch = Pitch(pitch_type='tracab', pitch_length=105, pitch_width=68)
+
+# Customisation
+pitch = Pitch(
+    pitch_type='statsbomb',
+    pitch_color='grass',       # 'grass' or any color
+    line_color='white',
+    stripe=True,               # alternating grass stripes
+    stripe_color='#c2d59d',
+    half=True,                 # show only half pitch
+    goal_type='box',           # 'line', 'box', 'circle', or None
+    positional=True,           # Juego de Posición zone lines
+    corner_arcs=True,
+    pad_left=5, pad_right=5,   # padding in data units
+    pad_bottom=5, pad_top=5,
+)
+
+# Vertical orientation (rotated 90°)
+vpitch = VerticalPitch(pitch_type='opta')
+```
+
+## Coordinate Standardization
+
+The `Standardizer` converts coordinates between any two pitch types by mapping pitch markings (penalty areas, six-yard boxes, etc.) -- not just linear scaling. This is more accurate for event data but means the mapping is piecewise-linear.
+
+```python
+from mplsoccer import Standardizer
+
+# Convert Opta (0-100) to StatsBomb (120x80)
+std = Standardizer(pitch_from='opta', pitch_to='statsbomb')
+x_new, y_new = std.transform(x, y)
+
+# Reverse direction
+x_orig, y_orig = std.transform(x_new, y_new, reverse=True)
+
+# For tracking data, specify dimensions
+std = Standardizer(
+    pitch_from='tracab', pitch_to='statsbomb',
+    length_from=105, width_from=68
+)
+```
+
+## Custom Dimensions
+
+For normalised ML coordinate systems, use `center_scale_dims()`:
+
+```python
+from mplsoccer.dimensions import center_scale_dims
+
+# Create a -1 to 1 coordinate space
+custom_dims = center_scale_dims(
+    pitch_width=68, pitch_length=105,
+    width=2, length=2,
+    invert_y=False
+)
+
+pitch = Pitch(pitch_type=custom_dims)
+```
+
+For fully custom dimensions, subclass `BaseSoccerDims`.

package/docs/mplsoccer/visualizations.md

@@ -0,0 +1,280 @@
+# mplsoccer Visualizations
+
+## Drawing a Pitch
+
+```python
+from mplsoccer import Pitch, VerticalPitch
+
+pitch = Pitch()
+fig, ax = pitch.draw()
+
+# Grid of pitches
+fig, axs = pitch.draw(nrows=2, ncols=3)
+
+# On existing axes
+pitch.draw(ax=existing_ax)
+```
+
+All plotting methods are called on the pitch object, passing `ax=ax` as a parameter.
+
+## Scatter Plots (Shot Maps, Player Positions)
+
+```python
+pitch.scatter(x, y, ax=ax, s=100, c='red', edgecolors='black', zorder=2)
+
+# With rotation (e.g., for player orientation arrows)
+pitch.scatter(x, y, rotation_degrees=angle, ax=ax)
+
+# Football marker
+pitch.scatter(x, y, marker='football', ax=ax)
+```
+
+## Heatmaps (Binned Statistics)
+
+Two-step workflow: bin the data, then plot.
+
+```python
+# Step 1: Bin the data
+bin_statistic = pitch.bin_statistic(x, y, statistic='count', bins=(25, 25))
+
+# Optional: Gaussian smoothing
+from scipy.ndimage import gaussian_filter
+bin_statistic['statistic'] = gaussian_filter(bin_statistic['statistic'], sigma=1)
+
+# Step 2: Plot
+pcm = pitch.heatmap(bin_statistic, ax=ax, cmap='hot', edgecolors='#22312b')
+
+# Optional: Add labels
+pitch.label_heatmap(bin_statistic, ax=ax, str_format='{:.0f}', color='white',
+                     fontsize=8, exclude_zeros=True)
+```
+
+## Juego de Posición Heatmaps
+
+Positional play zones (used by Pep Guardiola-style analysis):
+
+```python
+bin_statistic = pitch.bin_statistic_positional(x, y, statistic='count')
+pitch.heatmap_positional(bin_statistic, ax=ax, cmap='coolwarm', edgecolors='#22312b')
+pitch.label_heatmap(bin_statistic, ax=ax, str_format='{:.0f}')
+```
+
+## Hexbin Plots
+
+```python
+pitch.hexbin(x, y, ax=ax, gridsize=20, cmap='Reds', edgecolors='grey')
+```
+
+NaN values are filtered out internally.
+
+## KDE Plots (Kernel Density Estimation)
+
+Uses seaborn internally, auto-clipped to pitch boundaries.
+
+```python
+pitch.kdeplot(x, y, ax=ax, fill=True, levels=100, cmap='Reds', thresh=0)
+```
+
+## Arrows (Pass Maps)
+
+```python
+pitch.arrows(xstart, ystart, xend, yend, ax=ax,
+             color='blue', width=2, headwidth=5, headlength=5)
+```
+
+## Lines and Comet Lines
+
+```python
+# Standard lines
+pitch.lines(xstart, ystart, xend, yend, ax=ax, lw=2, color='blue')
+
+# Comet lines (transparency gradient from start to end)
+pitch.lines(xstart, ystart, xend, yend, ax=ax, comet=True,
+            transparent=True, alpha_start=0.01, alpha_end=1.0)
+
+# Comet with colormap
+pitch.lines(xstart, ystart, xend, yend, ax=ax, comet=True,
+            cmap='plasma', n_segments=100)
+```
+
+Note: comet lines split each line into `n_segments` (default 100). Large datasets may be slow.
+
+## Flow Maps
+
+Binned average direction and distance as arrows:
+
+```python
+pitch.flow(xstart, ystart, xend, yend, ax=ax,
+           bins=(6, 4), arrow_type='same', arrow_length=10, color='blue')
+```
+
+## Voronoi Diagrams
+
+```python
+team1, team2 = pitch.voronoi(x, y, teams)
+pitch.polygon(team1, ax=ax, fc='red', alpha=0.3, ec='black')
+pitch.polygon(team2, ax=ax, fc='blue', alpha=0.3, ec='black')
+```
+
+Uses a reflection trick to extend Voronoi cells to pitch edges. Players outside pitch boundaries are clipped.
+
+## Convex Hulls
+
+```python
+hull = pitch.convexhull(x, y)
+pitch.polygon(hull, ax=ax, facecolor='cornflowerblue', alpha=0.3)
+```
+
+## Delaunay Tessellation
+
+```python
+pitch.triplot(x, y, ax=ax, color='blue', linewidth=2)
+```
+
+## Goal Angle Visualization
+
+```python
+pitch.goal_angle(x, y, ax=ax, goal='right', alpha=0.3, color='red')
+```
+
+## Pass Sonars
+
+```python
+bin_statistic = pitch.bin_statistic_sonar(x, y, angle, bins=(6, 4, 8))
+pitch.sonar(bin_statistic, ax=ax, fc='cornflowerblue')
+pitch.sonar_grid(bin_statistic, ax=ax)
+```
+
+## Radar Charts
+
+```python
+from mplsoccer import Radar
+
+radar = Radar(
+    params=['Goals', 'Assists', 'xG', 'xA', 'Passes'],
+    min_range=[0, 0, 0, 0, 0],
+    max_range=[30, 20, 25, 15, 3000],
+    lower_is_better=['Miscontrol'],  # invert specific params
+    num_rings=4,
+    ring_width=1,
+    center_circle_radius=2,
+)
+
+fig, ax = radar.setup_axis()
+radar.draw_circles(ax=ax)
+rings_inner, rings_outer, vertices = radar.draw_radar(
+    values, ax=ax, kwargs_radar={'facecolor': '#aa65b2', 'alpha': 0.6}
+)
+radar.draw_range_labels(ax=ax)
+radar.draw_param_labels(ax=ax)
+
+# Comparison radar (two players)
+radar.draw_radar_compare(values1, values2, ax=ax)
+
+# Multi-player (3+) -- stacked solid fills
+radar.draw_radar_solid(values_list, ax=ax)
+```
+
+## Pizza Charts (Percentile Ranks)
+
+```python
+from mplsoccer import PyPizza
+
+baker = PyPizza(
+    params=params,
+    straight_line_color="#000000",
+    straight_line_lw=1,
+    last_circle_lw=1,
+    other_circle_lw=1,
+    other_circle_ls="-.",
+    inner_circle_size=20,
+)
+
+fig, ax = baker.make_pizza(
+    values, figsize=(8, 8), param_location=110,
+    kwargs_slices=dict(facecolor='cornflowerblue', edgecolor='black'),
+    kwargs_params=dict(color='black', fontsize=12),
+    kwargs_values=dict(color='black', fontsize=12),
+)
+```
+
+## Bumpy Charts (Rank Changes)
+
+```python
+from mplsoccer import Bumpy
+
+bumpy = Bumpy(
+    scatter_color='#282828',
+    line_color='#252525',
+    rotate_xticks=90,
+    ticklabel_size=12,
+)
+
+fig, ax = bumpy.plot(
+    x_list=matchweeks, y_list=rankings, values=team_names,
+    highlight_dict={'Arsenal': 'red'},
+    figsize=(16, 10),
+)
+```
+
+## Layout Helpers
+
+### Grid (title + pitch + endnote)
+
+```python
+fig, axs = pitch.grid(figheight=10, title_height=0.06, endnote_height=0.03)
+# axs is a dict: axs['pitch'], axs['title'], axs['endnote']
+axs['title'].text(0.5, 0.5, 'My Title', ha='center', va='center')
+```
+
+### Joint Grid (pitch + marginal axes)
+
+```python
+fig, axs = pitch.jointgrid(ax_top=True, ax_right=True)
+# axs['pitch'], axs['top'], axs['right'], axs['title'], axs['endnote']
+```
+
+## StatsBomb Data Loading
+
+```python
+from mplsoccer import Sbopen
+
+parser = Sbopen()
+
+# Browse available data
+df_competition = parser.competition()
+df_match = parser.match(competition_id=11, season_id=1)
+
+# Load match data
+df_lineup = parser.lineup(match_id)
+df_event, df_related, df_freeze, df_tactics = parser.event(match_id)
+
+# StatsBomb 360 data
+frames, visible = parser.frame(match_id)
+```
+
+Also available: `Sbapi` (for API access with credentials) and `Sblocal` (for local files).
+
+## Utility Functions
+
+```python
+from mplsoccer import FontManager, add_image
+
+# Load Google Fonts
+fm = FontManager('https://raw.githubusercontent.com/google/fonts/main/ofl/roboto/Roboto-Regular.ttf')
+
+# Add image/logo to plot
+add_image(image, fig, left=0.1, bottom=0.9, width=0.1)
+
+# Inset axes on pitch (e.g., for mini charts at player positions)
+inset_ax = pitch.inset_axes(x, y, width=10, height=10, ax=ax)
+
+# Inset image on pitch
+pitch.inset_image(x, y, image, width=10, ax=ax)
+
+# Flip coordinates to other half
+x_flip, y_flip = pitch.flip_side(x, y, flip=True)
+
+# Calculate angle and distance
+angle, distance = pitch.calculate_angle_and_distance(x1, y1, x2, y2, degrees=True)
+```