Demo

This module contains the Demo class, which is used to parse and hold demo file data.

awpy.demo

Defines the Demo class.

class awpy.demo.Demo(path: Path, tickrate: int = 128, inferno_duration: float = 7.03125, smoke_duration: float = 20.0, *, verbose: bool = False)

Bases: object

Class to parse and store a demo’s data.

This class encapsulates functionality for parsing various aspects of a demo file, including header information, event data, tick data, and grenade events. Instances of this class are typically created with a file path to the demo file.

Example

demo = Demo(path=Path(“path/to/demo.dem”), verbose=True)

property bomb: DataFrame

Cached property that returns a Polars DataFrame of bomb events from the demo.

This property leverages the awpy.parsers.bomb.parse_bomb function to parse and standardize bomb-related events extracted from the demo’s events. These events include bomb drops, pickups, plantings, and explosions. The parsing process uses the demo’s parsed events (self.events) and filters them based on the valid in-play tick values (self.in_play_ticks) to ensure that only bomb events occurring during active gameplay are included.

The resulting DataFrame typically contains columns such as: - tick: The tick at which the bomb event occurred. - status: The bomb event status (e.g., “dropped”, “carried”, “planted”, or “detonated”). - Position coordinates (x, y, z) of the bomb, derived from tick data. - steamid: The steam ID of the player associated with the bomb event. - name: The name of the player associated with the bomb event. - bombsite: For planted events, the bombsite information; otherwise, null.

Returns:

A DataFrame containing standardized bomb event data.

Return type:

pl.DataFrame

Raises:

KeyError – If the necessary bomb event data is missing from the parsed events.

compress(outpath: Path | None = None) → None

Compress the parsed contents of the demo file.

Parameters:

outpath (Path | None, optional) – The output path for the compressed demo file. If None, the compressed file will be saved to the original file path.

property damages: DataFrame

Cached property that returns a Polars DataFrame of damage events parsed from the demo.

This property extracts the ‘player_hurt’ events from the parsed events dictionary, and then processes these events using the awpy.parsers.events.parse_damages function to create a standardized DataFrame of damage (player hurt) data.

Returns:

A DataFrame containing damage event data.

Return type:

pl.DataFrame

Raises:

KeyError – If ‘player_hurt’ events are not found in the parsed events, which likely indicates that the demo has not been parsed yet. In this case, please run the .parse() method.

property default_events: list[str]

Get the default list of event names to parse from the demo file.

This default list includes key events such as round events, player actions, bomb events, and grenade detonations that are typically of interest when analyzing a demo.

Returns:

A list of default event names.

Return type:

list[str]

property detected_events: list[str]

Retrieve the list of events detected in the demo file.

This property queries the underlying demo parser to obtain a list of all event types that have been identified within the demo.

Returns:

A list of event names detected in the demo.

Return type:

list[str]

property footsteps: DataFrame

Cached property that returns a Polars DataFrame of footstep events from the demo.

Footstep events are derived from the ‘player_sound’ events parsed from the demo. These events are processed using the awpy.parsers.events.parse_footsteps function, which standardizes the data for further analysis. The resulting DataFrame typically contains details such as the position and timing of player sounds (often corresponding to footsteps).

Returns:

A DataFrame containing footstep event data.

Return type:

pl.DataFrame

Raises:

KeyError – If ‘player_sound’ events are not found in the parsed events. This may indicate that the demo has not been parsed yet. Please run the .parse() method.

property infernos: DataFrame

Cached property that returns a Polars DataFrame of inferno events in the demo.

Inferno events are derived from the “inferno_startburn” and “inferno_expire” events. The effective duration is computed as tickrate multiplied by inferno_duration (in seconds).

Returns:

A DataFrame containing inferno event data.

Return type:

pl.DataFrame

Raises:

KeyError – If the necessary inferno events (“inferno_startburn” or “inferno_expire”) are not found in the parsed events.

property kills: DataFrame

Cached property that returns a Polars DataFrame of kill events parsed from the demo.

This property extracts the ‘player_death’ events from the parsed events dictionary, and then processes these events using the awpy.parsers.events.parse_kills function to create a standardized DataFrame of kill data.

Returns:

A DataFrame containing kill event data.

Return type:

pl.DataFrame

Raises:

KeyError – If ‘player_death’ events are not found in the parsed events, which likely indicates that the demo has not been parsed yet. In this case, please run the .parse() method.

parse(events: list[str] | None = None, player_props: list[str] | None = None, other_props: list[str] | None = None) → None

Parse the demo file for events, rounds, tick data, and grenade events.

This comprehensive parsing method processes the demo file in several stages:

1. It extracts event data for a specified set of events (or a default set if None is provided).

2. It creates a rounds DataFrame from the event data.

3. It extracts and filters valid in-play ticks.

