diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 0000000..c7373be --- /dev/null +++ b/.github/workflows/docs.yaml @@ -0,0 +1,26 @@ +name: Publish Sphinx Documentation + +on: + push: + branches: + - main + +jobs: + publish_sphinx_docs: + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - uses: actions/checkout@v3 + - uses: ./.github/actions/setup + - name: Install dependencies + run: uv sync + - name: Sphinx build + run: uv run sphinx-build docs/source docs/build/html + - name: Deploy + uses: peaceiris/actions-gh-pages@v3 + with: + publish_branch: gh-pages + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: docs/build/html + force_orphan: true diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..dd2de35 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,42 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +SPHINXAPIDOC = sphinx-apidoc +SOURCEAPI = source/api/ +BACKEND = ../backend +ALLAPIDOCOPTS = -e -M --tocfile backend --implicit-namespaces -o + + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: rst +rst: + $(SPHINXAPIDOC) $(ALLAPIDOCOPTS) $(SOURCEAPI) $(BACKEND) + @echo + @echo "rst API documentation files generated. The .rst files are in $(SOURCEAPI)." + +.PHONY: rstf +rstf: + $(SPHINXAPIDOC) -f $(ALLAPIDOCOPTS) $(SOURCEAPI) $(BACKEND) + @echo + @echo "rst API documentation files generated. The .rst files are in $(SOURCEAPI)." + +clean: + @$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O); + cd build; git worktree add -f html gh-pages diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..747ffb7 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/_static/img/architecture.svg b/docs/source/_static/img/architecture.svg new file mode 100644 index 0000000..8ff3ccd --- /dev/null +++ b/docs/source/_static/img/architecture.svg @@ -0,0 +1,4 @@ + + + +
Repo
Repo
backend
backend
frontend
frontend
tests (mirrors structure of backend)
tests (mirrors structure of backend)
celonis_part
celonis_part
api
(structured according to functionality)
api...
conformance_checking
conformanc...
temporal_profile.py
temporal_profile.py
log_skeleton.py
log_skeleton.py
resource_based.py
resource_based.py
declarative_based.py
declarative_based.py \ No newline at end of file diff --git a/docs/source/_static/img/backend.svg b/docs/source/_static/img/backend.svg new file mode 100644 index 0000000..4d59784 --- /dev/null +++ b/docs/source/_static/img/backend.svg @@ -0,0 +1,4 @@ + + + +
celonis_connection
utils
api
main.py
modules
Declarative
Temporal
Log Skeleton
Resource-based
General
conformance_checking
Declarative
Temporal
Log Skeleton
Resource-based
pql_queries
Declarative
Temporal
Log Skeleton
Resource-based
celonis.py
jobs.py
log.py
setup.py
general purpose
tasks
Declarative
Temporal
Resource-based
Log Skeleton
models/
schemas
Backend
 \ No newline at end of file diff --git a/docs/source/_static/img/dark-logo.png b/docs/source/_static/img/dark-logo.png new file mode 100644 index 0000000..9e92876 Binary files /dev/null and b/docs/source/_static/img/dark-logo.png differ diff --git a/docs/source/_static/img/frontend/api_token.png b/docs/source/_static/img/frontend/api_token.png new file mode 100644 index 0000000..7916e04 Binary files /dev/null and b/docs/source/_static/img/frontend/api_token.png differ diff --git a/docs/source/_static/img/frontend/celonis_credentials.jpeg b/docs/source/_static/img/frontend/celonis_credentials.jpeg new file mode 100644 index 0000000..56c3343 Binary files /dev/null and b/docs/source/_static/img/frontend/celonis_credentials.jpeg differ diff --git a/docs/source/_static/img/frontend/conf_insight.jpeg b/docs/source/_static/img/frontend/conf_insight.jpeg new file mode 100644 index 0000000..11ae0c7 Binary files /dev/null and b/docs/source/_static/img/frontend/conf_insight.jpeg differ diff --git a/docs/source/_static/img/frontend/mapping.jpeg b/docs/source/_static/img/frontend/mapping.jpeg new file mode 100644 index 0000000..623564f Binary files /dev/null and b/docs/source/_static/img/frontend/mapping.jpeg differ diff --git a/docs/source/_static/img/frontend/settings.jpeg b/docs/source/_static/img/frontend/settings.jpeg new file mode 100644 index 0000000..36ddd54 Binary files /dev/null and b/docs/source/_static/img/frontend/settings.jpeg differ diff --git a/docs/source/_static/img/frontend/upload.jpeg b/docs/source/_static/img/frontend/upload.jpeg new file mode 100644 index 0000000..41e4b7c Binary files /dev/null and b/docs/source/_static/img/frontend/upload.jpeg differ diff --git a/docs/source/_static/img/light-logo.png b/docs/source/_static/img/light-logo.png new file mode 100644 index 0000000..69d8950 Binary files /dev/null and b/docs/source/_static/img/light-logo.png differ diff --git a/docs/source/_static/img/logo.png b/docs/source/_static/img/logo.png new file mode 100644 index 0000000..2141c68 Binary files /dev/null and b/docs/source/_static/img/logo.png differ diff --git a/docs/source/architecture.rst b/docs/source/architecture.rst new file mode 100644 index 0000000..4acea90 --- /dev/null +++ b/docs/source/architecture.rst @@ -0,0 +1,81 @@ +System Architecture +=================== + +This page explains the architecture of the system. +It explains the overall structure of the backend and how the the backend interacts with the Celonis platform via `PyCelonis `_. + +Backend Architecture +-------------------- + +The overall backend architecture is shown in the following diagram: + +.. _backend-architecture: + +.. figure:: ./_static/img/backend.svg + + Backend Architecture + +In the following, we explain the key components of the backend. + +Celonis Connection +^^^^^^^^^^^^^^^^^^ +The :py:mod:`celonis_connection_manager ` module houses the :py:class:`CelonisConnectionManager ` class. +This class is responsible for managing the connection to the Celonis platform. +For this it uses the `PyCelonis `_ library to connect. + +It offers mechanisms to upload event logs to the Celonis platform, and run arbitrary PQL queries on the platform against the uploaded data. +In the :py:mod:`API ` module, we use this class as a dependency to connect to Celonis. +This is done in the :py:mod:`celonis ` module. + +Conformance Checking +^^^^^^^^^^^^^^^^^^^^ + +The :py:mod:`conformance_checking ` package contains modules for the four different conformance checking techniques. +Each module defines a class that implements the conformance checking technique. +These implementations are based on `PM4Py `_. + +These were built in a first iteration of the application. +The application also allows to run the conformance techniques based on **PQL queries** instead of the PM4Py implementations. + +PQL Queries +^^^^^^^^^^^ + +The :py:mod:`pql_queries ` package contains modules that define the PQL queries for the conformance checking techniques. +As :ref:`backend-architecture` shows this package mirrors the strucuture of the :py:mod:`conformance_checking ` package. + +Each module defines PQL queries that can be used to run the conformance checking techniques on the Celonis platform. + +API +^^^ + +The :py:mod:`API ` package contains the API endpoints for the application. +It is probably the biggest package in the backend. +It houses all the API relevant code. + +The backend API is built using the `FastAPI `_ framework. +The main application is defined in the :py:mod:`main ` module. + +The API endpoints are split-up into different routers, each responsible for a specific functionality. +The routers have the following functionality: + +* :py:mod:`setup `: Contains endpoints for setting up the application, such as inserting Celonis credentials. +* :py:mod:`log `: Contains endpoints for uploading event logs to the application and commiting them to the Celonis platform. +* :py:mod:`jobs `: Contains endpoints for getting the status of jobs for conformance checking techniques. +* :py:mod:`modules `: Contains a module each, which defines a router, for each conformance checking technique. + These routers contain endpoints for running the conformance checking techniques and getting the results. + +Remaining Modules +^^^^^^^^^^^^^^^^^ + +The remaining modules in the backend contain code for various utilities and configurations. +All modules are well documented and we refer the reader to the code itself and the :doc:`autoapi/index` for more details. + +Interaction with Celonis +------------------------ + +All conformance checking techniques use the Celonis platform to store the event logs. +The basic implementations that are based on `PM4Py `_ (see :py:mod:`conformance_checking `) download a basic variant of the event log from the Celonis platform. +They then run all the conformance checking locally using PM4Py. + +The PQL-based implementations (see :py:mod:`pql_queries `) perform pre-computations on the event logs on the Celonis platform using `PQL `_. +They then fetch the results of these pre-computations and process them locally to compute the wanted results. \ No newline at end of file diff --git a/docs/source/autoapi/backend/api/celonis/index.rst b/docs/source/autoapi/backend/api/celonis/index.rst new file mode 100644 index 0000000..d5f4718 --- /dev/null +++ b/docs/source/autoapi/backend/api/celonis/index.rst @@ -0,0 +1,87 @@ +backend.api.celonis +=================== + +.. py:module:: backend.api.celonis + +.. autoapi-nested-parse:: + + Contains the dependency injection for the CelonisConnectionManager. + + This module contains one function, which is used to return a + CelonisConnectionManager instance. The function is used as a dependency + in the FastAPI application. + + + +Classes +------- + +.. autoapisummary:: + + backend.api.celonis.CelonisSettings + + +Functions +--------- + +.. autoapisummary:: + + backend.api.celonis.get_celonis_connection + + +Module Contents +--------------- + +.. py:class:: CelonisSettings(_case_sensitive: bool | None = None, _nested_model_default_partial_update: bool | None = None, _env_prefix: str | None = None, _env_file: pydantic_settings.sources.DotenvType | None = ENV_FILE_SENTINEL, _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_nested_max_split: int | None = None, _env_parse_none_str: str | None = None, _env_parse_enums: bool | None = None, _cli_prog_name: str | None = None, _cli_parse_args: bool | list[str] | tuple[str, Ellipsis] | None = None, _cli_settings_source: pydantic_settings.sources.CliSettingsSource[Any] | None = None, _cli_parse_none_str: str | None = None, _cli_hide_none_type: bool | None = None, _cli_avoid_json: bool | None = None, _cli_enforce_required: bool | None = None, _cli_use_class_docs_for_groups: bool | None = None, _cli_exit_on_error: bool | None = None, _cli_prefix: str | None = None, _cli_flag_prefix_char: str | None = None, _cli_implicit_flags: bool | None = None, _cli_ignore_unknown_args: bool | None = None, _cli_kebab_case: bool | None = None, _secrets_dir: pydantic_settings.sources.PathType | None = None, **values: Any) + + Bases: :py:obj:`pydantic_settings.BaseSettings` + + + Settings for the Celonis connection. + + This class is used to load the Celonis connection settings from the + environment variables. The settings are loaded from a .env file + using the `pydantic_settings` library. The settings include the + Celonis base URL, data pool name, data model name, and API token. + + + .. py:attribute:: CELONIS_BASE_URL + :type: str + + + .. py:attribute:: CELONIS_DATA_POOL_NAME + :type: str + + + .. py:attribute:: CELONIS_DATA_MODEL_NAME + :type: str + + + .. py:attribute:: API_TOKEN + :type: str + + + .. py:attribute:: model_config + + Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. + + +.. py:function:: get_celonis_connection(request: fastapi.Request) -> backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager + + Returns a CelonisConnectionManager instance. + + It tries to get the CelonisConnectionManager instance from the + application state. If it is not present, it creates a new instance + using the settings from the environment variables. The instance is + then stored in the application state for later use. + This function is used as a dependency in the FastAPI application. + + :param request: The FastAPI request object. This is used to access the + application state via `request.app.state`. The application state + contains the `CelonisConnectionManager` instance, which is created + during application startup and stored for later use. + + :returns: The CelonisConnectionManager instance. This is used to connect to the + Celonis API and perform operations on the data pool. + + diff --git a/docs/source/autoapi/backend/api/index.rst b/docs/source/autoapi/backend/api/index.rst new file mode 100644 index 0000000..328d7b2 --- /dev/null +++ b/docs/source/autoapi/backend/api/index.rst @@ -0,0 +1,21 @@ +backend.api +=========== + +.. py:module:: backend.api + + +Submodules +---------- + +.. toctree:: + :maxdepth: 1 + + /autoapi/backend/api/celonis/index + /autoapi/backend/api/jobs/index + /autoapi/backend/api/log/index + /autoapi/backend/api/models/index + /autoapi/backend/api/modules/index + /autoapi/backend/api/setup/index + /autoapi/backend/api/tasks/index + + diff --git a/docs/source/autoapi/backend/api/jobs/index.rst b/docs/source/autoapi/backend/api/jobs/index.rst new file mode 100644 index 0000000..b9e315f --- /dev/null +++ b/docs/source/autoapi/backend/api/jobs/index.rst @@ -0,0 +1,63 @@ +backend.api.jobs +================ + +.. py:module:: backend.api.jobs + +.. autoapi-nested-parse:: + + Contains the router for handling jobs. + + + +Attributes +---------- + +.. autoapisummary:: + + backend.api.jobs.router + + +Functions +--------- + +.. autoapisummary:: + + backend.api.jobs.get_jobs + backend.api.jobs.verify_correct_job_module + + +Module Contents +--------------- + +.. py:data:: router + +.. py:function:: get_jobs(job_id: str, request: fastapi.Request) -> backend.api.models.schemas.job_models.JobStatus + :async: + + + Fetches the status of a job via its ID. + + :param job_id: The ID of the job to be fetched. + :param request: The FastAPI request object. This is used to access the + application state via `request.app.state`. + + :raises HTTPException: If the job with the given ID is not found in the + :raises application state.: + + :returns: The status of the job as a JobStatus object. + + +.. py:function:: verify_correct_job_module(job_id: str, request: fastapi.Request, module: str) + + Verifies if a job belongs to the module. + + Helper funciton used for the request of job states. + + :param job_id: The ID of the job to be fetched. + :param request: The FastAPI request object. This is used to access the + application state via `request.app.state`. + :param module: The name of the module that the job is checked against + + :raises HTTPException: If the job with the given ID does not belong to the module + + diff --git a/docs/source/autoapi/backend/api/log/index.rst b/docs/source/autoapi/backend/api/log/index.rst new file mode 100644 index 0000000..b9a1a98 --- /dev/null +++ b/docs/source/autoapi/backend/api/log/index.rst @@ -0,0 +1,80 @@ +backend.api.log +=============== + +.. py:module:: backend.api.log + +.. autoapi-nested-parse:: + + Contains the API routes to handle logs and log-related operations. + + This module defines the FastAPI routes for managing logs, including + retrieving logs, filtering logs by date, and deleting logs. It also + includes utility functions for handling log data and formatting + responses. In case of and log upload, it also includes the necessary + metadata to create a celonis connection. + + + +Attributes +---------- + +.. autoapisummary:: + + backend.api.log.router + + +Functions +--------- + +.. autoapisummary:: + + backend.api.log.upload_log + backend.api.log.commit_log_to_celonis + + +Module Contents +--------------- + +.. py:data:: router + +.. py:function:: upload_log(file: fastapi.UploadFile, request: fastapi.Request) -> Dict[str, List[str]] + :async: + + + Uploads an event log file and retrieves its columns. + + The file gets stored in a temporary file for the later upload to Celonis. + + :param file: The event log file to be uploaded. This should be a .csv or .xes file. + :param request: The FastAPI request object. This is used to access the + application state via `request.app.state`. + + :returns: The columns of the uploaded log file as a dictionary. + + :raises HTTPException: If the file name is not provided or if the file type is + :raises invalid, or if there is an error processing the file.: + + +.. py:function:: commit_log_to_celonis(request: fastapi.Request, payload: Optional[backend.api.models.schemas.setup_models.ColumnMapping] = None, celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager = Depends(get_celonis_connection)) -> Dict[str, str] + :async: + + + Uploads the log file to Celonis and creates a table. + + :param payload: The column mapping for the event log. This should be a + ColumnMapping object containing the case ID, activity, and timestamp + columns. It is only needed if the log is a csv file. + :type payload: optional + :param request: The FastAPI request object. This is used to access the + application state via `request.app.state`. + :param celonis: The Celonis Connection DI. Defaults to + Depends(get_celonis_connection). + :type celonis: optional + + :raises HTTPException: If no log file is found in the app state, or if there is an + :raises error processing the file.: + + :returns: A dictionary containing a message indicating the success of the + operation. + + diff --git a/docs/source/autoapi/backend/api/models/index.rst b/docs/source/autoapi/backend/api/models/index.rst new file mode 100644 index 0000000..b1df6c0 --- /dev/null +++ b/docs/source/autoapi/backend/api/models/index.rst @@ -0,0 +1,15 @@ +backend.api.models +================== + +.. py:module:: backend.api.models + + +Submodules +---------- + +.. toctree:: + :maxdepth: 1 + + /autoapi/backend/api/models/schemas/index + + diff --git a/docs/source/autoapi/backend/api/models/schemas/index.rst b/docs/source/autoapi/backend/api/models/schemas/index.rst new file mode 100644 index 0000000..daf473a --- /dev/null +++ b/docs/source/autoapi/backend/api/models/schemas/index.rst @@ -0,0 +1,17 @@ +backend.api.models.schemas +========================== + +.. py:module:: backend.api.models.schemas + + +Submodules +---------- + +.. toctree:: + :maxdepth: 1 + + /autoapi/backend/api/models/schemas/job_models/index + /autoapi/backend/api/models/schemas/resource_based_models/index + /autoapi/backend/api/models/schemas/setup_models/index + + diff --git a/docs/source/autoapi/backend/api/models/schemas/job_models/index.rst b/docs/source/autoapi/backend/api/models/schemas/job_models/index.rst new file mode 100644 index 0000000..22945ea --- /dev/null +++ b/docs/source/autoapi/backend/api/models/schemas/job_models/index.rst @@ -0,0 +1,60 @@ +backend.api.models.schemas.job_models +===================================== + +.. py:module:: backend.api.models.schemas.job_models + +.. autoapi-nested-parse:: + + Contains the Pydantic model for a generic job. + + The job is used to represent a job in the system. + + + +Classes +------- + +.. autoapisummary:: + + backend.api.models.schemas.job_models.JobStatus + + +Module Contents +--------------- + +.. py:class:: JobStatus(/, **data: Any) + + Bases: :py:obj:`pydantic.BaseModel` + + + The job status model. + + This model is used to represent the status of a job in the system. + It contains the module name, status, result, and error message. + The status can be one of the following: "pending", "running", + "completed", or "failed". + The result is an optional dictionary containing the result of the job. + The error is an optional string containing the error message if the + job failed. + + + .. py:attribute:: module + :type: str + + + .. py:attribute:: status + :type: Literal['pending', 'running', 'complete', 'failed'] + + + .. py:attribute:: result + :type: Optional[Dict[str, Any]] + :value: None + + + + .. py:attribute:: error + :type: Optional[str] + :value: None + + + diff --git a/docs/source/autoapi/backend/api/models/schemas/resource_based_models/index.rst b/docs/source/autoapi/backend/api/models/schemas/resource_based_models/index.rst new file mode 100644 index 0000000..3d30697 --- /dev/null +++ b/docs/source/autoapi/backend/api/models/schemas/resource_based_models/index.rst @@ -0,0 +1,59 @@ +backend.api.models.schemas.resource_based_models +================================================ + +.. py:module:: backend.api.models.schemas.resource_based_models + +.. autoapi-nested-parse:: + + Contains the Pydantic models for resource-based conformance checking. + + + +Classes +------- + +.. autoapisummary:: + + backend.api.models.schemas.resource_based_models.SNAMetric + backend.api.models.schemas.resource_based_models.OrganizationalRole + + +Module Contents +--------------- + +.. py:class:: SNAMetric(/, **data: Any) + + Bases: :py:obj:`pydantic.BaseModel` + + + Represents a single connection (edge) in an SNA graph. + + + .. py:attribute:: source + :type: str + + + .. py:attribute:: target + :type: str + + + .. py:attribute:: value + :type: float + + +.. py:class:: OrganizationalRole(/, **data: Any) + + Bases: :py:obj:`pydantic.BaseModel` + + + Represents an organizational role used for role discovery. + + + .. py:attribute:: activities + :type: List[str] + + + .. py:attribute:: originators_importance + :type: Dict[str, float] + + diff --git a/docs/source/autoapi/backend/api/models/schemas/setup_models/index.rst b/docs/source/autoapi/backend/api/models/schemas/setup_models/index.rst new file mode 100644 index 0000000..8770a37 --- /dev/null +++ b/docs/source/autoapi/backend/api/models/schemas/setup_models/index.rst @@ -0,0 +1,83 @@ +backend.api.models.schemas.setup_models +======================================= + +.. py:module:: backend.api.models.schemas.setup_models + +.. autoapi-nested-parse:: + + Contains the Pydantic models for the setup API. + + This module defines the Pydantic models used for validating the input + data for the setup API endpoints. It includes models for Celonis + credentials, and column mapping. + + + +Classes +------- + +.. autoapisummary:: + + backend.api.models.schemas.setup_models.CelonisCredentials + backend.api.models.schemas.setup_models.ColumnMapping + + +Module Contents +--------------- + +.. py:class:: CelonisCredentials(/, **data: Any) + + Bases: :py:obj:`pydantic.BaseModel` + + + Defines the Celonis credentials required for the connection. + + + .. py:attribute:: celonis_base_url + :type: str + + + .. py:attribute:: celonis_data_pool_name + :type: str + + + .. py:attribute:: celonis_data_model_name + :type: str + + + .. py:attribute:: api_token + :type: str + + +.. py:class:: ColumnMapping(/, **data: Any) + + Bases: :py:obj:`pydantic.BaseModel` + + + Defines the column mapping for the event log. + + + .. py:attribute:: case_id_column + :type: str + + + .. py:attribute:: activity_column + :type: str + + + .. py:attribute:: timestamp_column + :type: str + + + .. py:attribute:: resource_1_column + :type: Optional[str] + :value: None + + + + .. py:attribute:: group_column + :type: Optional[str] + :value: None + + + diff --git a/docs/source/autoapi/backend/api/modules/declarative_router/index.rst b/docs/source/autoapi/backend/api/modules/declarative_router/index.rst new file mode 100644 index 0000000..ee1f7b5 --- /dev/null +++ b/docs/source/autoapi/backend/api/modules/declarative_router/index.rst @@ -0,0 +1,265 @@ +backend.api.modules.declarative_router +====================================== + +.. py:module:: backend.api.modules.declarative_router + +.. autoapi-nested-parse:: + + Contains the routes for handling declarative constraints. + + + +Attributes +---------- + +.. autoapisummary:: + + backend.api.modules.declarative_router.ReturnGraphType + backend.api.modules.declarative_router.router + backend.api.modules.declarative_router.MODULE_NAME + + +Functions +--------- + +.. autoapisummary:: + + backend.api.modules.declarative_router.compute_declarative_constraints + backend.api.modules.declarative_router.get_existance_violations + backend.api.modules.declarative_router.get_absence_violations + backend.api.modules.declarative_router.get_exactly_one_violations + backend.api.modules.declarative_router.get_init_violations + backend.api.modules.declarative_router.get_responded_existence_violations + backend.api.modules.declarative_router.get_coexistence_violations + backend.api.modules.declarative_router.get_response_violations + backend.api.modules.declarative_router.get_precedence_violations + backend.api.modules.declarative_router.get_succession_violations + backend.api.modules.declarative_router.get_altprecedence_violations + backend.api.modules.declarative_router.get_altsuccession_violations + backend.api.modules.declarative_router.get_chainresponse_violations + backend.api.modules.declarative_router.get_chainprecedence_violations + backend.api.modules.declarative_router.get_chainsuccession_violations + backend.api.modules.declarative_router.get_noncoexistence_violations + backend.api.modules.declarative_router.get_nonsuccession_violations + backend.api.modules.declarative_router.get_nonchainsuccession_violations + + +Module Contents +--------------- + +.. py:type:: ReturnGraphType + :canonical: Dict[str, List[Dict[str, List[Union[str, Dict[str, str]]]]]] + + +.. py:data:: router + +.. py:data:: MODULE_NAME + :value: 'declarative_constraints' + + +.. py:function:: compute_declarative_constraints(background_tasks: fastapi.BackgroundTasks, request: fastapi.Request, celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager = Depends(get_celonis_connection)) -> Dict[str, str] + :async: + + + Computes the declarative constraints and stores it. + + The declarative model is computed in the background and stored in the app state. + + :param background_tasks: The background tasks object. This is used to schedule + the computation of the declarative model. + :param request: The FastAPI request object. This is used to access the + application state via `request.app.state`. + :param celonis: The CelonisManager dependency injection. + Defaults to Depends(get_celonis_connection). + :type celonis: optional + + :returns: A dictionary containing the job ID of the scheduled task. + + +.. py:function:: get_existance_violations(job_id: str, request: fastapi.Request) -> ReturnGraphType + + Retrieves the existance violations from the declarative model. + + :param job_id: The ID of the job for which to retrieve the existance violations. + :param request: The FastAPI request object. This is used to access the + application state via `request.app.state`. + + :returns: A list of lists containing the existance violations for the specified job. + + +.. py:function:: get_absence_violations(job_id: str, request: fastapi.Request) -> ReturnGraphType + + Retrieves the absence violations from the declarative model. + + :param job_id: The ID of the job for which to retrieve the violations. + :param request: The FastAPI request object. This is used to access the + application state via `request.app.state`. + + :returns: A list of lists containing the absence violations for the specified job. + + +.. py:function:: get_exactly_one_violations(job_id: str, request: fastapi.Request) -> ReturnGraphType + + Retrieves the exactly_one violations from the declarative model. + + :param job_id: The ID of the job for which to retrieve the violations. + :param request: The FastAPI request object. This is used to access the + application state via `request.app.state`. + + :returns: A list of lists containing the exactly_one violations for the specified job. + + +.. py:function:: get_init_violations(job_id: str, request: fastapi.Request) -> ReturnGraphType + + Retrieves the init violations from the declarative model. + + :param job_id: The ID of the job for which to retrieve the violations. + :param request: The FastAPI request object. This is used to access the + application state via `request.app.state`. + + :returns: A list of lists containing the init violations for the specified job. + + +.. py:function:: get_responded_existence_violations(job_id: str, request: fastapi.Request) -> ReturnGraphType + + Retrieves the responded_existence violations from the declarative model. + + :param job_id: The ID of the job for which to retrieve the violations. + :param request: The FastAPI request object. This is used to access the + application state via `request.app.state`. + + :returns: A list of lists containing the responded_existence violations for the specified job. + + +.. py:function:: get_coexistence_violations(job_id: str, request: fastapi.Request) -> ReturnGraphType + + Retrieves the coexistence violations from the declarative model. + + :param job_id: The ID of the job for which to retrieve the violations. + :param request: The FastAPI request object. This is used to access the + application state via `request.app.state`. + + :returns: A list of lists containing the coexistence violations for the specified job. + + +.. py:function:: get_response_violations(job_id: str, request: fastapi.Request) -> ReturnGraphType + + Retrieves the response violations from the declarative model. + + :param job_id: The ID of the job for which to retrieve the violations. + :param request: The FastAPI request object. This is used to access the + application state via `request.app.state`. + + :returns: A list of lists containing the response violations for the specified job. + + +.. py:function:: get_precedence_violations(job_id: str, request: fastapi.Request) -> ReturnGraphType + + Retrieves the precedence violations from the declarative model. + + :param job_id: The ID of the job for which to retrieve the violations. + :param request: The FastAPI request object. This is used to access the + application state via `request.app.state`. + + :returns: A list of lists containing the precedence violations for the specified job. + + +.. py:function:: get_succession_violations(job_id: str, request: fastapi.Request) -> ReturnGraphType + + Retrieves the succession violations from the declarative model. + + :param job_id: The ID of the job for which to retrieve the violations. + :param request: The FastAPI request object. This is used to access the + application state via `request.app.state`. + + :returns: A list of lists containing the succession violations for the specified job. + + +.. py:function:: get_altprecedence_violations(job_id: str, request: fastapi.Request) -> ReturnGraphType + + Retrieves the altprecedence violations from the declarative model. + + :param job_id: The ID of the job for which to retrieve the violations. + :param request: The FastAPI request object. This is used to access the + application state via `request.app.state`. + + :returns: A list of lists containing the altprecedence violations for the specified job. + + +.. py:function:: get_altsuccession_violations(job_id: str, request: fastapi.Request) -> ReturnGraphType + + Retrieves the altsuccession violations from the declarative model. + + :param job_id: The ID of the job for which to retrieve the violations. + :param request: The FastAPI request object. This is used to access the + application state via `request.app.state`. + + :returns: A list of lists containing the altsuccession violations for the specified job. + + +.. py:function:: get_chainresponse_violations(job_id: str, request: fastapi.Request) -> ReturnGraphType + + Retrieves the chainresponse violations from the declarative model. + + :param job_id: The ID of the job for which to retrieve the violations. + :param request: The FastAPI request object. This is used to access the + application state via `request.app.state`. + + :returns: A list of lists containing the chainresponse violations for the specified job. + + +.. py:function:: get_chainprecedence_violations(job_id: str, request: fastapi.Request) -> ReturnGraphType + + Retrieves the chainprecedence violations from the declarative model. + + :param job_id: The ID of the job for which to retrieve the violations. + :param request: The FastAPI request object. This is used to access the + application state via `request.app.state`. + + :returns: A list of lists containing the chainprecedence violations for the specified job. + + +.. py:function:: get_chainsuccession_violations(job_id: str, request: fastapi.Request) -> ReturnGraphType + + Retrieves the chainsuccession violations from the declarative model. + + :param job_id: The ID of the job for which to retrieve the violations. + :param request: The FastAPI request object. This is used to access the + application state via `request.app.state`. + + :returns: A list of lists containing the chainsuccession violations for the specified job. + + +.. py:function:: get_noncoexistence_violations(job_id: str, request: fastapi.Request) -> ReturnGraphType + + Retrieves the noncoexistence violations from the declarative model. + + :param job_id: The ID of the job for which to retrieve the violations. + :param request: The FastAPI request object. This is used to access the + application state via `request.app.state`. + + :returns: A list of lists containing the noncoexistence violations for the specified job. + + +.. py:function:: get_nonsuccession_violations(job_id: str, request: fastapi.Request) -> ReturnGraphType + + Retrieves the nonsuccession violations from the declarative model. + + :param job_id: The ID of the job for which to retrieve the violations. + :param request: The FastAPI request object. This is used to access the + application state via `request.app.state`. + + :returns: A list of lists containing the nonsuccession violations for the specified job. + + +.. py:function:: get_nonchainsuccession_violations(job_id: str, request: fastapi.Request) -> ReturnGraphType + + Retrieves the nonchainsuccession violations from the declarative model. + + :param job_id: The ID of the job for which to retrieve the violations. + :param request: The FastAPI request object. This is used to access the + application state via `request.app.state`. + + :returns: A list of lists containing the nonchainsuccession violations for the specified job. + + diff --git a/docs/source/autoapi/backend/api/modules/general_router/index.rst b/docs/source/autoapi/backend/api/modules/general_router/index.rst new file mode 100644 index 0000000..843acc9 --- /dev/null +++ b/docs/source/autoapi/backend/api/modules/general_router/index.rst @@ -0,0 +1,110 @@ +backend.api.modules.general_router +================================== + +.. py:module:: backend.api.modules.general_router + +.. autoapi-nested-parse:: + + Contains the router for general informtion API endpoints. + + + +Attributes +---------- + +.. autoapisummary:: + + backend.api.modules.general_router.router + backend.api.modules.general_router.TableType + backend.api.modules.general_router.GraphType + backend.api.modules.general_router.EndpointReturnType + + +Functions +--------- + +.. autoapisummary:: + + backend.api.modules.general_router.get_general_information + backend.api.modules.general_router.transform_counts_df_to_endpoint_format + backend.api.modules.general_router.transform_traces_df_to_endpoint_format + backend.api.modules.general_router.transform_dfg_df_to_endpoint_format + backend.api.modules.general_router.get_unique_activities + + +Module Contents +--------------- + +.. py:data:: router + +.. py:type:: TableType + :canonical: Dict[str, Union[List[str], List[List[str]]]] + + +.. py:type:: GraphType + :canonical: Dict[str, List[Dict[str, str]]] + + +.. py:type:: EndpointReturnType + :canonical: Dict[str, Union[List[TableType], List[GraphType]]] + + +.. py:function:: get_general_information(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager = Depends(get_celonis_connection)) -> EndpointReturnType + :async: + + + Fetches general information about the process from Celonis. + + This endpoint retrieves the number of cases, activities, trace variants, + and the Directly-Follows Graph (DFG) representation of the process. + + :param celonis: The CelonisConnectionManager. Defaults to + Depends(get_celonis_connection). + :type celonis: optional + + :returns: A dictionary containing tables with general information and a graph + representing the Directly-Follows Graph (DFG). + + +.. py:function:: transform_counts_df_to_endpoint_format(counts_df: pandas.DataFrame) -> TableType + + Transforms the counts DataFrame into a format suitable for the endpoint. + + :param counts_df: The DataFrame containing counts of cases, activities, and + trace variants. + + :returns: A dictionary encoding a table with general information. + + +.. py:function:: transform_traces_df_to_endpoint_format(traces_df: pandas.DataFrame) -> TableType + + Transforms the traces DataFrame into a format suitable for the endpoint. + + :param traces_df: The DataFrame containing traces and their counts. + + :returns: A dictionary encoding a table with trace variants and their counts. + + +.. py:function:: transform_dfg_df_to_endpoint_format(dfg_df: pandas.DataFrame, activities_df: pandas.DataFrame) -> GraphType + + Transforms the DFG DataFrame into a format suitable for the endpoint. + + This function encodes the DFG as a dictionary with nodes and edges, + where nodes represent unique activities and edges represent the + relationships between them with their respective counts. + + :param dfg_df: The DataFrame containing the DFG representation. + :param activities_df: The DataFrame containing the activities. + + :returns: A dictionary containing the encoded DFG. + + +.. py:function:: get_unique_activities(activities_df: pandas.DataFrame) -> List[str] + + Extracts unique activities from the activities DataFrame. + + :param activities_df: The DataFrame containing activities. + + :returns: A list of the unique activities. + + diff --git a/docs/source/autoapi/backend/api/modules/index.rst b/docs/source/autoapi/backend/api/modules/index.rst new file mode 100644 index 0000000..01db14d --- /dev/null +++ b/docs/source/autoapi/backend/api/modules/index.rst @@ -0,0 +1,19 @@ +backend.api.modules +=================== + +.. py:module:: backend.api.modules + + +Submodules +---------- + +.. toctree:: + :maxdepth: 1 + + /autoapi/backend/api/modules/declarative_router/index + /autoapi/backend/api/modules/general_router/index + /autoapi/backend/api/modules/log_skeleton_router/index + /autoapi/backend/api/modules/resource_based_router/index + /autoapi/backend/api/modules/temporal_profile_router/index + + diff --git a/docs/source/autoapi/backend/api/modules/log_skeleton_router/index.rst b/docs/source/autoapi/backend/api/modules/log_skeleton_router/index.rst new file mode 100644 index 0000000..0361454 --- /dev/null +++ b/docs/source/autoapi/backend/api/modules/log_skeleton_router/index.rst @@ -0,0 +1,99 @@ +backend.api.modules.log_skeleton_router +======================================= + +.. py:module:: backend.api.modules.log_skeleton_router + +.. autoapi-nested-parse:: + + Contains the routes for handling log skeletons and related operations. + + + +Attributes +---------- + +.. autoapisummary:: + + backend.api.modules.log_skeleton_router.router + backend.api.modules.log_skeleton_router.MODULE_NAME + + +Functions +--------- + +.. autoapisummary:: + + backend.api.modules.log_skeleton_router.compute_log_skeleton + backend.api.modules.log_skeleton_router.get_equivalence + backend.api.modules.log_skeleton_router.get_always_after + backend.api.modules.log_skeleton_router.get_always_before + backend.api.modules.log_skeleton_router.get_never_together + backend.api.modules.log_skeleton_router.get_directly_follows + backend.api.modules.log_skeleton_router.get_activity_frequencies + + +Module Contents +--------------- + +.. py:data:: router + +.. py:data:: MODULE_NAME + :value: 'log_skeleton' + + +.. py:function:: compute_log_skeleton(background_tasks: fastapi.BackgroundTasks, request: fastapi.Request, celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager = Depends(get_celonis_connection)) -> Dict[str, str] + :async: + + + Computes the log skeleton and stores it. + + The log skeleton is computed in the background and stored in the app state. + + :param background_tasks: The background tasks object. This is used to schedule + the computation of the log skeleton. + :param request: The FastAPI request object. This is used to access the + application state via `request.app.state`. + :param celonis: The CelonisManager dependency injection. + Defaults to Depends(get_celonis_connection). + :type celonis: optional + + :returns: A dictionary containing the job ID of the scheduled task. + + +.. py:function:: get_equivalence(job_id: str, request: fastapi.Request) -> dict + + Retrieves the equivalence relations from the log skeleton. + + :param job_id: The ID of the job for which to retrieve the equivalence relations. + :param request: The FastAPI request object. + + :returns: A JSON object with "tables" and "graphs" keys. + + +.. py:function:: get_always_after(job_id: str, request: fastapi.Request) -> dict + + Retrieves the always-after relations from the log skeleton. + + :returns: A dictionary with a "tables" list and optional "graphs" list. + + +.. py:function:: get_always_before(job_id: str, request: fastapi.Request) -> dict + + Retrieves the always-before relations from the log skeleton. + + +.. py:function:: get_never_together(job_id: str, request: fastapi.Request) -> dict + + Retrieves the never-together relations from the log skeleton. + + +.. py:function:: get_directly_follows(job_id: str, request: fastapi.Request) -> dict + + Retrieves the directly-follows relations from the log skeleton. + + +.. py:function:: get_activity_frequencies(job_id: str, request: fastapi.Request) -> dict + + Retrieves the activity frequencies from the log skeleton. + + diff --git a/docs/source/autoapi/backend/api/modules/resource_based_router/index.rst b/docs/source/autoapi/backend/api/modules/resource_based_router/index.rst new file mode 100644 index 0000000..a76f8db --- /dev/null +++ b/docs/source/autoapi/backend/api/modules/resource_based_router/index.rst @@ -0,0 +1,431 @@ +backend.api.modules.resource_based_router +========================================= + +.. py:module:: backend.api.modules.resource_based_router + +.. autoapi-nested-parse:: + + Contains the routes for handling resource-based conformance checking. + + + +Attributes +---------- + +.. autoapisummary:: + + backend.api.modules.resource_based_router.ReturnGraphType + backend.api.modules.resource_based_router.router + backend.api.modules.resource_based_router.MODULE_NAME + + +Functions +--------- + +.. autoapisummary:: + + backend.api.modules.resource_based_router.compute_sna_metrics + backend.api.modules.resource_based_router.get_handover_of_work_metric + backend.api.modules.resource_based_router.get_subcontracting_metric + backend.api.modules.resource_based_router.get_working_together_metric + backend.api.modules.resource_based_router.get_similar_activities_metric + backend.api.modules.resource_based_router.get_organizational_roles_result + backend.api.modules.resource_based_router.get_distinct_activities + backend.api.modules.resource_based_router.get_distinct_activities_pql + backend.api.modules.resource_based_router.get_resource_activity_frequency + backend.api.modules.resource_based_router.get_resource_activity_frequency_pql + backend.api.modules.resource_based_router.get_resource_activity_completions + backend.api.modules.resource_based_router.get_resource_activity_completions_pql + backend.api.modules.resource_based_router.get_resource_case_completions + backend.api.modules.resource_based_router.get_resource_case_completions_pql + backend.api.modules.resource_based_router.get_resource_fraction_case_completions + backend.api.modules.resource_based_router.get_resource_fraction_case_completions_pql + backend.api.modules.resource_based_router.get_resource_average_workload + backend.api.modules.resource_based_router.get_resource_average_workload_pql + backend.api.modules.resource_based_router.get_resource_multitasking + backend.api.modules.resource_based_router.get_resource_average_activity_duration + backend.api.modules.resource_based_router.get_resource_average_case_duration + backend.api.modules.resource_based_router.get_interaction_of_two_resources + backend.api.modules.resource_based_router.get_interaction_of_two_resources_pql + backend.api.modules.resource_based_router.get_resource_social_position + backend.api.modules.resource_based_router.get_group_relative_focus_metric + backend.api.modules.resource_based_router.get_group_relative_stake_metric + backend.api.modules.resource_based_router.get_group_coverage_metric + backend.api.modules.resource_based_router.get_group_member_contribution_metric + + +Module Contents +--------------- + +.. py:type:: ReturnGraphType + :canonical: Dict[str, List[Dict[str, List[Union[str, Dict[str, str]]]]]] + + +.. py:data:: router + +.. py:data:: MODULE_NAME + :value: 'resource_based' + + +.. py:function:: compute_sna_metrics(background_tasks: fastapi.BackgroundTasks, request: fastapi.Request, celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager = Depends(get_celonis_connection)) -> Dict[str, str] + :async: + + + Computes the SNA metrics and stores it. + + :param background_tasks: The background tasks manager. + :param request: The FastAPI request object. + :param celonis: The Celonis connection manager instance. + + :returns: A dictionary containing the job ID of the scheduled task. + + +.. py:function:: get_handover_of_work_metric(job_id: str, request: fastapi.Request) -> Dict[str, List[Dict[str, List[Any]]]] + :async: + + + Retrieves the computed Handover of Work SNA metric and returns it. + + In a frontend-compatible format. + + +.. py:function:: get_subcontracting_metric(job_id: str, request: fastapi.Request) -> Dict[str, List[Dict[str, List[Any]]]] + :async: + + + Returns subcontracting metric in table/graph format. + + +.. py:function:: get_working_together_metric(job_id: str, request: fastapi.Request) -> Dict[str, List[Dict[str, List[Any]]]] + :async: + + + Returns working together metric in table/graph format. + + +.. py:function:: get_similar_activities_metric(job_id: str, request: fastapi.Request) -> Dict[str, List[Dict[str, List[Any]]]] + :async: + + + Returns similar activities metric in table/graph format. + + +.. py:function:: get_organizational_roles_result(job_id: str, request: fastapi.Request) -> List[backend.api.models.schemas.resource_based_models.OrganizationalRole] + :async: + + + Retrieves the computed organizational roles. + + :param job_id: The ID of the job to retrieve the organizational roles for. + :param request: The FastAPI request object. + + :returns: A list of OrganizationalRole objects representing the discovered roles. + + +.. py:function:: get_distinct_activities(resource: str = Query(..., description='The resource identifier.'), start_time: str = Query(..., description='Start time.'), end_time: str = Query(..., description='End time.'), celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager = Depends(get_celonis_connection)) -> int + :async: + + + Retrieves the number of distinct activities. + + :param start_time: The start time of the range. + :param end_time: The end time of the range. + :param resource: The resource for which to calculate the number of + distinct activities. + :param celonis: The Celonis connection manager instance. + + :returns: The number of distinct activities for the specified resource. + + +.. py:function:: get_distinct_activities_pql(resource: str = Query(..., description='The resource identifier.'), start_time: str = Query(..., description='Start time.'), end_time: str = Query(..., description='End time.'), celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager = Depends(get_celonis_connection)) -> int + :async: + + + Retrieves the number of distinct activities via a pql query. + + :param start_time: The start time of the range. + :param end_time: The end time of the range. + :param resource: The resource for which to calculate the number of + distinct activities. + :param celonis: The Celonis connection manager instance. + + :returns: The number of distinct activities for the specified resource. + + +.. py:function:: get_resource_activity_frequency(resource: str = Query(..., description='The resource identifier.'), activity: str = Query(..., description='The specific activity name.'), start_time: str = Query(..., description='Start time of the interval.'), end_time: str = Query(..., description='End time of the interval.'), celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager = Depends(get_celonis_connection)) -> float + :async: + + + Retrieves the activity frequency for a given resource and activity. + + :param resource: The resource for which to calculate the activity frequency. + :param activity: The activity for which to calculate the frequency. + :param start_time: The start time of the interval. + :param end_time: The end time of the interval. + :param celonis: The Celonis connection manager instance. + + :returns: A float indicating the activity frequency. + + +.. py:function:: get_resource_activity_frequency_pql(resource: str = Query(..., description='The resource identifier.'), activity: str = Query(..., description='The specific activity name.'), start_time: str = Query(..., description='Start time of the interval.'), end_time: str = Query(..., description='End time of the interval.'), celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager = Depends(get_celonis_connection)) -> float + :async: + + + Retrieves the activity frequency for an activity via a PQL query. + + :param resource: The resource for which to calculate the activity frequency. + :param activity: The activity for which to calculate the frequency. + :param start_time: The start time of the interval. + :param end_time: The end time of the interval. + :param celonis: The Celonis connection manager instance. + + :returns: A float indicating the activity frequency. + + +.. py:function:: get_resource_activity_completions(resource: str = Query(..., description='The resource identifier.'), start_time: str = Query(..., description='Start time of the interval.'), end_time: str = Query(..., description='End time of the interval.'), celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager = Depends(get_celonis_connection)) -> int + :async: + + + Retrieves the number of activity instances completed by a resource. + + :param resource: The resource for which to calculate activity completions. + :param start_time: The start time of the interval. + :param end_time: The end time of the interval. + :param celonis: The Celonis connection manager instance. + + :returns: An integer indicating the number of activity completions. + + +.. py:function:: get_resource_activity_completions_pql(resource: str = Query(..., description='The resource identifier.'), start_time: str = Query(..., description='Start time of the interval.'), end_time: str = Query(..., description='End time of the interval.'), celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager = Depends(get_celonis_connection)) -> int + :async: + + + Retrieves the number of activity instances completed via a PQL query. + + :param resource: The resource for which to calculate activity completions. + :param start_time: The start time of the interval. + :param end_time: The end time of the interval. + :param celonis: The Celonis connection manager instance. + + :returns: An integer indicating the number of activity completions. + + +.. py:function:: get_resource_case_completions(resource: str = Query(..., description='The resource identifier.'), start_time: str = Query(..., description='Start time of the interval.'), end_time: str = Query(..., description='End time of the interval.'), celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager = Depends(get_celonis_connection)) -> int + :async: + + + Retrieves the number of cases completed by a resource. + + :param resource: The resource for which to calculate case completions. + :param start_time: The start time of the interval. + :param end_time: The end time of the interval. + :param celonis: The Celonis connection manager instance. + + :returns: An integer indicating the number of case completions involving the resource. + + +.. py:function:: get_resource_case_completions_pql(resource: str = Query(..., description='The resource identifier.'), start_time: str = Query(..., description='Start time of the interval.'), end_time: str = Query(..., description='End time of the interval.'), celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager = Depends(get_celonis_connection)) -> int + :async: + + + Retrieves the number of cases completed by a resource via a PQL query. + + :param resource: The resource for which to calculate case completions. + :param start_time: The start time of the interval. + :param end_time: The end time of the interval. + :param celonis: The Celonis connection manager instance. + + :returns: An integer indicating the number of case completions involving the resource. + + +.. py:function:: get_resource_fraction_case_completions(resource: str = Query(..., description='The resource identifier.'), start_time: str = Query(..., description='Start time of the interval.'), end_time: str = Query(..., description='End time of the interval.'), celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager = Depends(get_celonis_connection)) -> float + :async: + + + Retrieves the fraction of cases completed by a resource. + + :param resource: The resource for which to calculate the fraction of case completions. + :param start_time: The start time of the interval. + :param end_time: The end time of the interval. + :param celonis: The Celonis connection manager instance. + + :returns: A float indicating the fraction of case completions involving the resource. + + +.. py:function:: get_resource_fraction_case_completions_pql(resource: str = Query(..., description='The resource identifier.'), start_time: str = Query(..., description='Start time of the interval.'), end_time: str = Query(..., description='End time of the interval.'), celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager = Depends(get_celonis_connection)) -> float + :async: + + + Retrieves the fraction of cases completed by a resource via a PQL query. + + :param resource: The resource for which to calculate the fraction of case completions. + :param start_time: The start time of the interval. + :param end_time: The end time of the interval. + :param celonis: The Celonis connection manager instance. + + :returns: A float indicating the fraction of case completions involving the resource. + + +.. py:function:: get_resource_average_workload(resource: str = Query(..., description='The resource identifier.'), start_time: str = Query(..., description='Start time of the interval.'), end_time: str = Query(..., description='End time of the interval.'), celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager = Depends(get_celonis_connection)) -> float + :async: + + + Retrieves the average workload for a given resource in a time interval. + + :param resource: The resource for which to calculate the average workload. + :param start_time: The start time of the interval. + :param end_time: The end time of the interval. + :param celonis: The Celonis connection manager instance. + + :returns: A float indicating the average workload. + + +.. py:function:: get_resource_average_workload_pql(resource: str = Query(..., description='The resource identifier.'), start_time: str = Query(..., description='Start time of the interval.'), end_time: str = Query(..., description='End time of the interval.'), celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager = Depends(get_celonis_connection)) -> float + :async: + + + Retrieves the average workload for a resource via a PQL query. + + :param resource: The resource for which to calculate the average workload. + :param start_time: The start time of the interval. + :param end_time: The end time of the interval. + :param celonis: The Celonis connection manager instance. + + :returns: A float indicating the average workload. + + +.. py:function:: get_resource_multitasking(resource: str = Query(..., description='The resource identifier.'), start_time: str = Query(..., description='Start time of the interval.'), end_time: str = Query(..., description='End time of the interval.'), celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager = Depends(get_celonis_connection)) -> float + :async: + + + Retrieves the multitasking metric for a given resource. + + :param resource: The resource for which to calculate multitasking. + :param start_time: The start time of the interval. + :param end_time: The end time of the interval. + :param celonis: The Celonis connection manager instance. + + :returns: A float indicating the multitasking metric. + + +.. py:function:: get_resource_average_activity_duration(resource: str = Query(..., description='The resource identifier.'), activity: str = Query(..., description='The specific activity name.'), start_time: str = Query(..., description='Start time of the interval.'), end_time: str = Query(..., description='End time of the interval.'), celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager = Depends(get_celonis_connection)) -> float + :async: + + + Retrieves the average duration for an activity completed by a resource. + + :param resource: The resource involved. + :param activity: The activity name. + :param start_time: The start time of the interval. + :param end_time: The end time of the interval. + :param celonis: The Celonis connection manager instance. + + :returns: A float indicating the average duration of the activity for the resource. + + +.. py:function:: get_resource_average_case_duration(resource: str = Query(..., description='The resource identifier.'), start_time: str = Query(..., description='Start time of the interval.'), end_time: str = Query(..., description='End time of the interval.'), celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager = Depends(get_celonis_connection)) -> float + :async: + + + Retrieves the average duration of cases completed by a resource. + + :param resource: The resource involved. + :param start_time: The start time of the interval. + :param end_time: The end time of the interval. + :param celonis: The Celonis connection manager instance. + + :returns: A float indicating the average duration of cases involving the resource. + + +.. py:function:: get_interaction_of_two_resources(resource1: str = Query(..., description='The first resource identifier.'), resource2: str = Query(..., description='The second resource identifier.'), start_time: str = Query(..., description='Start time of the interval.'), end_time: str = Query(..., description='End time of the interval.'), celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager = Depends(get_celonis_connection)) -> float + :async: + + + Retrieves the interaction between two resources. + + :param resource1: The first resource. + :param resource2: The second resource. + :param start_time: The start time of the interval. + :param end_time: The end time of the interval. + :param celonis: The Celonis connection manager instance. + + :returns: A float indicating the interaction (number of common cases) between the two resources. + + +.. py:function:: get_interaction_of_two_resources_pql(resource1: str = Query(..., description='The first resource identifier.'), resource2: str = Query(..., description='The second resource identifier.'), start_time: str = Query(..., description='Start time of the interval.'), end_time: str = Query(..., description='End time of the interval.'), celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager = Depends(get_celonis_connection)) -> float + :async: + + + Retrieves the interaction between two resources via a PQL query. + + :param resource1: The first resource. + :param resource2: The second resource. + :param start_time: The start time of the interval. + :param end_time: The end time of the interval. + :param celonis: The Celonis connection manager instance. + + :returns: A float indicating the interaction (number of common cases) between the two resources. + + +.. py:function:: get_resource_social_position(resource: str = Query(..., description='The resource identifier.'), start_time: str = Query(..., description='Start time of the interval.'), end_time: str = Query(..., description='End time of the interval.'), celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager = Depends(get_celonis_connection)) -> float + :async: + + + Retrieves the social position of a given resource in a time interval. + + :param resource: The resource for which to calculate the social position. + :param start_time: The start time of the interval. + :param end_time: The end time of the interval. + :param celonis: The Celonis connection manager instance. + + :returns: A float indicating the social position of the resource. + + +.. py:function:: get_group_relative_focus_metric(job_id: str, request: fastapi.Request) -> Dict[str, Dict[str, float]] + :async: + + + Retrieves the Group Relative Focus metric. + + :param job_id: The ID of the job to retrieve the metric for. + :param request: The FastAPI request object. + + :returns: A dictionary containing the Group Relative Focus metric. + + +.. py:function:: get_group_relative_stake_metric(job_id: str, request: fastapi.Request) -> Dict[str, Dict[str, float]] + :async: + + + Retrieves the Group Relative Stake metric. + + :param job_id: The ID of the job to retrieve the metric for. + :param request: The FastAPI request object. + + :returns: A dictionary containing the Group Relative Stake metric. + + +.. py:function:: get_group_coverage_metric(job_id: str, request: fastapi.Request) -> Dict[str, Dict[str, float]] + :async: + + + Retrieves the Group Coverage metric. + + :param job_id: The ID of the job to retrieve the metric for. + :param request: The FastAPI request object. + + :returns: A dictionary containing the Group Coverage metric. + + +.. py:function:: get_group_member_contribution_metric(job_id: str, request: fastapi.Request) -> Dict[str, Dict[str, Dict[str, int]]] + :async: + + + Retrieves the Group Member Contribution metric. + + :param job_id: The ID of the job to retrieve the metric for. + :param request: The FastAPI request object. + + :returns: A dictionary containing the Group Member Contribution metric. + + diff --git a/docs/source/autoapi/backend/api/modules/temporal_profile_router/index.rst b/docs/source/autoapi/backend/api/modules/temporal_profile_router/index.rst new file mode 100644 index 0000000..14ac828 --- /dev/null +++ b/docs/source/autoapi/backend/api/modules/temporal_profile_router/index.rst @@ -0,0 +1,69 @@ +backend.api.modules.temporal_profile_router +=========================================== + +.. py:module:: backend.api.modules.temporal_profile_router + +.. autoapi-nested-parse:: + + Contains the routes for temporal conformance checking. + + + +Attributes +---------- + +.. autoapisummary:: + + backend.api.modules.temporal_profile_router.router + backend.api.modules.temporal_profile_router.MODULE_NAME + + +Functions +--------- + +.. autoapisummary:: + + backend.api.modules.temporal_profile_router.compute_temporal_conformance_result + backend.api.modules.temporal_profile_router.get_temporal_conformance_result + + +Module Contents +--------------- + +.. py:data:: router + +.. py:data:: MODULE_NAME + :value: 'temporal' + + +.. py:function:: compute_temporal_conformance_result(background_tasks: fastapi.BackgroundTasks, request: fastapi.Request, zeta: float = Query(0.5, description='Zeta value for temporal profile conformance checking', gt=0.0), celonis_connection: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager = Depends(get_celonis_connection)) -> Dict[str, str] + :async: + + + Computes the temporal conformance result and stores it. + + :param background_tasks: The background tasks manager. + :param request: The FastAPI request object. + :param zeta: The zeta value used for temporal profile conformance checking. + :param celonis_connection: The Celonis connection manager instance. + + :returns: A dictionary containing the job ID of the scheduled task. + + +.. py:function:: get_temporal_conformance_result(job_id: str, request: fastapi.Request) -> dict + :async: + + + Retrieves the temporal conformance result for a given job ID. + + This result is expected to be a list of lists of tuples, representing + the raw output from TemporalProfile.get_temporal_conformance_result(). + + :param job_id: The ID of the job for which to retrieve the result. + :param request: The FastAPI request object. + + :returns: The temporal conformance result as a list of lists of tuples. + + :raises HTTPException: If the job is not found or if the result is not available. + + diff --git a/docs/source/autoapi/backend/api/setup/index.rst b/docs/source/autoapi/backend/api/setup/index.rst new file mode 100644 index 0000000..22733f5 --- /dev/null +++ b/docs/source/autoapi/backend/api/setup/index.rst @@ -0,0 +1,71 @@ +backend.api.setup +================= + +.. py:module:: backend.api.setup + +.. autoapi-nested-parse:: + + Contains a router for the setup of the application. + + It contains several 'utility' endpoints that are used in the setup of + the application and the general configuration for event logs. + + + +Attributes +---------- + +.. autoapisummary:: + + backend.api.setup.router + backend.api.setup.ENV_PATH + backend.api.setup.LOCK_PATH + + +Functions +--------- + +.. autoapisummary:: + + backend.api.setup.celonis_credentials + backend.api.setup.get_column_names + + +Module Contents +--------------- + +.. py:data:: router + +.. py:data:: ENV_PATH + +.. py:data:: LOCK_PATH + +.. py:function:: celonis_credentials(credentials: backend.api.models.schemas.setup_models.CelonisCredentials) + :async: + + + Saves the Celonis credentials to the .env file. + + :param credentials: The Celonis credentials to be saved. This should be a + CelonisCredentials object. + + :returns: A dictionary containing a message indicating the success of the + operation. + + +.. py:function:: get_column_names(request: fastapi.Request) -> Dict[str, List[str]] + :async: + + + Provides the column names of the current log. + + :param request: The FastAPI request object. This is used to access the app state + and retrieve the current log columns. + + :returns: A dictionary containing the column names of the current log. + + :raises HTTPException: If no log columns are found in the app state, a 400 error is raised + :raises with a message indicating that no log columns were found. The user should: + :raises upload a log first.: + + diff --git a/docs/source/autoapi/backend/api/tasks/declarative_constraints_tasks/index.rst b/docs/source/autoapi/backend/api/tasks/declarative_constraints_tasks/index.rst new file mode 100644 index 0000000..1363d3b --- /dev/null +++ b/docs/source/autoapi/backend/api/tasks/declarative_constraints_tasks/index.rst @@ -0,0 +1,33 @@ +backend.api.tasks.declarative_constraints_tasks +=============================================== + +.. py:module:: backend.api.tasks.declarative_constraints_tasks + +.. autoapi-nested-parse:: + + Contains the tasks for handling log skeletons and related operations. + + + +Functions +--------- + +.. autoapisummary:: + + backend.api.tasks.declarative_constraints_tasks.compute_and_store_declarative_constraints + + +Module Contents +--------------- + +.. py:function:: compute_and_store_declarative_constraints(app: fastapi.FastAPI, job_id: str, celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager, min_support_ratio: float = 0.3, min_confidence_ratio: float = 0.75) -> None + + Computes the declarative constraints and stores it in the app state. + + :param app: The FastAPI app instance. + :param job_id: The ID of the job to be computed. + :param celonis: The CelonisConnectionManager instance. + :param min_support_ratio: The minimum support ratio for the constraints. + :param min_confidence_ratio: The minimum confidence ratio for the constraints. + + diff --git a/docs/source/autoapi/backend/api/tasks/index.rst b/docs/source/autoapi/backend/api/tasks/index.rst new file mode 100644 index 0000000..c71a3ad --- /dev/null +++ b/docs/source/autoapi/backend/api/tasks/index.rst @@ -0,0 +1,18 @@ +backend.api.tasks +================= + +.. py:module:: backend.api.tasks + + +Submodules +---------- + +.. toctree:: + :maxdepth: 1 + + /autoapi/backend/api/tasks/declarative_constraints_tasks/index + /autoapi/backend/api/tasks/log_skeleton_tasks/index + /autoapi/backend/api/tasks/resource_based_tasks/index + /autoapi/backend/api/tasks/temporal_profile_tasks/index + + diff --git a/docs/source/autoapi/backend/api/tasks/log_skeleton_tasks/index.rst b/docs/source/autoapi/backend/api/tasks/log_skeleton_tasks/index.rst new file mode 100644 index 0000000..0feeaec --- /dev/null +++ b/docs/source/autoapi/backend/api/tasks/log_skeleton_tasks/index.rst @@ -0,0 +1,31 @@ +backend.api.tasks.log_skeleton_tasks +==================================== + +.. py:module:: backend.api.tasks.log_skeleton_tasks + +.. autoapi-nested-parse:: + + Contains the tasks for handling log skeletons and related operations. + + + +Functions +--------- + +.. autoapisummary:: + + backend.api.tasks.log_skeleton_tasks.compute_and_store_log_skeleton + + +Module Contents +--------------- + +.. py:function:: compute_and_store_log_skeleton(app: fastapi.FastAPI, job_id: str, celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager) -> None + + Computes the log skeleton and stores it in the app state. + + :param app: The FastAPI app instance. + :param job_id: The ID of the job to be computed. + :param celonis: The CelonisConnectionManager instance. + + diff --git a/docs/source/autoapi/backend/api/tasks/resource_based_tasks/index.rst b/docs/source/autoapi/backend/api/tasks/resource_based_tasks/index.rst new file mode 100644 index 0000000..8a4b9f2 --- /dev/null +++ b/docs/source/autoapi/backend/api/tasks/resource_based_tasks/index.rst @@ -0,0 +1,34 @@ +backend.api.tasks.resource_based_tasks +====================================== + +.. py:module:: backend.api.tasks.resource_based_tasks + +.. autoapi-nested-parse:: + + Contains the tasks for handling resource-based conformance checking. + + + +Functions +--------- + +.. autoapisummary:: + + backend.api.tasks.resource_based_tasks.compute_and_store_resource_based_metrics + + +Module Contents +--------------- + +.. py:function:: compute_and_store_resource_based_metrics(app: fastapi.FastAPI, job_id: str, celonis_connection: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager) -> None + + Computes the resource-based metrics and stores it in the app state. + + :param app: The FastAPI application instance. + :param job_id: The job ID for tracking the task. + :param celonis_connection: The CelonisConnectionManager instance. + :param resource_column_name: The name of the resource column in the DataFrame. + + :raises RuntimeError: If the DataFrame is empty. + + diff --git a/docs/source/autoapi/backend/api/tasks/temporal_profile_tasks/index.rst b/docs/source/autoapi/backend/api/tasks/temporal_profile_tasks/index.rst new file mode 100644 index 0000000..a1088bf --- /dev/null +++ b/docs/source/autoapi/backend/api/tasks/temporal_profile_tasks/index.rst @@ -0,0 +1,35 @@ +backend.api.tasks.temporal_profile_tasks +======================================== + +.. py:module:: backend.api.tasks.temporal_profile_tasks + +.. autoapi-nested-parse:: + + Contains the tasks for temporal profile based conformance checking. + + + +Functions +--------- + +.. autoapisummary:: + + backend.api.tasks.temporal_profile_tasks.compute_and_store_temporal_conformance_result + + +Module Contents +--------------- + +.. py:function:: compute_and_store_temporal_conformance_result(app: fastapi.FastAPI, job_id: str, celonis_connection: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager, zeta: float) -> None + + Computes the temporal conformance result and stores it in the app state. + + :param app: The FastAPI application instance. + :type app: FastAPI + :param job_id: The ID of the job. + :param celonis_connection: The Celonis connection manager instance. + :param zeta: The zeta value used for temporal profile conformance checking. + + :raises RuntimeError: If the DataFrame is empty. + + diff --git a/docs/source/autoapi/backend/celonis_connection/celonis_connection_manager/index.rst b/docs/source/autoapi/backend/celonis_connection/celonis_connection_manager/index.rst new file mode 100644 index 0000000..0a54274 --- /dev/null +++ b/docs/source/autoapi/backend/celonis_connection/celonis_connection_manager/index.rst @@ -0,0 +1,214 @@ +backend.celonis_connection.celonis_connection_manager +===================================================== + +.. py:module:: backend.celonis_connection.celonis_connection_manager + +.. autoapi-nested-parse:: + + The module provides a class to manage the connection to Celonis. + + It includes methods to create tables, add data frames, and retrieve data + from Celonis via the help of PQL queries. It relies on the PyCelonis + library. + + + +Classes +------- + +.. autoapisummary:: + + backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager + + +Module Contents +--------------- + +.. py:class:: CelonisConnectionManager(base_url: str, data_pool_name: str, data_model_name: str, api_token: str) + + Class to manage the connection to Celonis. + + + .. py:attribute:: base_url + :type: str + + + .. py:attribute:: api_token + :type: str + + + .. py:attribute:: data_pool_name + :type: str + + + .. py:attribute:: data_model_name + :type: str + + + .. py:attribute:: data_frame + :type: pandas.DataFrame + + + .. py:attribute:: celonis + + + .. py:attribute:: data_pool + :value: None + + + + .. py:attribute:: data_model + :value: None + + + + .. py:method:: find_data_pool(data_pool_name: str) -> pycelonis.ems.data_integration.data_pool.DataPool + + Find a data pool by name. + + It will return the datapool if it is found or create a new one if it does not exist. + + :param data_pool_name: Name of the data pool to find. + + :returns: Data pool object. + + + + .. py:method:: find_data_model(data_model_name: str) -> Union[pycelonis.ems.data_integration.data_model.DataModel, None] + + Find a data model by name. + + It will return the data model if it is found or create a new one if it does not exist. + If the data pool does not exist, it will return None. + + :param data_model_name: Name of the data model to find. + + :returns: Data model object or None. + + + + .. py:method:: create_table(table_name: str = 'ACTIVITIES', case_id_column: str = 'case:concept:name', activity_column: str = 'concept:name', timestamp_column: str = 'time:timestamp', drop_if_exists: bool = True, force: bool = True) -> None + + Add a table to the data pool. + + It will create a new table in the data pool and add it to the + data model. If the table already exists, it will delete it and + create a new one. The function then uses the specified columns + to create a process configuration in the data model and reload it. + + :param table_name: Name of the table to create. + :param case_id_column: Name of the case ID column. + :param activity_column: Name of the activity column. + :param timestamp_column: Name of the timestamp column. + :param drop_if_exists: If True, drop the table if it already exists. + :param force: If True, force the creation of the table. + + :returns: None + + + + .. py:method:: add_dataframe(df: pandas.DataFrame) -> None + + Add a DataFrame to the CelonisConnection object. + + Allows the data frame to be created outside of the class and + then passed in. This is allows for more flexibility in how and + when the data frame is created and used. + + :param df: DataFrame to add to the CelonisConnection object. + + :returns: None + + + + .. py:method:: get_basic_dataframe_from_celonis(table_name: str = 'ACTIVITIES') -> Union[pandas.DataFrame, None] + + Get the dataframe from the data model in Celonis. + + It will create a new dataframe with the columns "case:concept:name", + "concept:name" and "time:timestamp" from the table in the data model. + Returns None if the data model does not exist or the table is not + found. + + :param table_name: Name of the table to get. Default is "ACTIVITIES". + + :returns: DataFrame object or None. + + + + .. py:method:: get_dataframe_with_resource_group_from_celonis(table_name: str = 'ACTIVITIES') -> Union[pandas.DataFrame, None] + + Get the dataframe from the data model in Celonis. + + It will create a new dataframe with the columns "case:concept:name", + "concept:name", "time:timestamp", "org:resource", and "org:group" + from the table in the data model. Returns None if the data model + does not exist or the table is not found. + + :param table_name: Name of the table to get. Default is "ACTIVITIES". + + :returns: DataFrame object or None. + + + + .. py:method:: get_dataframe_from_celonis(pql_query: collections.abc.MutableMapping[str, saolapy.types.SeriesLike | pycelonis.ems.data_integration.data_model_table_column.DataModelTableColumn]) -> Union[pandas.DataFrame, None] + + Get the dataframe from the data model in Celonis. + + It will create a new dataframe with the columns from the PQL + query. The PQL query must be a dictionary with the column names + as keys and the column values as values. The column values can + be either a string or a DataModelTableColumn object. The + function will return None if the data model does not exist or + the PQL query is empty. + + :param pql_query: PQL query used to define the dataframe. + + :returns: DataFrame object or None. + + + + .. py:method:: get_table(table_name: str = 'ACTIVITIES') -> Union[pycelonis.ems.data_integration.data_model_table.DataModelTable, None] + + Get the table from the data model in Celonis. + + It will return the table object if it is found or None if it + does not exist. The table name must be the same as the one used + in the data model. + + :param table_name: Name of the table to get. Default is "ACTIVITIES". + + :returns: DataModelTable object or None. + + + + .. py:method:: get_table_columns(table_name: str = 'ACTIVITIES') -> Union[pycelonis_core.base.collection.CelonisCollection[pycelonis.ems.data_integration.data_model_table_column.DataModelTableColumn], None] + + Get the columns of the table from the data model in Celonis. + + It will return the columns of the table object if it is found or + None if it does not exist. The table name must be the same as the + one used in the data model. + + :param table_name: Name of the table to get. Default is "ACTIVITIES". + + :returns: List of DataModelTableColumn objects or None. + + + + .. py:method:: get_data_pool() -> Union[pycelonis.ems.data_integration.data_pool.DataPool, None] + + Get the data pool object. + + :returns: Data pool object or None. + + + + .. py:method:: get_data_model() -> Union[pycelonis.ems.data_integration.data_model.DataModel, None] + + Get the data model object. + + :returns: Data model object or None. + + + diff --git a/docs/source/autoapi/backend/celonis_connection/index.rst b/docs/source/autoapi/backend/celonis_connection/index.rst new file mode 100644 index 0000000..c3b82aa --- /dev/null +++ b/docs/source/autoapi/backend/celonis_connection/index.rst @@ -0,0 +1,15 @@ +backend.celonis_connection +========================== + +.. py:module:: backend.celonis_connection + + +Submodules +---------- + +.. toctree:: + :maxdepth: 1 + + /autoapi/backend/celonis_connection/celonis_connection_manager/index + + diff --git a/docs/source/autoapi/backend/conformance_checking/declarative_constraints/index.rst b/docs/source/autoapi/backend/conformance_checking/declarative_constraints/index.rst new file mode 100644 index 0000000..a3da33c --- /dev/null +++ b/docs/source/autoapi/backend/conformance_checking/declarative_constraints/index.rst @@ -0,0 +1,315 @@ +backend.conformance_checking.declarative_constraints +==================================================== + +.. py:module:: backend.conformance_checking.declarative_constraints + +.. autoapi-nested-parse:: + + Contains functionality for declarative conformance checking. + + This module defines the DeclerativeConstraints class which uses PM4Py to + discover declarative profiles from event logs and checks conformance + based on the discovered declarative profiles. + + + +Attributes +---------- + +.. autoapisummary:: + + backend.conformance_checking.declarative_constraints.DeclareModelType + backend.conformance_checking.declarative_constraints.ReturnGraphType + + +Classes +------- + +.. autoapisummary:: + + backend.conformance_checking.declarative_constraints.DeclarativeConstraints + + +Module Contents +--------------- + +.. py:type:: DeclareModelType + :canonical: Dict[str, Dict[Any, Dict[str, int]]] + + +.. py:type:: ReturnGraphType + :canonical: Dict[str, List[Dict[str, List[Union[str, Dict[str, str]]]]]] + + +.. py:class:: DeclarativeConstraints(log: pandas.DataFrame, min_support_ratio: Optional[float] = 0.3, min_confidence_ratio: Optional[float] = 0.75, case_id_col: Optional[str] = None, activity_col: Optional[str] = None, timestamp_col: Optional[str] = None) + + Represents the declarative constraints of an event log. + + Attributes : + log: The main event log. + min_support_ratio: The minimum support ratio for discovering rules. + min_confidence_ratio: The minimum confidence ratio for discovering rules. + + + .. py:attribute:: log + + + .. py:attribute:: min_support_ratio + :value: 0.3 + + + + .. py:attribute:: min_confidence_ratio + :value: 0.75 + + + + .. py:attribute:: declare_model + :type: Optional[DeclareModelType] + :value: None + + + + .. py:attribute:: case_id_col + :type: Optional[str] + :value: None + + + + .. py:attribute:: activity_col + :type: Optional[str] + :value: None + + + + .. py:attribute:: timestamp_col + :type: Optional[str] + :value: None + + + + .. py:attribute:: valid_rules + :value: ['existence', 'absence', 'exactly_one', 'init', 'responded_existence', 'coexistence',... + + + + .. py:attribute:: conf_results_memory + :type: Dict[str, None] + + + .. py:method:: run_model(log: Optional[pandas.DataFrame] = None, min_support_ratio: Optional[float] = None, min_confidence_ratio: Optional[float] = None) -> None + + Runs the declarative model on the event log. + + It stores the result in memory. + + :param log: The event log to use. + :param min_support_ratio: The minimum support ratio for discovering rules. + :param min_confidence_ratio: The minimum confidence ratio for discovering rules. + + + + .. py:method:: rule_specific_violation_summary(declare_model: Optional[DeclareModelType] = None, log: Optional[pandas.DataFrame] = None, rule_name: Optional[str] = None, verbose: bool = False) -> ReturnGraphType + + Summarizes number of violations for a declarative rule. + + This function does not access memory variable, so it runs the rule from + scratch even if results are pre-computed and stored. + + :param declare_model: The Declare model. If None, uses the default model. + :param log: The event log. If None, uses the default log. + :param rule_name: Name of the rule to check. + :param verbose: Whether to print details for debugging. + + :returns: Summary with graph and table information of rule violations. + + :raises ValueError: If an unsupported rule name is provided. + + + + .. py:method:: get_declarative_conformance_diagnostics(rule_name: str, run_from_scratch: Optional[bool] = False) -> ReturnGraphType + + Gets conformance diagnostics for a specific declarative rule. + + Check for results stored in memory and runs conformance checking of any + rule only if results previously not stored in memory. + + :param rule_name: The name of the declarative rule to analyze. + :param run_from_scratch: If True, re-evaluates the rule even if results + stored. + + :returns: Cached or newly generated rule violation summary. + + :raises ValueError: If the rule name is not supported. + + + + .. py:method:: declarative_conformance_for_existence() -> ReturnGraphType + + Gets results for the existence rule. + + :returns: For existance rule. + :rtype: Dict + + + + .. py:method:: declarative_conformance_for_absence() -> ReturnGraphType + + Gets results for the absence rule. + + :returns: For absence rule. + :rtype: Dict + + + + .. py:method:: declarative_conformance_for_exactly_one() -> ReturnGraphType + + Gets results for the exactly_one rule. + + :returns: For exactly_one rule. + :rtype: Dict + + + + .. py:method:: declarative_conformance_for_init() -> ReturnGraphType + + Gets results for the init rule. + + :returns: For init rule. + :rtype: Dict + + + + .. py:method:: declarative_conformance_for_responded_existence() -> ReturnGraphType + + Gets results for the responded existence rule. + + :returns: For responded existence rule. + :rtype: Dict + + + + .. py:method:: declarative_conformance_for_coexistence() -> ReturnGraphType + + Gets results for the coexistence rule. + + :returns: For coexistence rule. + :rtype: Dict + + + + .. py:method:: declarative_conformance_for_response() -> ReturnGraphType + + Gets results for the response rule. + + :returns: For response rule. + :rtype: Dict + + + + .. py:method:: declarative_conformance_for_precedence() -> ReturnGraphType + + Gets results for the precedence rule. + + :returns: For precedence rule. + :rtype: Dict + + + + .. py:method:: declarative_conformance_for_succession() -> ReturnGraphType + + Gets results for the succession rule. + + :returns: For succession rule. + :rtype: Dict + + + + .. py:method:: declarative_conformance_for_altprecedence() -> ReturnGraphType + + Gets results for the altprecedence rule. + + :returns: For altprecedence rule. + :rtype: Dict + + + + .. py:method:: declarative_conformance_for_altsuccession() -> ReturnGraphType + + Gets results for the altsuccession rule. + + :returns: For altsuccession rule. + :rtype: Dict + + + + .. py:method:: declarative_conformance_for_chainresponse() -> ReturnGraphType + + Gets results for the chainresponse rule. + + :returns: For chainresponse rule. + :rtype: Dict + + + + .. py:method:: declarative_conformance_for_chainprecedence() -> ReturnGraphType + + Gets results for the chainprecedence rule. + + :returns: For chainprecedence rule. + :rtype: Dict + + + + .. py:method:: declarative_conformance_for_chainsuccession() -> ReturnGraphType + + Gets results for the chainsuccession rule. + + :returns: For chainsuccession rule. + :rtype: Dict + + + + .. py:method:: declarative_conformance_for_noncoexistence() -> ReturnGraphType + + Gets results for the noncoexistence rule. + + :returns: For noncoexistence rule. + :rtype: Dict + + + + .. py:method:: declarative_conformance_for_nonsuccession() -> ReturnGraphType + + Gets results for the nonsuccession rule. + + :returns: For nonsuccession rule. + :rtype: Dict + + + + .. py:method:: declarative_conformance_for_nonchainsuccession() -> ReturnGraphType + + Gets results for the nonchainsuccession rule. + + :returns: For nonchainsuccession rule. + :rtype: Dict + + + + .. py:method:: run_all_rules(list_of_rules: Optional[List[str]] = None, run_from_scratch: Optional[bool] = False) -> Any + + Runs conformance checking for all rules. + + It stores results in memory. + Useful for poling when all rules need to be pre-computed in the background. + + :param list_of_rules: List of rule names to check. If None, runs for all + valid rules. + :param run_from_scratch: If True, re-evaluates all rules even if results + stored. + + :returns: Dictionary of all violations. + + + diff --git a/docs/source/autoapi/backend/conformance_checking/index.rst b/docs/source/autoapi/backend/conformance_checking/index.rst new file mode 100644 index 0000000..bbe6e3d --- /dev/null +++ b/docs/source/autoapi/backend/conformance_checking/index.rst @@ -0,0 +1,18 @@ +backend.conformance_checking +============================ + +.. py:module:: backend.conformance_checking + + +Submodules +---------- + +.. toctree:: + :maxdepth: 1 + + /autoapi/backend/conformance_checking/declarative_constraints/index + /autoapi/backend/conformance_checking/log_skeleton/index + /autoapi/backend/conformance_checking/resource_based/index + /autoapi/backend/conformance_checking/temporal_profile/index + + diff --git a/docs/source/autoapi/backend/conformance_checking/log_skeleton/index.rst b/docs/source/autoapi/backend/conformance_checking/log_skeleton/index.rst new file mode 100644 index 0000000..57c6c33 --- /dev/null +++ b/docs/source/autoapi/backend/conformance_checking/log_skeleton/index.rst @@ -0,0 +1,161 @@ +backend.conformance_checking.log_skeleton +========================================= + +.. py:module:: backend.conformance_checking.log_skeleton + +.. autoapi-nested-parse:: + + Contains the LogSkeleton class. + + This module is used to create a log skeleton from a given event log and + to compute various metrics related to the log skeleton. + + + +Classes +------- + +.. autoapisummary:: + + backend.conformance_checking.log_skeleton.LogSkeleton + + +Module Contents +--------------- + +.. py:class:: LogSkeleton(log: pandas.DataFrame, case_id_col: Optional[str] = None, activity_col: Optional[str] = None, timestamp_col: Optional[str] = None) + + Represents a log skeleton. + + .. attribute:: log + + The event log. + + .. attribute:: _skeleton + + The log skeleton. + + .. attribute:: case_id_col + + The name of the case ID column. Only needed if + the log is read as csv file. + + :type: optional + + .. attribute:: activity_col + + The name of the activity column. Only needed if + the log is read as csv file. + + :type: optional + + .. attribute:: timestamp_col + + The name of the timestamp column. Only needed if + the log is read as csv file. + + :type: optional + + + .. py:attribute:: log + :type: pandas.DataFrame + + + .. py:attribute:: case_id_col + :type: Optional[str] + :value: None + + + + .. py:attribute:: activity_col + :type: Optional[str] + :value: None + + + + .. py:attribute:: timestamp_col + :type: Optional[str] + :value: None + + + + .. py:method:: compute_skeleton(noise_thr: float = 0.0) -> None + + Computes the log skeleton. + + :param noise_thr: The noise threshold. Value between 0 and 1. + + + + .. py:method:: check_conformance_traces(traces: pandas.DataFrame) -> List[Set[Any]] + + Computes the conformance of traces with the log skeleton. + + :param traces: A DataFrame containing the traces to be checked. + + :returns: A list of sets containing the results of the conformance. The + conformance checking results for each trace include: + - Outputs.IS_FIT: boolean that tells if the trace is perfectly + fit according to the model. + - Outputs.DEV_FITNESS: deviation based fitness (between 0 and 1; + the more the trace is near to 1 the more fit is). + - Outputs.DEVIATIONS: list of deviations in the model. + + + + .. py:method:: get_equivalence_relation() -> Set[Tuple[str, str]] + + Returns the equivalence relation of the log skeleton. + + :returns: A set of tuples representing two activities that are equivalent. + + + + .. py:method:: get_always_after_relation() -> Set[Tuple[str, str]] + + Returns the always after relation of the log skeleton. + + :returns: A set of tuples representing two activities where the first + activity always happens before the second activity. + + + + .. py:method:: get_always_before_relation() -> Set[Tuple[str, str]] + + Returns the always before relation of the log skeleton. + + :returns: A set of tuples representing two activities where the first + activity always happens after the second activity. + + + + .. py:method:: get_never_together_relation() -> Set[Tuple[str, str]] + + Returns the never together relation of the log skeleton. + + :returns: A set of tuples representing two activities that never happen + together. + + + + .. py:method:: get_activity_frequencies() -> Dict[str, Set[int]] + + Returns the activity frequencies. + + For each activity, it returns the number of possible occurences per + trace. + + :returns: A dictionary where the keys are the activities and the values + are sets of integers representing the number of possible + occurences per trace. + + + + .. py:method:: get_skeleton() -> Dict[str, Any] + + Returns the log skeleton. + + :returns: The log skeleton. + + + diff --git a/docs/source/autoapi/backend/conformance_checking/resource_based/index.rst b/docs/source/autoapi/backend/conformance_checking/resource_based/index.rst new file mode 100644 index 0000000..5e387d1 --- /dev/null +++ b/docs/source/autoapi/backend/conformance_checking/resource_based/index.rst @@ -0,0 +1,646 @@ +backend.conformance_checking.resource_based +=========================================== + +.. py:module:: backend.conformance_checking.resource_based + +.. autoapi-nested-parse:: + + Contains functionality for resource-based conformance checking. + + This module defines the ResourceBased class which uses PM4Py to discover + resource-based conformance checking metrics from event logs. + + + +Attributes +---------- + +.. autoapisummary:: + + backend.conformance_checking.resource_based.SocialNetworkAnalysisType + + +Classes +------- + +.. autoapisummary:: + + backend.conformance_checking.resource_based.ResourceBased + + +Module Contents +--------------- + +.. py:type:: SocialNetworkAnalysisType + :canonical: Dict[Tuple[str, str], float] + + +.. py:class:: ResourceBased(log: pandas.DataFrame, case_id_col: Optional[str] = None, activity_col: Optional[str] = None, timestamp_col: Optional[str] = None, resource_col: Optional[str] = None, group_col: Optional[str] = None) + + Represents the resource-based conformance checking metrics of a log. + + .. attribute:: log + + The event log. + + .. attribute:: case_id_col + + The name of the Case ID column. Only needed if + the log is read as a csv file. + + :type: optional + + .. attribute:: activity_col + + The name of the Activity column. Only needed if + the log is read as a csv file. + + :type: optional + + .. attribute:: timestamp_col + + The name of the Timestamp column. Only needed if + the log is read as a csv file. + + :type: optional + + .. attribute:: resource_col + + The name of the Resource column. Only needed if + the log is read as a csv file. + + :type: optional + + .. attribute:: _handover_of_work + + The Handover of Work metric. Defaults to None. + + .. attribute:: _subcontracting + + The Subcontracting metric. Defaults to None. + + .. attribute:: _working_together + + The Working Together metric. Defaults to None. + + .. attribute:: _similar_activities + + The Similar Activities metric. Defaults to None. + + .. attribute:: _organizational_roles + + The Organizational Roles of the log. Defaults + to None. + + .. attribute:: _organizational_diagnostics + + The Organizational Diagnostics of the log. + Defaults to None. + + + .. py:attribute:: log + + + .. py:attribute:: case_id_col + :type: Optional[str] + :value: None + + + + .. py:attribute:: activity_col + :type: Optional[str] + :value: None + + + + .. py:attribute:: timestamp_col + :type: Optional[str] + :value: None + + + + .. py:attribute:: resource_col + :type: Optional[str] + :value: None + + + + .. py:attribute:: group_col + :type: Optional[str] + :value: None + + + + .. py:method:: compute_handover_of_work() -> None + + Calculates the Handover of Work metric. + + The Handover of Work metric measures how many times an + individual is followed by another individual in the execution of + a business process. It is stored in a dictionary where the keys + are tuples of two individuals and the values are the number of + times the first individual is followed by the second individual + in the execution of a business process. + + + + .. py:method:: get_handover_of_work_values() -> SocialNetworkAnalysisType + + Returns the Handover of Work metric. + + The Handover of Work metric is a dictionary where the keys are + tuples of two individuals and the values are the number of times + the first individual is followed by the second individual + in the execution of a business process. + + :returns: The Handover of Work metric. + + :raises ValueError: If the Handover of Work values have not been calculated yet. + + + + .. py:method:: is_handover_of_work_directed() -> bool + + Checks if the Handover of Work metric is directed. + + :returns: True if the Handover of Work metric is directed, False otherwise. + + + + .. py:method:: compute_subcontracting() -> None + + Calculates the Subcontracting metric. + + The Subcontracting metric calculates how many times the work of + an individual is interleaved by the work of another individual, + only to eventually “return” to the original individual. It is + stored in a dictionary where the keys are tuples of two + individuals and the values are the number of times the first + individual is interleaved by the second individual in the + execution of a business process. + + + + .. py:method:: get_subcontracting_values() -> SocialNetworkAnalysisType + + Returns the Subcontracting metric. + + The Subcontracting metric is a dictionary where the keys are + tuples of two individuals and the values are the number of times + the first individual is interleaved by the second individual + in the execution of a business process. + + :returns: The Subcontracting metric. + + :raises ValueError: If the Subcontracting values have not been calculated yet. + + + + .. py:method:: is_subcontracting_directed() -> bool + + Checks if the Subcontracting metric is directed. + + :returns: True if the Subcontracting metric is directed, False otherwise. + + :raises ValueError: If the Subcontracting values have not been calculated yet. + + + + .. py:method:: compute_working_together() -> None + + Calculates the Working Together metric. + + The Working Together metric calculates how many times two + individuals work together to resolve a process instance. It is + stored in a dictionary where the keys are tuples of two + individuals and the values are the number of times the two + individuals worked together to resolve a process instance. + + + + .. py:method:: get_working_together_values() -> SocialNetworkAnalysisType + + Returns the Working Together metric. + + The Working Together metric is a dictionary where the keys are + tuples of two individuals and the values are the number of times + the two individuals worked together to resolve a process instance. + + :returns: The Working Together metric. + + :raises ValueError: If the Working Together values have not been calculated yet. + + + + .. py:method:: is_working_together_directed() -> bool + + Checks if the Working Together metric is directed. + + :returns: True if the Working Together metric is directed, False otherwise. + + :raises ValueError: If the Working Together values have not been calculated yet. + + + + .. py:method:: compute_similar_activities() -> None + + Calculates the Similar Activities metric. + + The Similar Activities metric calculates how similar the work + patterns are between two individuals. It is stored in a + dictionary where the keys are tuples of two individuals and the + values are the similarity score between the two individuals. + + + + .. py:method:: get_similar_activities_values() -> SocialNetworkAnalysisType + + Returns the Similar Activities metric. + + The Similar Activities metric is a dictionary where the keys are + tuples of two individuals and the values are the similarity score + between the two individuals. + + :returns: The Similar Activities metric. + + :raises ValueError: If the Similar Activities values have not been calculated yet. + + + + .. py:method:: is_similar_activities_directed() -> bool + + Checks if the Similar Activities metric is directed. + + :returns: True if the Similar Activities metric is directed, False otherwise. + + :raises ValueError: If the Similar Activities values have not been calculated yet. + + + + .. py:method:: compute_organizational_roles() -> None + + Calculates the organizational roles. + + A role is a set of activities in the log that are executed by a similar + (multi)set of resources. Hence, it is a specific function within an + organization. Grouping the activities into roles can help: + + - In understanding which activities are executed by which roles, + - By understanding roles themselves (the numerosity of resources for + a single activity may not provide enough explanation). + + Initially, each activity corresponds to a different role and is + associated with the multiset of its originators. After that, roles are + merged according to their similarity until no more merges are possible. + + The information about the roles is stored as a semi-structured list of + activity groups, where each group associates a list of activities + with a dictionary of originators and their corresponding + importance scores. + + + + .. py:method:: get_organizational_roles() -> List[Dict[str, Any]] + + Returns the organizational roles. + + The organizational roles are stored as a semi-structured list of + activity groups, where each group associates a list of activities + with a dictionary of originators and their corresponding + importance scores. + + :returns: A list of dictionaries, where each dictionary + contains the activities and their corresponding originators' importance + scores. + Each dictionary has the following structure: + { + "activities": List[str], # List of activities in the role + "originators_importance": Dict[str, float] + # Dictionary of originators and their importance scores + } + + :raises ValueError: If the organizational roles have not been calculated yet. + + + + .. py:method:: get_number_of_distinct_activities(start_time: str, end_time: str, resource: str) -> int + + Calculates the number of distinct activities. + + Number of distinct activities done by a resource in a given time + interval [t1, t2). + + :param start_time: The start time of the interval. + :type start_time: str + :param end_time: The end time of the interval. + :type end_time: str + :param resource: The resource for which to calculate the number of + distinct activities. + :type resource: str + + :returns: An integer indicating the number of distinct activities done by + the resource in the given time interval. + + + + .. py:method:: get_activity_frequency(start_time: str, end_time: str, resource: str, activity: str) -> float + + Calculates the activity frequency. + + Fraction of completions of a given activity a by a given + resource r during a given time slot [t1, t2), with respect to + the total number of activity completions by resource r during + [t1, t2). + + :param start_time: The start time of the interval. + :type start_time: str + :param end_time: The end time of the interval. + :type end_time: str + :param resource: The resource for which to calculate the activity + frequency. + :type resource: str + :param activity: The activity for which to calculate the frequency. + :type activity: str + + :returns: A float indicating the activity frequency of the given activity + by the resource in the given time interval. + + + + .. py:method:: get_activity_completions(start_time: str, end_time: str, resource: str) -> int + + Calculates the activity completions. + + The number of activity instances completed by a given resource + during a given time slot. + + :param start_time: The start time of the interval. + :type start_time: str + :param end_time: The end time of the interval. + :type end_time: str + :param resource: The resource for which to calculate the activity + completions. + :type resource: str + + :returns: An integer indicating the number of activity instances completed + by the resource in the given time interval. + + + + .. py:method:: get_case_completions(start_time: str, end_time: str, resource: str) -> int + + Calculates the case completion. + + The number of cases completed during a given time slot in which + a given resource was involved. + + :param start_time: The start time of the interval. + :type start_time: str + :param end_time: The end time of the interval. + :type end_time: str + :param resource: The resource for which to calculate the case + completions. + :type resource: str + + :returns: An integer indicating the number of cases completed by the + resource in the given time interval. + + + + .. py:method:: get_fraction_case_completions(start_time: str, end_time: str, resource: str) -> float + + Calculates the fraction case completion. + + The fraction of cases completed during a given time slot in + which a given resource was involved with respect to the total + number of cases completed during the time slot. + + :param start_time: The start time of the interval. + :type start_time: str + :param end_time: The end time of the interval. + :type end_time: str + :param resource: The resource for which to calculate the + fraction case completions. + :type resource: str + + :returns: A float indicating the fraction of cases completed by the + resource in the given time interval. + + + + .. py:method:: get_average_workload(start_time: str, end_time: str, resource: str) -> float + + Calculates the average workload. + + The average number of activities started by a given resource but + not completed at a moment in time. + + :param start_time: The start time of the interval. + :type start_time: str + :param end_time: The end time of the interval. + :type end_time: str + :param resource: The resource for which to calculate the average + workload. + :type resource: str + + :returns: A float indicating the average workload of the given resource + in the given time interval. + + + + .. py:method:: get_multitasking(start_time: str, end_time: str, resource: str) -> float + + Calculates the multitasking. + + The fraction of active time during which a given resource is + involved in more than one activity with respect to the + resource's active time. + + :param start_time: The start time of the interval. + :type start_time: str + :param end_time: The end time of the interval. + :type end_time: str + :param resource: The resource for which to calculate the + multitasking. + :type resource: str + + :returns: A float indicating the multitasking of the given resource + in the given time interval. + + + + .. py:method:: get_average_activity_duration(start_time: str, end_time: str, resource: str, activity: str) -> float + + Calculates the average activity duration. + + The average duration of instances of a given activity completed + during a given time slot by a given resource. + + :param start_time: The start time of the interval. + :type start_time: str + :param end_time: The end time of the interval. + :type end_time: str + :param resource: The resource for which to calculate the average + activity duration. + :type resource: str + :param activity: The activity for which to calculate the average + duration. + :type activity: str + + :returns: A float indicating the average duration of the given activity + by the resource in the given time interval. + + + + .. py:method:: get_average_case_duration(start_time: str, end_time: str, resource: str) -> float + + Calculates the average case duration. + + The average duration of cases completed during a given time slot + in which a given resource was involved. + + :param start_time: The start time of the interval. + :type start_time: str + :param end_time: The end time of the interval. + :type end_time: str + :param resource: The resource for which to calculate the average + case duration. + :type resource: str + + :returns: A float indicating the average duration of cases completed + by the resource in the given time interval. + + + + .. py:method:: get_interaction_two_resources(start_time: str, end_time: str, resource1: str, resource2: str) -> float + + Calculates the interaction between two resources. + + The number of cases completed during a given time slot in which + two given resources were involved. + + :param start_time: The start time of the interval. + :type start_time: str + :param end_time: The end time of the interval. + :type end_time: str + :param resource1: The first resource for which to calculate the + interaction. + :type resource1: str + :param resource2: The second resource for which to calculate the + interaction. + :type resource2: str + + :returns: A float indicating the interaction between the two resources + in the given time interval. + + + + .. py:method:: get_social_position(start_time: str, end_time: str, resource: str) -> float + + Calculates the social position. + + The fraction of resources involved in the same cases with a + given resource during a given time slot with respect to the + total number of resources active during the time slot. + + :param start_time: The start time of the interval. + :type start_time: str + :param end_time: The end time of the interval. + :type end_time: str + :param resource: The resource for which to calculate the + social position. + :type resource: str + + :returns: A float indicating the social position of the given resource + in the given time interval. + + + + .. py:method:: compute_organizational_diagnostics() -> None + + Calculates the organizational diagnostics. + + Provides the local diagnostics for the organizational model + starting from a log object and considering the resource group + specified by the attribute. It is stored in a dictionary where the keys are + the names of the group-related metrics and the values are the + corresponding diagnostic values. + + :raises ValueError: If the resource column name is not provided. + + + + .. py:method:: get_group_relative_focus() -> Dict[str, Dict[str, float]] + + Returns the Group Relative Focus metric. + + The Group Relative Focus metric specifies for a given work how + much a resource group performed this type of work compared to + the overall workload of the group. It can be used to measure how + the workload of a resource group is distributed over different + types of work, i.e., work diversification of the group. + + :returns: A dictionary where the keys are the names of the resources + and the values are dictionaries containing activity names + and the Group Relative Focus metric. + + :raises ValueError: If the organizational diagnostics have not been + :raises calculated yet.: + + + + .. py:method:: get_group_relative_stake() -> Dict[str, Dict[str, float]] + + Returns the Group Relative Stake metric. + + The Group Relative Stake metric specifies for a given work how much + this type of work was performed by a certain resource group among + all groups. It can be used to measure how the workload devoted to + a certain type of work is distributed over resource groups in an + organizational model, i.e., work participation by different groups. + + :returns: A dictionary where the keys are the names of the resources and + the values are dictionaries containing activity names and the + Group Relative Stake metric. + + :raises ValueError: If the organizational diagnostics have not been + :raises calculated yet.: + + + + .. py:method:: get_group_coverage() -> Dict[str, Dict[str, float]] + + Returns the Group Coverage metric. + + The Group Coverage metric with respect to a given type of work, + specifies the proportion of members of a resource group that + performed this type of work. + + :returns: A dictionary where the keys are the names of the resources + and the values are dictionaries containing resources and the + Group Coverage metric. + + :raises ValueError: If the organizational diagnostics have not been + :raises calculated yet.: + + + + .. py:method:: get_group_member_contribution() -> Dict[str, Dict[str, Dict[str, int]]] + + Returns the Group Member Contribution metric. + + The Group Member Contribution metric of a member of a resource group + with respect to a given type of work specifies how much of this type + of work by the group was performed by the member. It can be used to + measure how the workload of the entire group devoted to a certain + type of work is distributed over the group members. + + :returns: A dictionary where the keys are the names of the resources and + the values are dictionaries containing resources and the Group + Member Contribution metric. + + :raises ValueError: If the organizational diagnostics have not been + :raises calculated yet.: + + + diff --git a/docs/source/autoapi/backend/conformance_checking/temporal_profile/index.rst b/docs/source/autoapi/backend/conformance_checking/temporal_profile/index.rst new file mode 100644 index 0000000..6d03182 --- /dev/null +++ b/docs/source/autoapi/backend/conformance_checking/temporal_profile/index.rst @@ -0,0 +1,206 @@ +backend.conformance_checking.temporal_profile +============================================= + +.. py:module:: backend.conformance_checking.temporal_profile + +.. autoapi-nested-parse:: + + Contains functionality for temporal conformance checking. + + This module defines the TemporalProfile class which uses PM4Py to + discover temporal profiles from event logs and checks conformance based + on the discovered temporal profiles. + + + +Attributes +---------- + +.. autoapisummary:: + + backend.conformance_checking.temporal_profile.TemporalProfileType + backend.conformance_checking.temporal_profile.ConformanceResultType + + +Classes +------- + +.. autoapisummary:: + + backend.conformance_checking.temporal_profile.TemporalProfile + + +Module Contents +--------------- + +.. py:type:: TemporalProfileType + :canonical: Dict[Tuple[str, str], Tuple[float, float]] + + +.. py:type:: ConformanceResultType + :canonical: List[List[Tuple[Any, ...]]] + + +.. py:class:: TemporalProfile(log: pandas.DataFrame, case_id_col: Optional[str] = None, activity_col: Optional[str] = None, timestamp_col: Optional[str] = None) + + Represents the temporal profile of an event log. + + .. attribute:: log + + The event log. + + .. attribute:: _temporal_profile + + The discovered temporal profile. + + .. attribute:: _temporal_conformance_result + + The result of temporal conformance checking. + + .. attribute:: _zeta + + The zeta value used for temporal conformance checking. + + .. attribute:: case_id_col + + The name of the Case ID column. Only needed if + + :type: optional + + .. attribute:: the log is read as a csv file. + + + + .. attribute:: activity_col + + The name of the Activity column. Only needed if + the log is read as a csv file. + + :type: optional + + .. attribute:: timestamp_col + + The name of the Timestamp column. Only needed if + the log is read as a csv file. + + :type: optional + + + .. py:attribute:: log + :type: pandas.DataFrame + + + .. py:attribute:: case_id_col + :type: Optional[str] + :value: None + + + + .. py:attribute:: activity_col + :type: Optional[str] + :value: None + + + + .. py:attribute:: timestamp_col + :type: Optional[str] + :value: None + + + + .. py:method:: discover_temporal_profile() -> None + + Discovers the temporal profile from the log. + + The result is stored in _temporal_profile which is a dictionary + where each key is a tuple of two activity names (source, target), + and the value is a tuple containing: + 1. The mean duration between the two activities + 2. The standard deviation of those durations. + + + + .. py:method:: check_temporal_conformance(zeta: float = 0.5) -> None + + Checks conformance of the log against the temporal profile. + + The result is stored in _temporal_conformance_result which is a list containing, + for each trace, all the deviations. Each deviation is a tuple containing: + 1. The source activity of the recorded deviation. + 2. The target activity of the recorded deviation. + 3. The time passed between the occurrence of the source activity and the + target activity. + 4. The value of (time passed - mean)/std for this occurrence (zeta). + + :param zeta: Multiplier for the standard deviation. + + :raises ValueError: If the temporal profile has not been discovered yet. + + + + .. py:method:: get_temporal_profile() -> TemporalProfileType + + Returns the discovered temporal profile. + + :returns: A dictionary where each key is a tuple of two activity names (source, target), + and the value is a tuple containing: + 1. The mean duration between the two activities + 2. The standard deviation of those durations. + + :raises ValueError: If the temporal profile has not been discovered yet. + + + + .. py:method:: get_temporal_conformance_result() -> ConformanceResultType + + Returns the result of temporal conformance checking. + + :returns: 1. The source activity of the recorded deviation. + 2. The target activity of the recorded deviation. + 3. The time passed between the occurrence of the source activity and the + target activity. + 4. The value of (time passed - mean)/std for this occurrence (zeta). + :rtype: A list containing, for each trace, all the deviations. Each deviation is a tuple containing + + :raises ValueError: If the temporal conformance result has not been computed yet. + + + + .. py:method:: get_zeta() -> Optional[float] + + Returns the zeta value used for temporal conformance checking. + + :returns: The zeta value used for temporal conformance checking. + + + + .. py:method:: get_conformance_diagnostics() -> pandas.DataFrame + + Returns the result of temporal conformance checking as a DataFrame. + + :returns: 1. The Case ID of the recorded deviation. + 2. The source activity of the recorded deviation. + 3. The target activity of the recorded deviation. + 4. The time passed between the occurrence of the source activity and the + target activity. + 5. The value of (time passed - mean)/std for this occurrence (zeta). + :rtype: A DataFrame containing the deviations for each trace. Each row contains + + :raises ValueError: If the temporal conformance result has not been computed yet. + + + + .. py:method:: get_sorted_coloured_diagnostics() -> pandas.io.formats.style.Styler + + Returns the diagnostics DataFrame with sorting and styling. + + Sorts the diagnostics DataFrame in descending order of the number of standard deviations (num_st_devs) + and applies a colour-coded strip to the rows based on the value of num_st_devs - zeta: + - Green: If the value is less than 0.5 + - Yellow: If the value is between 0.5 and 1.0 + - Red: If the value is greater than 1.0 + + :returns: A styled DataFrame containing the sorted diagnostics with colour-coding. + + + diff --git a/docs/source/autoapi/backend/index.rst b/docs/source/autoapi/backend/index.rst new file mode 100644 index 0000000..828b906 --- /dev/null +++ b/docs/source/autoapi/backend/index.rst @@ -0,0 +1,21 @@ +backend +======= + +.. py:module:: backend + + +Submodules +---------- + +.. toctree:: + :maxdepth: 1 + + /autoapi/backend/api/index + /autoapi/backend/celonis_connection/index + /autoapi/backend/conformance_checking/index + /autoapi/backend/main/index + /autoapi/backend/pql_queries/index + /autoapi/backend/usage_example/index + /autoapi/backend/utils/index + + diff --git a/docs/source/autoapi/backend/main/index.rst b/docs/source/autoapi/backend/main/index.rst new file mode 100644 index 0000000..0116269 --- /dev/null +++ b/docs/source/autoapi/backend/main/index.rst @@ -0,0 +1,54 @@ +backend.main +============ + +.. py:module:: backend.main + +.. autoapi-nested-parse:: + + Contains the main entry point for the FastAPI backend. + + This module initializes the FastAPI application, sets up middleware, and + includes the API routers. + + + +Attributes +---------- + +.. autoapisummary:: + + backend.main.app + + +Functions +--------- + +.. autoapisummary:: + + backend.main.lifespan + backend.main.home + + +Module Contents +--------------- + +.. py:function:: lifespan(app: fastapi.FastAPI) + :async: + + + Initializes the CelonisConnectionManager and stores it in the app state. + + This function is used as a context manager to ensure that the + CelonisConnectionManager is properly initialized. + + :param app: The FastAPI application instance. This is used to store the + CelonisConnectionManager instance in the application state. + + +.. py:data:: app + +.. py:function:: home() -> Dict[str, str] + + Returns a simple message indicating that the API is running. + + diff --git a/docs/source/autoapi/backend/pql_queries/declerative_queries/index.rst b/docs/source/autoapi/backend/pql_queries/declerative_queries/index.rst new file mode 100644 index 0000000..15f9e3d --- /dev/null +++ b/docs/source/autoapi/backend/pql_queries/declerative_queries/index.rst @@ -0,0 +1,11 @@ +backend.pql_queries.declerative_queries +======================================= + +.. py:module:: backend.pql_queries.declerative_queries + +.. autoapi-nested-parse:: + + Queries used to get declerative constraint related data from celonis. + + + diff --git a/docs/source/autoapi/backend/pql_queries/general_queries/index.rst b/docs/source/autoapi/backend/pql_queries/general_queries/index.rst new file mode 100644 index 0000000..a4688d2 --- /dev/null +++ b/docs/source/autoapi/backend/pql_queries/general_queries/index.rst @@ -0,0 +1,98 @@ +backend.pql_queries.general_queries +=================================== + +.. py:module:: backend.pql_queries.general_queries + +.. autoapi-nested-parse:: + + Queries that can be used to get general data from celonis. + + + +Functions +--------- + +.. autoapisummary:: + + backend.pql_queries.general_queries.get_dfg_representation + backend.pql_queries.general_queries.get_cases + backend.pql_queries.general_queries.get_number_of_cases + backend.pql_queries.general_queries.get_activities + backend.pql_queries.general_queries.get_number_of_activities + backend.pql_queries.general_queries.get_traces_with_count + backend.pql_queries.general_queries.get_general_information + + +Module Contents +--------------- + +.. py:function:: get_dfg_representation(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager) -> pandas.DataFrame + + A query that gets the DFG representation of a process. + + :param celonis: the celonis connection + :type celonis: CelonisConnectionManager + + :returns: a pandas Dataframe that represents a graph + + +.. py:function:: get_cases(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager) -> pandas.DataFrame + + A query that gets the cases from an event log. + + :param celonis: the celonis connection + :type celonis: CelonisConnectionManager + + :returns: a pandas Dataframe that contains the cases + + +.. py:function:: get_number_of_cases(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager) -> pandas.DataFrame + + A query that gets the count of cases from an event log. + + :param celonis: the celonis connection + :type celonis: CelonisConnectionManager + + :returns: a pandas Dataframe that contains the count of cases + + +.. py:function:: get_activities(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager) -> pandas.DataFrame + + A query that gets the activities from an event log. + + :param celonis: the celonis connection + :type celonis: CelonisConnectionManager + + :returns: a pandas Dataframe that contains the count of cases + + +.. py:function:: get_number_of_activities(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager) -> pandas.DataFrame + + A query that gets the count of activities from an event log. + + :param celonis: the celonis connection + :type celonis: CelonisConnectionManager + + :returns: a pandas Dataframe that contains the count of activites + + +.. py:function:: get_traces_with_count(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager) -> pandas.DataFrame + + A query that gets the traces and their count. + + :param celonis: the celonis connection + :type celonis: CelonisConnectionManager + + :returns: a pandas Dataframe that contains the traces and their count + + +.. py:function:: get_general_information(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager) -> pandas.DataFrame + + Fetches number of cases, activities, and trace variants from Celonis. + + :param celonis: The CelonisConnectionManager instance to interact with Celonis. + + :returns: A pandas DataFrame containing the counts of cases, activities, and trace + variants. + + diff --git a/docs/source/autoapi/backend/pql_queries/index.rst b/docs/source/autoapi/backend/pql_queries/index.rst new file mode 100644 index 0000000..d622a28 --- /dev/null +++ b/docs/source/autoapi/backend/pql_queries/index.rst @@ -0,0 +1,19 @@ +backend.pql_queries +=================== + +.. py:module:: backend.pql_queries + + +Submodules +---------- + +.. toctree:: + :maxdepth: 1 + + /autoapi/backend/pql_queries/declerative_queries/index + /autoapi/backend/pql_queries/general_queries/index + /autoapi/backend/pql_queries/log_skeleton_queries/index + /autoapi/backend/pql_queries/resource_based_queries/index + /autoapi/backend/pql_queries/temporal_profile_queries/index + + diff --git a/docs/source/autoapi/backend/pql_queries/log_skeleton_queries/index.rst b/docs/source/autoapi/backend/pql_queries/log_skeleton_queries/index.rst new file mode 100644 index 0000000..2100ad8 --- /dev/null +++ b/docs/source/autoapi/backend/pql_queries/log_skeleton_queries/index.rst @@ -0,0 +1,104 @@ +backend.pql_queries.log_skeleton_queries +======================================== + +.. py:module:: backend.pql_queries.log_skeleton_queries + +.. autoapi-nested-parse:: + + Queries that can be used to get log-skeleton related data from celonis. + + + +Functions +--------- + +.. autoapisummary:: + + backend.pql_queries.log_skeleton_queries.get_always_before_relation + backend.pql_queries.log_skeleton_queries.get_always_after_relation + backend.pql_queries.log_skeleton_queries.get_equivalance_relation + backend.pql_queries.log_skeleton_queries.get_exclusive_choice_relaion + backend.pql_queries.log_skeleton_queries.get_never_together_relation + backend.pql_queries.log_skeleton_queries.get_directly_follows_relation_and_count + backend.pql_queries.log_skeleton_queries.get_act_freq + + +Module Contents +--------------- + +.. py:function:: get_always_before_relation(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager) -> pandas.DataFrame + + Caculates which pairs of Activity always occurr before each other. + + :param celonis: the celonis connection + :type celonis: CelonisConnectionManager + + :returns: A dataframe that contains for pairs of Activities whether + they always occurr before each other. + + +.. py:function:: get_always_after_relation(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager) -> pandas.DataFrame + + Caculates which pairs of Activity always occurr after each other. + + :param celonis: the celonis connection + :type celonis: CelonisConnectionManager + + :returns: A dataframe that contains for pairs of Activities whether + they always occurr after each other. + + +.. py:function:: get_equivalance_relation(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager) -> pandas.DataFrame + + Caculates which pairs of Activity are equivalent. + + :param celonis: the celonis connection + :type celonis: CelonisConnectionManager + + :returns: A dataframe that contains for pairs of Activities whether + they are equivalent. + + +.. py:function:: get_exclusive_choice_relaion(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager) -> pandas.DataFrame + + Caculates which pairs of Activity are exclusive choice. + + :param celonis: the celonis connection + :type celonis: CelonisConnectionManager + + :returns: A dataframe that contains for pairs of Activities whether + they are exclusive choice. + + +.. py:function:: get_never_together_relation(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager) -> pandas.DataFrame + + Caculates which pairs of Activity never occurr together. + + :param celonis: the celonis connection + :type celonis: CelonisConnectionManager + + :returns: A dataframe that contains for pairs of Activities whether + they are never together in a trace + + +.. py:function:: get_directly_follows_relation_and_count(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager) -> pandas.DataFrame + + Gets the directly follows relation and count. + + :param celonis: the celonis connection + :type celonis: CelonisConnectionManager + + :returns: A pandas dataframe that contains a statement whether the + dirctly follows relation is true and the count for each + + +.. py:function:: get_act_freq(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager) -> pandas.DataFrame + + Gets the activity frequencies. + + :param celonis: the celonis connection + :type celonis: CelonisConnectionManager + + :returns: A pandas dataframe that contains the activity frequencies + + diff --git a/docs/source/autoapi/backend/pql_queries/resource_based_queries/index.rst b/docs/source/autoapi/backend/pql_queries/resource_based_queries/index.rst new file mode 100644 index 0000000..b2faa30 --- /dev/null +++ b/docs/source/autoapi/backend/pql_queries/resource_based_queries/index.rst @@ -0,0 +1,431 @@ +backend.pql_queries.resource_based_queries +========================================== + +.. py:module:: backend.pql_queries.resource_based_queries + +.. autoapi-nested-parse:: + + Queries that can be used to get resource related data from celonis. + + + +Functions +--------- + +.. autoapisummary:: + + backend.pql_queries.resource_based_queries.get_number_of_resources + backend.pql_queries.resource_based_queries.get_number_of_groups + backend.pql_queries.resource_based_queries.get_resource_for_activity + backend.pql_queries.resource_based_queries.get_handover_of_work_values + backend.pql_queries.resource_based_queries.get_subcontracting_values + backend.pql_queries.resource_based_queries.get_working_together_values + backend.pql_queries.resource_based_queries.get_similar_activities_values + backend.pql_queries.resource_based_queries.get_organizational_roles + backend.pql_queries.resource_based_queries.get_number_of_distinct_activities + backend.pql_queries.resource_based_queries.get_activity_frequency + backend.pql_queries.resource_based_queries.get_activity_completions + backend.pql_queries.resource_based_queries.get_case_completions + backend.pql_queries.resource_based_queries.get_fraction_case_completions + backend.pql_queries.resource_based_queries.get_average_workload + backend.pql_queries.resource_based_queries.get_average_activity_duration + backend.pql_queries.resource_based_queries.get_average_case_duration + backend.pql_queries.resource_based_queries.get_interaction_two_resources + backend.pql_queries.resource_based_queries.get_social_position + backend.pql_queries.resource_based_queries.get_group_relative_focus + backend.pql_queries.resource_based_queries.get_group_relative_stake + backend.pql_queries.resource_based_queries.get_group_coverage + backend.pql_queries.resource_based_queries.get_group_member_interaction + + +Module Contents +--------------- + +.. py:function:: get_number_of_resources(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager) -> pandas.DataFrame + + A query that gets the count of resources from an event log. + + :param celonis: the celonis connection + :type celonis: CelonisConnectionManager + + :returns: a pandas Dataframe that contains the count of resources + + +.. py:function:: get_number_of_groups(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager) -> pandas.DataFrame + + A query that gets the count of groups from an event log. + + :param celonis: the celonis connection + :type celonis: CelonisConnectionManager + + :returns: a pandas Dataframe that contains the count of groups + + +.. py:function:: get_resource_for_activity(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager) -> pandas.DataFrame + + A query that maps activities to their related resources. + + :param celonis: the celonis connection + :type celonis: CelonisConnectionManager + + :returns: a pandas Dataframe that contains the mapping between activities to their related resources + + +.. py:function:: get_handover_of_work_values(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager) -> pandas.DataFrame + + Returns the Handover of Work metric. + + The Handover of Work metric is a dictionary where the keys are + tuples of two individuals and the values are the number of times + the first individual is followed by the second individual + in the execution of a business process. + + :param celonis: the celonis connection + :type celonis: CelonisConnectionManager + + :returns: A DataFrame containing the Handover of Work metric. + + +.. py:function:: get_subcontracting_values(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager) -> pandas.DataFrame + + Returns the Subcontracting metric. + + The Subcontracting metric is a dictionary where the keys are + tuples of two individuals and the values are the number of times + the first individual is interleaved by the second individual + in the execution of a business process. + + :param celonis: the celonis connection + :type celonis: CelonisConnectionManager + + :returns: A DataFrame containing the Subcontracting metric. + + +.. py:function:: get_working_together_values(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager) -> pandas.DataFrame + + Returns the Working Together metric. + + The Working Together metric is a dictionary where the keys are + tuples of two individuals and the values are the number of times + the two individuals worked together to resolve a process instance. + + :param celonis: the celonis connection + :type celonis: CelonisConnectionManager + + :returns: A DataFrame containing the Working Together metric. + + +.. py:function:: get_similar_activities_values(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager) -> pandas.DataFrame + + Returns the Similar Activities metric. + + The Similar Activities metric is a dictionary where the keys are + tuples of two individuals and the values are the similarity score + between the two individuals. + + :param celonis: the celonis connection + :type celonis: CelonisConnectionManager + + :returns: A DataFrame containing the Similar Activities metric. + + +.. py:function:: get_organizational_roles(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager) -> pandas.DataFrame + + Returns the organizational roles. + + The organizational roles are stored as a semi-structured list of + activity groups, where each group associates a list of activities + with a dictionary of originators and their corresponding + importance scores. + + :param celonis: the celonis connection + :type celonis: CelonisConnectionManager + + :returns: A DataFrame containing the organizational roles. + + +.. py:function:: get_number_of_distinct_activities(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager, start_time: str, end_time: str, resource: str) -> int + + Calculates the number of distinct activities. + + Number of distinct activities done by a resource in a given time + interval [t1, t2). + + :param celonis: The Celonis connection + :type celonis: CelonisConnectionManager + :param start_time: The start time of the interval. + :type start_time: str + :param end_time: The end time of the interval. + :type end_time: str + :param resource: The resource for which to calculate the number of + distinct activities. + :type resource: str + + :returns: An integer denoting the number of distinct activities. + + +.. py:function:: get_activity_frequency(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager, start_time: str, end_time: str, resource: str, activity: str) -> float + + Calculates the activity frequency. + + Fraction of completions of a given activity a by a given + resource r during a given time slot [t1, t2), with respect to + the total number of activity completions by resource r during + [t1, t2). + + :param celonis: The Celonis connection + :type celonis: CelonisConnectionManager + :param start_time: The start time of the interval. + :type start_time: str + :param end_time: The end time of the interval. + :type end_time: str + :param resource: The resource for which to calculate the activity + frequency. + :type resource: str + :param activity: The activity for which to calculate the frequency. + :type activity: str + + :returns: A float indicating the activity frequency of the given activity + by the resource in the given time interval. + + +.. py:function:: get_activity_completions(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager, start_time: str, end_time: str, resource: str) -> int + + Calculates the number of activity completions. + + Number of completions of a given activity by a given resource + during a given time slot [t1, t2). + + :param celonis: The Celonis connection + :type celonis: CelonisConnectionManager + :param start_time: The start time of the interval. + :type start_time: str + :param end_time: The end time of the interval. + :type end_time: str + :param resource: The resource for which to calculate the number of + activity completions. + :type resource: str + + :returns: An integer denoting the number of activity completions by the + resource in the given time interval. + + +.. py:function:: get_case_completions(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager, start_time: str, end_time: str, resource: str) -> int + + Calculates the number of case completions. + + Number of completions of a given case by a given resource + during a given time slot [t1, t2). + + :param celonis: The Celonis connection + :type celonis: CelonisConnectionManager + :param start_time: The start time of the interval. + :type start_time: str + :param end_time: The end time of the interval. + :type end_time: str + :param resource: The resource for which to calculate the number of + case completions. + :type resource: str + + :returns: An integer denoting the number of case completions by the + resource in the given time interval. + + +.. py:function:: get_fraction_case_completions(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager, start_time: str, end_time: str, resource: str) -> float + + Calculates the fraction of case completions. + + Fraction of completions of a case by a given resource r during + a given time slot [t1, t2), with respect to the total number of + case completions during [t1, t2). + + :param celonis: The Celonis connection + :type celonis: CelonisConnectionManager + :param start_time: The start time of the interval. + :type start_time: str + :param end_time: The end time of the interval. + :type end_time: str + :param resource: The resource for which to calculate the fraction + of case completions. + :type resource: str + + :returns: A float indicating the fraction of case completions by the + resource in the given time interval. + + +.. py:function:: get_average_workload(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager, start_time: str, end_time: str, resource: str) -> float + + Calculates the average workload. + + Average workload of a given resource r during a given time slot + [t1, t2). + + :param celonis: The Celonis connection + :type celonis: CelonisConnectionManager + :param start_time: The start time of the interval. + :type start_time: str + :param end_time: The end time of the interval. + :type end_time: str + :param resource: The resource for which to calculate the average + workload. + :type resource: str + + :returns: A float indicating the average workload of the resource in the + given time interval. + + +.. py:function:: get_average_activity_duration(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager, start_time: str, end_time: str, resource: str, activity: str) -> float + + Calculates the average activity duration. + + The average duration of instances of a given activity completed + during a given time slot by a given resource. + + :param celonis: The Celonis connection + :type celonis: CelonisConnectionManager + :param start_time: The start time of the interval. + :type start_time: str + :param end_time: The end time of the interval. + :type end_time: str + :param resource: The resource for which to calculate the average + activity duration. + :type resource: str + :param activity: The activity for which to calculate the average + duration. + :type activity: str + + :returns: A float indicating the average duration of the given activity + by the resource in the given time interval. + + +.. py:function:: get_average_case_duration(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager, start_time: str, end_time: str, resource: str) -> float + + Calculates the average case duration. + + The average duration of cases completed during a given time slot + in which a given resource was involved. + + :param celonis: The Celonis connection + :type celonis: CelonisConnectionManager + :param start_time: The start time of the interval. + :type start_time: str + :param end_time: The end time of the interval. + :type end_time: str + :param resource: The resource for which to calculate the average + case duration. + :type resource: str + + :returns: A float indicating the average duration of cases completed + by the resource in the given time interval. + + +.. py:function:: get_interaction_two_resources(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager, start_time: str, end_time: str, resource1: str, resource2: str) -> float + + Calculates the interaction between two resources. + + The number of cases completed during a given time slot in which + two given resources were involved. + + :param celonis: The Celonis connection + :type celonis: CelonisConnectionManager + :param start_time: The start time of the interval. + :type start_time: str + :param end_time: The end time of the interval. + :type end_time: str + :param resource1: The first resource for which to calculate the + interaction. + :type resource1: str + :param resource2: The second resource for which to calculate the + interaction. + :type resource2: str + + :returns: A float indicating the interaction between the two resources + in the given time interval. + + +.. py:function:: get_social_position(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager, start_time: str, end_time: str, resource: str) -> float + + Calculates the social position of a resource. + + The social position is the fraction of resources that interacted + with a given resource during a given time slot with respect to + the total number of resources that were active during that time + slot. + + :param celonis: The Celonis connection + :type celonis: CelonisConnectionManager + :param start_time: The start time of the interval. + :type start_time: str + :param end_time: The end time of the interval. + :type end_time: str + :param resource: The resource for which to calculate the social + position. + :type resource: str + + :returns: A float indicating the social position of the resource in the + given time interval. + + +.. py:function:: get_group_relative_focus(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager) -> pandas.DataFrame + + Returns the Group Relative Focus. + + The Group Relative Focus metric specifies for a given work how + much a resource group performed this type of work compared to + the overall workload of the group. It can be used to measure how + the workload of a resource group is distributed over different + types of work, i.e., work diversification of the group. + + + :param celonis: The Celonis connection + :type celonis: CelonisConnectionManager + + :returns: A DataFrame containing the Group Relative Focus for each group + and activity. + + +.. py:function:: get_group_relative_stake(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager) -> pandas.DataFrame + + Returns" the Group Relative Stake. + + The Group Relative Stake metric specifies for a given work how much + this type of work was performed by a certain resource group among + all groups. It can be used to measure how the workload devoted to + a certain type of work is distributed over resource groups in an + organizational model, i.e., work participation by different groups. + + + :param celonis: The Celonis connection + :type celonis: CelonisConnectionManager + + :returns: A DataFrame containing the Group Relative Stake for each group + and activity. + + +.. py:function:: get_group_coverage(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager) -> pandas.DataFrame + + Returns the Group Coverage metric. + + The Group Coverage metric with respect to a given type of work, + specifies the proportion of members of a resource group that + performed this type of work. + + :returns: A dictionary where the keys are the names of the resources + and the values are dictionaries containing resources and the + Group Coverage metric. + + +.. py:function:: get_group_member_interaction(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager) -> pandas.DataFrame + + Returns the Group Member Contribution metric. + + The Group Member Contribution metric of a member of a resource group + with respect to a given type of work specifies how much of this type + of work by the group was performed by the member. It can be used to + measure how the workload of the entire group devoted to a certain + type of work is distributed over the group members. + + :param celonis: The Celonis connection + :type celonis: CelonisConnectionManager + + diff --git a/docs/source/autoapi/backend/pql_queries/temporal_profile_queries/index.rst b/docs/source/autoapi/backend/pql_queries/temporal_profile_queries/index.rst new file mode 100644 index 0000000..81e1376 --- /dev/null +++ b/docs/source/autoapi/backend/pql_queries/temporal_profile_queries/index.rst @@ -0,0 +1,42 @@ +backend.pql_queries.temporal_profile_queries +============================================ + +.. py:module:: backend.pql_queries.temporal_profile_queries + +.. autoapi-nested-parse:: + + Queries tused to get temporal profile related data from Celonis. + + + +Functions +--------- + +.. autoapisummary:: + + backend.pql_queries.temporal_profile_queries.get_temporal_conformance_result + + +Module Contents +--------------- + +.. py:function:: get_temporal_conformance_result(celonis: backend.celonis_connection.celonis_connection_manager.CelonisConnectionManager, zeta: float) -> pandas.DataFrame + + Returns the temporal conformance result from Celonis. + + Parameters: + celonis: CelonisConnectionManager + The Celonis connection manager instance. + zeta: float + The zeta value used for temporal conformance checking. + + Returns: + DataFrame + A DataFrame containing the deviations for each trace. Each row contains: + - Case ID of the recorded deviation. + - Source activity of the recorded deviation. + - Target activity of the recorded deviation. + - Time passed between the occurrence of the source activity and the target activity. + - Value of (time passed - mean)/std for this occurrence (zeta). + + diff --git a/docs/source/autoapi/backend/usage_example/index.rst b/docs/source/autoapi/backend/usage_example/index.rst new file mode 100644 index 0000000..8276744 --- /dev/null +++ b/docs/source/autoapi/backend/usage_example/index.rst @@ -0,0 +1,84 @@ +backend.usage_example +===================== + +.. py:module:: backend.usage_example + +.. autoapi-nested-parse:: + + The file is an example of how to use the CelonisConnection Class. + + It contains examples of how to create a Celonis connection, add a + dataframe to the data model, create a table, and get a dataframe from + Celonis. + + + +Attributes +---------- + +.. autoapisummary:: + + backend.usage_example.EVENT_LOG_LOC + backend.usage_example.cfg + backend.usage_example.my_celonis + backend.usage_example.starttime + backend.usage_example.result + + +Classes +------- + +.. autoapisummary:: + + backend.usage_example.CelonisSettings + + +Module Contents +--------------- + +.. py:data:: EVENT_LOG_LOC + :value: '/home/rene/MyProjects/Auto_CC/conformance_checking_spp/tests/input_data/running-example.xes' + + +.. py:class:: CelonisSettings(_case_sensitive: bool | None = None, _nested_model_default_partial_update: bool | None = None, _env_prefix: str | None = None, _env_file: pydantic_settings.sources.DotenvType | None = ENV_FILE_SENTINEL, _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_nested_max_split: int | None = None, _env_parse_none_str: str | None = None, _env_parse_enums: bool | None = None, _cli_prog_name: str | None = None, _cli_parse_args: bool | list[str] | tuple[str, Ellipsis] | None = None, _cli_settings_source: pydantic_settings.sources.CliSettingsSource[Any] | None = None, _cli_parse_none_str: str | None = None, _cli_hide_none_type: bool | None = None, _cli_avoid_json: bool | None = None, _cli_enforce_required: bool | None = None, _cli_use_class_docs_for_groups: bool | None = None, _cli_exit_on_error: bool | None = None, _cli_prefix: str | None = None, _cli_flag_prefix_char: str | None = None, _cli_implicit_flags: bool | None = None, _cli_ignore_unknown_args: bool | None = None, _cli_kebab_case: bool | None = None, _secrets_dir: pydantic_settings.sources.PathType | None = None, **values: Any) + + Bases: :py:obj:`pydantic_settings.BaseSettings` + + + Settings for the Celonis connection. + + This class is used to load the Celonis connection settings from the + environment variables. The settings are loaded from a .env file + using the `pydantic_settings` library. The settings include the + Celonis base URL, data pool name, data model name, and API token. + + + .. py:attribute:: CELONIS_BASE_URL + :type: str + + + .. py:attribute:: CELONIS_DATA_POOL_NAME + :type: str + + + .. py:attribute:: CELONIS_DATA_MODEL_NAME + :type: str + + + .. py:attribute:: API_TOKEN + :type: str + + + .. py:attribute:: model_config + + Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. + + +.. py:data:: cfg + +.. py:data:: my_celonis + +.. py:data:: starttime + +.. py:data:: result + diff --git a/docs/source/autoapi/backend/utils/file_handlers/index.rst b/docs/source/autoapi/backend/utils/file_handlers/index.rst new file mode 100644 index 0000000..36c26ae --- /dev/null +++ b/docs/source/autoapi/backend/utils/file_handlers/index.rst @@ -0,0 +1,66 @@ +backend.utils.file_handlers +=========================== + +.. py:module:: backend.utils.file_handlers + +.. autoapi-nested-parse:: + + Contains utility functions for handling file uploads. + + + +Functions +--------- + +.. autoapisummary:: + + backend.utils.file_handlers.process_xes_file + backend.utils.file_handlers.process_csv_file + backend.utils.file_handlers.process_file + + +Module Contents +--------------- + +.. py:function:: process_xes_file(file_content: bytes) -> pandas.DataFrame + + Processes XES file content and converts it to a DataFrame. + + This function is needed, as the transferred file via the API is in bytes, + and pm4py does not support reading from bytes directly. Therefore, we + create a temporary file to store the uploaded content and then read it + using pm4py. + + :param file_content: Binary content of the XES file. + + :returns: A pandas DataFrame containing the event log. + + :raises ValueError: If the file cannot be processed. + + +.. py:function:: process_csv_file(file_content: bytes) -> pandas.DataFrame + + Processes CSV file content and converts it to a Pandas DataFrame. + + :param file_content: The binary content of the CSV file. + + :returns: A pandas DataFrame containing the CSV data. + + :raises ValueError: If the file cannot be processed. + + +.. py:function:: process_file(file_content: bytes, file_extension: str) -> pandas.DataFrame + + Processes file content and converts it to a pandas DataFrame. + + This function acts as a dispatcher that directs the file processing + to the appropriate handler based on the file extension. + + :param file_content: Binary content of the file. + :param file_extension: The file extension (e.g., ".csv" or ".xes"). + + :returns: A pandas DataFrame containing the processed data. + + :raises ValueError: If the file cannot be processed or if the file type is unsupported. + + diff --git a/docs/source/autoapi/backend/utils/index.rst b/docs/source/autoapi/backend/utils/index.rst new file mode 100644 index 0000000..b75d528 --- /dev/null +++ b/docs/source/autoapi/backend/utils/index.rst @@ -0,0 +1,15 @@ +backend.utils +============= + +.. py:module:: backend.utils + + +Submodules +---------- + +.. toctree:: + :maxdepth: 1 + + /autoapi/backend/utils/file_handlers/index + + diff --git a/docs/source/autoapi/index.rst b/docs/source/autoapi/index.rst new file mode 100644 index 0000000..fc2b120 --- /dev/null +++ b/docs/source/autoapi/index.rst @@ -0,0 +1,11 @@ +API Reference +============= + +This page contains auto-generated API reference documentation [#f1]_. + +.. toctree:: + :titlesonly: + + /autoapi/backend/index + +.. [#f1] Created with `sphinx-autoapi `_ \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..002b386 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,60 @@ +"""Configuration file for the Sphinx documentation builder.""" +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +import os +import sys + +ROOT = os.path.abspath("../..") # …/conformance_checking_spp +BACKEND = os.path.join(ROOT, "backend") + +sys.path.insert(0, ROOT) # <-- ADD THIS +sys.path.insert(0, BACKEND) + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = "Automatic Conformance Checking Insights in Celonis" +copyright = ( + "2025, Samadrita Saha, René Rockstedt, Ekansh Agarwal, Yash Raj, Ole Seifert" +) +author = "Samadrita Saha, René Rockstedt, Ekansh Agarwal, Yash Raj, Ole Seifert" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = ["autoapi.extension", "sphinx.ext.napoleon", "sphinx.ext.githubpages"] + +autoclass_content = "both" + +templates_path = ["_templates"] +exclude_patterns = [] + +# **************** AutoAPI Configuration **************** + +autoapi_type = "python" +autoapi_dirs = [os.path.abspath(os.path.join(os.path.dirname(__file__), "../../backend"))] +autoapi_ignore = ["*tests/*", "*/backend/usage_2.py", "*backend/usage_2.*"] +autoapi_root = "autoapi" +# which things to include +autoapi_options = [ + "members", + "undoc-members", + "show-inheritance", + "show-module-summary", +] +# keep the generated files around (handy for debugging) +autoapi_keep_files = True + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "furo" +html_static_path = ["_static"] +html_theme_options = { + "light_logo": "/img/light-logo.png", + "dark_logo": "/img/dark-logo.png", + "sidebar_hide_name": True, +} diff --git a/docs/source/conformance_checking.rst b/docs/source/conformance_checking.rst new file mode 100644 index 0000000..fdb6fcf --- /dev/null +++ b/docs/source/conformance_checking.rst @@ -0,0 +1,21 @@ +Automatic Conformance Checking +============================== + +This page describes the conformance checking techniques implemented in the project and how they can be interpreted. + +General Insights +---------------- + +The + +Log Skeleton +------------ + +Resource-based +-------------- + +Temporal +-------- + +Declarative +----------- \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..cde68eb --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,46 @@ +.. Automatic Conformance Checking Insights in Celonis documentation master file, created by + sphinx-quickstart on Thu Jun 12 16:58:04 2025. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Automatic Conformance Checking Insights in Celonis documentation +================================================================ + +The 'Automatic Conformance Checking Insights in Celonis' project provides a web application for automatic conformance checking techniques. +It uses the Celonis platform to analyze and pre-process event logs. +It provides insights into the conformance of processes by offering declarative-based, log skeleton-based, temporal, and resource-based conformance checking techniques. +The term 'automatic' stems from the fact that the application automatically computes the insights, without the need for the user to manually upload a process model. + +.. note:: + + This project was developed as part of the "Automatic Conformance Checking Insights in Celonis" software lab offered by the `Chair for Process and Data Science (PADS) `_ at the `RWTH Aachen University `_ under Alessandro Berti. + + All code was written by `Samadrita Saha `_, `René Rockstedt `_, `Ekansh Agrarwal `_, `Yash Raj `_, and `Ole Seifert `_. + +Contents +-------- +.. toctree:: + :maxdepth: 2 + :caption: Contents + :hidden: + + + installation + usage + conformance_checking + architecture + autoapi/index + + +* :doc:`installation` +* :doc:`usage` +* :doc:`conformance_checking` +* :doc:`architecture` + + +Indices and tables +------------------ + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` \ No newline at end of file diff --git a/docs/source/installation.rst b/docs/source/installation.rst new file mode 100644 index 0000000..4274abd --- /dev/null +++ b/docs/source/installation.rst @@ -0,0 +1,77 @@ +Installation +============ + +This page describes how to install the package. +There exist two ways to install the application: manually or via Docker. + +.. tip:: + + We recommend using Docker for installation, as it is the easiest way to get started with the application. + +Manual Installation +------------------- + +Manually installing the application requires setting up both the backend and frontend dependencies. +To install the application manually, you need to follow these steps: + +Backend Dependencies +^^^^^^^^^^^^^^^^^^^^ + +For installing the project's backend dependencies, we recommend using `uv `_ as it operates very quickly. +To install the project's backend dependencies using uv, follow these steps: + +1. Ensure that you have uv installed on your system (see `here `_ for installation instructions). +2. Clone the repository to your local machine using ``git clone``. +3. Navigate to the root directory of the repository. +4. Run ``uv sync``. uv will then install all necessary dependencies and create a virtual environment in the ``.venv`` folder at the root of the project. +5. Activate the environment by running ``source ./.venv/bin/activate`` on Mac and Linux, or ``.venv\Scripts\activate`` on Windows. + +Frontend Dependencies +^^^^^^^^^^^^^^^^^^^^^ + +To install the project's frontend dependencies, you need to have `Node.js `_ and `npm `_ installed on your system. +To install the project's frontend dependencies, follow these steps: + +1. Ensure that you have Node.js and npm installed on your system. +2. Navigate to the ``frontend`` directory of the repository. +3. Run ``npm install``. This will install all necessary frontend dependencies. + + +Running the project +^^^^^^^^^^^^^^^^^^^ + +To run the project, locally you have to start the **backend server** and the **frontend server**. +To start the backend server, open the shell of your choice and run the following command: + +.. code-block:: shell + + uv run uvicorn backend.main:app + +This runs the backend server on port ``8000`` by default. + +To start the frontend server, open another shell, navigate to the ``frontend`` directory and run the following command: + +.. code-block:: shell + + npm run frontend + +This runs the frontend server on port ``3000`` by default. + +To access the application, open your web browser and navigate to ``_. + +Docker Installation +------------------- + +Installing the application via Docker is the easiest way to get started. +To install the application via Docker, follow these steps: + +1. Ensure that you have Docker installed on your system (see `here `_ for installation instructions). +2. Clone the repository to your local machine using ``git clone``. +3. Navigate to the root directory of the repository. +4. Build the Docker image by running the following command (make sure **Docker is running**): + +.. code-block:: shell + + docker compose up --build + +5. Once the build is complete, the application will be running on port ``3000`` by default. \ No newline at end of file diff --git a/docs/source/usage.rst b/docs/source/usage.rst new file mode 100644 index 0000000..ce98f49 --- /dev/null +++ b/docs/source/usage.rst @@ -0,0 +1,100 @@ +Usage +===== + +This page explains how to use the application after installation. + +.. important:: + + You need a Celonis account to use the application. + +Adding Celonis Credentials +-------------------------- + +The first page you will see after starting the application in your browser is the **Celonis Credentials** page. + +.. image:: ./_static/img/frontend/celonis_credentials.jpeg + + +Here you you need to enter your Celonis credentials. +In the following we explain how to obtain these credentials. + +Celonis API URL +^^^^^^^^^^^^^^^ + +You need access to the Celonis Academic programm to obtain the ``API URL``. +When you are logged in to the Celonis platform you can copy your ``API URL`` from the URL bar of your browser. +It should look something like this: + +``https://academic-celonis-.celonis.cloud/`` + +Celonis API Token +^^^^^^^^^^^^^^^^^ + +To obtain your ``API Token``, you need to log in to the Celonis platform and navigate to the your account settings section. +You find it in the bottom of the left sidebar. +Then you have to click on "Edit Profile". + +.. image:: ./_static/img/frontend/settings.jpeg + +Then you need to scroll down to the **API-Keys** section. + +.. image:: ./_static/img/frontend/api_token.png + +There you can create a new ``API Token`` that you can copy and paste into the application. + +.. note:: + + Maybe store it somewhere safe, so you can use it again later. + +Data Model and Data Pool Name +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Here you can choose names you like for your Data Model and Data Pool. +These names will be used to store the data you upload in the Celonis platform. + +Uploading an Event Log +---------------------- + +The next page you will see is the **Upload Event Log** page. + +.. image:: ./_static/img/frontend/upload.jpeg + +Here you can upload your event log in ``CSV`` or ``XES`` format. + + +Mapping the Event Log Columns +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +After you uploaded your event log, you will be redirected to the **Map Event Log Columns** page. + +.. image:: ./_static/img/frontend/mapping.jpeg + +Here you need to map the columns of your event log to the required columns for the conformance checking techniques. +The required columns are: + +* **Case ID**: The unique identifier for each case in the event log. +* **Activity**: The activity that was performed in the case. +* **Timestamp**: The timestamp of the activity in the case. + +Optionally, you can also map the following columns: + +* **Resource**: The resource that performed the activity in the case (if applicable). +* **Group**: The Group that the resource belongs to (if applicable). + +.. note:: + + Note that you need to map the Resource column in order to use the resource-based conformance checking techniques. + If you do not have a Resource column in your event log, you can leave it empty. + +Conformance Checking Insights +----------------------------- + +The last page you see is the **Conformance Checking Insights** page. +This is the main page of the application, where you can see the results of the different conformance checking techniques. + +.. image:: ./_static/img/frontend/conf_insight.jpeg + +Here you can select different conformance checking techniques. +For each technique you can select different aspects to analyze. + +For an indepth explanation of the different conformance checking techniques, please refer to the :doc:`conformance_checking` page. \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index e5d60b0..7f5136f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -35,4 +35,4 @@ pythonpath = "backend" url = "https://pypi.celonis.cloud/" [tool.mypy] -exclude = "tests/" +exclude = ["tests/", "docs/"] diff --git a/ruff.toml b/ruff.toml index 71a0815..79feaab 100644 --- a/ruff.toml +++ b/ruff.toml @@ -26,6 +26,7 @@ exclude = [ "node_modules", "site-packages", "venv", + "docs/" ] # Same as Black.