The csgo package provides data parsing, analytics and visualization capabilities for Counter-Strike: Global Offensive (CSGO) data. In this repository, you will find the source code, issue tracker and other useful information pertaining to the csgo package. Please join our Discord for discussion around the library, along with other resources for esports analytics.
csgo requires Python >= 3.7 and Golang >= 1.16. Python acts as a wrapper for the Go code which parses demofiles.
To install csgo, clone the repository by running git clone https://github.com/pnxenopoulos/csgo. Then, change directories to the newly cloned repository, and install the library by running python setup.py install. For more help, you can visit the installation channel in our Discord.
Do your work in Colab? No problem, the csgo Python library runs there, too. Check out how to setup csgo Python library in Google Colab.
Using the csgo package is straightforward. Just choose a demofile and have output in a JSON or Pandas DataFrame in a few seconds. Use the example below to get started.
from csgo.parser import DemoParser
# Set parse_rate to a power of 2 between 2^0 and 2^7. It indicates the spacing between parsed ticks. Larger numbers result in fewer frames recorded. 128 indicates a frame per second on professional game demos.
demo_parser = DemoParser(demofile="og-vs-natus-vincere-m1-dust2.dem", demo_id="og-vs-natus-vincere", parse_rate=128)
# Parse the demofile, output results to dictionary with df name as key
data = demo_parser.parse()
# The following keys exist
data["matchID"]
data["clientName"]
data["mapName"]
data["tickRate"]
data["playbackTicks"]
data["parserParameters"]
data["serverVars"]
data["matchPhases"]
data["parsedPlaceNames"]
data["matchmakingRanks"]
data["gameRounds"] # From this value, you can extract player events via: data['gameRounds'][i]['kills'], etc.
# You can also parse the data into dataframes using
data_df = demo_parser.parse(return_type="df")
# You can also access the data in the file demoId_mapName.json, which is written in your working directoryPlease note that the parser parses everything in the demo. This means that you may have rounds from the warmup (denoted with the isWarmup flag), rounds that may have ended in a draw, and other odd-looking rounds. You will have to do your own cleaning, although we hope that whatever functions exist in csgo.parser.cleaning can help you.
If you need help with the parser, join our Discord. CSGO demos are oftentimes imperfect, but if you ask on Discord, we can try to figure out what the problem is. Also, note the help section above. If you come across any issue, whether a demo doesn't parse, parsed demo data is incorrect or you want a new feature, do not hesitate to open an issue or ask on Discord. You can see open issues here and can visit our documentation for more information on the library's capabilities.
Take a look at the following Jupyter notebooks provided in our examples/ directory. These will help you get started parsing and analyzing CSGO data.
You can also visit the documentation to see examples of content that uses the csgo Python library. If you use the parser in research, please cite Valuing Actions in Counter-Strike: Global Offensive, below. If you use the parser for any analysis on Twitter, we kindly ask you to cite back to the parser, so that others may know how you parsed your data. If you have a paper that uses the parser, please let us know in Discord so we can add it! Here is the paper citation:
Xenopoulos, Peter, et al. "Valuing Actions in Counter-Strike: Global Offensive." 2020 IEEE International Conference on Big Data (Big Data). IEEE, 2020.
We welcome any contributions from the community. You can visit the issue page to see what issues are still open, or you can message on Discord. We will always have a need for writing tests and expanding functionality. Currently, we are focused on refining our tests and on building more visualization functions. We also see contributors as those who use the library to produce interesting content (such as tweets, analyses, papers, etc.) -- you can see more examples of community content here.
When contributing code, be sure to lint your code using black, and to run the tests using pytest.
This csgo Python library is structured as follows:
.
├── csgo
│ ├── analytics # Code for CSGO analytics
│ ├── data
│ │ ├── map # Map images, map data
│ │ └── nav # Map navigation files
│ ├── parser # Code for CSGO demo parser
│ └── visualization # Code for CSGO visualization
├── doc # Contains documentation markdown files
├── examples # Contains Jupyter Notebooks showing example code
└── tests # Contains tests for the csgo package
This project is made possible by the amazing work done in the demoinfocs-golang and gonav packages. To fix errors brought about in the gonav package from Go 1.14, we provide an updated version in the gonavparse.
Big shoutout to SimpleRadar for allowing use of their map images.
Special thanks to arjun-22 for his work on the stats module and expanding test coverage.