d3-soccer

A D3 plugin for visualizing event stream soccer data.

Installing

If you use NPM, npm install d3-soccer. Otherwise, download the latest release. AMD, CommonJS, and vanilla environments are supported. In vanilla, a d3 global is exported:

``html




`

Examples

An introduction to the features and basic usage of d3-soccer can found in this notebook. For additional examples, see the examples folder in this repo or this collection of notebooks.

API Reference

# d3.pitch()

Creates a new pitch generator with the default configuration values. The pitch contains two layers (#below and #above) which can be used to plot additional markers respectively below and above the pitch markers. The origin is located in the top-left corner of the pitch and the default dimensions are (105, 68).

# pitch(context)

Render the pitch to the given context, which may be either a selection of containers (either HTML, SVG or G elements) or a corresponding transition.

# pitch.height([height])

If a _height_ is specified, it sets the height of the corresponding SVG element and computes the adequate width. If _height_ is not specified, returns the current height, which defaults to 300 px.

# pitch.width()

Returns the current width of the SVG element.

# pitch.rotate([bool])

If _bool_ is specified and set to true, rotate the plot by 90 degrees. If _bool_ is not specified, returns the current setting, which defaults to false.

# pitch.showDirOfPlay([bool])

If _bool_ is specified and set to true, shows an arrow on the plot from left to right to indicate the direction of play. If _bool_ is not specified, returns the current setting, which defaults to false.

# pitch.shadeMiddleThird([bool])

If _bool_ is specified and set to true, the middle third of the pitch is shaded. If _bool_ is not specified, returns the current setting, which defaults to false.

# pitch.goals([goals])

The standard goal markings can be customized by supplying a function to the _goals_ argument. Additionally, the _goals_ argument supports the strings "line" and "box", which correspond to line-style and box-style goal markings.
If _goals_ is not specified, returns the current setting, which defaults to line-style markings.

# pitch.clip([clip])

If _clip_ is specified, sets the clipping rectangle and computes the adequate _width_. _clip_ is specified as a pair of 2D coordinates \[x, y\]. If _clip_ is not specified, returns the current clipping rectangle, which defaults to: [[0, 0], [105, 68]]

# pitch.pitchStrokeWidth([width])

If _width_ is specified, it sets the stroke width of the pitch markers. If _width_ is not specified, returns the current stroke width, which defaults to 0.5 px.

# d3.heatmap(pitch)

Creates a new heatmap generator with the default configuration values and the specified pitch configuration.

# heatmap(context)

Render the heatmap to the given context, which may be either a selection of containers (either HTML, SVG or G elements) or a corresponding transition. Reads the data for the heatmap from the datum property on the container. This data should be in the following format:

`
[
{
height: 0.99, // height of the cell
width: 0.99, // width of the cell
x: 4.95, // x-position of the cell
y: 54.20, // y-position of the cell
i: 5, // x-index of the cell
j: 55, // y-index of the cell
value: 0 // value of the cell
},
...
]
`

D3 soccer provides two layouts to convert data to this format: d3.grid() and d3.rectbin() .

# heatmap.colorScale([scale])

If _scale_ is specified, sets the color scale, which should be an instance of d3-scale. If _scale_ is not specified, returns the current color scale, which defaults to d3.scaleSequential(d3.interpolateGreens).

# heatmap.enableInteraction([enable])

If _enable_ is set to true, a border will be drawn around a cell of the heatmap when hovered. Additional actions can be assigned trough onSelect and onDeselect. If not set, returns the current configuration. Interaction is disabled by default.

# heatmap.interpolate([interpolate])

If _interpolate_ is set to true, the heatmap will be interpolated using bicubic interpolation. If not set, returns the current configuration, which defaults to false.

# heatmap.selected([cell])

If _cell_ is specified, sets the selected cell. _cell_ should be specified as 2D coordinates \[x, y\], where (0,0) corresponds to the top left corner cell. If _cell_ is not specified, returns the current selection. Returns [undefined, undefined] if no cell is selected, which is the default.

# heatmap.onSelect([f])

If _f_ is specified, hovering over a cell will trigger execution of _f(x, y, v)_, where _x_ and _y_ are the coordinates of the selected cell and _v_ the cell value.

# heatmap.onDeselect([f])

If _f_ is specified, stopping hovering over a cell will trigger execution of _f()_.


# heatmap.showValues([show])

If _show_ is set to true, the value of each cell will we displayed. If not set, returns the default configuration, which defaults to false.

# heatmap.heatmap_valueFormatter([f])

If _f_ is specified, the cell values will be formatted as a string using _f(v)_, where _v_ is the cell value.

# heatmap.heatmap_valueFontSize([f])

If _f_ is specified, the font size of a cell value will be set using _f(h, w, v)_, where _h_ and _w_ are the height and width of the cell and _v_ the cell value. Defaults to 20% of the cell height.


# d3.actions(pitch)

Creates a new generator for plotting soccer actions in the SPADL format with the default configuration values and the specified pitch configuration.


# actions(context)

Render the actions to the given context, which may be either a selection of containers (either HTML, SVG or G elements) or a corresponding transition. Reads the data for the actions from the datum property on the container.

# actions.showTooltip([show])

If _show_ is set to an instance of actionTooltip, will show a tooltip upon hovering an action. If not specified, will return a reference to the current tooltip or false if no tooltip is attached. Defaults to false.

# actions.scale([scale])

If _scale_ is specified, will set the scale of the action markers. If not specified, will return the current scale, which defaults to 4.

# actions.teamColors([colors])

If _colors_ is specified, will set the colors used for the markers of both teams. Excepts a mapping between team ID and a color hex code, for example {782:"#EF3340", 781:"#FDB913"}. If _colors_ is not specified, returns the current mapping between teams and colors, which defaults to {0: "#FDB913", 1: "#87CEEB"}.

# actions.draggable([draggable])

If _draggable_ is set to true, will enable dragging the action markers around and trigger onUpdate. If not specified, returns the current setting which defaults to false.

# actions.onUpdate([f])

If _f_ is specified, dragging an action's marker will trigger execution of _f(data)_, where _data_ are the updated actions.

# d3.actionsTable()

# actionsTable(context)

# actionsTable.tableColumns([columns])

# actionsTable.scale([scale])

# actionsTable.teamColors([colors])

# d3.actionTooltip()


# actionTooltip(context)

# actionTooltip.show([data])

# actionTooltip.hide()


# d3.scoreline()


# scoreline(context)

# scoreline.height([height])

# scoreline.teams([teams])

# scoreline.score([score])

# scoreline.clock([clock])

# d3.grid()

Constructs a new default grid layout, which can be used to generate data for the heatmap.

# grid(values)

Evaluates the grid layout on the specified 2d array of values, returning a 1d array corresponding to the data format required by the heatmap.

# d3.rectbin()

Constructs a new default rectbin layout, which can be used to generate data for the heatmap.

# rectbin(points)

Evaluates the rectbin layout on the specified array of points, returning an array of rectangular bins. Each bin is an array containing the bin’s points, as well as some additional properties which are required by the heatmap.

Bins that are empty are not omitted. The origin bin at ⟨0,0⟩ is in the top-left.

# rectbin.x([accessor])

If accessor is specified, sets the x-accessor function and returns the rectbin layout; if accessor is not specified, returns the current x-accessor function, which defaults to function(d) { return d[0]; }.

# rectbin.y([accessor])

If accessor is specified, sets the y-accessor function and returns the rectbin layout; if accessor is not specified, returns the current y-accessor function, which defaults to function(d) { return d[1]; }`.

# rectbin.dx([dx])

If dx is specified, sets the horizontal bin size to the specified value. If dx is not specified, returns the current value, which defaults to 0.1.

# rectbin.dy([dy])

If dy is specified, sets the vertical bin size to the specified value. If dy is not specified, returns the current value, which defaults to 0.1.