{
"cells": [
{
"cell_type": "markdown",
"id": "ba2d3f24",
"metadata": {},
"source": [
"# Pitch Examples"
]
},
{
"cell_type": "code",
"execution_count": 1,
"id": "5377871b",
"metadata": {},
"outputs": [
{
"name": "stderr",
"output_type": "stream",
"text": [
"/Users/martin/repos/penaltyblog/venv/lib/python3.13/site-packages/statsbombpy/api_client.py:21: NoAuthWarning: credentials were not supplied. open data access only\n",
" warnings.warn(\n"
]
}
],
"source": [
"from penaltyblog.viz import Pitch\n",
"from penaltyblog.matchflow import Flow, where_equals, get_field\n",
"from IPython.display import HTML\n",
"import plotly.io as pio\n",
"\n",
"\n",
"flow = (\n",
" Flow\n",
" .statsbomb\n",
" .events(22912)\n",
" .cache()\n",
")"
]
},
{
"cell_type": "markdown",
"id": "02b55b8b",
"metadata": {},
"source": [
"## Scatter Plot\n",
"\n",
"The scatter plot is the most versatile and commonly used chart for visualizing individual events or locations on the pitch. Each marker represents a single data point - such as a shot, pass, or player position - plotted using its `(x, y)` coordinates. This type of chart is ideal for exploring patterns, clusters, or areas of activity. You can customize marker size, color, and tooltip content to highlight specific aspects of the data. Hover over the dots to reveal interactive tooltips with additional context, such as player names, event types, or timestamps. Note that by default, the tooltips will only show the x and y coordinates of the marker."
]
},
{
"cell_type": "code",
"execution_count": 2,
"id": "d5874344",
"metadata": {},
"outputs": [
{
"name": "stderr",
"output_type": "stream",
"text": [
"/Users/martin/repos/penaltyblog/venv/lib/python3.13/site-packages/statsbombpy/api_client.py:21: NoAuthWarning:\n",
"\n",
"credentials were not supplied. open data access only\n",
"\n"
]
},
{
"data": {
"text/html": [
"\n",
"\n",
"\n",
" \n",
"\n",
""
],
"text/plain": [
""
]
},
"execution_count": 2,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"pitch = Pitch(\n",
" provider=\"statsbomb\",\n",
" orientation=\"horizontal\",\n",
" view=\"right\",\n",
" theme=\"night\",\n",
" show_axis=False,\n",
" show_legend=False,\n",
" width=400,\n",
" height=400\n",
")\n",
"\n",
"shots = (\n",
" flow\n",
" .filter(where_equals(\"type.name\", \"Shot\"))\n",
" .filter(where_equals(\"team.name\", \"Liverpool\"))\n",
")\n",
"\n",
"pitch.plot_scatter(shots, \"location.0\", \"location.1\")\n",
"\n",
"# NOTE: normally we'd just call `pitch.show()` here, but since\n",
"# we're exporting to HTML docs, we need to use `HTML` to export \n",
"# the plot\n",
"HTML(pio.to_html(pitch.fig, include_plotlyjs=\"cdn\"))"
]
},
{
"cell_type": "markdown",
"id": "501b54cb",
"metadata": {},
"source": [
"## Heatmap\n",
"\n",
"The heatmap chart shows the distribution or intensity of activity across different areas of the pitch. It works by dividing the field into a grid of rectangular bins and counting how many events (e.g. passes, touches, defensive actions) fall into each one. This makes it easy to identify hotspots - areas where play is concentrated or where certain players are most active. Heatmaps are particularly useful for summarizing large datasets at a glance. Hover over each cell to see the exact count of events and the corresponding location on the pitch."
]
},
{
"cell_type": "code",
"execution_count": 3,
"id": "ae121425",
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"\n",
"\n",
"\n",
" \n",
"\n",
""
],
"text/plain": [
""
]
},
"execution_count": 3,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"pitch = Pitch(\n",
" provider=\"statsbomb\",\n",
" orientation=\"horizontal\",\n",
" view=\"full\",\n",
" theme=\"night\",\n",
" show_axis=False,\n",
" show_legend=False,\n",
" width=400,\n",
" height=400\n",
")\n",
"\n",
"passes = flow.filter(where_equals(\"type.name\", \"Pass\"))\n",
"\n",
"pitch.plot_heatmap(\n",
" passes,\n",
" x=\"location.0\",\n",
" y=\"location.1\",\n",
" colorscale=\"Viridis\",\n",
" opacity=0.6,\n",
")\n",
"\n",
"# NOTE: normally we'd just call `pitch.show()` here, but since\n",
"# we're exporting to HTML docs, we need to use `HTML` to export \n",
"# the plot\n",
"HTML(pio.to_html(pitch.fig, include_plotlyjs=\"cdn\"))"
]
},
{
"cell_type": "markdown",
"id": "c148fbc5",
"metadata": {},
"source": [
"## KDE Plot\n",
"\n",
"The KDE (Kernel Density Estimate) chart provides a smooth, continuous visualization of where events are most concentrated on the pitch. Unlike a heatmap, which uses fixed-size grid bins, the KDE computes a probability density surface by estimating how densely points are clustered in different regions. This results in a more fluid, contour-like view of player movement, shot locations, or ball recoveries. It's especially useful for visualizing tendencies or patterns in noisy or unevenly distributed data. Hover over any area to see the estimated density value at that point."
]
},
{
"cell_type": "code",
"execution_count": 4,
"id": "7720fb58",
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"\n",
"\n",
"\n",
" \n",
"\n",
""
],
"text/plain": [
""
]
},
"execution_count": 4,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"pitch = Pitch(\n",
" provider=\"statsbomb\",\n",
" orientation=\"horizontal\",\n",
" view=\"full\",\n",
" theme=\"night\",\n",
" show_axis=False,\n",
" show_legend=False,\n",
" width=400,\n",
" height=400\n",
")\n",
"\n",
"passes = flow.filter(where_equals(\"type.name\", \"Pass\"))\n",
"\n",
"pitch.plot_kde(\n",
" passes,\n",
" x=\"location.0\",\n",
" y=\"location.1\",\n",
" colorscale=\"Viridis\",\n",
")\n",
"\n",
"# NOTE: normally we'd just call `pitch.show()` here, but since\n",
"# we're exporting to HTML docs, we need to use `HTML` to export \n",
"# the plot\n",
"HTML(pio.to_html(pitch.fig, include_plotlyjs=\"cdn\"))"
]
},
{
"cell_type": "markdown",
"id": "64133b55",
"metadata": {},
"source": [
"## Arrow Plot\n",
"\n",
"The `plot_arrows` method is used to visualize directional movement between two points—such as passes, runs, or ball progressions—by drawing arrows from a start `(x, y)` to an end `(x2, y2)` location. This provides a clear, intuitive way to represent flows of play or tactical patterns on the pitch. Arrows can be styled with adjustable width, head size, and color. However, due to Plotly’s rendering limitations, these arrows are implemented as annotations and may not support interactive hover tooltips in all environments. For fully interactive arrows with hover text, consider using `plot_comets` as an alternative, or overlay a scatter chart."
]
},
{
"cell_type": "code",
"execution_count": 5,
"id": "10b5242a",
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"\n",
"\n",
"\n",
" \n",
"\n",
""
],
"text/plain": [
""
]
},
"execution_count": 5,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"pitch = Pitch(\n",
" provider=\"statsbomb\",\n",
" orientation=\"horizontal\",\n",
" view=\"full\",\n",
" theme=\"night\",\n",
" show_axis=False,\n",
" show_legend=False,\n",
" width=400,\n",
" height=400\n",
")\n",
"\n",
"arrows = Flow.from_records([\n",
" {\"x\": 10, \"y\": 20, \"x2\": 40, \"y2\": 50},\n",
" {\"x\": 60, \"y\": 30, \"x2\": 80, \"y2\": 60}\n",
"])\n",
"\n",
"pitch.plot_arrows(\n",
" arrows, \n",
" width=3,\n",
")\n",
"\n",
"# NOTE: normally we'd just call `pitch.show()` here, but since\n",
"# we're exporting to HTML docs, we need to use `HTML` to export \n",
"# the plot\n",
"HTML(pio.to_html(pitch.fig, include_plotlyjs=\"cdn\")) "
]
},