<!-- markdownlint-disable MD033 -->
# soccerbars <img width="90em" height="24em" src="https://raw.githubusercontent.com/meakbiyik/soccerbars/master/resources/example.png">
<!-- badges: start -->
[](https://github.com/meakbiyik/soccerbars/actions)
[](https://github.com/meakbiyik/soccerbars/actions)
<!-- To include when the repo becomes public.
[](https://codecov.io/gh/meakbiyik/soccerbars?branch=master)
-->
<!-- badges: end -->
Word-sized tallies of association football results using multivariate sparklines based on Gestalt theory (gestaltlines).
This repository contains a Python package, an R package, and a command line tool based on Python.
Soccerbars is created by Prof. Dr. Ulrik Brandes of ETH Zürich and this repository is a port of his [LaTeX package](https://github.com/ubrandes-ethz/soccerbars). An introduction to the theory behind this work can be found [here](https://sn.ethz.ch/research/soccerbars.html).
## Usage
The signature of the main function `soccerbar` is identical in both Python and R implementations. The input (`scores` argument) can be either a list of matches in the form ```(home_team_score: integer, away_team_score: integer, away_game: boolean)```, a list of three same-length score lists with the same types as the previous scheme, or common data frame objects of each language (`pandas.DataFrame` in Python and `data.frame` in R). A list of these entities can also be given as input if multiple leagues/tournaments are wanted to be plotted.
Both languages preserve the flags and the `color` arguments from the LaTeX package, and also expose a series of common parameters as keyword arguments. `output_path` and `show` arguments can be used to determine whether the call is to save the resulting image to the given path(s), or just to show it via the available graphical interface (not possible in Python if the function is called from the command line). In both cases, the functions return the plotted objects (`matplotlib.Axes` object(s) in Python and `ggplot` object(s) in R).
For `color` and `output_path` arguments, the function expects the structure of these to be consistent with the `scores` argument: if multiple lists of match lists are given, then for each such list an output path and a list of colors must be specified, therefore the lengths must be equal in all levels. These arguments are optional, when not provided the configuration will use the LaTeX defaults. Also, the `color` argument should not be necessary in most cases, as the color-related keyword arguments provide sufficient flexibility with much easier usage in both languages (see [Parameters](#parameters) below for more details).
### in Python
Give the matches to the ```soccerbar``` function as an iterable of matches in row-wise, column-wise or DataFrame format. A list of values following these formats (e.g. in the context of multiple leagues) are also accepted without mixing.
```python
from soccerbars import soccerbar
# Row-wise format
soccerbar([
(1, 2, True), (3, 4, False), (5, 6, True), (7, 8, False)
])
# Column-wise format
soccerbar([
(1, 3, 5, 7),
(2, 4, 6, 8),
(True, False, True, False)
], outlined=True, output_path="matches.png")
# List of row-wise inputs: observe that both color and output_path
# parameters match with the scores
soccerbar([
[(1, 2, True), (3, 4, False)],
[(5, 6, True), (7, 8, False)]
],
color=[("r", "b"), ("g", "y")],
output_path=["league1.png", "league2.png"]
)
# Input as pandas DataFrame
import pandas as pd
soccerbar(pd.DataFrame([
(1, 2, True), (3, 4, False), (5, 6, True), (7, 8, False)
]), home_color="red")
```
### in R
Similarly with its Python counterpart, ```soccerbar``` admits both list of match score lists, and a list of three vectors, along with `data.frame` objects. A list of these (e.g. in the context of multiple leagues) are also allowed.
```R
library(soccerbars)
# Row-wise format
soccerbar(list(
list(1, 2, TRUE), list(3, 4, FALSE), list(5, 6, TRUE), list(7, 8, FALSE)
))
# Column-wise (vector) format
soccerbar(list(
c(1, 3, 5, 7),
c(2, 4, 6, 8),
c(TRUE, FALSE, TRUE, FALSE)
), outlined = TRUE, output_path = "matches.png")
# List of column-wise inputs: observe that both color and output_path
# parameters match with the scores
soccerbar(list(
list(c(1, 3), c(2, 4), c(TRUE, FALSE)),
list(c(5, 7), c(6, 8), c(TRUE, FALSE))
),
color = list(c("red", "blue"), c("green", "yellow")),
output_path = c("league1.png", "league2.png")
)
# Input as data.frame object
soccerbar(data.frame(
c(1, 3, 5, 7),
c(2, 4, 6, 8),
c(TRUE, FALSE, TRUE, FALSE)
), home_color = "red")
```
### via CLI
After installing the package (see the instructions [below](#as-a-command-line-tool)), navigate into the folder and run
```bash
poetry run soccerbars --help
```
to see the available options. The CLI is a thin wrapper around the Python API, and writes the output image to the specified location with the `--output-path` argument. Input syntax is identical with the LaTeX package. In addition to the capabilities of the Python core, CLI can also admit a glob pattern to match with `.csv` files.
```bash
# Vanilla usage
poetry run soccerbars "(1-2) (3-1)* (2-2)"
# Specifying the output path (default is "output.png")
poetry run soccerbars -o out.tiff "(1-2) (3-1)* (2-2)"
# Reading from a .csv file and specifying an output file
poetry run soccerbars matches.csv -o matches.pdf
# Reading from a glob of csv files and saving the output images to a directory
poetry run soccerbars *.csv -o ".\output-dir"
# `-t`, `-z`, `-ol` flags stand for twogoalline, zerodots and outlined options
# `-p` option can be used to specify additional parameters with syntax key:value
poetry run soccerbars -z -ol -p fill_color:"(1,1,1,1)" -p home_color:red *.csv
```
### Parameters
These parameters can be used to customize the output images in all components.
| Parameter | Description | Default |
|-|-|-|
| dpi | Dots per inch resolution | 300 |
| thickness | Line thickness in cartesian coordinates | 0.36 |
| edge_thickness | Edge thickness for outlined patches (when outlined=True) as the ratio to the line thickness | 0.35 |
| goalless_edge_thickness | Edge thickness for outlined no-goal patches (when outlined=True) as the ratio to the line thickness | 0.5 |
| zerodot | Zero-dot diameter ratio to thickness (when zerodots=True) | 0.6 |
| slant | Slope for unbalanced scores in degrees | 14 |
| spacing | Spacing between matches in cartesian coordinates | 0.9 |
| padding | Padding before and after the matches in cartesian coordinates | 0.2 |
| baseline_factor | Thickness of baseline with respect to line thickness | 0.2 |
| away_brighter | Set away game colors 33% brighter (when outlined=False) | True |
| away_darker | Set away game colors 33% darker (when outlined=False, setting this flag will turn "away_brighter" off) | False |
| transparent_background | Set the background transparent instead of white | False |
| home_color | Color of home match lines (in Python: matplotlib-acceptable formats, in R: any of the three kinds of R color specifications; either a color name as listed by colors(), a hexadecimal string of the form "#rrggbb" or "#rrggbbaa", or a positive integer i meaning `palette()[i]`) | #000000FF |
| away_color | Color of away match lines | #000000FF |
| baseline_color | Color of baselines | #000000FF |
| fill_color | Fill color for the outlined sparklines | #00000000 |
| clip_slanted_lines | Clip the ends of the slanted lines | True |
## Installation
### As a Python package
```bash
pip install soccerbars
```
For command line usage, you need to install the package with the `cli` extra.
```bash
pip install soccerbars[cli]
```
### As an R package
This package is not published in CRAN yet, so you need to use the Github installation functionality of `devtools`.
```R
devtools::install_github("meakbiyik/soccerbars")
```
### As a command line tool
Although it is possible to use the command line interface after installing the Python package into the current environment and running `python -m soccerbars`, installation as an isolated tool might be preferrable to keep the environment clean. Following steps will create a new environment and install `soccerbars` for this purpose.
1. Install Python from [here](https://www.python.org/downloads/)
2. Install [Poetry](https://python-poetry.org/), a dependency management tool for Python, via the following command
```bash
curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python
```
3. Clone this repository to your local, navigate into the folder and run
```bash
poetry install --no-dev --extras cli
```
Raw data
{
"_id": null,
"home_page": "https://github.com/meakbiyik/soccerbars",
"name": "soccerbars",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "soccer,sparklines,football,association-football",
"author": "M. Eren Akbiyik",
"author_email": "erenakbiyik@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/d5/91/ccfb72a2e8e6cd589ce987a79e86f87164af15e3c4c215d965d9e80ba95f/soccerbars-0.2.1.tar.gz",
"platform": null,
"description": "\n<!-- markdownlint-disable MD033 -->\n# soccerbars <img width=\"90em\" height=\"24em\" src=\"https://raw.githubusercontent.com/meakbiyik/soccerbars/master/resources/example.png\">\n\n<!-- badges: start -->\n[](https://github.com/meakbiyik/soccerbars/actions)\n[](https://github.com/meakbiyik/soccerbars/actions)\n<!-- To include when the repo becomes public.\n[](https://codecov.io/gh/meakbiyik/soccerbars?branch=master)\n-->\n<!-- badges: end -->\n\nWord-sized tallies of association football results using multivariate sparklines based on Gestalt theory (gestaltlines).\n\nThis repository contains a Python package, an R package, and a command line tool based on Python.\n\nSoccerbars is created by Prof. Dr. Ulrik Brandes of ETH Z\u00fcrich and this repository is a port of his [LaTeX package](https://github.com/ubrandes-ethz/soccerbars). An introduction to the theory behind this work can be found [here](https://sn.ethz.ch/research/soccerbars.html).\n\n## Usage\n\nThe signature of the main function `soccerbar` is identical in both Python and R implementations. The input (`scores` argument) can be either a list of matches in the form ```(home_team_score: integer, away_team_score: integer, away_game: boolean)```, a list of three same-length score lists with the same types as the previous scheme, or common data frame objects of each language (`pandas.DataFrame` in Python and `data.frame` in R). A list of these entities can also be given as input if multiple leagues/tournaments are wanted to be plotted.\n\nBoth languages preserve the flags and the `color` arguments from the LaTeX package, and also expose a series of common parameters as keyword arguments. `output_path` and `show` arguments can be used to determine whether the call is to save the resulting image to the given path(s), or just to show it via the available graphical interface (not possible in Python if the function is called from the command line). In both cases, the functions return the plotted objects (`matplotlib.Axes` object(s) in Python and `ggplot` object(s) in R).\n\nFor `color` and `output_path` arguments, the function expects the structure of these to be consistent with the `scores` argument: if multiple lists of match lists are given, then for each such list an output path and a list of colors must be specified, therefore the lengths must be equal in all levels. These arguments are optional, when not provided the configuration will use the LaTeX defaults. Also, the `color` argument should not be necessary in most cases, as the color-related keyword arguments provide sufficient flexibility with much easier usage in both languages (see [Parameters](#parameters) below for more details).\n\n### in Python\n\nGive the matches to the ```soccerbar``` function as an iterable of matches in row-wise, column-wise or DataFrame format. A list of values following these formats (e.g. in the context of multiple leagues) are also accepted without mixing.\n\n```python\nfrom soccerbars import soccerbar\n\n# Row-wise format\nsoccerbar([\n (1, 2, True), (3, 4, False), (5, 6, True), (7, 8, False)\n])\n# Column-wise format\nsoccerbar([\n (1, 3, 5, 7), \n (2, 4, 6, 8), \n (True, False, True, False)\n], outlined=True, output_path=\"matches.png\")\n# List of row-wise inputs: observe that both color and output_path\n# parameters match with the scores\nsoccerbar([\n [(1, 2, True), (3, 4, False)], \n [(5, 6, True), (7, 8, False)]\n ],\n color=[(\"r\", \"b\"), (\"g\", \"y\")],\n output_path=[\"league1.png\", \"league2.png\"]\n)\n# Input as pandas DataFrame\nimport pandas as pd\n\nsoccerbar(pd.DataFrame([\n (1, 2, True), (3, 4, False), (5, 6, True), (7, 8, False)\n]), home_color=\"red\")\n```\n\n### in R\n\nSimilarly with its Python counterpart, ```soccerbar``` admits both list of match score lists, and a list of three vectors, along with `data.frame` objects. A list of these (e.g. in the context of multiple leagues) are also allowed.\n\n```R\nlibrary(soccerbars)\n\n# Row-wise format\nsoccerbar(list(\n list(1, 2, TRUE), list(3, 4, FALSE), list(5, 6, TRUE), list(7, 8, FALSE)\n))\n# Column-wise (vector) format\nsoccerbar(list(\n c(1, 3, 5, 7),\n c(2, 4, 6, 8),\n c(TRUE, FALSE, TRUE, FALSE)\n), outlined = TRUE, output_path = \"matches.png\")\n# List of column-wise inputs: observe that both color and output_path\n# parameters match with the scores\nsoccerbar(list(\n list(c(1, 3), c(2, 4), c(TRUE, FALSE)), \n list(c(5, 7), c(6, 8), c(TRUE, FALSE))\n ),\n color = list(c(\"red\", \"blue\"), c(\"green\", \"yellow\")),\n output_path = c(\"league1.png\", \"league2.png\")\n)\n# Input as data.frame object\nsoccerbar(data.frame(\n c(1, 3, 5, 7),\n c(2, 4, 6, 8),\n c(TRUE, FALSE, TRUE, FALSE)\n), home_color = \"red\")\n```\n\n### via CLI\n\nAfter installing the package (see the instructions [below](#as-a-command-line-tool)), navigate into the folder and run\n\n```bash\npoetry run soccerbars --help\n```\n\nto see the available options. The CLI is a thin wrapper around the Python API, and writes the output image to the specified location with the `--output-path` argument. Input syntax is identical with the LaTeX package. In addition to the capabilities of the Python core, CLI can also admit a glob pattern to match with `.csv` files.\n\n```bash\n# Vanilla usage\npoetry run soccerbars \"(1-2) (3-1)* (2-2)\"\n# Specifying the output path (default is \"output.png\")\npoetry run soccerbars -o out.tiff \"(1-2) (3-1)* (2-2)\"\n# Reading from a .csv file and specifying an output file\npoetry run soccerbars matches.csv -o matches.pdf\n# Reading from a glob of csv files and saving the output images to a directory\npoetry run soccerbars *.csv -o \".\\output-dir\"\n# `-t`, `-z`, `-ol` flags stand for twogoalline, zerodots and outlined options\n# `-p` option can be used to specify additional parameters with syntax key:value\npoetry run soccerbars -z -ol -p fill_color:\"(1,1,1,1)\" -p home_color:red *.csv\n```\n\n### Parameters\n\nThese parameters can be used to customize the output images in all components.\n\n| Parameter | Description | Default |\n|-|-|-|\n| dpi | Dots per inch resolution | 300 |\n| thickness | Line thickness in cartesian coordinates | 0.36 |\n| edge_thickness | Edge thickness for outlined patches (when outlined=True) as the ratio to the line thickness | 0.35 |\n| goalless_edge_thickness | Edge thickness for outlined no-goal patches (when outlined=True) as the ratio to the line thickness | 0.5 |\n| zerodot | Zero-dot diameter ratio to thickness (when zerodots=True) | 0.6 |\n| slant | Slope for unbalanced scores in degrees | 14 |\n| spacing | Spacing between matches in cartesian coordinates | 0.9 |\n| padding | Padding before and after the matches in cartesian coordinates | 0.2 |\n| baseline_factor | Thickness of baseline with respect to line thickness | 0.2 |\n| away_brighter | Set away game colors 33% brighter (when outlined=False) | True |\n| away_darker | Set away game colors 33% darker (when outlined=False, setting this flag will turn \"away_brighter\" off) | False |\n| transparent_background | Set the background transparent instead of white | False |\n| home_color | Color of home match lines (in Python: matplotlib-acceptable formats, in R: any of the three kinds of R color specifications; either a color name as listed by colors(), a hexadecimal string of the form \"#rrggbb\" or \"#rrggbbaa\", or a positive integer i meaning `palette()[i]`) | #000000FF |\n| away_color | Color of away match lines | #000000FF |\n| baseline_color | Color of baselines | #000000FF |\n| fill_color | Fill color for the outlined sparklines | #00000000 |\n| clip_slanted_lines | Clip the ends of the slanted lines | True |\n\n## Installation\n\n### As a Python package\n\n```bash\npip install soccerbars\n```\n\nFor command line usage, you need to install the package with the `cli` extra.\n\n```bash\npip install soccerbars[cli]\n```\n\n### As an R package\n\nThis package is not published in CRAN yet, so you need to use the Github installation functionality of `devtools`.\n\n```R\ndevtools::install_github(\"meakbiyik/soccerbars\")\n```\n\n### As a command line tool\n\nAlthough it is possible to use the command line interface after installing the Python package into the current environment and running `python -m soccerbars`, installation as an isolated tool might be preferrable to keep the environment clean. Following steps will create a new environment and install `soccerbars` for this purpose.\n\n1. Install Python from [here](https://www.python.org/downloads/)\n2. Install [Poetry](https://python-poetry.org/), a dependency management tool for Python, via the following command\n\n ```bash\n curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python\n ```\n\n3. Clone this repository to your local, navigate into the folder and run\n\n ```bash\n poetry install --no-dev --extras cli\n ```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Word-sized tallies of association football results using multivariate sparklines based on Gestalt theory (gestaltlines).",
"version": "0.2.1",
"project_urls": {
"Homepage": "https://github.com/meakbiyik/soccerbars",
"Repository": "https://github.com/meakbiyik/soccerbars"
},
"split_keywords": [
"soccer",
"sparklines",
"football",
"association-football"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9979862a3e27bbf91fde60d84ea8acfde06acbeffa8c8b0757d005fad3c8e197",
"md5": "7467b6893ae8ba015688185051612270",
"sha256": "bdb2e5e4836fbf2da955fcd07af663b1b0165a3c62962e71b2d73e5dc000aa54"
},
"downloads": -1,
"filename": "soccerbars-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7467b6893ae8ba015688185051612270",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 14492,
"upload_time": "2023-07-02T12:04:51",
"upload_time_iso_8601": "2023-07-02T12:04:51.735593Z",
"url": "https://files.pythonhosted.org/packages/99/79/862a3e27bbf91fde60d84ea8acfde06acbeffa8c8b0757d005fad3c8e197/soccerbars-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d591ccfb72a2e8e6cd589ce987a79e86f87164af15e3c4c215d965d9e80ba95f",
"md5": "dbfd4403b681cd6de21a3f0f3f3c9783",
"sha256": "edf3ab0c7e2976cf139dc7a11f9c23ff6d371b0cb7fc99cec6fe4d2dfb878ecd"
},
"downloads": -1,
"filename": "soccerbars-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "dbfd4403b681cd6de21a3f0f3f3c9783",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 15712,
"upload_time": "2023-07-02T12:04:53",
"upload_time_iso_8601": "2023-07-02T12:04:53.125574Z",
"url": "https://files.pythonhosted.org/packages/d5/91/ccfb72a2e8e6cd589ce987a79e86f87164af15e3c4c215d965d9e80ba95f/soccerbars-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-02 12:04:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "meakbiyik",
"github_project": "soccerbars",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "soccerbars"
}
JSON
