awpy

The awpy 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 awpy information. Please join our Discord for discussion around the library and esports analytics. You may visit the documentation here.

Table of Contents

Setup and Installation

Example Code and Projects

Contributing

Structure

Acknowledgments

Setup

Requirements

awpy requires Python >= 3.11 and Golang >= 1.18. Python acts as a wrapper for the Go code which parses demofiles.

Installation

To install awpy, you can run

pip install awpy

To update the library, just run pip install --upgrade awpy. For more help, you can visit the installation channel in our Discord.

Colab Notebook

Do you work in Google Colab? No problem, the awpy Python library runs there, too! Check out how to setup awpy Python library in Google Colab.

Example Code

Using the awpy package is straightforward. Just grab a demofile and have output in a JSON or Pandas DataFrame in a few seconds. Use the example below to get started.

from awpy import DemoParser
from awpy.analytics.stats import player_stats

# Set the parse_rate equal to the tick rate at which you would like to parse the frames of the demo.
# This parameter only matters if parse_frames=True ()
# For reference, MM demos are usually 64 ticks, and pro/FACEIT demos are usually 128 ticks.
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()


# There are a variety of top level keys
# You can view game rounds and events in 'gameRounds']
data["matchID"]
data["clientName"]
data["mapName"]
data["tickRate"]
data["playbackTicks"]
data["playbackFramesCount"]
data["parsedToFrameIdx"]
data["parserParameters"]
data["serverVars"]
data["matchPhases"]
data["matchmakingRanks"]
data["playerConnections"]
data["gameRounds"] # From this value, you can extract player events via: data['gameRounds'][i]['kills'], etc.

player_stats(data["gameRounds"])  # You can create a dictionary of player stats over a list of rounds

# You can also parse the data into dataframes using
data_df = demo_parser.parse(return_type="df")


# The parser also writes a JSON file of the output named demo_id.json

Help! The parser returns weird rounds.

Please 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. Try using the DemoParser.clean_rounds() method to clean up. Note that this is not going to be 100 percent perfect.

Help! The parser doesn't work or lacks a feature

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 is the problem. Please remember to post the error and demo if you can! You can also check the open issues or visit visit our documentation.

Examples and Projects

Take a look at the following Jupyter notebooks provided in our examples/ directory. These will help you get started parsing and analyzing CSGO data.

• Parsing a CSGO demofile
• Basic CSGO analysis
• Basic CSGO visualization
• Working with navigation meshes
• Advanced navigation functionality
• Map control

If you use the parser for any public analysis, we kindly ask you to link to this repository, so that others may know how you parsed, analyzed or visualized your data. If you have a paper or project that uses the parser, please let us know in Discord so we can add it!

Contributing

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, quality assurance and expanding functionality. We also seek contributors to produce interesting content (such as tweets, analyses, papers, etc.) -- you can see more examples of community content here. If you are interested in contributing to Awpy, learn more here.

Structure

awpy is structured as follows:

.
├── awpy
│   ├── analytics                 # Code for CSGO analytics
│   ├── data                      # Code for dealing with CSGO map and nav data
│   ├── parser                    # Code for CSGO demo parser
│   └── visualization             # Code for CSGO visualization
├── doc                           # Contains documentation files
├── examples                      # Contains Jupyter Notebooks showing example code
└── tests                         # Contains tests for the awpy package

Acknowledgments

This project is made possible by the amazing work done in the demoinfocs-golang.

The name "Awpy" is due to Nick Wan's great idea!

Big shoutout to SimpleRadar for allowing use of their map images.

Special thanks to arjun-22 for his work on the initial stats module, expanding test coverage, and quality assurance checks.

Thanks to Jan-Eric for his contributions extending the navigation functionality, greatly expanding test coverage and fixing bugs.

Additional thanks to those of you in the Discord community who file bug reports and test awpy thoroughly.