
{
"cell_type": "markdown",
"id": "16dd9395",
"metadata": {},
"source": [
"## Comet Plot\n",
"\n",
"The `plot_comets` method is designed to show movement between two points using fading trail lines - ideal for illustrating passes, runs, or ball trajectories with a sense of motion. Each \"comet\" is drawn as a series of line segments that fade from opaque (start) to transparent (end), mimicking momentum or direction. You can customize the number of segments, line width, color, and whether the trail fades. Unlike `plot_arrows`, comets are built using Plotly Scatter traces, so they fully support interactive hover tooltips — even in static exports or notebook environments. This makes them a great choice when you want directional lines and interactivity."
]
},
{
"cell_type": "code",
"execution_count": 6,
"id": "fc23fd76",
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"\n",
"\n",
"\n",
" \n",
"\n",
""
],
"text/plain": [
""
]
},
"execution_count": 6,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"pitch = Pitch(\n",
" provider=\"statsbomb\",\n",
" orientation=\"horizontal\",\n",
" view=\"full\",\n",
" theme=\"night\",\n",
" show_axis=False,\n",
" show_legend=False,\n",
" width=400,\n",
" height=400\n",
")\n",
"\n",
"arrows = Flow.from_records([\n",
" {\"x\": 10, \"y\": 20, \"x2\": 40, \"y2\": 50, \"player\": \"Daniella\"},\n",
" {\"x\": 60, \"y\": 30, \"x2\": 80, \"y2\": 60, \"player\": \"Natalie\"}\n",
"])\n",
"\n",
"pitch.plot_comets(\n",
" arrows, \n",
" width=5,\n",
" hover=\"player\",\n",
")\n",
"\n",
"# NOTE: normally we'd just call `pitch.show()` here, but since\n",
"# we're exporting to HTML docs, we need to use `HTML` to export \n",
"# the plot\n",
"HTML(pio.to_html(pitch.fig, include_plotlyjs=\"cdn\")) "
]
},
{
"cell_type": "markdown",
"id": "523022da",
"metadata": {},
"source": [
"## Overlaying Charts\n",
"\n",
"One of the key strengths of the `Pitch` class is its ability to layer multiple charts on top of each other. This makes it easy to combine different types of visual information in a single, coherent view - for example, overlaying a scatter plot of shots on top of a heatmap of overall activity. Each plot is added to a named layer, which can be reordered, hidden, or removed independently. This layering system is especially useful for building rich tactical visualizations that show both patterns and specific events at once."
]
},
{
"cell_type": "code",
"execution_count": 7,
"id": "1fb28b56",
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"\n",
"\n",
"\n",
" \n",
"\n",
""
],
"text/plain": [
""
]
},
"execution_count": 7,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"pitch = Pitch(\n",
" provider=\"statsbomb\",\n",
" orientation=\"horizontal\",\n",
" view=\"full\",\n",
" theme=\"night\",\n",
" show_axis=False,\n",
" show_legend=False,\n",
" width=400,\n",
" height=400\n",
")\n",
"\n",
"passes = flow.filter(where_equals(\"type.name\", \"Pass\"))\n",
"\n",
"pitch.plot_heatmap(\n",
" passes,\n",
" x=\"location.0\",\n",
" y=\"location.1\",\n",
" colorscale=\"Viridis\",\n",
")\n",
"\n",
"pitch.plot_scatter(\n",
" passes,\n",
" x=\"location.0\",\n",
" y=\"location.1\",\n",
" size=2,\n",
" color=\"white\",\n",
")\n",
"\n",
"# NOTE: normally we'd just call `pitch.show()` here, but since\n",
"# we're exporting to HTML docs, we need to use `HTML` to export \n",
"# the plot\n",
"HTML(pio.to_html(pitch.fig, include_plotlyjs=\"cdn\"))"
]
},
{
"cell_type": "markdown",
"id": "3259bc65",
"metadata": {},
"source": [
"## Themes\n",
"\n",
"The Pitch class supports a range of built-in themes that control the visual style of your charts, including pitch color, line styling, marker colors, fonts, and hover tooltip appearance. Themes like `\"classic\"`, `\"night\"`, `\"retro\"`, `\"minimal\"`, and `\"turf\"` provide distinct aesthetics suited to different presentation styles or branding needs. You can switch themes with a single parameter, or define your own by passing a custom dictionary of style values. Themes ensure your visualizations look polished and consistent with minimal effort, whether you're building reports, presentations, or interactive dashboards."
]
},
{
"cell_type": "markdown",
"id": "9d7fc9a1",
"metadata": {},
"source": [
"### Minimal Theme"
]
},
{
"cell_type": "code",
"execution_count": 8,
"id": "f48c8346",
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"\n",
"\n",
"\n",
" \n",
"\n",
""
],
"text/plain": [
""
]
},
"execution_count": 8,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"pitch = Pitch(\n",
" provider=\"statsbomb\",\n",
" orientation=\"horizontal\",\n",
" view=\"full\",\n",
" theme=\"minimal\",\n",
" show_axis=False,\n",
" show_legend=False,\n",
" width=400,\n",
" height=400\n",
")\n",
"\n",
"pitch.plot_scatter(shots, \"location.0\", \"location.1\")\n",
"\n",
"HTML(pio.to_html(pitch.fig, include_plotlyjs=\"cdn\"))"
]
},
{
"cell_type": "markdown",
"id": "de1dd487",
"metadata": {},
"source": [
"### Night Theme"
]
},
{
"cell_type": "code",
"execution_count": 9,
"id": "7014e86a",
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"\n",
"\n",
"\n",
" \n",
"\n",
""
],
"text/plain": [
""
]
},
"execution_count": 9,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"pitch = Pitch(\n",
" provider=\"statsbomb\",\n",
" orientation=\"horizontal\",\n",
" view=\"full\",\n",
" theme=\"night\",\n",
" show_axis=False,\n",
" show_legend=False,\n",
" width=400,\n",
" height=400\n",
")\n",
"\n",
"pitch.plot_scatter(shots, \"location.0\", \"location.1\")\n",
"\n",
"HTML(pio.to_html(pitch.fig, include_plotlyjs=\"cdn\"))"
]
},
{
"cell_type": "markdown",
"id": "ffd48bf3",
"metadata": {},
"source": [
"### Classic Theme"
]
},
{
"cell_type": "code",
"execution_count": 10,
"id": "346899ba",
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"\n",
"\n",
"\n",
" \n",
"\n",
""
],
"text/plain": [
""
]
},
"execution_count": 10,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"pitch = Pitch(\n",
" provider=\"statsbomb\",\n",
" orientation=\"horizontal\",\n",
" view=\"full\",\n",
" theme=\"classic\",\n",
" show_axis=False,\n",
" show_legend=False,\n",
" width=400,\n",
" height=400\n",
")\n",
"\n",
"pitch.plot_scatter(shots, \"location.0\", \"location.1\")\n",
"\n",
"HTML(pio.to_html(pitch.fig, include_plotlyjs=\"cdn\"))"
]
},
{
"cell_type": "markdown",
"id": "e3b51ece",
"metadata": {},
"source": [
"### Turf"
]
},
{
"cell_type": "code",
"execution_count": 11,
"id": "9f83f2ba",
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"\n",
"\n",
"\n",
" \n",
"\n",
""
],
"text/plain": [
""
]
},
"execution_count": 11,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"pitch = Pitch(\n",
" provider=\"statsbomb\",\n",
" orientation=\"horizontal\",\n",
" view=\"full\",\n",
" theme=\"turf\",\n",
" show_axis=False,\n",
" show_legend=False,\n",
" width=400,\n",
" height=400\n",
")\n",
"\n",
"pitch.plot_scatter(shots, \"location.0\", \"location.1\")\n",
"\n",
"HTML(pio.to_html(pitch.fig, include_plotlyjs=\"cdn\"))"
]
},
{
"cell_type": "markdown",
"id": "d1bf87a0",
"metadata": {},
"source": [
"### Retro"
]
},
{
"cell_type": "code",
"execution_count": 12,
"id": "55814074",
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"\n",
"\n",
"\n",
" \n",
"\n",
""
],
"text/plain": [
""
]
},
"execution_count": 12,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"pitch = Pitch(\n",
" provider=\"statsbomb\",\n",
" orientation=\"horizontal\",\n",
" view=\"full\",\n",
" theme=\"retro\",\n",
" show_axis=False,\n",
" show_legend=False,\n",
" width=400,\n",
" height=400\n",
")\n",
"\n",
"pitch.plot_scatter(shots, \"location.0\", \"location.1\")\n",
"\n",
"HTML(pio.to_html(pitch.fig, include_plotlyjs=\"cdn\"))"
]
},
{
"cell_type": "markdown",
"id": "907e9bf8",
"metadata": {},
"source": [
"### Custom Themes\n",
"\n",
"In addition to the built-in themes, you can create your own custom theme by passing a dictionary of style settings to the `Theme.from_dict()` method. Custom themes are built on top of a base theme (e.g., `\"minimal\"` or `\"classic\"`), so you only need to specify the styles you want to change. This makes it easy to tweak one or more aspects of the appearance without redefining everything. You can control background color, line color, marker size, font family, tooltip styling, and more. Custom themes are especially useful for aligning visuals with a specific color palette, branding guidelines, or publication style. Once created, your custom theme can be passed to the Pitch constructor just like a preset, making it easy to reuse across multiple visualizations."
]
},
{
"cell_type": "code",
"execution_count": 13,
"id": "6b9ba9e2",
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"\n",
"\n",
"\n",
" \n",
"\n",
""
],
"text/plain": [
""
]
},
"execution_count": 13,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"from penaltyblog.viz import Theme\n",
"\n",
"# Define your custom theme\n",
"my_theme = Theme.from_dict({\n",
" \"pitch_color\": \"#fdf6e3\", \n",
" \"line_color\": \"#657b83\", \n",
" \"marker_color\": \"#ff69b4\", \n",
" \"heatmap_colorscale\": \"YlOrRd\", \n",
" \"heatmap_opacity\": 0.7,\n",
" \"font_family\": \"Georgia, serif\",\n",
" \"line_width\": 1.2,\n",
" \"marker_size\": 10,\n",
" \"spot_size\": 6,\n",
" \"hover_bgcolor\": \"#eee8d5\",\n",
" \"hover_font_color\": \"#073642\",\n",
" \"hover_border_color\": \"#93a1a1\",\n",
" \"hover_font_size\": 14,\n",
" \"title_margin\": 40,\n",
" \"subtitle_margin\": 20,\n",
" \"subnote_margin\": 30,\n",
"}, base=\"minimal\")\n",
"\n",
"# Use the theme with a pitch\n",
"pitch = Pitch(\n",
" provider=\"statsbomb\",\n",
" orientation=\"horizontal\",\n",
" view=\"full\",\n",
" theme=my_theme,\n",
" show_axis=False,\n",
" show_legend=False,\n",
" width=400,\n",
" height=400\n",
")\n",
"\n",
"pitch.plot_scatter(shots, \"location.0\", \"location.1\")\n",
"\n",
"HTML(pio.to_html(pitch.fig, include_plotlyjs=\"cdn\"))"
]
},
{
"cell_type": "markdown",
"id": "6b6fc037",
"metadata": {},
"source": [
"## Hover Tooltips\n",
"\n",
"You can customize the hover tooltips shown on the pitch by specifying which data field should appear when users hover over a chart element. Most plotting methods (such as `plot_scatter`, `plot_comets`, and `plot_arrows`) accept a hover argument, which takes the name of a field from your data — e.g. `\"player\"`, `\"event_type\"`, or any nested path like `\"player.name\"`. \n",
"\n",
"This field will be shown as the tooltip when hovering over each point, line, or arrow. For more complex needs, you can preprocess your data to combine multiple fields into a single string before passing it in. Custom tooltips are a great way to provide context and interactivity without cluttering the visual layout."
]
},