A small update to Understat

What is Understat?

It's a Python wrapper for the website Understat, which provides revolutionary football metrics multiple leagues. An example of this is expected goals (xG), which is the main new revolutionary football metric, and allows you to evaluate team and player performance. In a low-scoring game such as football, the final score does not really provide a clear picture of the teams' performances, and this is why more and more sports analytics turn to the advanced models like xG, which is a statistical measure of the quality of chances created and conceded. Understat's goal was to create the most precise method for shot quality evaluation. They did this by training neural network prediction algorithms with a large dataset (>100,000 shots, over 10 parameters for each), and have now made this data available for the public!

In the last update I added quite a lot of functions. Today I was writing the documentation for it, and realised I had missed some data, and so in this update I've added these as well. The update is a bit smaller than last time, but I wanted to make sure everything that is available on https://understat.com/ is also available in the package, so I still felt it was pretty important to add these.

https://github.com/amosbastian/understat/pull/2

The pull request also includes all the documentation stuff, so I'm sorry for that. You can find the changes relevant to this update in the .py files (apart from conf.py). Here's what changed:

Add new functions and tests:

* `get_team_stats()`
* `get_team_results()`
* `get_team_fixtures()`
* `get_team_players()`

Rename:

* `get_players()` -> `get_league_players()`
* `get_results()` -> `get_league_results()`
* `get_fixtures()` -> `get_league_fixtures()`

Team stats

Before this update to get a specific team's stats you would need to get the stats of the league the team plays in, and then filter the result by team name. Obviously this is pretty tedious, and so with this function you can get a team's stats directly. Basically, it returns all the information you can find in the screenshot below

and an example showing how to use can be found below

Team results & fixtures

Getting the results and fixtures of a team was very similar to getting the stats of a team. You'd have to get a specific league's fixtures, and then filter by team. This was even more annoying in this case, because instead of passing something like team_name="Manchester United" and side="h" as a keyword arguments, you'd have to pass a dictionary like this for example:

{
    "h": {
        "id": "89",
        "title": "Manchester United",
        "short_title": "MUN"
    }
}

which is obviously very difficult to remember. With this new function you can simply do the following

This is equivalent to the fixtures you can find on a team's page, as seen in the screenshot below

Team players

Same thing as the stats really, except with players. It's much easier to use this function to get a team's players, because, for one, you don't need to remember the league anymore, and secondly, you don't need to remember which key value pair to filter by.

An example showing how to get all Manchester United players who have played in the forward position in this season is shown below:

Roadmap

I've also completed the documentation for Understat, which I will be posting about tomorrow. Because of this I will also post about the package as a whole on Reddit, and hopefully get some more people interested in it, who will also hopefully come up with some suggestions, and maybe even help!

Usage & installation

The recommended way to install understat is via pip.

pip install understat

To install it directly from GitHub you can do the following:

git clone git://github.com/amosbastian/understat.git

You can also install a .tar file
or .zip file

$ curl -OL https://github.com/amosbastian/understat/tarball/master
$ curl -OL https://github.com/amosbastian/understat/zipball/master # Windows

Once it has been downloaded you can easily install it using pip::

$ cd understat
$ pip install .

Import Understat and call its functions like so:

import asyncio
import json

import aiohttp

from understat import Understat


async def main():
    async with aiohttp.ClientSession() as session:
        understat = Understat(session)
        data = await understat.get_league_players("epl", 2018, {"team_title": "Manchester United"})
        print(json.dumps(data))


if __name__ == "__main__":
    loop = asyncio.get_event_loop()
    loop.run_until_complete(main())

Contributing

1. Fork the repository on GitHub.
2. Run the tests with pytest tests/ to confirm they all pass on your system.
   If the tests fail, then try and find out why this is happening. If you aren't
   able to do this yourself, then don't hesitate to either create an issue on
   GitHub, or send an email to amosbastian@gmail.com.
3. Either create your feature and then write tests for it, or do this the other
   way around.
4. Run all tests again with with pytest tests/ to confirm that everything
   still passes, including your newly added test(s).
5. Create a pull request for the main repository's master branch.

Documentation

Documentation and examples for understat can be found at http://understat.readthedocs.io/en/latest/.