Parser

This is the parser module. You can use it to parse and clean CSGO demos. To see what parsed demo looks like, and what the JSON keys indicate, please visit Example Parser JSON.

awpy.parser.cleaning

Data cleaning functions.

class awpy.parser.cleaning.DistMetricCallable(*args, **kwargs)[source]

Bases: Protocol

Class to define valid text dist callables.

awpy.parser.cleaning.associate_entities(game_names: list[str | None] | None = None, entity_names: list[str] | None = None, metric: Literal['lcss', 'hamming', 'levenshtein', 'jaro', 'difflib'] = 'lcss') → dict[source]

A function to return a dict of associated entities. Accepts.

Parameters:

game_names (list, optional) – A list of names generated by the demofile. Defaults to []
entity_names (list, optional) – A list of names: Defaults to []
metric (string, optional) – A string indicating distance metric, one of lcss, hamming, levenshtein, jaro, difflib. Defaults to ‘lcss’

Returns:

A dictionary where the keys are entries in game_names, values are the matched entity names.

Raises:

ValueError – If metric is not in: [“lcss”, “hamming”, “levenshtein”, “jaro”, “difflib”]

awpy.parser.cleaning.replace_entities(dataframe: DataFrame, col_name: str, entity_dict: dict) → DataFrame[source]

A function to replace values in a Pandas df column given an entity dict.

entity_dict as created in associate_entities().

Parameters:

dataframe (DataFrame) – A Pandas DataFrame
col_name (string) – A column in the Pandas DataFrame
entity_dict (dict) – A dictionary as created in associate_entities()

Returns:

A dataframe with replaced names.

awpy.parser.demoparser

This module defines the DemoParser class that handles the core functionality.

Core functionality is parsing and cleaning a csgo demo file.

Example:

from awpy.parser import DemoParser

# Create parser object
# Set log=True above if you want to produce a logfile for the parser
demo_parser = DemoParser(
    demofile = "og-vs-natus-vincere-m1-dust2.dem",
    demo_id = "OG-NaVi-BLAST2020",
    parse_rate=128,
    trade_time=5,
    buy_style="hltv"
)

# Parse the demofile, output results to dictionary
data = demo_parser.parse()

https://github.com/pnxenopoulos/awpy/blob/main/examples/00_Parsing_a_CSGO_Demofile.ipynb

class awpy.parser.demoparser.DemoParser(*, demofile: str = '', outpath: str | None = None, demo_id: str | None = None, log: bool = False, debug: bool = False, **parser_args: Unpack[ParserArgs])[source]

Bases: object

DemoParser can parse, load and clean data from a CSGO demofile.

Can be instantiated without a specified demofile.

demofile

A string denoting the path to the demo file, which ends in .dem. Defaults to ‘’

Type:: string

outpath

Path where to save the outputfile to. Default is current directory

Type:: string

demo_id

A unique demo name/game id. Default is inferred from demofile name

Type:: string

output_file

The output file name. Default is ‘demoid’+”.json”

Type:: str

parse_rate

One of 128, 64, 32, 16, 8, 4, 2, or 1. The lower the value, the more frames are collected. Indicates spacing between parsed demo frames in ticks. Default is 128.

Type:: int, optional

parse_frames

Flag if you want to parse frames (trajectory data) or not. Default is True

Type:: bool

parse_kill_frames

Flag if you want to parse frames on kills. Default is False

Type:: bool

trade_time

Length of the window for a trade (in seconds). Default is 5.

Type:: int, optional

dmg_rolled

Boolean if you want damages rolled up. As multiple damages for a player can happen in 1 tick from the same weapon. Default is False

Type:: bool

parse_chat

Flag if you want to parse chat messages. Default is False

Type:: bool

buy_style

Buy style string, one of “hltv” or “csgo” Default is “hltv”

Type:: string

json_indentation

Whether the json file should be pretty printed with indentation (larger, more readable) or not (smaller, less human readable) Default is False

Type:: bool

json

Dictionary containing the parsed json file

Type:: dict

Raises:: ValueError – Raises a ValueError if the Golang version is lower than 1.18

add_player_specific_information(player_item: dict[str, Any], player: PlayerInfo) → None[source]

Add player specific information to player_item dict.

Parameters:

player_item (dict[str, Any]) – Dictionary containing player specific and general information for a frame.
player (PlayerInfo) – TypedDict containing information for a single player for a specific frame.

property buy_style: Literal['hltv', 'csgo']

buy_style getter.

Returns:: Current buy_style.
Return type:: BuyStyle

clean_rounds(*, remove_no_frames: bool = True, remove_warmups: bool = True, remove_knifes: bool = True, remove_bad_timings: bool = True, remove_excess_players: bool = True, remove_excess_kills: bool = True, remove_bad_endings: bool = True, remove_bad_scoring: bool = True, return_type: Literal['json'] = 'json', save_to_json: bool = True) → Game[source]

clean_rounds(*, remove_no_frames: bool = True, remove_warmups: bool = True, remove_knifes: bool = True, remove_bad_timings: bool = True, remove_excess_players: bool = True, remove_excess_kills: bool = True, remove_bad_endings: bool = True, remove_bad_scoring: bool = True, return_type: Literal['df'] = 'json', save_to_json: bool = True) → dict[str, Any]

Cleans a parsed demofile JSON.

Parameters:

remove_no_frames (bool, optional) – Remove rounds where there are no frames. Default to True.
remove_warmups (bool, optional) – Remove warmup rounds. Defaults to True.
remove_knifes (bool, optional) – Remove knife rounds. Defaults to True.
remove_bad_timings (bool, optional) – Remove bad timings. Defaults to True.
remove_excess_players (bool, optional) – Remove rounds with more than 5 players. Defaults to True.
remove_excess_kills (bool, optional) – Remove rounds with more than 10 kills. Defaults to True.
remove_bad_endings (bool, optional) – Remove rounds with bad round end reasons. Defaults to True.
remove_bad_scoring (bool, optional) – Remove rounds where the scoring is off Like scores going below the previous round’s. Defaults to False.
return_type (str, optional) – Return JSON or DataFrame. Defaults to “json”.
save_to_json (bool, optional) – Whether to write the JSON to a file. Defaults to True.

Raises:

AttributeError – Raises an AttributeError if the .json attribute is None
ValueError – Raises a ValueError if the return type is neither ‘json’ nor ‘df’

Returns:

A dictionary of the cleaned demo.

Return type:

dict

property dmg_rolled: bool

dmg_rolled getter.

Returns:: Current dmg_rolled.
Return type:: bool

property json: Game | None

Json getter.

Returns:: Parsed demo information in json format
Return type:: Game

property json_indentation: bool

json_indentation getter.

Returns:: Current json_indentation.
Return type:: bool

log_settings() → None[source]: Log the settings produced in the constructor.

parse(*, return_type: Literal['json'] = 'json', clean: bool = True) → Game[source]

parse(*, return_type: Literal['df'], clean: bool = True) → dict[str, Any]

Wrapper for parse_demo() and read_json(). Use to parse a demo.

Parameters:

return_type (string, optional) – Either “json” or “df”. Default is “json”
clean (bool, optional) – True to run clean_rounds. Otherwise, uncleaned data is returned. Defaults to True.

Returns:

A dictionary of output which is parsed to a JSON file in the working directory.

Raises:

ValueError – Raises a ValueError if the return_type is not “json” or “df”
AttributeError – Raises an AttributeError if the .json attribute is None

property parse_chat: bool

parse_chat getter.

Returns:: Current parse_chat.
Return type:: bool

parse_demo() → None[source]

Parse a demofile using the Go script parse_demo.go.

This function needs the .demofile to be set in the class, and the file needs to exist.

Returns:

Outputs a JSON file to current working directory.

Raises:

ValueError – Raises a ValueError if the Golang version is lower than 1.18
FileNotFoundError – Raises a FileNotFoundError if the demofile path does not exist.

property parse_frames: bool

parse_frames getter.

Returns:: Current parse_frames.
Return type:: bool

parse_json_to_df() → dict[str, Any][source]

Returns JSON into dictionary where keys correspond to data frames.

Returns:: A dictionary of output
Raises:: AttributeError – Raises an AttributeError if the .json attribute is None

property parse_kill_frames: bool

parse_kill_frames getter.

Returns:: Current parse_kill_frames.
Return type:: bool

property parse_rate: Literal[128, 64, 32, 16, 8, 4, 2, 1]

Parse rate getter.

Returns:: Current parse rate.
Return type:: int

read_json(json_path: str) → Game[source]

Reads the JSON file given a JSON path.

Can be used to read in already processed demofiles.

Parameters:: json_path (string) – Path to JSON file

Returns (Game):: JSON in Python dictionary form

Raises:: FileNotFoundError – Raises a FileNotFoundError if the JSON path doesn’t exist

remove_bad_scoring() → None[source]

Removes rounds where the scoring is bad.

We loop through the rounds: If the round ahead has equal or less score, we do not add the current round. If the round ahead has +1 score, we add the current round

Raises:: AttributeError – Raises an AttributeError if the .json attribute is None

remove_end_round(bad_endings: list[str] | None = None) → None[source]

Removes rounds with bad end reason.

Parameters:: bad_endings (list, optional) – List of bad round end reasons. Defaults to [“Draw”, “Unknown”, “”].
Raises:: AttributeError – Raises an AttributeError if the .json attribute is None

remove_excess_kill_rounds() → None[source]

Removes rounds with more than 10 kills.

Raises:: AttributeError – Raises an AttributeError if the .json attribute is None

remove_excess_players() → None[source]

Removes rounds where there are more than 5 players on a side.

Raises:: AttributeError – Raises an AttributeError if the .json attribute is None

remove_knife_rounds() → None[source]

Removes knife rounds.

Raises:: AttributeError – Raises an AttributeError if the .json attribute is None

remove_rounds_with_no_frames() → None[source]

Removes rounds with no frames.

Raises:: AttributeError – Raises an AttributeError if the .json attribute is None

remove_time_rounds() → None[source]

Remove rounds with odd round timings.

Raises:: AttributeError – Raises an AttributeError if the .json attribute is None

remove_warmups() → None[source]

Removes warmup rounds.

Raises:: AttributeError – Raises an AttributeError if the .json attribute is None

renumber_frames() → None[source]

Renumbers the frames.

Needed since cleaning can remove frames and cause some indices to be skipped.

Raises:: AttributeError – Raises an AttributeError if the .json attribute has no “gameRounds” key.

renumber_rounds() → None[source]

Renumbers the rounds.

Raises:: AttributeError – Raises an AttributeError if the .json attribute has no “gameRounds” key.

rescore_rounds() → None[source]

Rescore the rounds based on round end reason.

Raises:: AttributeError – Raises an AttributeError if the .json attribute has no “gameRounds” key.

property trade_time: int

Trade time getter.

Returns:: Current trade time.
Return type:: int

write_json() → None[source]: Rewrite the JSON file.