Tools for displaying roller derby game data from the CRG scoreboard (versions 4.x and later).
You can build jamstats plots from game JSON files online! No need to install anything. Check out jamstats.net.
So, why download Jamstats and run it on your laptop? To connect to a live game on a running scoreboard!
Jamstats is great for announcers! See who's on the track (including positions and penalties), vital game stats and rosters for both teams and officials. You can even connect to a live scoreboard from anywhere on the Internet using wsproxy!
- Get up-to-date game data from a live scoreboard
- Visualize points per jam, lead, mean net points, calloffs, time to initial pass, penalties and much more
- Read in JSON files from completed games
- Save plots as PDF files, or start a webserver that anyone on your network can browse to
Do you already love Jamstats? Tell us about it!
Jamstats was developed by TheDM, with Seattle Derby Brats. Like Jamstats? Consider a donation to SDB, a 501(c)(3) organization!
Quickstart: download the latest release and run it.
In more detail:
What penalties got you down the most?
Use the colors defined for each team in the scoreboard file, or provide your own on the command line.
Want to do your own analytics? Save down a spreadsheet and do your own thing with it!
- Windows: go to the latest release and download
jamstats-<version>.exe - Mac: go to the latest release and download
jamstats-mac-<version>.zip, then unzip that file into your Applications directory (or wherever you want to run Jamstats from)- Note that the Mac app is particularly slow to start up
- Linux (also an alternative for Windows or Mac): install Python 3.9 or higher, then run
pip install jamstats. That will putjamstatson your path so you can run it from the command line.- Depending on distribution, the
pipinstallation may end up being more compicated than that. Detailed Python installation instructions below
- Depending on distribution, the
Full user manual (PDF), including how to start Jamstats up and how to interpret all the plots.
On Windows or Mac, to generate a plots PDF, you can simply drag and drop your game JSON file onto the jamstats.exe file or Jamstats app. That will generate a .pdf file in the same directory as your .json file, with the same name but with the .json extension replaced with .pdf.
Double-click on the jamstats executable to open a graphical window to specify your parameters.
To connect to a scoreboard, all you need to specify is scoreboardserver -- give that the combined IP address and port number of your scoreboard server (e.g., 172.21.12.7:8000), as reported in the scoreboard GUI.
With that usage, Jamstats will start its own server on your laptop, and the output in the GUI window will tell you where to point your browser. By default, that's http://localhost:8080, which will make Jamstats available only on your own machine. If you want to make Jamstats available to other browsers on your network, set jamstatsip to your computer's IP address.
You can also use the GUI to specify all other arguments you could specify from the commandline.
It's possible to use Jamstats from anywhere in the world to connect to a running scoreboard! This lets remote announcers use Jamstats to help with calling games. Here's how:
- Download wsproxy and follow its instructions to set up a proxy. This will feed your scoreboard data, read-only, to the Internet
- If you're using the default scoreboard settings, the default wsproxy settings will work fine.
- If not, pay attention to the port you're running your scoreboard on, and change from 8000 to that same port in wsproxy's config.ini file
- Your proxy can send your scoreboard data wherever you tell it to. On the other end, there needs to be another copy of wsproxy running.
- With the default configuration, your proxy data will be sent to a new subdomain of
derbystats.eu- e.g.,
https://jammer-lane.derbystats.eu/, but it will not be that, it will be something else unique to your scoreboard
- e.g.,
- When you start wsproxy, it will tell you where the data is going.
- For example,
Display URL: https://jammer-lane.derbystats.eu - Give this to the person who'll be running Jamstats remotely.
- For example,
- With the default configuration, your proxy data will be sent to a new subdomain of
- Get the "Display URL" from the person who set up wsproxy
- For example,
https://jammer-lane.derbystats.eu
- For example,
- Start up Jamstats and give it two arguments (either through the GUI or on the command line):
scoreboardserver: make this the full subdomain of the "Display URL", without thehttps://part, with:443added to the end- For example:
jammer-lane.derbystats.eu:443
- For example:
ssl: set this totrue(default isfalse)
Example of how this looks on the commandline:
python bin/jamstats --scoreboardserver=jammer-lane.derbystats.eu:443 --ssl
Example of how this looks in the GUI:
That's it! If that setup all worked correctly, Jamstats should now behave exactly as though you were right there at the track.
The command you'll use is the same as the name of the file you downloaded (e.g., jamstats-v0.3.4-alpha.exe on Windows, or jamstats-mac-v0.3.4-alpha on Mac).
In the usage below, I'm replacing that with simply jamstats. If you want the command to be jamstats, rename your file to jamstats.
Get full commandline help running the command with the --help argument.
jamstats --jsonfile <JSON file> [optional arguments]
where:
<JSON file>is the path to a scoreboard JSON file[optional arguments]: by default, Jamstats will write the output to the same path as the input file, but with ".json" replaced with ".pdf". You can adjust that behavior by specifying an output--outfilefile or using the--mode=webargument to start a webserver (see below), instead.- there are also several options, explained in the help message, that affect the charts that are built.
jamstats --scoreboardserver <server:port> [optional arguments]
where:
<server:port>is the server and port number (e.g.,127.0.0.1:8000) of a running scoreboard. jamstats will connect to the scoreboard and download the current game state.<some arguments to define the output>: same as above. You can route the output to a PDF file by specifying--mode=pdf.
* I am not a web security expert, and I make no guarantees whatsoever about webserver security. If you're concerned and want to help make it more secure, please open an issue!
If pip install jamstats (or pipx install jamstats if you're using pipx) doesn't work for you, don't give up yet! There are a few quirks that may make installation more complicated, particularly on Linux distributions.
As described in Issue 175, at least one user successfully installed JamStats with pipx in both Debian Linux 12 (Bookworm) and Ubuntu 22.04.1 LTS. They noted that Debian and Ubuntu don't install the following packages by default, which you will need to build jamstats:
- libgtk-3-dev - this package is needed for compiling the gui during install.
- python3-pip - if you install Python from the official repositories, you'll also need the corresponding package for pip
- python3-venv - is needed if you want to run Jamstats in a virtual environment. You will need this if you want to use pipx.
Use
sudo apt install libgtk-3-dev python3-pip python3-venv
to install all those things at once.
Also, note that you can use pip upgrade jamstats to upgrade to the latest version.
Finally, you may notice that the installation bogs down while trying to install wxpython. That package is only needed for the GUI interface. If you don't need the GUI interface and installing wxpython is giving you trouble, you can:
- Install all of jamstats' dependencies except wxpython
- you can find them in requirements.txt)
- If you want a semi-automated way to do that, you could download that file and then
pip install $(grep -ivE "wxpython" requirements.txt)
pip install jamstats --no-deps
And if none of that works, please log a bug!