
{
"cell_type": "code",
"execution_count": 14,
"id": "6283f2e9",
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"\n",
"\n",
"\n",
" \n",
"\n",
""
],
"text/plain": [
""
]
},
"execution_count": 14,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"pitch = Pitch(\n",
" provider=\"statsbomb\",\n",
" orientation=\"horizontal\",\n",
" view=\"right\",\n",
" theme=\"night\",\n",
" show_axis=False,\n",
" show_legend=False,\n",
" width=400,\n",
" height=400\n",
")\n",
"\n",
"shots = (\n",
" flow\n",
" .filter(where_equals(\"type.name\", \"Shot\"))\n",
" .filter(where_equals(\"team.name\", \"Liverpool\"))\n",
" .assign(\n",
" hover_text=lambda x: get_field(x, \"player.name\") \\\n",
" + \": (\" \\\n",
" + str(get_field(x, \"location.0\")) \\\n",
" + \", \" \\\n",
" + str(get_field(x, \"location.1\"))\n",
" + \")\"\n",
" ) \n",
")\n",
"\n",
"pitch.plot_scatter(shots, \"location.0\", \"location.1\", hover=\"hover_text\")\n",
"\n",
"HTML(pio.to_html(pitch.fig, include_plotlyjs=\"cdn\"))"
]
},
{
"cell_type": "markdown",
"id": "ff8b4f85",
"metadata": {},
"source": [
"## Exporting\n",
"\n",
"The Pitch class supports exporting your visualizations to a variety of static formats, including `PNG`, `SVG`, `PDF`, and more. This is done using the `.save()` method, which saves the current figure to a file with your chosen filename and format. If no format is specified, it is inferred from the file extension. You can also adjust the resolution using the `scale`, `width`, and `height` parameters. This makes it easy to generate high-quality visuals for use in reports, presentations, or publications. Note that exporting requires the `kaleido` package, which you can install with `pip install kaleido`\n",
"\n",
"```python\n",
"pitch.save(\"pitch.png\")\n",
"pitch.save(\"pitch.svg\")\n",
"pitch.save(\"pitch.pdf\")\n",
"pitch.save(\"pitch.png\", scale=2)\n",
"pitch.save(\"pitch.png\", width=800, height=600)\n",
"pitch.save(\"pitch.png\", scale=2, width=800, height=600)\n",
"```"
]
},
{
"cell_type": "markdown",
"id": "9c87a1b6",
"metadata": {},
"source": [
"## View Modes and Zooming\n",
"\n",
"The `view` parameter lets you control how much of the pitch is visible, making it easy to zoom in on specific areas of the field. This is useful for highlighting activity in a particular zone, such as the final third, a penalty box, or a team's attacking half.\n",
"\n",
"You can set view in three different ways:\n",
"\n",
"### Named views (strings)\n",
"\n",
"```python\n",
"Pitch(view=\"left\") # Show left half\n",
"Pitch(view=\"right\") # Show right half\n",
"Pitch(view=\"top\") # Top half (horizontal orientation)\n",
"Pitch(view=\"bottom\") # Bottom half\n",
"Pitch(view=\"full\") # (default) Show the full pitch\n",
"```\n",
"\n",
"These work across all pitch providers and orientations.\n",
"\n",
"---\n",
"\n",
"### Horizontal slice `(x0, x1)`\n",
"\n",
"Zoom in on a portion of the pitch by specifying the horizontal range (in native units):\n",
"\n",
"```python\n",
"Pitch(view=(30, 90)) # Show only the middle third of the pitch\n",
"```\n",
"\n",
"---\n",
"\n",
"### Custom bounding box ((x0, x1, y0, y1))\n",
"\n",
"For full control, you can specify both X and Y bounds in the pitch’s native coordinate system:\n",
"\n",
"```python\n",
"Pitch(view=(100, 120, 18, 62)) # Zoom in on the right penalty area (StatsBomb units)\n",
"```\n",
"\n",
"This is especially useful for isolating set-piece areas, goalmouth activity, or tight pressing zones.\n",
"\n",
"---\n",
"\n",
"### Notes\n",
"\n",
"- The view works with any provider (`\"statsbomb\"`, `\"wyscout\"`, etc.) and is automatically scaled and oriented correctly.\n",
"- Margins are applied automatically to avoid clipping lines or markers.\n",
"- When using vertical orientation, the axes will flip appropriately behind the scenes."
]
},
{
"cell_type": "markdown",
"id": "0f78a9d1",
"metadata": {},
"source": [
"## Orientation Handling\n",
"\n",
"The `orientation` parameter controls whether the pitch is drawn horizontally or vertically. By default, `Pitch` uses a horizontal orientation (left to right), but you can switch to vertical to flip the field and better match certain tactical views.\n",
"\n",
"```python\n",
"Pitch(orientation=\"horizontal\") # Default\n",
"Pitch(orientation=\"vertical\") # Flips X and Y axes\n",
"```\n"
]
},
{
"cell_type": "code",
"execution_count": 15,
"id": "2943b510",
"metadata": {},
"outputs": [
{
"name": "stderr",
"output_type": "stream",
"text": [
"/Users/martin/repos/penaltyblog/venv/lib/python3.13/site-packages/statsbombpy/api_client.py:21: NoAuthWarning:\n",
"\n",
"credentials were not supplied. open data access only\n",
"\n"
]
},
{
"data": {
"text/html": [
"\n",
"\n",
"\n",
" \n",
"\n",
""
],
"text/plain": [
""
]
},
"execution_count": 15,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"pitch = Pitch(\n",
" provider=\"statsbomb\",\n",
" orientation=\"vertical\",\n",
" view=\"top\",\n",
" theme=\"minimal\",\n",
" show_axis=False,\n",
" show_legend=False,\n",
" width=400,\n",
" height=400\n",
")\n",
"\n",
"pitch.plot_scatter(shots, \"location.0\", \"location.1\")\n",
"\n",
"HTML(pio.to_html(pitch.fig, include_plotlyjs=\"cdn\"))"
]
},
{
"cell_type": "markdown",
"id": "8e663004",
"metadata": {},
"source": [
"## Layer management\n",
"\n",
"Every visual element you add with a plotting method is placed on a named layer, allowing you to treat groups of traces and annotations as a single unit. By default, `plot_scatter`, `plot_heatmap`, `plot_kde`, `plot_arrows`, and `plot_comets` drop their output on layers called `\"scatter\"`, `\"heatmap\"`, `\"kde\"`, `\"arrows\"`, and `\"comets\"` respectively, but you can override the name with the `layer=` argument. Once the figure is built you can:\n",
"\n",
"- Hide / show a layer at any time with `set_layer_visibility(\"heatmap\", visible=False)`.\n",
"- Remove it completely with `remove_layer(\"arrows\")`.\n",
"- Re-order layers so one set of traces sits above or below another using `set_layer_order([\"heatmap\", \"scatter\", \"arrows\"])`.\n",
"\n",
"This makes it easy to toggle tactical annotations, switch between different analytical overlays, or export multiple variants of the same figure without redrawing."
]
},
{
"cell_type": "markdown",
"id": "d419b04f",
"metadata": {},
"source": [
"## Titles, Subtitles and Subnotes\n",
"\n",
"You can easily add contextual information to your pitch visualizations by specifying a title, subtitle, and subnote when initializing the `Pitch` object. These elements are automatically positioned above and below the pitch and styled according to the selected theme. This makes it simple to provide clear, consistent annotations—such as competition names, data sources, or author credits—without needing to manually configure layout or annotations. All elements adapt intelligently to the pitch orientation and available space, ensuring your visuals remain clean and professional."
]
},
{
"cell_type": "code",
"execution_count": 16,
"id": "83e5b2b5",
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"\n",
"\n",
"\n",
" \n",
"\n",
""
],
"text/plain": [
""
]
},
"execution_count": 16,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"pitch = Pitch(\n",
" title=\"Shot Map\",\n",
" subtitle=\"Stockport County vs Liverpool\",\n",
" subnote=\"penaltyblog is awesome\",\n",
" orientation=\"horizontal\",\n",
" theme=\"minimal\",\n",
" width=400,\n",
" height=400\n",
")\n",
"\n",
"# Plot some example data (e.g., scatter of shot locations)\n",
"data = [{\"x\": 102, \"y\": 34}, {\"x\": 95, \"y\": 20}, {\"x\": 88, \"y\": 42}]\n",
"pitch.plot_scatter(data)\n",
"\n",
"HTML(pio.to_html(pitch.fig, include_plotlyjs=\"cdn\"))"
]
}
],
"metadata": {
"kernelspec": {
"display_name": "venv",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.13.5"
}
},
"nbformat": 4,
"nbformat_minor": 5
}