{"id":16489873,"url":"https://github.com/aarkue/exdpn","last_synced_at":"2025-10-27T20:31:31.824Z","repository":{"id":41475106,"uuid":"485807322","full_name":"aarkue/eXdpn","owner":"aarkue","description":"Tool to mine and evaluate explainable data Petri nets using different classification techniques.","archived":false,"fork":false,"pushed_at":"2022-11-28T22:38:42.000Z","size":46165,"stargazers_count":8,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-25T04:45:52.730Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://aarkue.github.io/eXdpn","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aarkue.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-04-26T13:52:04.000Z","updated_at":"2025-02-10T02:11:11.000Z","dependencies_parsed_at":"2023-01-22T20:15:56.329Z","dependency_job_id":null,"html_url":"https://github.com/aarkue/eXdpn","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/aarkue/eXdpn","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aarkue%2FeXdpn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aarkue%2FeXdpn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aarkue%2FeXdpn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aarkue%2FeXdpn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aarkue","download_url":"https://codeload.github.com/aarkue/eXdpn/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aarkue%2FeXdpn/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281336742,"owners_count":26483879,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-27T02:00:05.855Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-11T13:45:42.156Z","updated_at":"2025-10-27T20:31:29.948Z","avatar_url":"https://github.com/aarkue.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--This file is a copy of ./docs/_templates/md/exdpn.md, adding code block denotation around code examples. Please keep this file up to date--\u003e\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"docs/images/exdpn-logo.svg\" alt=\"eXdpn Logo\" style=\"display: block; margin-left: auto; margin-right: auto;\"/\u003e\n\u003c/p\u003e\n\neXdpn (e**X**plainable **d**ata **P**etri **n**ets) is a tool to mine and evaluate explainable data Petri nets using different classification techniques.\nThis can help you can find the underlying motivating factors behind decisions in your process.\n\n\u003cfigure style=\"text-align: center; width: 90%\"\u003e\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"docs/images/hero.svg\" alt=\"Example explainable representation of a neural network guard\" style=\" width: 90%; border-radius: 7.5px;\" class=\"\"/\u003e\n\u003cp\u003e\n\u003cfigcaption style=\"margin-top: 0.5rem;\"\u003e\n\n\u003cb\u003e\u003ci\u003eA Motivational Example:\u003c/i\u003e\u003c/b\u003e Decisions in the process are identified and different machine learning techniques are trained to find patterns in the decision making.\n\u003c/p\u003e\n\u003c/figcaption\u003e\n\u003c/figure\u003e\n\u003c/p\u003e\n\n\n\n**Table of Contents:**\n\n- [Getting Started](#getting-started)\n- [Source Code and UI-application](#source-code-and-ui-application)\n  - [Docker Deployment](#docker-deployment)\n      - [Using Docker Compose](#using-docker-compose)\n      - [Building the Docker Container](#building-the-docker-container)\n- [User Guide Web UI](#user-guide-web-ui)\n  - [Getting Started](#getting-started-1)\n  - [Example Run](#example-run)\n      - [Discovering a Process Model](#discovering-a-process-model)\n      - [Configuring the Mining Parameters](#configuring-the-mining-parameters)\n      - [Mining and Viewing Results](#mining-and-viewing-results)\n- [Explainable Representation](#explainable-representation)\n- [Qualitative Analysis of eXdpn](#qualitative-analysis-of-exdpn)\n\n---\n\n## Getting Started ##\nInstalling eXdpn is possible via pip:\n```bash\npython -m pip install exdpn \n```\n\nNow you can mine your first explainable data Petri net given an event log in XES format:\n```python\nfrom exdpn.util import import_log\nfrom exdpn.data_petri_net import Data_Petri_Net\nevent_log = import_log('\u003cpath_to_event_log.xes\u003e')\ndpn = Data_Petri_Net(event_log, event_level_attributes=['event_level_attribute'])\n```\n\nThis will mine a data Petri net for your event log, considering only \"event_level_attribute\" as a possible attribute for classification. \nThe `exdpn.data_petri_net.data_petri_net.Data_Petri_Net` class already takes care of the workflow to create a data Petri net. In cases where fine-grained \ncontrol of the data Petri net creation is needed or only certain functionallity of this package is needed, one can simply call all the needed functions and methods directly. \n\nLet's say we are only interested in extracting the guard dataset at one specific decision point in the Petri net.\nWe start off by importing the event log from memory and creating a standard Petri net:\n\n```python\nfrom exdpn.util import import_log\nfrom exdpn.petri_net import get_petri_net\nevent_log = import_log('\u003cpath_to_event_log.xes\u003e')\nnet, im, fm = get_petri_net(event_log)\n```\n\nWe then extract all the decision points and specify our place of interest using the `exdpn.decisionpoints` module:\n\n```python\nfrom exdpn.decisionpoints import find_decision_points\ndp_dict = find_decision_points(net)\ndecision_point = list(dp_dict.keys())[0]\n```\n\nTo extract a guard dataset for the specific place `decision_point`, we call the following data extraction function from `exdpn.guard_datasets`:\n\n```python\nfrom exdpn.guard_datasets import extract_all_datasets\ndataset = extract_all_datasets(event_log, net, im, fm, event_level_attributes=['event_level_attribute'], places=[decision_point])\n```\n\n\nFurther examples can be seen in the API documentation. The sometimes referenced XES file `p2p_base.xes` can be found on Github.\n\n--- \n\n\n## Source Code and UI-application ##\nThe source code of this package is available on Github ([aarkue/eXdpn](https://github.com/aarkue/eXdpn)).\nFurthermore, a graphical user interface is available in the form of a web-based UI and a Docker container to easily start it locally.\n\n### Docker Deployment ###\nThe project can be run with Docker.\nThe easiest way to do so is with the included `docker-compose.yml` file.\n\n#### Using Docker Compose ####\nTo create and start the docker container with docker compose simply execute `docker-compose up` in the root directory of the project.\nThe web ui will then be available on port 5000.\n\nTo force re-creation of the container add the `--build` flag to the `docker-compose` command: `docker-compose up --build`.-\n\n\n#### Building the Docker Container ####\n1. `docker build .`\n2. `docker run -p 5000:5000 \u003ccontainer id\u003e`\n\nThe web ui will then be available on port 5000.\n\n---\n\n## User Guide Web UI ##\nIn the next few sections we will introduce how you can use the web UI to mine decisions in a process. \n### Getting Started ###\nWhen you first run the web UI (either locally or through docker) you will be prompted with the following screen:\n\u003cimg src=\"docs/images/user-guide/start.png\" alt=\"Welcome screen of eXdpn UI\" style=\"\"/\u003e\nHere you can start by importing any existing event log in the XES format.\nIf you do not have any XES event log at hand, you can try our P2P base event log and download it \u003ca href=\"https://github.com/aarkue/eXdpn/raw/main/datasets/p2p_base.xes\" target=\"_blank\"\u003ehere\u003c/a\u003e.\n\nAfter importing a local event log, you will see it appear on the page.\n\n\u003cimg src=\"docs/images/user-guide/log-imported.png\" alt=\"Screenshot showing the page listing the uploaded event log p2p_base.xes\" style=\"\"/\u003e\n\nTo continue select an event log from the list of imported logs.\n\n### Example Run ###\nWhen selecting an event log the log will be loaded to memory and initial statistics about the log (like case or event count) are displayed.\n\n\u003cimg src=\"docs/images/user-guide/mine_decisions_step1.png\" alt=\"Screenshot showing the basic statistics of the selected event log\" style=\"\"/\u003e\n\nTo gain insights into the decisions of the process, you will need to go through the following steps:\n\n\n1. [Discovering a Process Model](#discovering-a-process-model)\n2. [Configuring the Mining Parameters](#configuring-the-mining-parameters)\n3. [Mining and Viewing Results](#mining-and-viewing-results)\n\n#### Discovering a Process Model ###\nTo find where decisions are made in the process, you first have to **discover a process model** for it. This can be done using the Inductive Miner or the Alpha Miner.\nOnce the process mining is done the discovered accepting Petri net will be displayed on the page, and every decision point is highlighted in red.\n\n\u003cimg src=\"docs/images/user-guide/mine_decisions_step2.png\" alt=\"Screenshot showing the discovered Petri net and the available mining parameters.\" style=\"\"/\u003e\n\n#### Configuring the Mining Parameters ###\nNext, you can select the **parameters for the decision mining**.\nThe techniques that should be used can be changed.\nBy default, all available techniques (Decision Tree, Logistic Regression, Support Vector Machine (SVM), Neural Network) are selected.\n\nIn addition, the data on which the machine learning techniques will base their decisions can be configured.\nFor that, you can choose for each of the following attribute type whether or not it should be considered in the decision mining:\n- Case attributes\n  - Case attributes are on a case-level and are used for all decisions related to that case\n- Event attributes\n  - Event-level attributes found in the event log. These attributes are used for decision points occurring immediately after this event\n- Synthetic attributes\n  - Synthetic attributes are not present in the input event log but added artifically based on other event data\n  - The following synthetic attributes are currently available:\n      - ***Elapsed time in case***: Time duration since the case started is added as an attribute to every event\n      - ***Time since last event***: The duration since the previous event occurred is added as an attribute to every event\n\n#### Mining and Viewing Results ####\nBy clicking on **Mine Decisions** the decision mining process is started in the background. Please stand by as this might take a few minutes. Once the mining finished, the loading indicator on the button will disappear, and the *mean guard conformance*[^1] will be displayed on the Petri net.\n\n[^1]: The mean guard conformance represents the fraction of cases which can be replayed perfectly on the Data Petri net, respecting all discovered guards.\n\n\u003cimg src=\"docs/images/user-guide/mine_decisions_step3.png\" alt=\"Screenshot showing the discovered Petri net and the available mining parameters.\" style=\"\"/\u003e\n\nTo **inspect how decisions are made** at a certain part of the process, you can click on one of the colored decision places in the Petri net.\nThis will open a panel on the bottom, which displays further information on the discovered decision guards for the selected place.\n\nThe technique that performed best for the selected place and its corresponding F1 score is shown together with a comparison of the F1 scores of the all other techniques.\nAdditionally the *explainable representation* of the winning technique is shown and can give further insights into what aspects motivate the decision in question.\nTo view the explainable representation of other technique, simply select it from the dropdown menu.\n\n---\n\n## Explainable Representation ##\nTo provide a better understandig of the prediction models created by the used machine learning techniques, we use two types of explainable representations.   \nDecision Tree models are represented by simply drawing the detected Decision Tree. Each node represents a splitting point and contains information about the splitting criteria. The leaves show the final classification for all samples in the particular leaf.   \nFor the explainable representation of Neural Network, Support Vector Machine and Logistic Regression the [SHAP library](https://shap.readthedocs.io/en/latest/index.html) is used. The bar plots show the mean absolute values of the SHAP values of the most important feature attributes. These SHAP values indicate the importance of a feature attribute on the the model prediction. If you are interested in learning more about SHAP values and the theory behind them, please check the references.  \n  \nReferences:  \nhttps://towardsdatascience.com/shap-explained-the-way-i-wish-someone-explained-it-to-me-ab81cc69ef30  \nhttps://towardsdatascience.com/using-shap-values-to-explain-how-your-machine-learning-model-works-732b3f40e137  \n\n---\n\n## Qualitative Analysis of eXdpn ##\nTo provide insight to the eXdpn application, the tool was tested and analyzed using four different synthetic P2P event logs. This allowed us to test whether the different machine learning techniques are able to model the decision-making behavior in the event logs. For each event log different so-called guards have been created. These guards are used to model the behavior at a decision point by either enabling or disabling the possible transitions after the decision point. Each event log focuses on differnt types of decision behavior, like non-random or random decisions, decisions based on nonlinear functions or based on previous activities.  \nThe qualitative analysis revealed some differences between the four different machine learning techniques. If the decision was made based on the value of a feature attribute, either numerical or categorical, most machine learning guards were able to detect that behavior. This also applies if a decision was made based on previous activities. If the decision points became more complex, guards based on Neural Networks, Support Vector Machines or Logistic Regression often performed better than the corresponding Decision Tree guards.  \nThe complete analysis can be found [here](https://github.com/aarkue/eXdpn/tree/main/qualitative_analysis).  \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faarkue%2Fexdpn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faarkue%2Fexdpn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faarkue%2Fexdpn/lists"}