02_handle_tracker_events.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#default_exp ingest.handle_tracker_event"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#hide\r\n",
    "from nbdev.showdoc import *"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#exporti\r\n",
    "\r\n",
    "#Load Module's dependencies\r\n",
    "\r\n",
    "from pathlib import Path\r\n",
    "from pprint import pprint\r\n",
    "from typing import *\r\n",
    "\r\n",
    "import fastcore.test as ft\r\n",
    "\r\n",
    "import sc2reader"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 4 - Handling Tracker Events"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Introduction\n",
    "\n",
    "In this chapter, I analyse the common elements of all `TrackerEvents` and build the `handle_tracker_event` module. This module exports some general-purpose functions that facilitate the processing of these events.\n",
    "\n",
    "### Exported Memebers\n",
    "\n",
    "#### Constants\n",
    "- INTERVALS_BASE\n",
    "\n",
    "#### Functions\n",
    "- calc_realtime_index\n",
    "\n",
    "## Events\n",
    "\n",
    "In the previous module (<<Chapter 1 - Summarising Replays>>), I discuss how `sc2reader` packs all information necessary to reproduce a match in a `Replay` object. I also showed how to obtain some descriptive information about the game from this object and the `Players` linked to it.\n",
    "\n",
    "Here, I review the data contained in the `Replay`'s `Event` objects. These objects are crucial, given how\n",
    "\n",
    "> : All of the gameplay and state information contained in the replay is packed into events. [(Kim, 2015, p. 22)](https://sc2reader.readthedocs.io/en/latest/events/index.html)\n",
    "\n",
    "The main types of events registered by `sc2reader` are:\n",
    "\n",
    "- Game Events: Human actions and certain triggered events.\n",
    "- Message Events: Message and Pings to other players.\n",
    "- Tracker Events: Game state information.\n",
    "\n",
    "Additionally, users can access these objects through the `Replay` objects' `events` attribute.\n",
    "\n",
    "For example, I can extract a list of all the events in a replay as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The match contains 4988 events total\n",
      "The match contains 830 events total\n",
      "The match contains 4143 events total\n",
      "The match contains 15 events total\n"
     ]
    }
   ],
   "source": [
    "# Load sample replays\r\n",
    "rps_path = Path(\"./test_replays\")\r\n",
    "game_path = str(rps_path/\"Jagannatha LE.SC2Replay\")\r\n",
    "single_replay = sc2reader.load_replay(game_path)\r\n",
    "single_replay\r\n",
    "\r\n",
    "# Extract all events\r\n",
    "match_events = [event for event in single_replay.events]\r\n",
    "\r\n",
    "# Separate the events by type\r\n",
    "tracker_e = [event for event in single_replay.events \r\n",
    "            if isinstance(event, sc2reader.events.tracker.TrackerEvent)]\r\n",
    "\r\n",
    "game_e = [event for event in single_replay.events \r\n",
    "         if isinstance(event, sc2reader.events.game.GameEvent)]\r\n",
    "\r\n",
    "message_e = [event for event in single_replay.events \r\n",
    "            if isinstance(event, sc2reader.events.message.MessageEvent)]\r\n",
    "\r\n",
    "print(f'The match contains {len(match_events)} events total')\r\n",
    "print(f'The match contains {len(tracker_e)} events total')\r\n",
    "print(f'The match contains {len(game_e)} events total')\r\n",
    "print(f'The match contains {len(message_e)} events total')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the following test, I check that the sum of the Tracker, Message and Game events effectively make up the whole of the events registered by the system."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "ft.equals((len(tracker_e) + len(game_e) + len(message_e)), len(match_events))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Tracker Events\n",
    "\n",
    "`TrackerEvent` objects store information about the state of the game. Users can use them to track various aspects of a player's performance. Here, I review different types of `TrackerEvents`, their attributes, and some of the issues I need to consider regarding each class.\n",
    "\n",
    "> Note: The official `TrackerEvents` documentation can be found at [(Kim, 2015, p. 24-25)](https://sc2reader.readthedocs.io/en/latest/events/tracker.html).Furthermore, each type of object stores data that goes beyond what I explore here. To extract a complete list of the data stored in each type of event, you can call the `__dict__` attribute on an object of each type.\n",
    "\n",
    "In a `Replay`, one will typically found several kinds of `TrackerEvents`. In the following code, I build a `set` containing these types using a sample replay. This list shows all the `TrackerEvent`'s classes.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{sc2reader.events.tracker.PlayerSetupEvent,\n",
       " sc2reader.events.tracker.PlayerStatsEvent,\n",
       " sc2reader.events.tracker.UnitBornEvent,\n",
       " sc2reader.events.tracker.UnitDiedEvent,\n",
       " sc2reader.events.tracker.UnitDoneEvent,\n",
       " sc2reader.events.tracker.UnitInitEvent,\n",
       " sc2reader.events.tracker.UnitPositionsEvent,\n",
       " sc2reader.events.tracker.UnitTypeChangeEvent,\n",
       " sc2reader.events.tracker.UpgradeCompleteEvent}"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tracker_e_types = {type(event) for event in single_replay.events \r\n",
    "             if isinstance(event, sc2reader.events.tracker.TrackerEvent)}\r\n",
    "\r\n",
    "tracker_e_types"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### PlayerSetupEvent\n",
    "\n",
    "These are basic events used by the system to organise players at the start of the match. However, since most of the data they stored exists elsewhere, I will not use this type of events."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "setup_e = [event for event in single_replay.events \r\n",
    "           if isinstance(event, sc2reader.events.tracker.PlayerSetupEvent) \r\n",
    "           and event.pid == 1]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### PlayerStatsEvents\n",
    "\n",
    "To extract some initial information regarding the game's flow, one can consult the instances of `sc2reader.events.tracker.PlayerStatsEvent`.\n",
    "\n",
    "These events are generated for each player every ten seconds, regardless of the player's presence in the match. In other words, if one is analysing a game of more than two players and one leaves the match, the game still generates `PlayerStatsEvents` for that player up until the end of the match.\n",
    "\n",
    "> Warning: In 1v1 games, the above behaviour can cause the losing player to have two events generated at the end of the game. One for leaving and one for the end of the game. Source [(Kim, 2015, p. 24)](https://sc2reader.readthedocs.io/en/latest/events/tracker.html)\n",
    "\n",
    "Following these rules, one can estimate the number of `PlayerStatsEvents` a match should have. For example, the following sample match lasted 590 seconds. Hence, there should be 59 `PlayerStatEvent`s per player, plus two or three for start and end events. Similarly, taking into account the game's frames-per-second, one could estimate the duration of the match in frames.\n",
    "\n",
    "Bellow, I show how one can get this information from a `Replay` object. This information is critical for debugging and managing these events afterwards."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Game length in seconds:          590\n",
      "Game frames per second:         16.0\n",
      "Total frames in the match:    9440.0\n"
     ]
    }
   ],
   "source": [
    "rpl_length = single_replay.game_length.seconds\r\n",
    "rpl_fps = single_replay.game_fps #frames-per-second\r\n",
    "rpl_frame_length = single_replay.game_length.seconds * single_replay.game_fps\r\n",
    "\r\n",
    "print(f'{\"Game length in seconds:\":<30}{rpl_length:>6}')\r\n",
    "print(f'{\"Game frames per second:\":<30}{rpl_fps:>6}')\r\n",
    "print(f'{\"Total frames in the match:\":<30}{rpl_frame_length:>6}')\r\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Likewise, in the following code, I extract the `PlayerStatEvent` related to one player in the test match I am analysing."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Number of PlayerStatsEvents for player 1: 85\n"
     ]
    }
   ],
   "source": [
    "p_one_state = [event for event in match_events \r\n",
    "               if isinstance(event, sc2reader.events.tracker.PlayerStatsEvent) \r\n",
    "               and event.pid == 1]\r\n",
    "\r\n",
    "print(f'Number of PlayerStatsEvents for player 1: {len(p_one_state)}')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This information shows that there is a discrepancy in the number of `PlayerStatsEvenst` there should be (around 60 for the sample match) and the actual number there is (85).\n",
    "\n",
    "Similarly, looking at the seconds and frame count registered in the last event, it is clear that they do not match the duration of the game (590 seconds, 9440 frames)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Second recorded in the last event:    826\n",
      "Frame recorded in the last event:   13224\n"
     ]
    }
   ],
   "source": [
    "print(f'Second recorded in the last event:', end=' ')\r\n",
    "print(f'{p_one_state[len(p_one_state)-1].second:>6}')\r\n",
    "\r\n",
    "print(f'Frame recorded in the last event:', end=' ')\r\n",
    "print(f'{p_one_state[len(p_one_state)-1].frame:>7}')\r\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Fortunately, these mismatches are consistent for all the players. For example, look at the number of events, the last second and frame registered for Player 2. This player has one event less because they were the match's winner."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Number of events recorded for p2: 84\n",
      "Second recorded in the last event: 826\n",
      "Frame recorded in the last event: 13224\n"
     ]
    }
   ],
   "source": [
    "p_two_state = [event for event in match_events \r\n",
    "               if isinstance(event, sc2reader.events.tracker.PlayerStatsEvent) \r\n",
    "               and event.pid == 2]\r\n",
    "\r\n",
    "print(f'Number of events recorded for p2: {len(p_two_state)}')\r\n",
    "\r\n",
    "print(f'Second recorded in the last event:' , end=' ')\r\n",
    "print(f'{p_two_state[len(p_two_state)-1].second}')\r\n",
    "\r\n",
    "print(f'Frame recorded in the last event:', end=' ')\r\n",
    "print(f'{p_two_state[len(p_two_state)-1].frame}')\r\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> Note: because this time index discrepancy also affects other types of `Events`. I propose a basic solution in the functions section of this module further below (see `calc_realtime_index` function)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Unit trackers\n",
    "\n",
    "The following events contain data regarding the different units in the game. These units include player-controlled structures and troops, and some non-player controlled elements. However, in this case, I am primarily interested in the units controlled by players."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### UnitBornEvent\n",
    "\n",
    "Event generated any time a unit enters the game through a production building. This type of event stores the following useful attributes:\n",
    "\n",
    "- `second` (int): registered time of birth in seconds. Note that this timestamp does not match the match's duration. This inconsistency means that one must correct the time index of the event. (see `calc_realtime_index` function)\n",
    "- `unit_type_name` (str): type of the unit.\n",
    "- `location` (tuple(x, y)): tuple of ints that indicate the unit's x and y coordinates in the map.\n",
    "- `control_pid` (int): player id in the match.\n",
    "- `unit`: points to the `unit` object, which stores helpful information such as the minerals, vespene, and supply cost of the unit type [(see Kim, 2015, p. 30)](https://sc2reader.readthedocs.io/en/latest/dataobjects.html?highlight=unit#sc2reader.data.Unit).\n",
    "\n",
    "The following code illustrates some uses of these attributes:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The recorded time of birth of a unit:           731\n",
      "The supply cost of the unit type:                 4\n",
      "The unit type:                             Immortal\n",
      "The birth x, y location of the unit:        (72, 40)\n"
     ]
    }
   ],
   "source": [
    "# I can use the control_pid attribute to separate the UnitBornEvents \r\n",
    "# of a single player.\r\n",
    "UnitBorn_e = [event for event in match_events \r\n",
    "              if isinstance(event, sc2reader.events.tracker.UnitBornEvent) \r\n",
    "              and event.control_pid == 1] \r\n",
    "\r\n",
    "print(f'{\"The recorded time of birth of a unit:\":<40}', end=' ')\r\n",
    "print(f'{UnitBorn_e[62].second:>10}')\r\n",
    "\r\n",
    "print(f'{\"The supply cost of the unit type:\":<40}', end=' ')\r\n",
    "print(f'{UnitBorn_e[62].unit.supply:>10}')\r\n",
    "\r\n",
    "print(f'{\"The unit type:\":<40} {UnitBorn_e[62].unit_type_name:>10}')\r\n",
    "\r\n",
    "print(f'{\"The birth x, y location of the unit:\":<40} ', end=' ')\r\n",
    "print(f'{str(UnitBorn_e[62].location):>10}')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To group all the game's `UnitBornEvents`, I can use the  `control_pid` attribute, which points to the `Participant` that owns the unit.\n",
    "\n",
    "> Tip: Units with `control_pid` equal 0 are neutral units such as minerals, vespene geysers or obstacles.\n",
    "\n",
    "With this grouping, I can start to compose that player's build order. That is their sequence of built units during the game (see <<Chapter 4 - Parsing Build Orders>>).\n",
    "\n",
    "Additionally, having grouped all the `UnitBornEvent` instances related to a particular player, I notice the following pattern:\n",
    "\n",
    "- The first 15 units born (indexes 0-14) are `Beacons` sc2reader uses for tracking. I will ignore these objects.\n",
    "- Unit 15 is the starting base building (Nexus, CommandCenter, Hatchery).\n",
    "- Units 16-27 are the first worker units of each player.\n",
    "\n",
    "This pattern means I should only consider whatever units are born after index 27 to track the player's build order.\n",
    "\n",
    "The following code illustrates this pattern."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{0: (0, 'BeaconArmy', 'second: 0'),\n",
      " 1: (1, 'BeaconDefend', 'second: 0'),\n",
      " 2: (2, 'BeaconAttack', 'second: 0'),\n",
      " 3: (3, 'BeaconHarass', 'second: 0'),\n",
      " 4: (4, 'BeaconIdle', 'second: 0'),\n",
      " 5: (5, 'BeaconAuto', 'second: 0'),\n",
      " 6: (6, 'BeaconDetect', 'second: 0'),\n",
      " 7: (7, 'BeaconScout', 'second: 0'),\n",
      " 8: (8, 'BeaconClaim', 'second: 0'),\n",
      " 9: (9, 'BeaconExpand', 'second: 0'),\n",
      " 10: (10, 'BeaconRally', 'second: 0'),\n",
      " 11: (11, 'BeaconCustom1', 'second: 0'),\n",
      " 12: (12, 'BeaconCustom2', 'second: 0'),\n",
      " 13: (13, 'BeaconCustom3', 'second: 0'),\n",
      " 14: (14, 'BeaconCustom4', 'second: 0'),\n",
      " 15: (15, 'Nexus', 'second: 0'),\n",
      " 16: (16, 'Probe', 'second: 0'),\n",
      " 17: (17, 'Probe', 'second: 0'),\n",
      " 18: (18, 'Probe', 'second: 0'),\n",
      " 19: (19, 'Probe', 'second: 0'),\n",
      " 20: (20, 'Probe', 'second: 0'),\n",
      " 21: (21, 'Probe', 'second: 0'),\n",
      " 22: (22, 'Probe', 'second: 0'),\n",
      " 23: (23, 'Probe', 'second: 0'),\n",
      " 24: (24, 'Probe', 'second: 0'),\n",
      " 25: (25, 'Probe', 'second: 0'),\n",
      " 26: (26, 'Probe', 'second: 0'),\n",
      " 27: (27, 'Probe', 'second: 0'),\n",
      " 28: (28, 'Probe', 'second: 18'),\n",
      " 29: (29, 'Probe', 'second: 69'),\n",
      " 30: (30, 'Probe', 'second: 133')}\n"
     ]
    }
   ],
   "source": [
    "UnitBorn_e = [event for event in match_events\r\n",
    "              if isinstance(event, sc2reader.events.tracker.UnitBornEvent) \r\n",
    "              and event.control_pid == 1]\r\n",
    "\r\n",
    "born_order = {k:(k, event.unit_type_name, f'second: {event.second}') \r\n",
    "             for k, event in enumerate(UnitBorn_e) if k <=30}\r\n",
    "\r\n",
    "pprint(born_order, compact=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> Note: the first unit borned past second 0 is the 28th unit boned at 18th second.\n",
    "\n",
    "This information can also serve as the basis for a unit count (see <<Chapter 4 - Parsing Build Orders>>).\n",
    "\n",
    "For example, the following code produces a draft of the player's final unit tally."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'BeaconArmy': 1,\n",
       " 'BeaconDefend': 1,\n",
       " 'BeaconAttack': 1,\n",
       " 'BeaconHarass': 1,\n",
       " 'BeaconIdle': 1,\n",
       " 'BeaconAuto': 1,\n",
       " 'BeaconDetect': 1,\n",
       " 'BeaconScout': 1,\n",
       " 'BeaconClaim': 1,\n",
       " 'BeaconExpand': 1,\n",
       " 'BeaconRally': 1,\n",
       " 'BeaconCustom1': 1,\n",
       " 'BeaconCustom2': 1,\n",
       " 'BeaconCustom3': 1,\n",
       " 'BeaconCustom4': 1,\n",
       " 'Nexus': 1,\n",
       " 'Probe': 45,\n",
       " 'Stalker': 3,\n",
       " 'Sentry': 1,\n",
       " 'Immortal': 4}"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "counts = dict()\r\n",
    "\r\n",
    "for event in UnitBorn_e:\r\n",
    "    counts.setdefault(event.unit_type_name, 0)\r\n",
    "    counts[event.unit_type_name] += 1\r\n",
    "    \r\n",
    "counts\r\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### UnitInitEvent\n",
    "\n",
    "This type of event is a complement to the `UnitBonrEvent`, `UnitDoneEvent` and the `UnitTypeChangeEvent`.\n",
    "\n",
    "These events exists because not all units enter the game via production structures. Instead, buildings (other than the initial base), warped units, mutated units, and others are instantiated through the `UnitInitEvent` with 0 life. Afterwards, they are built over time. During this building time, players may lose or cancel this unit or buildings under construction.\n",
    "\n",
    "The information extracted from these type of events is similar to the information in the `UnitBornedEvent`. Here, again, I will use the following attributes:\n",
    "\n",
    "- `second` (int): registered time of birth in seconds. This attribute requires the same consideration as in the previous cases. (see `calc_realtime_index` function)\n",
    "- `unit_type_name` (str): type of the unit.\n",
    "- `location` (tuple(x, y)): tuple of ints that indicate the unit's x and y coordinates in the map.\n",
    "- `control_pid` (int): player id in the match.\n",
    "- `unit`: points to the `unit` object\n",
    "\n",
    "> Note: in this case, there are no initial units that should be disregarded from the player's build order."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{0: ('Pylon', 'second: 47'),\n",
       " 1: ('Pylon', 'second: 74'),\n",
       " 2: ('Gateway', 'second: 91'),\n",
       " 3: ('Gateway', 'second: 100'),\n",
       " 4: ('Forge', 'second: 111'),\n",
       " 5: ('CyberneticsCore', 'second: 170'),\n",
       " 6: ('Assimilator', 'second: 182'),\n",
       " 7: ('Assimilator', 'second: 188'),\n",
       " 8: ('Pylon', 'second: 203'),\n",
       " 9: ('Pylon', 'second: 224'),\n",
       " 10: ('PhotonCannon', 'second: 241'),\n",
       " 11: ('PhotonCannon', 'second: 244'),\n",
       " 12: ('PhotonCannon', 'second: 260'),\n",
       " 13: ('PhotonCannon', 'second: 264'),\n",
       " 14: ('Pylon', 'second: 316'),\n",
       " 15: ('Nexus', 'second: 322'),\n",
       " 16: ('RoboticsFacility', 'second: 368'),\n",
       " 17: ('Assimilator', 'second: 381'),\n",
       " 18: ('Assimilator', 'second: 385'),\n",
       " 19: ('RoboticsFacility', 'second: 408'),\n",
       " 20: ('RoboticsFacility', 'second: 411'),\n",
       " 21: ('Zealot', 'second: 479'),\n",
       " 22: ('Zealot', 'second: 487'),\n",
       " 23: ('Sentry', 'second: 540'),\n",
       " 24: ('Pylon', 'second: 651'),\n",
       " 25: ('Pylon', 'second: 662'),\n",
       " 26: ('Nexus', 'second: 682'),\n",
       " 27: ('PhotonCannon', 'second: 693'),\n",
       " 28: ('PhotonCannon', 'second: 702'),\n",
       " 29: ('Zealot', 'second: 705'),\n",
       " 30: ('Zealot', 'second: 706'),\n",
       " 31: ('Stalker', 'second: 755'),\n",
       " 32: ('Stalker', 'second: 755'),\n",
       " 33: ('Stalker', 'second: 803'),\n",
       " 34: ('Stalker', 'second: 804')}"
      ]
     },
     "execution_count": null,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "UnitInit_e = [event for event in match_events \r\n",
    "              if isinstance(event, sc2reader.events.tracker.UnitInitEvent) \r\n",
    "              and event.control_pid == 1]\r\n",
    "\r\n",
    "init_order = {k:(event.unit_type_name, f'second: {event.second}') \r\n",
    "             for k, event in enumerate(UnitInit_e)}\r\n",
    "\r\n",
    "init_order"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Also, given that these units can be buildings, troops or others, we can use this list to illustrate the use of the `unit.is_army`, `unit.is_building`, `unit.is_worker` attributes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Unit_name: RoboticsFacility is building: True\n",
      "Unit_name: RoboticsFacility is army: False\n",
      "Unit_name: RoboticsFacility is worker: False\n"
     ]
    }
   ],
   "source": [
    "print(f'Unit_name: {UnitInit_e[20].unit.name}', end=' ') \r\n",
    "print(f'is building: {UnitInit_e[20].unit.is_building}')\r\n",
    "\r\n",
    "print(f'Unit_name: {UnitInit_e[20].unit.name}', end=' ') \r\n",
    "print(f'is army: {UnitInit_e[20].unit.is_army}')\r\n",
    "\r\n",
    "print(f'Unit_name: {UnitInit_e[20].unit.name}', end=' ') \r\n",
    "print(f'is worker: {UnitInit_e[20].unit.is_worker}')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Unit_name: Stalker is building: False\n",
      "Unit_name: Stalker is army: True\n",
      "Unit_name: Stalker is worker: False\n"
     ]
    }
   ],
   "source": [
    "print(f'Unit_name: {UnitInit_e[31].unit.name}', end=' ')\r\n",
    "print(f'is building: {UnitInit_e[31].unit.is_building}')\r\n",
    "\r\n",
    "print(f'Unit_name: {UnitInit_e[31].unit.name}', end=' ')\r\n",
    "print(f'is army: {UnitInit_e[31].unit.is_army}')\r\n",
    "\r\n",
    "print(f'Unit_name: {UnitInit_e[31].unit.name}', end=' ')\r\n",
    "print(f'is worker: {UnitInit_e[31].unit.is_worker}')\r\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### UnitDoneEvent\n",
    "\n",
    "This type of event is a complement to the `UnitInitEvent`.\n",
    "\n",
    "After a `UnitInitEvent` and the unit's build time the unit comes into the game. At this point the unit triggers a `UnitDoneEvent`.\n",
    "\n",
    "This type of event has much less attributes associated to it than the `UnitBonrEvent` and `UnitInitEvent`. In this case, I will use the `second` and `unit` attributes.\n",
    "\n",
    "If I want to use these events to construct the build order based on completed units and not just only in units that where initiated, I need to use some of the `unit` object's attributes to complete the information. For example, to group the units per player I can use the `unit.owner.pid` attribute."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "UnitDone_e = [event for event in match_events \r\n",
    "              if isinstance(event, sc2reader.events.tracker.UnitDoneEvent)\r\n",
    "             and event.unit.owner.pid == 2]\r\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following code illustrates how an event's unit can offer some complementary attributes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Event's execution time: 124\n",
      "Event's execution frame: 1999\n",
      "Refinery\n",
      "Init frame: 1519\n",
      "Game-enter frame: 1999\n",
      "Owner: Player 2 - MxChrisxM (Terran)\n"
     ]
    }
   ],
   "source": [
    "sample_unit = UnitDone_e[2].unit\r\n",
    "\r\n",
    "print(f'Event\\'s execution time: {UnitDone_e[2].second}')\r\n",
    "print(f'Event\\'s execution frame: {UnitDone_e[2].frame}')\r\n",
    "print(sample_unit.name)\r\n",
    "print(f'Init frame: {sample_unit.started_at}')\r\n",
    "print(f'Game-enter frame: {sample_unit.finished_at}')\r\n",
    "print(f'Owner: {str(sample_unit.owner)}')\r\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### UpgradeCompleteEvent\n",
    "\n",
    "Other than constructing buildings and training troops, the third way players can spend their resources is by researching upgrades. Each time a player completes an upgrade it generates a `UpgradeCompleteEvent`.\n",
    "\n",
    "I will use the following features from this event type:\n",
    "\n",
    "- `pid` (int): player id in the match.\n",
    "-  `upgrade_type_name` (str): name of the upgrade.\n",
    "- `second (int)`: registered time of birth in seconds. This attribute requires the same consideration as in the previous cases. (see `calc_realtime_index` function)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{0: ('second: 0', 'RewardDanceGhost'),\n",
      " 1: ('second: 0', 'RewardDanceMule'),\n",
      " 2: ('second: 0', 'RewardDanceViking'),\n",
      " 3: ('second: 0', 'SprayTerran'),\n",
      " 4: ('second: 0', 'SprayTerran'),\n",
      " 5: ('second: 165', 'SprayTerran'),\n",
      " 6: ('second: 265', 'SprayTerran'),\n",
      " 7: ('second: 550', 'SprayTerran'),\n",
      " 8: ('second: 613', 'TerranVehicleWeaponsLevel1'),\n",
      " 9: ('second: 650', 'SprayTerran'),\n",
      " 10: ('second: 664', 'SmartServos'),\n",
      " 11: ('second: 712', 'HighCapacityBarrels'),\n",
      " 12: ('second: 819', 'SprayTerran')}\n"
     ]
    }
   ],
   "source": [
    "Upgrades = [event for event in single_replay.events \r\n",
    "           if isinstance(event, sc2reader.events.tracker.UpgradeCompleteEvent) \r\n",
    "           and event.pid == 2]\r\n",
    "\r\n",
    "upgrade_order = {k:(f'second: {event.second}', event.upgrade_type_name) \r\n",
    "                 for k, event in enumerate(Upgrades)}\r\n",
    "\r\n",
    "pprint(upgrade_order)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> Note: The upgrades that start with names that start with Spray or Reward are not activated by the player. They are generated by the game as a reward for a player's achievements but do not affect gameplay."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### UnitTypeChangeEvent\n",
    "\n",
    "During a game, some units and buildings appear (they change type) as the product of tech research, player ordered morphs, mergings and upgrades.\n",
    "\n",
    "All these changes are registered by the `UnitTypeChangeEvent` and each unit's `type_history` attribute.\n",
    "\n",
    "The following code lists two of player 1's GateWays, transformed into WarpGates via tech research."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Name: Gateway ID: 58195969\n",
      "Name: WarpGate ID: 58195969\n",
      "Name: Gateway ID: 57671681\n",
      "Name: WarpGate ID: 57671681\n"
     ]
    }
   ],
   "source": [
    "prototype = [(event.second, event.unit.type_history, event.unit_id)\r\n",
    "            for event in single_replay.events \r\n",
    "            if isinstance(event, sc2reader.events.tracker.UnitTypeChangeEvent)\r\n",
    "            and event.unit.owner.pid == 1]\r\n",
    "\r\n",
    "for unit in prototype:\r\n",
    "    for stage in unit[1].values():\r\n",
    "        print(f'Name: {stage.name} ID: {unit[2]}')\r\n",
    "    "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Meanwhile, in the following code, I show how one of Player 2's SiegeTanks changes back and forth between two states (i.e. SiegeTank and SiegeTankSieged). In contrast to the previous example, this change results from a player's direct command and can be reversed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Name: SiegeTank ID: 67633153\n",
      "Name: SiegeTankSieged ID: 67633153\n",
      "Name: SiegeTank ID: 67633153\n",
      "Name: SiegeTankSieged ID: 67633153\n",
      "Name: SiegeTank ID: 67633153\n",
      "Name: SiegeTankSieged ID: 67633153\n",
      "Name: SiegeTank ID: 67633153\n",
      "Name: SiegeTankSieged ID: 67633153\n"
     ]
    }
   ],
   "source": [
    "prototype_2 = [(event.second, event.unit.type_history, event.unit_id) \r\n",
    "            for event in single_replay.events \r\n",
    "            if isinstance(event, sc2reader.events.tracker.UnitTypeChangeEvent)\r\n",
    "            and event.unit.owner.pid == 2 \r\n",
    "            and 'SiegeTank' in event.unit_type_name]\r\n",
    "\r\n",
    "\r\n",
    "for unit in prototype_2[:1]:\r\n",
    "    for stage in unit[1].values():\r\n",
    "        print(f'Name: {stage.name} ID: {unit[2]}')\r\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### UnitDiedEvent\n",
    "\n",
    "These events are generated when units are taken off the match for any reason.\n",
    "\n",
    "Since `UnitDiedEvents` can be triggered when a unit is morphed, merged or exhausted, it is important not to assume that every kill results from an opponent's actions.\n",
    "\n",
    "Thus, in this case, I will use the following attributes:\n",
    "\n",
    "- `second` (int): registered time of birth in seconds. This attribute requires the same consideration as in the previous cases. (see `calc_realtime_index` function)\n",
    "- `killer_pid` (int): player id for the player who destroys a unit. This attribute can be a significant component to build a player kill list.\n",
    "- `unit` (unit)\n",
    "\n",
    "The following code lists the units killed by Player 1 in the sample replay."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Player 1 kill list:\n",
      "{0: 'second: 304 unit: SCV              owner: 2 killer: 1',\n",
      " 1: 'second: 608 unit: Hellion          owner: 2 killer: 1',\n",
      " 2: 'second: 617 unit: Hellion          owner: 2 killer: 1',\n",
      " 3: 'second: 687 unit: BattleHellion    owner: 2 killer: 1',\n",
      " 4: 'second: 703 unit: BattleHellion    owner: 2 killer: 1',\n",
      " 5: 'second: 723 unit: SiegeTankSieged  owner: 2 killer: 1',\n",
      " 6: 'second: 769 unit: BattleHellion    owner: 2 killer: 1',\n",
      " 7: 'second: 781 unit: Hellion          owner: 2 killer: 1',\n",
      " 8: 'second: 790 unit: BattleHellion    owner: 2 killer: 1'}\n"
     ]
    }
   ],
   "source": [
    "UnitDied_e = [event for event in single_replay.events \r\n",
    "              if isinstance(event, sc2reader.events.tracker.UnitDiedEvent)\r\n",
    "             and event.killer_pid == 1 \r\n",
    "             and event.unit.owner != None\r\n",
    "             and event.unit.owner.pid == 2]\r\n",
    "\r\n",
    "kill_list = {k:(f'second: {event.second} ' \r\n",
    "                + f'unit: {event.unit.name:<16} ' \r\n",
    "                + f'owner: {event.unit.owner.pid} ' \r\n",
    "                + f'killer: {event.killer_pid}') \r\n",
    "            for k, event in enumerate(UnitDied_e)}\r\n",
    "\r\n",
    "print('Player 1 kill list:')\r\n",
    "pprint(kill_list)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### UnitPositionEvent\n",
    "\n",
    "This events are generated every 15 seconds and they record \"the positions of the first 255 units that were damaged in the last interval\" [(Kim, 2015, p. 22)](https://sc2reader.readthedocs.io/en/latest/events/index.html).\n",
    "\n",
    "This events can be usefull to infer skirmishes during a match. However, I am not going to consider them into my analysis. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Module Exports"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Exportable constants\n",
    "\n",
    "Additionally, this module exports a constant `INTERVALS_BASE` which defines the number of seconds that should determine the time intervals used to analyse the replays.\n",
    "\n",
    "In the following modules, I separate the analysis of many performance indicators derived from several types of Tracker Events into four game intervals, i.e. the whole, early, mid and late games. These intervals are meant to match the economy and initial strategy building portion of the game (i.e. the early game), the initial strategy execution and response state (i.e. the mid-game), and the counter strategic stage of the game (i.e. the late-game).  The early match takes typically between 4 and 5 minutes, or 240 and 300 seconds. Afterwards, the mid-game takes about the same time. Suppose the game has not ended by minutes 8 to 10. In that case, players typically re-organise their strategy using updated, more advanced and expensive, units, i.e. late game.\n",
    "\n",
    "Thus, in this case, I establish a base value in seconds that I use in later modules as the finish time for the early game. I also use it to calculate the end mark of the mid-game as double this base value. The late-game always covers the portion from the mid-game's end to the match's end.\n",
    "\n",
    "I establish this constant here in case I need to change it. This way, any change will automatically be propagated through all modules."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#export\r\n",
    "INTERVALS_BASE = 4*60"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Exportable Functions\n",
    "\n",
    "Similarly, I export the `calc_realtime_index` function. I use this function in later modules to recalculate the time when an event took place in seconds to match the game's recorded length.\n",
    "\n",
    "This recalculation is necessary because Tracker Events seem to record the time they happened as the quotient of their recorded execution frame and the match's frames-per-second, which does not match its duration,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#export\r\n",
    "\r\n",
    "def calc_realtime_index(registered_time: int,\r\n",
    "                        rpl: sc2reader.resources.Replay) -> float:\r\n",
    "    \"\"\"Calculate the time index of an event based on the replay recorded\r\n",
    "    duration.\r\n",
    "\r\n",
    "    Given that the registered time index on TrackerEvents don not necessarily\r\n",
    "    coincide with the replay duration, this function recalculates the time\r\n",
    "    index of an event to correct this discrepancy.\r\n",
    "\r\n",
    "    *Args*\r\n",
    "        - registered_time (int)\r\n",
    "            The time index in seconds recorded in the event. Normally\r\n",
    "            accessible through the .second attribute.\r\n",
    "        - rpl (sc2reader.resources.Replay)\r\n",
    "            Working replay\r\n",
    "\r\n",
    "    *Returns*\r\n",
    "        - float\r\n",
    "            The time index that would match the replay's duration\r\n",
    "    \"\"\"\r\n",
    "    rpl_length = rpl.length.seconds\r\n",
    "    rpl_last_rec_time = [e.second for e in rpl.events\r\n",
    "                        if isinstance(e,\r\n",
    "                        sc2reader.events.tracker.PlayerStatsEvent)][-1]\r\n",
    "\r\n",
    "    return (registered_time/rpl_last_rec_time) * rpl_length"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following code illustrates the use of this function to correct the time index of various `UnitBornEvent`. The function should work just as well with all `TrakerEvents`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Unit:    Probe Birth recorded time:     0 Birth real time:     0.00\n",
      "Unit:    Probe Birth recorded time:    18 Birth real time:    12.86\n",
      "Unit:    Probe Birth recorded time:   820 Birth real time:   585.71\n",
      "Unit: FinalFrame Birth recorded time:   826 Birth real time:  590.00\n"
     ]
    }
   ],
   "source": [
    "first_e = UnitBorn_e[27]\r\n",
    "second_e = UnitBorn_e[28]\r\n",
    "last_e = UnitBorn_e[-1]\r\n",
    "\r\n",
    "print(f'Unit: {first_e.unit.name:>8}', \r\n",
    "    f'Birth recorded time: {first_e.second:>5}', \r\n",
    "    f'Birth real time: ', \r\n",
    "    f'{calc_realtime_index(first_e.second, single_replay):>7.2f}')\r\n",
    "\r\n",
    "print(f'Unit: {second_e.unit.name:>8}', \r\n",
    "    f'Birth recorded time: {second_e.second:>5}', \r\n",
    "    f'Birth real time: ', \r\n",
    "    f'{calc_realtime_index(second_e.second, single_replay):>7.2f}')\r\n",
    "\r\n",
    "print(f'Unit: {last_e.unit.name:>8}', \r\n",
    "    f'Birth recorded time: {last_e.second:>5}', \r\n",
    "    f'Birth real time: ', \r\n",
    "    f'{calc_realtime_index(last_e.second, single_replay):>7.2f}')\r\n",
    "\r\n",
    "print(f'Unit: {\"FinalFrame\":>8}', \r\n",
    "    f'Birth recorded time: {826:>5}', \r\n",
    "    f'Birth real time: {calc_realtime_index(826, single_replay):>7.2f}')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## References\n",
    "\n",
    "- Kim, G. (2015) 'sc2reader Documentation'. Available at: https://sc2reader.readthedocs.io/_/downloads/en/latest/pdf/."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Converted 00_Comp_model.ipynb.\n",
      "Converted 01_01_ingest_and_clustering.ipynb.\n",
      "Converted 01_summarise_rpl.ipynb.\n",
      "Converted 02_handle_tracker_events.ipynb.\n",
      "Converted 03_macro_econ_parser.ipynb.\n",
      "Converted 04_build_parser.ipynb.\n",
      "Converted 05_handle_command_events.ipynb.\n",
      "Converted 06_selection_parser.ipynb.\n",
      "Converted 07_ingest.ipynb.\n",
      "Converted 08_profiler.ipynb.\n",
      "Converted index.ipynb.\n"
     ]
    }
   ],
   "source": [
    "#hide\r\n",
    "from nbdev.export import notebook2script\r\n",
    "notebook2script()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3.9.7 64-bit ('sctraining_env': conda)",
   "name": "python3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}