docs/notebooks/flowkit-tutorial-part03-gating-strategy-and-gating-results-classes.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# FlowKit Tutorial - Part 3 - The `GatingStrategy` & `GatingResults` Classes\n",
    "\n",
    "https://flowkit.readthedocs.io/en/latest/?badge=latest\n",
    "\n",
    "So far, we've seen how to load FCS files using the Sample class and perform basic pre-processing like compensation and transformation for better visualization of event data. In part 3, we will explore using FlowKit for gating Sample event data using the `GatingStrategy` and `GatingResults` classes.\n",
    "\n",
    "If you have any questions about FlowKit, find any bugs, or feel something is missing from these tutorials [please submit an issue to the GitHub repository here](https://github.com/whitews/FlowKit/issues/new/).\n",
    "\n",
    "## Table of Contents\n",
    "\n",
    "* [GatingStrategy Class](#GatingStrategy-Class)\n",
    "  * [The Gate ID Concept](#The-Gate-ID-Concept)\n",
    "  * [Create a GatingStrategy from GatingML Document](#Create-a-GatingStrategy-from-GatingML-Document)\n",
    "    * [Retrieve the Gate Hierarchy](#Retrieve-the-Gate-Hierarchy)\n",
    "    * [Export Gate Hierarchy as Image](#Export-Gate-Hierarchy-as-Image)\n",
    "    * [Retrieve Gate IDs](#Retrieve-Gate-IDs)\n",
    "    * [Retrieve Gate Instances](#Retrieve-Gate-Instances)\n",
    "    * [Retrieve Compensation Matrices](#Retrieve-Compensation-Matrices)\n",
    "    * [Retrieve Transformations](#Retrieve-Transformations)\n",
    "* [GatingResults Class](#GatingResults-Class)\n",
    "  * [GatingResults Report](#GatingResults-Report)\n",
    "* [Next Tutorial - Manually Creating Gating Strategies](#Manually-Creating-Gating-Strategies)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "    <style>\n",
       "        .bk-notebook-logo {\n",
       "            display: block;\n",
       "            width: 20px;\n",
       "            height: 20px;\n",
       "            background-image: url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAAUCAYAAACNiR0NAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAALEgAACxIB0t1+/AAAABx0RVh0U29mdHdhcmUAQWRvYmUgRmlyZXdvcmtzIENTNui8sowAAAOkSURBVDiNjZRtaJVlGMd/1/08zzln5zjP1LWcU9N0NkN8m2CYjpgQYQXqSs0I84OLIC0hkEKoPtiH3gmKoiJDU7QpLgoLjLIQCpEsNJ1vqUOdO7ppbuec5+V+rj4ctwzd8IIbbi6u+8f1539dt3A78eXC7QizUF7gyV1fD1Yqg4JWz84yffhm0qkFqBogB9rM8tZdtwVsPUhWhGcFJngGeWrPzHm5oaMmkfEg1usvLFyc8jLRqDOMru7AyC8saQr7GG7f5fvDeH7Ej8CM66nIF+8yngt6HWaKh7k49Soy9nXurCi1o3qUbS3zWfrYeQDTB/Qj6kX6Ybhw4B+bOYoLKCC9H3Nu/leUTZ1JdRWkkn2ldcCamzrcf47KKXdAJllSlxAOkRgyHsGC/zRday5Qld9DyoM4/q/rUoy/CXh3jzOu3bHUVZeU+DEn8FInkPBFlu3+nW3Nw0mk6vCDiWg8CeJaxEwuHS3+z5RgY+YBR6V1Z1nxSOfoaPa4LASWxxdNp+VWTk7+4vzaou8v8PN+xo+KY2xsw6une2frhw05CTYOmQvsEhjhWjn0bmXPjpE1+kplmmkP3suftwTubK9Vq22qKmrBhpY4jvd5afdRA3wGjFAgcnTK2s4hY0/GPNIb0nErGMCRxWOOX64Z8RAC4oCXdklmEvcL8o0BfkNK4lUg9HTl+oPlQxdNo3Mg4Nv175e/1LDGzZen30MEjRUtmXSfiTVu1kK8W4txyV6BMKlbgk3lMwYCiusNy9fVfvvwMxv8Ynl6vxoByANLTWplvuj/nF9m2+PDtt1eiHPBr1oIfhCChQMBw6Aw0UulqTKZdfVvfG7VcfIqLG9bcldL/+pdWTLxLUy8Qq38heUIjh4XlzZxzQm19lLFlr8vdQ97rjZVOLf8nclzckbcD4wxXMidpX30sFd37Fv/GtwwhzhxGVAprjbg0gCAEeIgwCZyTV2Z1REEW8O4py0wsjeloKoMr6iCY6dP92H6Vw/oTyICIthibxjm/DfN9lVz8IqtqKYLUXfoKVMVQVVJOElGjrnnUt9T9wbgp8AyYKaGlqingHZU/uG2NTZSVqwHQTWkx9hxjkpWDaCg6Ckj5qebgBVbT3V3NNXMSiWSDdGV3hrtzla7J+duwPOToIg42ChPQOQjspnSlp1V+Gjdged7+8UN5CRAV7a5EdFNwCjEaBR27b3W890TE7g24NAP/mMDXRWrGoFPQI9ls/MWO2dWFAar/xcOIImbbpA3zgAAAABJRU5ErkJggg==);\n",
       "        }\n",
       "    </style>\n",
       "    <div>\n",
       "        <a href=\"https://bokeh.org\" target=\"_blank\" class=\"bk-notebook-logo\"></a>\n",
       "        <span id=\"aee87c26-a4ee-417b-ac2b-e31aaa4c975f\">Loading BokehJS ...</span>\n",
       "    </div>\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "application/javascript": [
       "'use strict';\n",
       "(function(root) {\n",
       "  function now() {\n",
       "    return new Date();\n",
       "  }\n",
       "\n",
       "  const force = true;\n",
       "\n",
       "  if (typeof root._bokeh_onload_callbacks === \"undefined\" || force === true) {\n",
       "    root._bokeh_onload_callbacks = [];\n",
       "    root._bokeh_is_loading = undefined;\n",
       "  }\n",
       "\n",
       "const JS_MIME_TYPE = 'application/javascript';\n",
       "  const HTML_MIME_TYPE = 'text/html';\n",
       "  const EXEC_MIME_TYPE = 'application/vnd.bokehjs_exec.v0+json';\n",
       "  const CLASS_NAME = 'output_bokeh rendered_html';\n",
       "\n",
       "  /**\n",
       "   * Render data to the DOM node\n",
       "   */\n",
       "  function render(props, node) {\n",
       "    const script = document.createElement(\"script\");\n",
       "    node.appendChild(script);\n",
       "  }\n",
       "\n",
       "  /**\n",
       "   * Handle when an output is cleared or removed\n",
       "   */\n",
       "  function handleClearOutput(event, handle) {\n",
       "    function drop(id) {\n",
       "      const view = Bokeh.index.get_by_id(id)\n",
       "      if (view != null) {\n",
       "        view.model.document.clear()\n",
       "        Bokeh.index.delete(view)\n",
       "      }\n",
       "    }\n",
       "\n",
       "    const cell = handle.cell;\n",
       "\n",
       "    const id = cell.output_area._bokeh_element_id;\n",
       "    const server_id = cell.output_area._bokeh_server_id;\n",
       "\n",
       "    // Clean up Bokeh references\n",
       "    if (id != null) {\n",
       "      drop(id)\n",
       "    }\n",
       "\n",
       "    if (server_id !== undefined) {\n",
       "      // Clean up Bokeh references\n",
       "      const cmd_clean = \"from bokeh.io.state import curstate; print(curstate().uuid_to_server['\" + server_id + \"'].get_sessions()[0].document.roots[0]._id)\";\n",
       "      cell.notebook.kernel.execute(cmd_clean, {\n",
       "        iopub: {\n",
       "          output: function(msg) {\n",
       "            const id = msg.content.text.trim()\n",
       "            drop(id)\n",
       "          }\n",
       "        }\n",
       "      });\n",
       "      // Destroy server and session\n",
       "      const cmd_destroy = \"import bokeh.io.notebook as ion; ion.destroy_server('\" + server_id + \"')\";\n",
       "      cell.notebook.kernel.execute(cmd_destroy);\n",
       "    }\n",
       "  }\n",
       "\n",
       "  /**\n",
       "   * Handle when a new output is added\n",
       "   */\n",
       "  function handleAddOutput(event, handle) {\n",
       "    const output_area = handle.output_area;\n",
       "    const output = handle.output;\n",
       "\n",
       "    // limit handleAddOutput to display_data with EXEC_MIME_TYPE content only\n",
       "    if ((output.output_type != \"display_data\") || (!Object.prototype.hasOwnProperty.call(output.data, EXEC_MIME_TYPE))) {\n",
       "      return\n",
       "    }\n",
       "\n",
       "    const toinsert = output_area.element.find(\".\" + CLASS_NAME.split(' ')[0]);\n",
       "\n",
       "    if (output.metadata[EXEC_MIME_TYPE][\"id\"] !== undefined) {\n",
       "      toinsert[toinsert.length - 1].firstChild.textContent = output.data[JS_MIME_TYPE];\n",
       "      // store reference to embed id on output_area\n",
       "      output_area._bokeh_element_id = output.metadata[EXEC_MIME_TYPE][\"id\"];\n",
       "    }\n",
       "    if (output.metadata[EXEC_MIME_TYPE][\"server_id\"] !== undefined) {\n",
       "      const bk_div = document.createElement(\"div\");\n",
       "      bk_div.innerHTML = output.data[HTML_MIME_TYPE];\n",
       "      const script_attrs = bk_div.children[0].attributes;\n",
       "      for (let i = 0; i < script_attrs.length; i++) {\n",
       "        toinsert[toinsert.length - 1].firstChild.setAttribute(script_attrs[i].name, script_attrs[i].value);\n",
       "        toinsert[toinsert.length - 1].firstChild.textContent = bk_div.children[0].textContent\n",
       "      }\n",
       "      // store reference to server id on output_area\n",
       "      output_area._bokeh_server_id = output.metadata[EXEC_MIME_TYPE][\"server_id\"];\n",
       "    }\n",
       "  }\n",
       "\n",
       "  function register_renderer(events, OutputArea) {\n",
       "\n",
       "    function append_mime(data, metadata, element) {\n",
       "      // create a DOM node to render to\n",
       "      const toinsert = this.create_output_subarea(\n",
       "        metadata,\n",
       "        CLASS_NAME,\n",
       "        EXEC_MIME_TYPE\n",
       "      );\n",
       "      this.keyboard_manager.register_events(toinsert);\n",
       "      // Render to node\n",
       "      const props = {data: data, metadata: metadata[EXEC_MIME_TYPE]};\n",
       "      render(props, toinsert[toinsert.length - 1]);\n",
       "      element.append(toinsert);\n",
       "      return toinsert\n",
       "    }\n",
       "\n",
       "    /* Handle when an output is cleared or removed */\n",
       "    events.on('clear_output.CodeCell', handleClearOutput);\n",
       "    events.on('delete.Cell', handleClearOutput);\n",
       "\n",
       "    /* Handle when a new output is added */\n",
       "    events.on('output_added.OutputArea', handleAddOutput);\n",
       "\n",
       "    /**\n",
       "     * Register the mime type and append_mime function with output_area\n",
       "     */\n",
       "    OutputArea.prototype.register_mime_type(EXEC_MIME_TYPE, append_mime, {\n",
       "      /* Is output safe? */\n",
       "      safe: true,\n",
       "      /* Index of renderer in `output_area.display_order` */\n",
       "      index: 0\n",
       "    });\n",
       "  }\n",
       "\n",
       "  // register the mime type if in Jupyter Notebook environment and previously unregistered\n",
       "  if (root.Jupyter !== undefined) {\n",
       "    const events = require('base/js/events');\n",
       "    const OutputArea = require('notebook/js/outputarea').OutputArea;\n",
       "\n",
       "    if (OutputArea.prototype.mime_types().indexOf(EXEC_MIME_TYPE) == -1) {\n",
       "      register_renderer(events, OutputArea);\n",
       "    }\n",
       "  }\n",
       "  if (typeof (root._bokeh_timeout) === \"undefined\" || force === true) {\n",
       "    root._bokeh_timeout = Date.now() + 5000;\n",
       "    root._bokeh_failed_load = false;\n",
       "  }\n",
       "\n",
       "  const NB_LOAD_WARNING = {'data': {'text/html':\n",
       "     \"<div style='background-color: #fdd'>\\n\"+\n",
       "     \"<p>\\n\"+\n",
       "     \"BokehJS does not appear to have successfully loaded. If loading BokehJS from CDN, this \\n\"+\n",
       "     \"may be due to a slow or bad network connection. Possible fixes:\\n\"+\n",
       "     \"</p>\\n\"+\n",
       "     \"<ul>\\n\"+\n",
       "     \"<li>re-rerun `output_notebook()` to attempt to load from CDN again, or</li>\\n\"+\n",
       "     \"<li>use INLINE resources instead, as so:</li>\\n\"+\n",
       "     \"</ul>\\n\"+\n",
       "     \"<code>\\n\"+\n",
       "     \"from bokeh.resources import INLINE\\n\"+\n",
       "     \"output_notebook(resources=INLINE)\\n\"+\n",
       "     \"</code>\\n\"+\n",
       "     \"</div>\"}};\n",
       "\n",
       "  function display_loaded(error = null) {\n",
       "    const el = document.getElementById(\"aee87c26-a4ee-417b-ac2b-e31aaa4c975f\");\n",
       "    if (el != null) {\n",
       "      const html = (() => {\n",
       "        if (typeof root.Bokeh === \"undefined\") {\n",
       "          if (error == null) {\n",
       "            return \"BokehJS is loading ...\";\n",
       "          } else {\n",
       "            return \"BokehJS failed to load.\";\n",
       "          }\n",
       "        } else {\n",
       "          const prefix = `BokehJS ${root.Bokeh.version}`;\n",
       "          if (error == null) {\n",
       "            return `${prefix} successfully loaded.`;\n",
       "          } else {\n",
       "            return `${prefix} <b>encountered errors</b> while loading and may not function as expected.`;\n",
       "          }\n",
       "        }\n",
       "      })();\n",
       "      el.innerHTML = html;\n",
       "\n",
       "      if (error != null) {\n",
       "        const wrapper = document.createElement(\"div\");\n",
       "        wrapper.style.overflow = \"auto\";\n",
       "        wrapper.style.height = \"5em\";\n",
       "        wrapper.style.resize = \"vertical\";\n",
       "        const content = document.createElement(\"div\");\n",
       "        content.style.fontFamily = \"monospace\";\n",
       "        content.style.whiteSpace = \"pre-wrap\";\n",
       "        content.style.backgroundColor = \"rgb(255, 221, 221)\";\n",
       "        content.textContent = error.stack ?? error.toString();\n",
       "        wrapper.append(content);\n",
       "        el.append(wrapper);\n",
       "      }\n",
       "    } else if (Date.now() < root._bokeh_timeout) {\n",
       "      setTimeout(() => display_loaded(error), 100);\n",
       "    }\n",
       "  }\n",
       "\n",
       "  function run_callbacks() {\n",
       "    try {\n",
       "      root._bokeh_onload_callbacks.forEach(function(callback) {\n",
       "        if (callback != null)\n",
       "          callback();\n",
       "      });\n",
       "    } finally {\n",
       "      delete root._bokeh_onload_callbacks\n",
       "    }\n",
       "    console.debug(\"Bokeh: all callbacks have finished\");\n",
       "  }\n",
       "\n",
       "  function load_libs(css_urls, js_urls, callback) {\n",
       "    if (css_urls == null) css_urls = [];\n",
       "    if (js_urls == null) js_urls = [];\n",
       "\n",
       "    root._bokeh_onload_callbacks.push(callback);\n",
       "    if (root._bokeh_is_loading > 0) {\n",
       "      console.debug(\"Bokeh: BokehJS is being loaded, scheduling callback at\", now());\n",
       "      return null;\n",
       "    }\n",
       "    if (js_urls == null || js_urls.length === 0) {\n",
       "      run_callbacks();\n",
       "      return null;\n",
       "    }\n",
       "    console.debug(\"Bokeh: BokehJS not loaded, scheduling load and callback at\", now());\n",
       "    root._bokeh_is_loading = css_urls.length + js_urls.length;\n",
       "\n",
       "    function on_load() {\n",
       "      root._bokeh_is_loading--;\n",
       "      if (root._bokeh_is_loading === 0) {\n",
       "        console.debug(\"Bokeh: all BokehJS libraries/stylesheets loaded\");\n",
       "        run_callbacks()\n",
       "      }\n",
       "    }\n",
       "\n",
       "    function on_error(url) {\n",
       "      console.error(\"failed to load \" + url);\n",
       "    }\n",
       "\n",
       "    for (let i = 0; i < css_urls.length; i++) {\n",
       "      const url = css_urls[i];\n",
       "      const element = document.createElement(\"link\");\n",
       "      element.onload = on_load;\n",
       "      element.onerror = on_error.bind(null, url);\n",
       "      element.rel = \"stylesheet\";\n",
       "      element.type = \"text/css\";\n",
       "      element.href = url;\n",
       "      console.debug(\"Bokeh: injecting link tag for BokehJS stylesheet: \", url);\n",
       "      document.body.appendChild(element);\n",
       "    }\n",
       "\n",
       "    for (let i = 0; i < js_urls.length; i++) {\n",
       "      const url = js_urls[i];\n",
       "      const element = document.createElement('script');\n",
       "      element.onload = on_load;\n",
       "      element.onerror = on_error.bind(null, url);\n",
       "      element.async = false;\n",
       "      element.src = url;\n",
       "      console.debug(\"Bokeh: injecting script tag for BokehJS library: \", url);\n",
       "      document.head.appendChild(element);\n",
       "    }\n",
       "  };\n",
       "\n",
       "  function inject_raw_css(css) {\n",
       "    const element = document.createElement(\"style\");\n",
       "    element.appendChild(document.createTextNode(css));\n",
       "    document.body.appendChild(element);\n",
       "  }\n",
       "\n",
       "  const js_urls = [\"https://cdn.bokeh.org/bokeh/release/bokeh-3.6.0.min.js\", \"https://cdn.bokeh.org/bokeh/release/bokeh-gl-3.6.0.min.js\", \"https://cdn.bokeh.org/bokeh/release/bokeh-widgets-3.6.0.min.js\", \"https://cdn.bokeh.org/bokeh/release/bokeh-tables-3.6.0.min.js\", \"https://cdn.bokeh.org/bokeh/release/bokeh-mathjax-3.6.0.min.js\"];\n",
       "  const css_urls = [];\n",
       "\n",
       "  const inline_js = [    function(Bokeh) {\n",
       "      Bokeh.set_log_level(\"info\");\n",
       "    },\n",
       "function(Bokeh) {\n",
       "    }\n",
       "  ];\n",
       "\n",
       "  function run_inline_js() {\n",
       "    if (root.Bokeh !== undefined || force === true) {\n",
       "      try {\n",
       "            for (let i = 0; i < inline_js.length; i++) {\n",
       "      inline_js[i].call(root, root.Bokeh);\n",
       "    }\n",
       "\n",
       "      } catch (error) {display_loaded(error);throw error;\n",
       "      }if (force === true) {\n",
       "        display_loaded();\n",
       "      }} else if (Date.now() < root._bokeh_timeout) {\n",
       "      setTimeout(run_inline_js, 100);\n",
       "    } else if (!root._bokeh_failed_load) {\n",
       "      console.log(\"Bokeh: BokehJS failed to load within specified timeout.\");\n",
       "      root._bokeh_failed_load = true;\n",
       "    } else if (force !== true) {\n",
       "      const cell = $(document.getElementById(\"aee87c26-a4ee-417b-ac2b-e31aaa4c975f\")).parents('.cell').data().cell;\n",
       "      cell.output_area.append_execute_result(NB_LOAD_WARNING)\n",
       "    }\n",
       "  }\n",
       "\n",
       "  if (root._bokeh_is_loading === 0) {\n",
       "    console.debug(\"Bokeh: BokehJS loaded, going straight to plotting\");\n",
       "    run_inline_js();\n",
       "  } else {\n",
       "    load_libs(css_urls, js_urls, function() {\n",
       "      console.debug(\"Bokeh: BokehJS plotting callback run at\", now());\n",
       "      run_inline_js();\n",
       "    });\n",
       "  }\n",
       "}(window));"
      ],
      "application/vnd.bokehjs_load.v0+json": "'use strict';\n(function(root) {\n  function now() {\n    return new Date();\n  }\n\n  const force = true;\n\n  if (typeof root._bokeh_onload_callbacks === \"undefined\" || force === true) {\n    root._bokeh_onload_callbacks = [];\n    root._bokeh_is_loading = undefined;\n  }\n\n\n  if (typeof (root._bokeh_timeout) === \"undefined\" || force === true) {\n    root._bokeh_timeout = Date.now() + 5000;\n    root._bokeh_failed_load = false;\n  }\n\n  const NB_LOAD_WARNING = {'data': {'text/html':\n     \"<div style='background-color: #fdd'>\\n\"+\n     \"<p>\\n\"+\n     \"BokehJS does not appear to have successfully loaded. If loading BokehJS from CDN, this \\n\"+\n     \"may be due to a slow or bad network connection. Possible fixes:\\n\"+\n     \"</p>\\n\"+\n     \"<ul>\\n\"+\n     \"<li>re-rerun `output_notebook()` to attempt to load from CDN again, or</li>\\n\"+\n     \"<li>use INLINE resources instead, as so:</li>\\n\"+\n     \"</ul>\\n\"+\n     \"<code>\\n\"+\n     \"from bokeh.resources import INLINE\\n\"+\n     \"output_notebook(resources=INLINE)\\n\"+\n     \"</code>\\n\"+\n     \"</div>\"}};\n\n  function display_loaded(error = null) {\n    const el = document.getElementById(\"aee87c26-a4ee-417b-ac2b-e31aaa4c975f\");\n    if (el != null) {\n      const html = (() => {\n        if (typeof root.Bokeh === \"undefined\") {\n          if (error == null) {\n            return \"BokehJS is loading ...\";\n          } else {\n            return \"BokehJS failed to load.\";\n          }\n        } else {\n          const prefix = `BokehJS ${root.Bokeh.version}`;\n          if (error == null) {\n            return `${prefix} successfully loaded.`;\n          } else {\n            return `${prefix} <b>encountered errors</b> while loading and may not function as expected.`;\n          }\n        }\n      })();\n      el.innerHTML = html;\n\n      if (error != null) {\n        const wrapper = document.createElement(\"div\");\n        wrapper.style.overflow = \"auto\";\n        wrapper.style.height = \"5em\";\n        wrapper.style.resize = \"vertical\";\n        const content = document.createElement(\"div\");\n        content.style.fontFamily = \"monospace\";\n        content.style.whiteSpace = \"pre-wrap\";\n        content.style.backgroundColor = \"rgb(255, 221, 221)\";\n        content.textContent = error.stack ?? error.toString();\n        wrapper.append(content);\n        el.append(wrapper);\n      }\n    } else if (Date.now() < root._bokeh_timeout) {\n      setTimeout(() => display_loaded(error), 100);\n    }\n  }\n\n  function run_callbacks() {\n    try {\n      root._bokeh_onload_callbacks.forEach(function(callback) {\n        if (callback != null)\n          callback();\n      });\n    } finally {\n      delete root._bokeh_onload_callbacks\n    }\n    console.debug(\"Bokeh: all callbacks have finished\");\n  }\n\n  function load_libs(css_urls, js_urls, callback) {\n    if (css_urls == null) css_urls = [];\n    if (js_urls == null) js_urls = [];\n\n    root._bokeh_onload_callbacks.push(callback);\n    if (root._bokeh_is_loading > 0) {\n      console.debug(\"Bokeh: BokehJS is being loaded, scheduling callback at\", now());\n      return null;\n    }\n    if (js_urls == null || js_urls.length === 0) {\n      run_callbacks();\n      return null;\n    }\n    console.debug(\"Bokeh: BokehJS not loaded, scheduling load and callback at\", now());\n    root._bokeh_is_loading = css_urls.length + js_urls.length;\n\n    function on_load() {\n      root._bokeh_is_loading--;\n      if (root._bokeh_is_loading === 0) {\n        console.debug(\"Bokeh: all BokehJS libraries/stylesheets loaded\");\n        run_callbacks()\n      }\n    }\n\n    function on_error(url) {\n      console.error(\"failed to load \" + url);\n    }\n\n    for (let i = 0; i < css_urls.length; i++) {\n      const url = css_urls[i];\n      const element = document.createElement(\"link\");\n      element.onload = on_load;\n      element.onerror = on_error.bind(null, url);\n      element.rel = \"stylesheet\";\n      element.type = \"text/css\";\n      element.href = url;\n      console.debug(\"Bokeh: injecting link tag for BokehJS stylesheet: \", url);\n      document.body.appendChild(element);\n    }\n\n    for (let i = 0; i < js_urls.length; i++) {\n      const url = js_urls[i];\n      const element = document.createElement('script');\n      element.onload = on_load;\n      element.onerror = on_error.bind(null, url);\n      element.async = false;\n      element.src = url;\n      console.debug(\"Bokeh: injecting script tag for BokehJS library: \", url);\n      document.head.appendChild(element);\n    }\n  };\n\n  function inject_raw_css(css) {\n    const element = document.createElement(\"style\");\n    element.appendChild(document.createTextNode(css));\n    document.body.appendChild(element);\n  }\n\n  const js_urls = [\"https://cdn.bokeh.org/bokeh/release/bokeh-3.6.0.min.js\", \"https://cdn.bokeh.org/bokeh/release/bokeh-gl-3.6.0.min.js\", \"https://cdn.bokeh.org/bokeh/release/bokeh-widgets-3.6.0.min.js\", \"https://cdn.bokeh.org/bokeh/release/bokeh-tables-3.6.0.min.js\", \"https://cdn.bokeh.org/bokeh/release/bokeh-mathjax-3.6.0.min.js\"];\n  const css_urls = [];\n\n  const inline_js = [    function(Bokeh) {\n      Bokeh.set_log_level(\"info\");\n    },\nfunction(Bokeh) {\n    }\n  ];\n\n  function run_inline_js() {\n    if (root.Bokeh !== undefined || force === true) {\n      try {\n            for (let i = 0; i < inline_js.length; i++) {\n      inline_js[i].call(root, root.Bokeh);\n    }\n\n      } catch (error) {display_loaded(error);throw error;\n      }if (force === true) {\n        display_loaded();\n      }} else if (Date.now() < root._bokeh_timeout) {\n      setTimeout(run_inline_js, 100);\n    } else if (!root._bokeh_failed_load) {\n      console.log(\"Bokeh: BokehJS failed to load within specified timeout.\");\n      root._bokeh_failed_load = true;\n    } else if (force !== true) {\n      const cell = $(document.getElementById(\"aee87c26-a4ee-417b-ac2b-e31aaa4c975f\")).parents('.cell').data().cell;\n      cell.output_area.append_execute_result(NB_LOAD_WARNING)\n    }\n  }\n\n  if (root._bokeh_is_loading === 0) {\n    console.debug(\"Bokeh: BokehJS loaded, going straight to plotting\");\n    run_inline_js();\n  } else {\n    load_libs(css_urls, js_urls, function() {\n      console.debug(\"Bokeh: BokehJS plotting callback run at\", now());\n      run_inline_js();\n    });\n  }\n}(window));"
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "import bokeh\n",
    "from bokeh.plotting import show\n",
    "from IPython.display import Image\n",
    "\n",
    "import flowkit as fk\n",
    "\n",
    "bokeh.io.output_notebook()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'1.2.0'"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# check version so users can verify they have the same version/API\n",
    "fk.__version__"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## GatingStrategy Class\n",
    "\n",
    "A GatingStrategy object represents a collection of hierarchical gates along with the compensation and transformation information referenced by any gate Dimension objects (covered in Part 4 of the tutorial series). A GatingStrategy can be created from a valid GatingML document or built programmatically. Methods in the GatingStrategy class fall in to 3 main categories: adding or removing gate-related objects, retrieving those objects, and applying the gating strategy to a Sample.\n",
    "\n",
    "This notebook demonstrates importing a GatingML gating strategy, applying it to an FCS file and covering the GatingResults class that is returned from that analysis.. Using the GatingStrategy class to programmatically create a gate hierarchy is covered in the next tutorial, where we will need to use more tools in the FlowKit package."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### The Gate ID Concept\n",
    "\n",
    "Quite a lot of thought has gone into the design of the GatingStrategy class in order to support the various ways gates are used and processed in typical FCM workflows. The most important concept to understand when interacting with a GatingStrategy instance is how gate IDs are used to reference gates and their position within the gating hierarchy. \n",
    "\n",
    "Gates are sometimes \"re-used\" in different branches of the hierarchy. For example, the same quadrant gate may be applied to each of the CD4+ and CD8+ populations. Because of this, the name of the gate is not sufficient to fully identify it. Simply coupling the gate name with its parent gate name can also be ambiguous if the nested gates are re-used.\n",
    "\n",
    "The GatingStrategy class solves this ambiguity by **defining a gate ID as a tuple combining the gate name and the full path of ancestor gate names**, similar in concept to a computer file system. However, this approach can be cumbersome for the common case where gates are not re-used. Therefore, referencing gates simply by their gate name string is allowed for cases where that name is not re-used within the gate hierarchy. For ambiguous cases, referencing a gate requires the full gate ID tuple of the gate name and gate path. \n",
    "\n",
    "We will see how this works in practice later, but for now let's create a GatingStrategy from an existing GatingML-2.0 document."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Create a GatingStrategy from GatingML Document"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "gml_path = '../../data/8_color_data_set/8_color_ICS.xml'\n",
    "g_strat = fk.parse_gating_xml(gml_path)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "GatingStrategy(6 gates, 3 transforms, 1 compensations)"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "g_strat"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The string representation reveals this GatingStrategy has 6 gates, 3 transforms, and 1 compensation (Matrix instance)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Retrieve the Gate Hierarchy\n",
    "\n",
    "We can retrieve the gate hierarchy in a variety of formats using the `get_gate_hiearchy` method. The method takes the following `output` options:\n",
    "\n",
    "* `ascii`: Generates a text-based representation of the gate tree, and is the most human-readable format for reviewing the hierarchy. This is the default option.\n",
    "* `json`: Generates a JSON representation of the gate tree, useful for programmatic parsing, especially outside of Python. When this option is used, all extra keywords are passed to `json.dumps` (e.g. `indent=2` works to indent the output).\n",
    "* `dict`: Generates a Python dictionary representation of the gate tree, useful for programmatic parsing within Python."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "text = g_strat.get_gate_hierarchy(output='ascii')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "root\n",
      "╰── TimeGate\n",
      "    ╰── Singlets\n",
      "        ╰── aAmine-\n",
      "            ╰── CD3-pos\n",
      "                ├── CD4-pos\n",
      "                ╰── CD8-pos\n"
     ]
    }
   ],
   "source": [
    "print(text)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "gs_json = g_strat.get_gate_hierarchy(output='json', indent=2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{\n",
      "  \"name\": \"root\",\n",
      "  \"children\": [\n",
      "    {\n",
      "      \"gate_type\": \"RectangleGate\",\n",
      "      \"custom_gates\": {},\n",
      "      \"name\": \"TimeGate\",\n",
      "      \"children\": [\n",
      "        {\n",
      "          \"gate_type\": \"PolygonGate\",\n",
      "          \"custom_gates\": {},\n",
      "          \"name\": \"Singlets\",\n",
      "          \"children\": [\n",
      "            {\n",
      "              \"gate_type\": \"PolygonGate\",\n",
      "              \"custom_gates\": {},\n",
      "              \"name\": \"aAmine-\",\n",
      "              \"children\": [\n",
      "                {\n",
      "                  \"gate_type\": \"PolygonGate\",\n",
      "                  \"custom_gates\": {},\n",
      "                  \"name\": \"CD3-pos\",\n",
      "                  \"children\": [\n",
      "                    {\n",
      "                      \"gate_type\": \"PolygonGate\",\n",
      "                      \"custom_gates\": {},\n",
      "                      \"name\": \"CD4-pos\"\n",
      "                    },\n",
      "                    {\n",
      "                      \"gate_type\": \"PolygonGate\",\n",
      "                      \"custom_gates\": {},\n",
      "                      \"name\": \"CD8-pos\"\n",
      "                    }\n",
      "                  ]\n",
      "                }\n",
      "              ]\n",
      "            }\n",
      "          ]\n",
      "        }\n",
      "      ]\n",
      "    }\n",
      "  ]\n",
      "}\n"
     ]
    }
   ],
   "source": [
    "print(gs_json)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "gs_dict = g_strat.get_gate_hierarchy(output='dict')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'name': 'root',\n",
       " 'children': [{'gate': RectangleGate(TimeGate, dims: 2),\n",
       "   'gate_type': 'RectangleGate',\n",
       "   'custom_gates': {},\n",
       "   'name': 'TimeGate',\n",
       "   'children': [{'gate': PolygonGate(Singlets, vertices: 8),\n",
       "     'gate_type': 'PolygonGate',\n",
       "     'custom_gates': {},\n",
       "     'name': 'Singlets',\n",
       "     'children': [{'gate': PolygonGate(aAmine-, vertices: 10),\n",
       "       'gate_type': 'PolygonGate',\n",
       "       'custom_gates': {},\n",
       "       'name': 'aAmine-',\n",
       "       'children': [{'gate': PolygonGate(CD3-pos, vertices: 8),\n",
       "         'gate_type': 'PolygonGate',\n",
       "         'custom_gates': {},\n",
       "         'name': 'CD3-pos',\n",
       "         'children': [{'gate': PolygonGate(CD4-pos, vertices: 12),\n",
       "           'gate_type': 'PolygonGate',\n",
       "           'custom_gates': {},\n",
       "           'name': 'CD4-pos'},\n",
       "          {'gate': PolygonGate(CD8-pos, vertices: 6),\n",
       "           'gate_type': 'PolygonGate',\n",
       "           'custom_gates': {},\n",
       "           'name': 'CD8-pos'}]}]}]}]}]}"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "gs_dict"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Export Gate Hierarchy as Image\n",
    "\n",
    "The gate hierarchy can also be exported as an image. \n",
    "\n",
    "**Note: The graphviz package must be installed (see https://graphviz.org/download/)**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "g_strat.export_gate_hierarchy_image('gs.png')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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",
      "text/plain": [
       "<IPython.core.display.Image object>"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Image('gs.png')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Retrieve Gate IDs \n",
    "\n",
    "Remember, a gate ID is a tuple of the gate name and the gate path. We can retrieve all the gate IDs using `get_gate_ids`. There are also convenience methods to get a parent gate ID or child gate IDs from a gate ID. If the gate name of a gate ID is unambiguous, the gate path can be omitted."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[('TimeGate', ('root',)),\n",
       " ('Singlets', ('root', 'TimeGate')),\n",
       " ('aAmine-', ('root', 'TimeGate', 'Singlets')),\n",
       " ('CD3-pos', ('root', 'TimeGate', 'Singlets', 'aAmine-')),\n",
       " ('CD4-pos', ('root', 'TimeGate', 'Singlets', 'aAmine-', 'CD3-pos')),\n",
       " ('CD8-pos', ('root', 'TimeGate', 'Singlets', 'aAmine-', 'CD3-pos'))]"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "g_strat.get_gate_ids()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "('aAmine-', ('root', 'TimeGate', 'Singlets'))"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "g_strat.get_parent_gate_id('CD3-pos')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[('CD4-pos', ('root', 'TimeGate', 'Singlets', 'aAmine-', 'CD3-pos')),\n",
       " ('CD8-pos', ('root', 'TimeGate', 'Singlets', 'aAmine-', 'CD3-pos'))]"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "g_strat.get_child_gate_ids('CD3-pos')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are a few other convenience methods for programatically traversing the gate tree to retrieve gate IDs."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Retrieve Gate Instances\n",
    "\n",
    "Below we demonstrate how to retrieve a Gate instance by its gate name, which works here because the name is unambigious within this gate hierarchy."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "PolygonGate(Singlets, vertices: 8)"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "g_strat.get_gate('Singlets')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[RectangleGate(TimeGate, dims: 2)]"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Get the list of gates at the root level\n",
    "g_strat.get_root_gates()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Before we move on, there is another feature of the GatingStrategy that is important to cover: custom sample gates. Users of cytometry software with a graphical user interface (e.g. FlowJo) know that sometimes a gate's boundaries need tweaking for a particular sample. The GatingStrategy supports adding such custom gates by adding a gate with a Sample ID. \n",
    "\n",
    "The next tutorial will demonstrate its usage, but let's look at the docstring for the `add_gate` method to get an idea of how it works. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on function add_gate in module flowkit._models.gating_strategy:\n",
      "\n",
      "add_gate(self, gate, gate_path, sample_id=None)\n",
      "    Add a gate to the gating strategy, see `gates` module. The gate ID and gate path\n",
      "    must be unique in the gating strategy. Custom sample gates may be added by specifying\n",
      "    an optional sample ID. Note, the gate & gate path must already exist prior to adding\n",
      "    custom sample gates.\n",
      "    \n",
      "    :param gate: instance from a subclass of the Gate class\n",
      "    :param gate_path: complete ordered tuple of gate names for unique set of gate ancestors\n",
      "    :param sample_id: text string for specifying given gate as a custom Sample gate\n",
      "    \n",
      "    :return: None\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(fk.GatingStrategy.add_gate)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Retrieve Compensation Matrices\n",
    "\n",
    "Compensation matrixes identified within the GatingStrategy by an ID. The `comp_matrices` attribute returns a dictionary where the IDs are the keys and the values are the Matrix instances."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'Acquisition-defined': Matrix(dims: 8)}"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "g_strat.comp_matrices"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Retrieve Transformations\n",
    "\n",
    "Retrieving tranformations works in a similar way as the compensation matrices. The `transformations` attribute returns a dictionary of ID keys and transformation instances>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'scatter-lin': LinearTransform(t: 262144.0, a: 0.0),\n",
       " 'logicle-default': LogicleTransform(t: 262144.0, w: 1.0, m: 4.418539922, a: 0.0),\n",
       " 'Time': LinearTransform(t: 72.0, a: 0.8511997311)}"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "g_strat.transformations"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## GatingResults Class\n",
    "\n",
    "The `gate_sample` method is used to apply a GatingStrategy to a FCS file. This method returns GatingResults instance. A GatingResults instance contains the results of applying the gating hierarchy on a single Sample. Note, a GatingResults instance is never created by the end user directly, it is only returned from applying a GatingStrategy, Session, or Workspace on a Sample (more on the Session and Workspace classes in the upcoming tutorials).\n",
    "\n",
    "Let's load a Sample and apply the previous GatingStrategy via the `gate_sample` method (setting `verbose=True` to print out each gate as it is processed)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [],
   "source": [
    "sample = fk.Sample(\"../../data/8_color_data_set/fcs_files/101_DEN084Y5_15_E01_008_clean.fcs\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "101_DEN084Y5_15_E01_008_clean.fcs: processing gate TimeGate\n",
      "101_DEN084Y5_15_E01_008_clean.fcs: processing gate Singlets\n",
      "101_DEN084Y5_15_E01_008_clean.fcs: processing gate aAmine-\n",
      "101_DEN084Y5_15_E01_008_clean.fcs: processing gate CD3-pos\n",
      "101_DEN084Y5_15_E01_008_clean.fcs: processing gate CD4-pos\n",
      "101_DEN084Y5_15_E01_008_clean.fcs: processing gate CD8-pos\n"
     ]
    }
   ],
   "source": [
    "gs_results = g_strat.gate_sample(sample, verbose=True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'101_DEN084Y5_15_E01_008_clean.fcs'"
      ]
     },
     "execution_count": 23,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# get the Sample ID for the GatingResults instance\n",
    "gs_results.sample_id"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### GatingResults Report\n",
    "\n",
    "As we can see, the GatingResults class is relatively simple, and it's main purpose is to provide a Pandas DataFrame of the results via the `report` attribute. The report contains a row for every gate and includes the following columns:\n",
    "\n",
    "* **sample**: the Sample ID of the processed Sample instance\n",
    "* **gate_path**: tuple of the gate path\n",
    "* **gate_name**: the name of the gate (or name of the Quadrant of a QuadrantGate)\n",
    "* **gate_type**: The class name of the gate (RectangleGate, PolygonGate, etc.)\n",
    "* **quadrant_parent**: Quadrant gates are a bit different, they are really a collection of gates. This field would contain the QuadrantGate name, and each Quadrant name would be in the gate_name field.\n",
    "* **parent**: the gate name of the parent gate\n",
    "* **count**: the absolute event count for events inside the gate\n",
    "* **absolute_percent**: the percentage of events inside the gate relative to the total event count in the Sample\n",
    "* **relative_percent**: the percentage of events inside the gate relative to the number of events in the parent gate\n",
    "* **level**: the depth of the gate in the gate tree relative to the root of the tree (Note: root level is 0) "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>sample</th>\n",
       "      <th>gate_path</th>\n",
       "      <th>gate_name</th>\n",
       "      <th>gate_type</th>\n",
       "      <th>quadrant_parent</th>\n",
       "      <th>parent</th>\n",
       "      <th>count</th>\n",
       "      <th>absolute_percent</th>\n",
       "      <th>relative_percent</th>\n",
       "      <th>level</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>101_DEN084Y5_15_E01_008_clean.fcs</td>\n",
       "      <td>(root,)</td>\n",
       "      <td>TimeGate</td>\n",
       "      <td>RectangleGate</td>\n",
       "      <td>None</td>\n",
       "      <td>root</td>\n",
       "      <td>290166</td>\n",
       "      <td>99.997932</td>\n",
       "      <td>99.997932</td>\n",
       "      <td>0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>101_DEN084Y5_15_E01_008_clean.fcs</td>\n",
       "      <td>(root, TimeGate)</td>\n",
       "      <td>Singlets</td>\n",
       "      <td>PolygonGate</td>\n",
       "      <td>None</td>\n",
       "      <td>TimeGate</td>\n",
       "      <td>239001</td>\n",
       "      <td>82.365287</td>\n",
       "      <td>82.366990</td>\n",
       "      <td>1</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>101_DEN084Y5_15_E01_008_clean.fcs</td>\n",
       "      <td>(root, TimeGate, Singlets)</td>\n",
       "      <td>aAmine-</td>\n",
       "      <td>PolygonGate</td>\n",
       "      <td>None</td>\n",
       "      <td>Singlets</td>\n",
       "      <td>164655</td>\n",
       "      <td>56.743931</td>\n",
       "      <td>68.893017</td>\n",
       "      <td>2</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>101_DEN084Y5_15_E01_008_clean.fcs</td>\n",
       "      <td>(root, TimeGate, Singlets, aAmine-)</td>\n",
       "      <td>CD3-pos</td>\n",
       "      <td>PolygonGate</td>\n",
       "      <td>None</td>\n",
       "      <td>aAmine-</td>\n",
       "      <td>133670</td>\n",
       "      <td>46.065782</td>\n",
       "      <td>81.181865</td>\n",
       "      <td>3</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>101_DEN084Y5_15_E01_008_clean.fcs</td>\n",
       "      <td>(root, TimeGate, Singlets, aAmine-, CD3-pos)</td>\n",
       "      <td>CD4-pos</td>\n",
       "      <td>PolygonGate</td>\n",
       "      <td>None</td>\n",
       "      <td>CD3-pos</td>\n",
       "      <td>82484</td>\n",
       "      <td>28.425899</td>\n",
       "      <td>61.707189</td>\n",
       "      <td>4</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5</th>\n",
       "      <td>101_DEN084Y5_15_E01_008_clean.fcs</td>\n",
       "      <td>(root, TimeGate, Singlets, aAmine-, CD3-pos)</td>\n",
       "      <td>CD8-pos</td>\n",
       "      <td>PolygonGate</td>\n",
       "      <td>None</td>\n",
       "      <td>CD3-pos</td>\n",
       "      <td>47165</td>\n",
       "      <td>16.254153</td>\n",
       "      <td>35.284656</td>\n",
       "      <td>4</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                              sample  \\\n",
       "0  101_DEN084Y5_15_E01_008_clean.fcs   \n",
       "1  101_DEN084Y5_15_E01_008_clean.fcs   \n",
       "2  101_DEN084Y5_15_E01_008_clean.fcs   \n",
       "3  101_DEN084Y5_15_E01_008_clean.fcs   \n",
       "4  101_DEN084Y5_15_E01_008_clean.fcs   \n",
       "5  101_DEN084Y5_15_E01_008_clean.fcs   \n",
       "\n",
       "                                      gate_path gate_name      gate_type  \\\n",
       "0                                       (root,)  TimeGate  RectangleGate   \n",
       "1                              (root, TimeGate)  Singlets    PolygonGate   \n",
       "2                    (root, TimeGate, Singlets)   aAmine-    PolygonGate   \n",
       "3           (root, TimeGate, Singlets, aAmine-)   CD3-pos    PolygonGate   \n",
       "4  (root, TimeGate, Singlets, aAmine-, CD3-pos)   CD4-pos    PolygonGate   \n",
       "5  (root, TimeGate, Singlets, aAmine-, CD3-pos)   CD8-pos    PolygonGate   \n",
       "\n",
       "  quadrant_parent    parent   count  absolute_percent  relative_percent  level  \n",
       "0            None      root  290166         99.997932         99.997932      0  \n",
       "1            None  TimeGate  239001         82.365287         82.366990      1  \n",
       "2            None  Singlets  164655         56.743931         68.893017      2  \n",
       "3            None   aAmine-  133670         46.065782         81.181865      3  \n",
       "4            None   CD3-pos   82484         28.425899         61.707189      4  \n",
       "5            None   CD3-pos   47165         16.254153         35.284656      4  "
      ]
     },
     "execution_count": 24,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "gs_results.report"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For convenience, you can get individual Sample statistics for a gate without having to filter the Pandas DataFrame"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "133670"
      ]
     },
     "execution_count": 25,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Retrieve the absolute gate count.\n",
    "# Remember to use the gate path if the gate name is ambiguous.\n",
    "gs_results.get_gate_count('CD3-pos')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "46.0657816743173"
      ]
     },
     "execution_count": 26,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Or, get the absolute percent\n",
    "gs_results.get_gate_absolute_percent('CD3-pos')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "81.18186511190063"
      ]
     },
     "execution_count": 27,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# And the same for the relative percent\n",
    "gs_results.get_gate_relative_percent('CD3-pos')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Retrieve Gate Membership\n",
    "\n",
    "The `get_gate_membership` method returns a Boolean array representing which of the Sample events are inside the specified gate. The arguments are the same gate name and gate path to identify the gate (gate path is optional if gate name is unambiguous)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [],
   "source": [
    "cd3_pos_gate_membership = gs_results.get_gate_membership('CD3-pos')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([False, False, False, ..., False, False,  True])"
      ]
     },
     "execution_count": 29,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "cd3_pos_gate_membership"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "133670"
      ]
     },
     "execution_count": 30,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Summing the Boolean values in the membership NumPy array gives the absolute event count of the gate\n",
    "cd3_pos_gate_membership.sum()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can then use the membership array to retrieve those events from the Sample\n",
    "\n",
    "**Note: The events we extract here are not necessarily pre-processed the same as they would be given the instructions of the gate, even if using the 'comp' or 'xform' source option.**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {},
   "outputs": [],
   "source": [
    "gated_raw_events = sample.get_events(source='raw')\n",
    "gated_raw_events = gated_raw_events[cd3_pos_gate_membership]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(133670, 15)"
      ]
     },
     "execution_count": 32,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "gated_raw_events.shape"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Even simpler, we can use the event_mask option of the Sample.get_events method to get the same gated events\n",
    "gated_raw_events = sample.get_events(source='raw', event_mask=cd3_pos_gate_membership)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(133670, 15)"
      ]
     },
     "execution_count": 34,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "gated_raw_events.shape"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Manually Creating Gating Strategies\n",
    "\n",
    "In the next tutorial, we will cover how to use the `gates` module to manually build a `GatingStrategy`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.12"
  },
  "varInspector": {
   "cols": {
    "lenName": 16,
    "lenType": 16,
    "lenVar": 40
   },
   "kernels_config": {
    "python": {
     "delete_cmd_postfix": "",
     "delete_cmd_prefix": "del ",
     "library": "var_list.py",
     "varRefreshCmd": "print(var_dic_list())"
    },
    "r": {
     "delete_cmd_postfix": ") ",
     "delete_cmd_prefix": "rm(",
     "library": "var_list.r",
     "varRefreshCmd": "cat(var_dic_list()) "
    }
   },
   "types_to_exclude": [
    "module",
    "function",
    "builtin_function_or_method",
    "instance",
    "_Feature"
   ],
   "window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}