# Declare4Py
Declare4Py is the first Python package for declarative Process Mining with core functionalities to
easily implement Machine Learning applications for Process Mining. Declarative process mining uses
declarative behavioural rules (based on Linear Temporal Logic on finite traces) for defining process models. This
results in a high flexibility of the business process model definition without neglecting hard
constraints that must be satisfied. Moreover, declarative languages can be used as a bridge between
Process Mining and Machine learning with the DECLARE encoding that encodes the traces in a log into a
numeric format suitable as input to Machine Learning algorithms. Declare4Py implements such a bridge
by including standard algorithms for:
1. declarative Process Mining with LTLf or (MP)-DECLARE templates (e.g., conformance checking, model discovery, trace generation, query checking);
2. log encodings (e.g., complex-index, aggregate, Declare);
3. log labelling according to filtering or declarative rules.
All the Declare4Py data formats are compatible with the main Machine Learning Python packages: scikit-learn, Tensorflow and PyTorch.
## Installation
We recommend the use of a virtual environment to avoid possible clashes between your local Python version and the required
libraries. A virtual environment can be created with [Conda](https://conda.io/projects/conda/en/latest/index.html)
or with the [venv](https://docs.python.org/3/library/venv.html) Python utility. Once a virtual environment has been created,
download the Declare4Py project on your local machine, activate the created virtual environment and use `pip` or `conda`
to install the required dependencies in the `requirements.txt` file. As an alternative you can install Declare4py from [PyPi](https://pypi.org/project/declare4py/).
In addition, the [Lydia](https://github.com/whitemech/lydia) backend for the LTLf conformance checking need to be installed with Docker:
1. Install [Docker](https://www.docker.com/get-started/);
2. Download the Lydia Docker image with `docker pull whitemech/lydia:latest`;
3. Make the Docker image executable under the name `lydia`. On Linux and MacOS machines, the following commands should work:
```
echo '#!/usr/bin/env sh' > lydia
echo 'docker run -v$(pwd):/home/default whitemech/lydia lydia "$@"' >> lydia
sudo chmod u+x lydia
sudo mv lydia /usr/local/bin/
```
4. More information can be found [here](https://github.com/whitemech/logaut).
## Tutorials
The `docs/source/tutorials/` folder contains a walk-through of Declare4Py. In order, the tutorials cover the following topics:
1. [Managing event logs](https://github.com/ivanDonadello/Declare4Py/blob/main/docs/source/tutorials/1.Managing_Event_Logs.ipynb): methods to manage event logs, importing them, extracting useful information, converting them in other formats;
2. [Managing process models](https://github.com/ivanDonadello/Declare4Py/blob/main/docs/source/tutorials/2.Managing_Process_Models.ipynb): simple methods to parse and manage process models from strings and/or files and checking their satisfiability;
3. [Conformance checking of LTLf templates/formulas](https://github.com/ivanDonadello/Declare4Py/blob/main/docs/source/tutorials/3.Conformance_checking_LTLf.ipynb): check what are the traces in an event log that satisfy a given LTLf model;
1. [Log filtering with LTLf properties](https://github.com/ivanDonadello/Declare4Py/blob/main/docs/source/tutorials/3.1.Log_Filtering_LTLf.ipynb): filter a log according to an LTLf model;
4. [Conformance checking of MP-DECLARE templates](https://github.com/ivanDonadello/Declare4Py/blob/main/docs/source/tutorials/4.Conformance_checking_DECLARE.ipynb): check what are the traces in an event log (along with the fulfillments/violations) that satisfy a given MP_DECLARE model;
5. [Query Checking with DECLARE models](https://github.com/ivanDonadello/Declare4Py/blob/main/docs/source/tutorials/5.Declare_Query_Checking.ipynb): discover what are the activities that make an input DECLARE constraint satisfied in an event log;
6. [Discovery of DECLARE models](https://github.com/ivanDonadello/Declare4Py/blob/main/docs/source/tutorials/6.Declare_Model_Discovery.ipynb): discover what are the most satisfied DECLARE constraints in an event log;
7. [Filtering an event log](https://github.com/ivanDonadello/Declare4Py/blob/main/docs/source/tutorials/7.Log_filtering.ipynb): select a subset of an event log that satisfy some input properties;
9. [Log generation with a MP-DECLARE model](https://github.com/ivanDonadello/Declare4Py/blob/main/docs/source/tutorials/9.Log_Generation.ipynb): generate synthetic cases that satisfy an MP-DECLARE model.
The tutorials are Jupyter notebooks and consider the [Sepsis cases log](https://data.4tu.nl/articles/dataset/Sepsis_Cases_-_Event_Log/12707639).
## Repository Structure
- `src/declare4py/ProcessModels` -- the implementation of the supported process models.
- `src/declare4py/ProcessMiningTasks/` -- the implementation of the supported Process Mining tasks.
- `tests/` -- a collection of tests for computing the Declare4Py performance.
- `docs/source/tutorials/` -- tutorials to start with Declare4Py,
## Citing Declare4Py
If you use Declare4Py in your research, please use the following BibTeX entry.
```
@inproceedings{DonadelloRMS22,
author = {Ivan Donadello and
Francesco Riva and
Fabrizio Maria Maggi and
Aladdin Shikhizada},
title = {Declare4Py: {A} Python Library for Declarative Process Mining},
booktitle = {{BPM} (PhD/Demos)},
series = {{CEUR} Workshop Proceedings},
volume = {3216},
pages = {117--121},
publisher = {CEUR-WS.org},
year = {2022}
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/ivanDonadello/Declare4Py",
"name": "declare4py",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9.7",
"maintainer_email": "",
"keywords": "python,bpm,declare,process-mining,rule-mining,business-process-management,declarative-process-models",
"author": "Ivan Donadello, Fabrizio Maria Maggi, Francesco Riva",
"author_email": "Ivan Donadello <ivan.donadello@unibz.it>, Francesco Riva <francesco.riva@unibz.it>, Fabrizio Maria Maggi <maggi@inf.unibz.it>",
"download_url": "https://files.pythonhosted.org/packages/a5/3f/b5e1a320a9d7c00f14d22e3c661b6f38a46cfa1174744548464f68663c9a/declare4py-2.2.0.tar.gz",
"platform": null,
"description": "# Declare4Py\n\nDeclare4Py is the first Python package for declarative Process Mining with core functionalities to \neasily implement Machine Learning applications for Process Mining. Declarative process mining uses \ndeclarative behavioural rules (based on Linear Temporal Logic on finite traces) for defining process models. This \nresults in a high flexibility of the business process model definition without neglecting hard \nconstraints that must be satisfied. Moreover, declarative languages can be used as a bridge between \nProcess Mining and Machine learning with the DECLARE encoding that encodes the traces in a log into a \nnumeric format suitable as input to Machine Learning algorithms. Declare4Py implements such a bridge \nby including standard algorithms for:\n\n1. declarative Process Mining with LTLf or (MP)-DECLARE templates (e.g., conformance checking, model discovery, trace generation, query checking);\n2. log encodings (e.g., complex-index, aggregate, Declare);\n3. log labelling according to filtering or declarative rules.\n\nAll the Declare4Py data formats are compatible with the main Machine Learning Python packages: scikit-learn, Tensorflow and PyTorch.\n\n\n## Installation\nWe recommend the use of a virtual environment to avoid possible clashes between your local Python version and the required \nlibraries. A virtual environment can be created with [Conda](https://conda.io/projects/conda/en/latest/index.html) \nor with the [venv](https://docs.python.org/3/library/venv.html) Python utility. Once a virtual environment has been created,\ndownload the Declare4Py project on your local machine, activate the created virtual environment and use `pip` or `conda` \nto install the required dependencies in the `requirements.txt` file. As an alternative you can install Declare4py from [PyPi](https://pypi.org/project/declare4py/).\n\nIn addition, the [Lydia](https://github.com/whitemech/lydia) backend for the LTLf conformance checking need to be installed with Docker:\n1. Install [Docker](https://www.docker.com/get-started/);\n2. Download the Lydia Docker image with `docker pull whitemech/lydia:latest`;\n3. Make the Docker image executable under the name `lydia`. On Linux and MacOS machines, the following commands should work:\n```\necho '#!/usr/bin/env sh' > lydia\necho 'docker run -v$(pwd):/home/default whitemech/lydia lydia \"$@\"' >> lydia\nsudo chmod u+x lydia\nsudo mv lydia /usr/local/bin/\n```\n4. More information can be found [here](https://github.com/whitemech/logaut).\n\n\n## Tutorials\nThe `docs/source/tutorials/` folder contains a walk-through of Declare4Py. In order, the tutorials cover the following topics:\n\n1. [Managing event logs](https://github.com/ivanDonadello/Declare4Py/blob/main/docs/source/tutorials/1.Managing_Event_Logs.ipynb): methods to manage event logs, importing them, extracting useful information, converting them in other formats;\n2. [Managing process models](https://github.com/ivanDonadello/Declare4Py/blob/main/docs/source/tutorials/2.Managing_Process_Models.ipynb): simple methods to parse and manage process models from strings and/or files and checking their satisfiability;\n3. [Conformance checking of LTLf templates/formulas](https://github.com/ivanDonadello/Declare4Py/blob/main/docs/source/tutorials/3.Conformance_checking_LTLf.ipynb): check what are the traces in an event log that satisfy a given LTLf model; \n 1. [Log filtering with LTLf properties](https://github.com/ivanDonadello/Declare4Py/blob/main/docs/source/tutorials/3.1.Log_Filtering_LTLf.ipynb): filter a log according to an LTLf model;\n4. [Conformance checking of MP-DECLARE templates](https://github.com/ivanDonadello/Declare4Py/blob/main/docs/source/tutorials/4.Conformance_checking_DECLARE.ipynb): check what are the traces in an event log (along with the fulfillments/violations) that satisfy a given MP_DECLARE model;\n5. [Query Checking with DECLARE models](https://github.com/ivanDonadello/Declare4Py/blob/main/docs/source/tutorials/5.Declare_Query_Checking.ipynb): discover what are the activities that make an input DECLARE constraint satisfied in an event log;\n6. [Discovery of DECLARE models](https://github.com/ivanDonadello/Declare4Py/blob/main/docs/source/tutorials/6.Declare_Model_Discovery.ipynb): discover what are the most satisfied DECLARE constraints in an event log;\n7. [Filtering an event log](https://github.com/ivanDonadello/Declare4Py/blob/main/docs/source/tutorials/7.Log_filtering.ipynb): select a subset of an event log that satisfy some input properties;\n9. [Log generation with a MP-DECLARE model](https://github.com/ivanDonadello/Declare4Py/blob/main/docs/source/tutorials/9.Log_Generation.ipynb): generate synthetic cases that satisfy an MP-DECLARE model.\n\nThe tutorials are Jupyter notebooks and consider the [Sepsis cases log](https://data.4tu.nl/articles/dataset/Sepsis_Cases_-_Event_Log/12707639).\n\n## Repository Structure\n- `src/declare4py/ProcessModels` -- the implementation of the supported process models.\n- `src/declare4py/ProcessMiningTasks/` -- the implementation of the supported Process Mining tasks.\n- `tests/` -- a collection of tests for computing the Declare4Py performance.\n- `docs/source/tutorials/` -- tutorials to start with Declare4Py,\n\n## Citing Declare4Py\nIf you use Declare4Py in your research, please use the following BibTeX entry.\n\n```\n@inproceedings{DonadelloRMS22,\n author = {Ivan Donadello and\n Francesco Riva and\n Fabrizio Maria Maggi and\n Aladdin Shikhizada},\n title = {Declare4Py: {A} Python Library for Declarative Process Mining},\n booktitle = {{BPM} (PhD/Demos)},\n series = {{CEUR} Workshop Proceedings},\n volume = {3216},\n pages = {117--121},\n publisher = {CEUR-WS.org},\n year = {2022}\n}\n```\n\n",
"bugtrack_url": null,
"license": "",
"summary": "Python library to perform discovery, conformance checking and query checking of DECLARE constraints.",
"version": "2.2.0",
"project_urls": {
"Homepage": "https://github.com/ivanDonadello/Declare4Py"
},
"split_keywords": [
"python",
"bpm",
"declare",
"process-mining",
"rule-mining",
"business-process-management",
"declarative-process-models"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1a8cb5f5585dd82210466bd1630e00eaea8ddcd14e7665e3c9f5ba57fbfa269b",
"md5": "1272a8bd49f6b98ff8ab1d8fcc16b8b2",
"sha256": "0c82ebba3abd140c39eec7524aeebc8a86156074a5f3fca67d1dcf7e138baa4a"
},
"downloads": -1,
"filename": "declare4py-2.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1272a8bd49f6b98ff8ab1d8fcc16b8b2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9.7",
"size": 89105,
"upload_time": "2023-09-27T08:46:44",
"upload_time_iso_8601": "2023-09-27T08:46:44.551654Z",
"url": "https://files.pythonhosted.org/packages/1a/8c/b5f5585dd82210466bd1630e00eaea8ddcd14e7665e3c9f5ba57fbfa269b/declare4py-2.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a53fb5e1a320a9d7c00f14d22e3c661b6f38a46cfa1174744548464f68663c9a",
"md5": "25492136af91f4a989f2567e0484153d",
"sha256": "e61041ce3aa0638a6025812bc0d89acc052fd1c0769ac05bc27a5d3ad4e86f24"
},
"downloads": -1,
"filename": "declare4py-2.2.0.tar.gz",
"has_sig": false,
"md5_digest": "25492136af91f4a989f2567e0484153d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9.7",
"size": 3272518,
"upload_time": "2023-09-27T08:46:45",
"upload_time_iso_8601": "2023-09-27T08:46:45.967459Z",
"url": "https://files.pythonhosted.org/packages/a5/3f/b5e1a320a9d7c00f14d22e3c661b6f38a46cfa1174744548464f68663c9a/declare4py-2.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-27 08:46:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ivanDonadello",
"github_project": "Declare4Py",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "pandas",
"specs": [
[
"~=",
"1.5.3"
]
]
},
{
"name": "numpy",
"specs": [
[
"~=",
"1.24.2"
]
]
},
{
"name": "scikit-learn",
"specs": [
[
"~=",
"1.2.2"
]
]
},
{
"name": "pm4py",
"specs": [
[
"~=",
"2.6.1"
]
]
},
{
"name": "logaut",
"specs": [
[
"~=",
"0.2.0"
]
]
},
{
"name": "pylogics",
"specs": [
[
"~=",
"0.2.0"
]
]
},
{
"name": "packaging",
"specs": [
[
"~=",
"23.0"
]
]
},
{
"name": "mlxtend",
"specs": [
[
"~=",
"0.21.0"
]
]
},
{
"name": "pythomata",
"specs": [
[
"~=",
"0.3.2"
]
]
},
{
"name": "numba",
"specs": [
[
"~=",
"0.57.0"
]
]
},
{
"name": "matplotlib",
"specs": [
[
"~=",
"3.6.3"
]
]
},
{
"name": "clingo",
"specs": [
[
"==",
"5.6.2"
]
]
},
{
"name": "boolean.py",
"specs": [
[
"==",
"4.0"
]
]
},
{
"name": "ltlf2dfa",
"specs": [
[
"==",
"1.0.2"
]
]
}
],
"lcname": "declare4py"
}
JSON