4. It parses player-specific tick data.

5. It parses grenade events.

6. It filters the data to include only valid ticks during match play.

Parameters:

• events (list[str] | None, optional) – List of event names to parse. If None, a default set of events defined by default_events is used.

• player_props (list[str] | None, optional) – List of player-related properties to extract.

• other_props (list[str] | None, optional) – List of additional properties to extract.

Returns:

None

parse_events(events_to_parse: list[str] | None = None, player_props: list[str] | None = None, other_props: list[str] | None = None) → dict[str, DataFrame]

Parse event data from the demo file.

This method extracts the specified events from the demo file using the demo parser, converts the results into Polars DataFrames, and applies additional processing for round events by setting custom labels and filtering out invalid data.

Parameters:

• events_to_parse (list[str] | None, optional) – List of event names to parse. If None, no additional events beyond the parser’s defaults will be processed.

• player_props (list[str] | None, optional) – List of player-specific properties to extract.

• other_props (list[str] | None, optional) – List of other properties to extract.

Returns:

A dictionary mapping event names to their respective Polars DataFrames.

Return type:

dict[str, pl.DataFrame]

parse_grenades() → DataFrame

Parse grenade event data from the demo file.

This method extracts grenade-related events using the demo parser and converts the resulting data into a Polars DataFrame for further analysis.

Returns:

A Polars DataFrame containing the parsed grenade event data.

Return type:

pl.DataFrame

parse_header() → dict

Parse and return the header of the demo file.

This method ensures that a parser is available and then extracts the header information from the demo file using the parser’s header parsing functionality. The returned header is processed through an auxiliary function.

Returns:

A dictionary containing the parsed header information.

Return type:

dict

parse_ticks(player_props: list[str] | None = None, other_props: list[str] | None = None) → DataFrame

Parse tick data from the demo file.

This method extracts tick-related data from the demo using the parser. It allows for the inclusion of player-specific and other additional properties. The resulting tick data is converted from a pandas DataFrame into a Polars DataFrame.

Parameters:

• player_props (list[str] | None, optional) – List of player-related properties to include.

• other_props (list[str] | None, optional) – List of other properties to include.

Returns:

A Polars DataFrame containing the parsed tick data.

Return type:

pl.DataFrame

property player_round_totals: DataFrame

Cached property that calculates and returns player round totals.

This property computes the total number of rounds played by each player, both for each specific side (e.g., ct or t) and overall (regardless of side). It uses data from the ticks and rounds DataFrames available on the demo object.

The process is as follows:

1. Select unique combinations of player name, steamid, side, and round number from the ticks DataFrame.

2. Join these unique records with the rounds DataFrame on the round number to filter and validate rounds.

3. Group the joined data by name, steamid, and side to count rounds per player for each team side.

4. Additionally, group by name and steamid to compute the total rounds played by each player, regardless of side, and label these records with side as “all”.

5. Concatenate the per-side and overall aggregates into a single DataFrame.

Returns:

A DataFrame with the following columns:

• name (str): The player’s name.

• steamid (str): The player’s Steam ID.

• side (str): The team side (“ct”, “t”, or “all” for total rounds).

• n_rounds (int): The number of rounds played by the player on the given side.

Return type:

pl.DataFrame

property server_cvars: DataFrame

Cached property that returns a Polars DataFrame of server configuration variable events.

This property extracts server configuration variables by parsing the ‘server_cvar’ event from the demo using the parser’s parse_event method. The returned data is converted from a pandas DataFrame to a Polars DataFrame, providing a standardized view of the server’s configuration variables at the time of the demo.

Returns:

A DataFrame containing server cvar event data.

Return type:

pl.DataFrame

property shots: DataFrame

Cached property that returns a Polars DataFrame of shot events from the demo.

Shot events are extracted from the ‘weapon_fire’ events parsed from the demo. These events are processed using the awpy.parsers.events.parse_shots function, which organizes the weapon fire events into a standardized format suitable for analysis. The resulting DataFrame typically includes details such as the weapon used and the time of the shot.

Returns:

A DataFrame containing shot event data.

Return type:

pl.DataFrame

Raises:

KeyError – If ‘weapon_fire’ events are not found in the parsed events. This may indicate that the demo has not been parsed yet. Please run the .parse() method.

property smokes: DataFrame

Cached property that returns a Polars DataFrame of smoke grenade events in the demo.

Smoke events are derived from the “smokegrenade_detonate” and “smokegrenade_expired” events. The effective duration is computed as tickrate multiplied by smoke_duration (in seconds).

Returns:

A DataFrame containing smoke grenade event data.

Return type:

pl.DataFrame

Raises:

KeyError – If the necessary smoke grenade events (“smokegrenade_detonate” or “smokegrenade_expired”) are not found in the parsed events.