tutorials/model_discovery.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "b3e8c31a",
   "metadata": {},
   "source": [
    "# Model Discovery in Declare4Py\n",
    "\n",
    "This tutorial explains how to perform the discovery of a DECLARE model and how to browse the results.\n",
    "\n",
    "After importing the Declare4Py package, a `Declare4Py` object has to be instantiated to load the log."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e6cc9c8b",
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "from declare4py.declare4py import Declare4Py\n",
    "\n",
    "\n",
    "log_path = os.path.join(\"..\", \"tests\", \"Sepsis Cases.xes.gz\")\n",
    "\n",
    "d4py = Declare4Py()\n",
    "d4py.parse_xes_log(log_path)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3a62f54f",
   "metadata": {},
   "source": [
    "The discovery of a DECLARE model is performed with two consecutive steps in Declare4Py:\n",
    "\n",
    "1. the computing of the frequent itemsets with an input support and of length 2 with the `compute_frequent_itemsets()` function, see the tutorial on the analysis of the logs.\n",
    "2. the model discovery with the `discovery()` function. This takes as input the boolean parameter `consider_vacuity=true` that considers vacuously satisfied traces as satisfied, violated otherwise. The integer parameter `max_declare_cardinality` sets the cardinality of the Exactly, Existence and Absence templates. This function returns a Python dictionary containing the results indexed by discovered constraints. The value is a Python dictionary with keys the single ids of the traces in the log (that can be retrieved with `get_trace_keys()`) that satisfy the constraint. The values of this inner dictionary is a `CheckerResult` object containing the number of pendings, activations, violations, fulfilments and the truth value of the trace for that constraint.\n",
    "```\n",
    "discovery_results = {constr_1: {trace_1: CheckerResult object, trace_2: CheckerResult object, ...},\n",
    "                     constr_2: {trace_1: CheckerResult object, ... },\n",
    "                     ...\n",
    "                    }\n",
    "```\n",
    "The `CheckerResult` objects can be accessed by the attributes `num_pendings`, `num_activations`, `num_fulfillments`, `num_violations` and `state`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2c50844d",
   "metadata": {},
   "outputs": [],
   "source": [
    "d4py.compute_frequent_itemsets(min_support=0.9, len_itemset=2)\n",
    "discovery_results = d4py.discovery(consider_vacuity=True, max_declare_cardinality=2)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dc19d8c5",
   "metadata": {},
   "source": [
    "Let's inspect the results for the constraint `Responded Existence[ER Sepsis Triage, ER Triage] | | |` and the trace `(488, 'VR')`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f45f2f39",
   "metadata": {},
   "outputs": [],
   "source": [
    "decl_constr = 'Responded Existence[ER Sepsis Triage, ER Triage] | | |'\n",
    "trace_id = (488, 'VR')\n",
    "print(f\"Number of pendings: {discovery_results[decl_constr][trace_id].num_pendings}\")\n",
    "print(f\"Number of activations: {discovery_results[decl_constr][trace_id].num_activations}\")\n",
    "print(f\"Number of fulfilments: {discovery_results[decl_constr][trace_id].num_fulfillments}\")\n",
    "print(f\"Number of violation: {discovery_results[decl_constr][trace_id].num_violations}\")\n",
    "print(f\"Truth value of: {discovery_results[decl_constr][trace_id].state}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0a9afda6",
   "metadata": {},
   "source": [
    "The results of the discovery can be filtered according to a support threshold and saved in a DECLARE file (if specified). This is performed by the `filter_discovery` function that returns a Python dictionary with the discovered DECLARE constraints as keys and their support as value."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "609476d4",
   "metadata": {},
   "outputs": [],
   "source": [
    "d4py.filter_discovery(min_support=0.7, output_path='sepsis_model_discovered.decl')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2fb924cf",
   "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.9.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}