[](https://discord.gg/W34XjsSs2H) [](https://pepy.tech/project/awpy) [](https://github.com/pnxenopoulos/awpy/actions/workflows/build.yml) [](https://awpy.readthedocs.io/en/latest/?badge=latest) [](https://www.python.org/downloads/release/python-311/)
[](https://github.com/pnxenopoulos/awpy/blob/main/LICENSE) [](https://github.com/psf/black) [](https://github.com/pylint-dev/pylint) [](https://github.com/charliermarsh/ruff) [](https://microsoft.github.io/pyright/) [](https://github.com/pre-commit/pre-commit)
# 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](https://discord.gg/W34XjsSs2H) for discussion around the library and esports analytics. You may visit the documentation [here](https://awpy.readthedocs.io/en/latest/).
## Table of Contents
[Setup and Installation](#setup)
[Example Code and Projects](#example-code)
[Contributing](#contributing)
[Structure](#structure)
[Acknowledgments](#acknowledgments)
## Setup
#### Requirements
`awpy` requires [Python](https://www.python.org/downloads/) >= 3.11 and [Golang](https://golang.org/dl/) >= 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](https://discord.gg/W34XjsSs2H).
#### 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](https://colab.research.google.com/drive/1xiXeWHSAlqYNa-xjSK9B2xalvLMpIlJF?usp=sharing).
## 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.
```python
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](https://discord.gg/3JrhKYcEKW). 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](https://github.com/pnxenopoulos/awpy/issues) or visit visit [our documentation](https://awpy.readthedocs.io/en/latest/).
## 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](https://github.com/pnxenopoulos/awpy/blob/main/examples/00_Parsing_a_CSGO_Demofile.ipynb)
- [Basic CSGO analysis](https://github.com/pnxenopoulos/awpy/blob/main/examples/01_Basic_CSGO_Analysis.ipynb)
- [Basic CSGO visualization](https://github.com/pnxenopoulos/awpy/blob/main/examples/02_Basic_CSGO_Visualization.ipynb)
- [Working with navigation meshes](https://github.com/pnxenopoulos/awpy/blob/main/examples/03_Working_with_Navigation_Meshes.ipynb)
- [Advanced navigation functionality](https://github.com/pnxenopoulos/awpy/blob/main/examples/04_Advanced_Navigation_Functionality.ipynb)
- [Map control](https://github.com/pnxenopoulos/awpy/blob/main/examples/05_Map_Control_Calculations_And_Visualizations.ipynb)
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](https://github.com/pnxenopoulos/awpy/issues) 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](https://awpy.readthedocs.io/en/latest/projects.html). If you are interested in contributing to Awpy, learn more [here](https://github.com/pnxenopoulos/awpy/blob/main/CONTRIBUTING.md).
## 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](https://github.com/markus-wa/demoinfocs-golang).
Big shoutout to [SimpleRadar](https://readtldr.gg/simpleradar?utm_source=github&utm_id=xenos-csgo-parser) for allowing use of their map images.
Special thanks to [arjun-22](https://github.com/arjun-22) for his work on the initial stats module, expanding test coverage, and quality assurance checks.
Thanks to [Jan-Eric](https://github.com/JanEricNitschke) 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.
Raw data
{
"_id": null,
"home_page": "https://github.com/pnxenopoulos/awpy",
"name": "awpy",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "",
"keywords": "esports,sports-analytics,csgo,counter-strike",
"author": "Peter Xenopoulos",
"author_email": "Peter Xenopoulos <xenopoulos@nyu.edu>, Jan-Eric Nitschke <janericnitschke@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/d5/da/16edfa78ecb7f535abaf85950c13c2198eeca475d1285909ca38ae13799a/awpy-1.3.1.tar.gz",
"platform": null,
"description": "[](https://discord.gg/W34XjsSs2H) [](https://pepy.tech/project/awpy) [](https://github.com/pnxenopoulos/awpy/actions/workflows/build.yml) [](https://awpy.readthedocs.io/en/latest/?badge=latest) [](https://www.python.org/downloads/release/python-311/)\n\n[](https://github.com/pnxenopoulos/awpy/blob/main/LICENSE) [](https://github.com/psf/black) [](https://github.com/pylint-dev/pylint) [](https://github.com/charliermarsh/ruff) [](https://microsoft.github.io/pyright/) [](https://github.com/pre-commit/pre-commit)\n\n\n# awpy\nThe `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](https://discord.gg/W34XjsSs2H) for discussion around the library and esports analytics. You may visit the documentation [here](https://awpy.readthedocs.io/en/latest/).\n\n## Table of Contents\n[Setup and Installation](#setup)\n\n[Example Code and Projects](#example-code)\n\n[Contributing](#contributing)\n\n[Structure](#structure)\n\n[Acknowledgments](#acknowledgments)\n\n## Setup\n#### Requirements\n`awpy` requires [Python](https://www.python.org/downloads/) >= 3.11 and [Golang](https://golang.org/dl/) >= 1.18. Python acts as a wrapper for the Go code which parses demofiles.\n\n#### Installation\nTo install `awpy`, you can run\n\n```\npip install awpy\n```\n\nTo update the library, just run `pip install --upgrade awpy`. For more help, you can visit the installation channel in [our Discord](https://discord.gg/W34XjsSs2H).\n\n#### Colab Notebook\nDo 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](https://colab.research.google.com/drive/1xiXeWHSAlqYNa-xjSK9B2xalvLMpIlJF?usp=sharing).\n\n## Example Code\nUsing 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.\n\n```python\nfrom awpy import DemoParser\nfrom awpy.analytics.stats import player_stats\n\n# Set the parse_rate equal to the tick rate at which you would like to parse the frames of the demo.\n# This parameter only matters if parse_frames=True ()\n# For reference, MM demos are usually 64 ticks, and pro/FACEIT demos are usually 128 ticks.\ndemo_parser = DemoParser(demofile=\"og-vs-natus-vincere-m1-dust2.dem\", demo_id=\"og-vs-natus-vincere\", parse_rate=128)\n\n\n# Parse the demofile, output results to dictionary with df name as key\ndata = demo_parser.parse()\n\n\n# There are a variety of top level keys\n# You can view game rounds and events in 'gameRounds']\ndata[\"matchID\"]\ndata[\"clientName\"]\ndata[\"mapName\"]\ndata[\"tickRate\"]\ndata[\"playbackTicks\"]\ndata[\"playbackFramesCount\"]\ndata[\"parsedToFrameIdx\"]\ndata[\"parserParameters\"]\ndata[\"serverVars\"]\ndata[\"matchPhases\"]\ndata[\"matchmakingRanks\"]\ndata[\"playerConnections\"]\ndata[\"gameRounds\"] # From this value, you can extract player events via: data['gameRounds'][i]['kills'], etc.\n\nplayer_stats(data[\"gameRounds\"]) # You can create a dictionary of player stats over a list of rounds\n\n# You can also parse the data into dataframes using\ndata_df = demo_parser.parse(return_type=\"df\")\n\n\n# The parser also writes a JSON file of the output named demo_id.json\n```\n\n### Help! The parser returns weird rounds.\nPlease 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.\n\n### Help! The parser doesn't work or lacks a feature\nIf you need help with the parser, join [our Discord](https://discord.gg/3JrhKYcEKW). 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](https://github.com/pnxenopoulos/awpy/issues) or visit visit [our documentation](https://awpy.readthedocs.io/en/latest/).\n\n## Examples and Projects\nTake a look at the following Jupyter notebooks provided in our `examples/` directory. These will help you get started parsing and analyzing CSGO data.\n\n- [Parsing a CSGO demofile](https://github.com/pnxenopoulos/awpy/blob/main/examples/00_Parsing_a_CSGO_Demofile.ipynb)\n- [Basic CSGO analysis](https://github.com/pnxenopoulos/awpy/blob/main/examples/01_Basic_CSGO_Analysis.ipynb)\n- [Basic CSGO visualization](https://github.com/pnxenopoulos/awpy/blob/main/examples/02_Basic_CSGO_Visualization.ipynb)\n- [Working with navigation meshes](https://github.com/pnxenopoulos/awpy/blob/main/examples/03_Working_with_Navigation_Meshes.ipynb)\n- [Advanced navigation functionality](https://github.com/pnxenopoulos/awpy/blob/main/examples/04_Advanced_Navigation_Functionality.ipynb)\n- [Map control](https://github.com/pnxenopoulos/awpy/blob/main/examples/05_Map_Control_Calculations_And_Visualizations.ipynb)\n\nIf 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!\n\n## Contributing\nWe welcome any contributions from the community. You can visit the [issue page](https://github.com/pnxenopoulos/awpy/issues) 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](https://awpy.readthedocs.io/en/latest/projects.html). If you are interested in contributing to Awpy, learn more [here](https://github.com/pnxenopoulos/awpy/blob/main/CONTRIBUTING.md).\n\n## Structure\n`awpy` is structured as follows:\n\n```\n.\n\u251c\u2500\u2500 awpy\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 analytics # Code for CSGO analytics\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 data # Code for dealing with CSGO map and nav data\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 parser # Code for CSGO demo parser\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 visualization # Code for CSGO visualization\n\u251c\u2500\u2500 doc # Contains documentation files\n\u251c\u2500\u2500 examples # Contains Jupyter Notebooks showing example code\n\u2514\u2500\u2500 tests # Contains tests for the awpy package\n```\n\n## Acknowledgments\nThis project is made possible by the amazing work done in the [demoinfocs-golang](https://github.com/markus-wa/demoinfocs-golang).\n\nBig shoutout to [SimpleRadar](https://readtldr.gg/simpleradar?utm_source=github&utm_id=xenos-csgo-parser) for allowing use of their map images.\n\nSpecial thanks to [arjun-22](https://github.com/arjun-22) for his work on the initial stats module, expanding test coverage, and quality assurance checks.\n\nThanks to [Jan-Eric](https://github.com/JanEricNitschke) for his contributions extending the navigation functionality, greatly expanding test coverage and fixing bugs.\n\nAdditional thanks to those of you in the Discord community who file bug reports and test awpy thoroughly.\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Counter-Strike: Global Offensive data parsing, analysis and visualization functions",
"version": "1.3.1",
"project_urls": {
"Documentation": "https://awpy.readthedocs.io/en/latest/?badge=latest",
"GitHub": "https://github.com/pnxenopoulos/awpy/",
"Homepage": "https://github.com/pnxenopoulos/awpy",
"Issues": "https://github.com/pnxenopoulos/awpy/issues"
},
"split_keywords": [
"esports",
"sports-analytics",
"csgo",
"counter-strike"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d5da16edfa78ecb7f535abaf85950c13c2198eeca475d1285909ca38ae13799a",
"md5": "200188166d9a4735ff860ba72819c68f",
"sha256": "9474546f94347e39fa82f305212bc98c9d08ba2dc053aa0e1ab7677f1114366c"
},
"downloads": -1,
"filename": "awpy-1.3.1.tar.gz",
"has_sig": false,
"md5_digest": "200188166d9a4735ff860ba72819c68f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 55808135,
"upload_time": "2023-07-28T13:34:51",
"upload_time_iso_8601": "2023-07-28T13:34:51.582726Z",
"url": "https://files.pythonhosted.org/packages/d5/da/16edfa78ecb7f535abaf85950c13c2198eeca475d1285909ca38ae13799a/awpy-1.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-28 13:34:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pnxenopoulos",
"github_project": "awpy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "awpy"
}
JSON
