objektviz 0.2.2__tar.gz

objektviz-0.2.2/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: objektviz
+Version: 0.2.2
+Summary: ObjektViz is a visualizer for object-centric process models that enables users to explore and analyze even _very complex_ processes involving multiple interacting objects
+Project-URL: Homepage, https://mamiksik.github.io/ObjektViz/
+Project-URL: Repository, https://github.com/mamiksik/ObjektViz.git
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: graphviz>=0.21
+Requires-Dist: kuzu>=0.11.3
+Requires-Dist: matplotlib>=3.10.7
+Requires-Dist: neo4j>=6.0.3
+Requires-Dist: scikit-learn>=1.7.2
+Requires-Dist: streamlit[charts]>=1.51.0
+Requires-Dist: watchdog>=6.0.0
+Provides-Extra: publish
+Requires-Dist: build; extra == "publish"
+Requires-Dist: twine; extra == "publish"
+
+# 📦 ObjektViz
+
+<p align="center">
+    <img src="assets/objektviz.png" alt="ObjektViz Screenshot" width="550px" align='center'/>
+</p>
+
+> ObjektViz is a visualizer for object-centric process models that enables users to explore and analyze even _very complex_ processes involving multiple interacting objects.
+
+## Features
+- 🔍 **Interactive Visualization**: Explore object-centric process models with intuitive visualizations.
+- 🤝 **Multi-Object Support**: Analyze processes involving multiple interacting objects seamlessly.
+- ⚙️ **Customizable**: Every dataset, every process is different. ObjektViz allows you to customize visualizations to fit your data.
+- 🧩 **Manage Complexity**: Designed to handle very complex processes without overwhelming the user.
+- ▶️ **Token Replay**: Replay the flow of tokens through the process to understand dynamics and interactions, even for **multi-object** scenarios.
+- 🔄 **Morphing Visualizations**: Smoothly transition between different views and representations of the process model to understand various aspects of the data.
+
+## Quick Start
+ObjektViz has a lot of customization, and is built with the idea that you as a user will compose your own dashboard for the analysis you have at hand. However, to get you started quickly, we provide some example dashboards that you can run and explore.
+
+In the examples we use KuzuDB, which works fine for small examples and the setup is easy. For real-world datasets, you might use Neo4J, but that requires more setup.
+We have exported and processed some OCEL datasets into EKG and generated aggregated views (i.e. process models) for you to explore in the examples.
+
+1. Clone the repository:
+   ```bash
+   git clone git@github.com:mamiksik/ObjektViz.git
+2. Navigate to the project directory:
+   ```bash
+   cd ObjektViz
+3. Install the required dependencies (we use [uv](https://docs.astral.sh/uv/) to manage the Python environment and dependencies):
+   ```bash
+   uv sync
+
+4. Activate the virtual environment (bash shell):
+   ```bash
+   source .venv/bin/activate
+
+5. Run the example dashboard:
+    ```bash
+   streamlit run examples/generic_ocel_viewer.py
+   ```
+> INFO: Using Chrome is strongly recommended. Mozilla Firefox and Safari should also work. (Although Safari does not support token replay.)
+
+> INFO: Token Replay for now requires APOC library and is thus not available with KuzuDB
+
+6. [OPTIONAL] If you are planning on editing the objektviz source code, you can install the objektviz package it in editable mode:
+    ```bash
+   uv add --editable --dev objektviz
+   ```
+
+<p align="center">
+    <img src="assets/generic_ocel_visualizer.png" alt="Visualizer" width="750px" align='center'/>
+</p>
+
+## Feature spotlight 
+
+**Morphing and Animation** - ObjektViz supports smooth morphing between different process model views. This allows users to transition seamlessly from one perspective to another, this helps to manage complexity and understand different aspects of the process.
+<p align="center">
+    <img src="assets/morphing.gif" alt="Morphing" width="550px" align='center'/>
+</p>
+
+**Shaders** - color lightness and thickness of edges play critical role in making a proces s model understandable. ObjektViz supports a variety of shaders that can be applied to nodes and edges to highlight different aspects of the process model or to deal with skewed distributions.
+<p align="center">
+    <img src="assets/shader-types.png" alt="Custom Shaders" width="300px" align='center'/>
+</p>
+
+**Token Replay** - understand the dynamics of your process by replaying tokens through the process model. This feature allows you to visualize how different objects interact over time within the process.
+<p align="center">
+    <img src="assets/token-replay.gif" alt="Custom Shaders" width="550px" align='center'/>
+</p>
+
+## Import your own OCEL dataset
+To import your own OCEL dataset, you need to convert it into EKG format first and then generate aggregated views (i.e., process models) from it.
+We provide scripts to help you with this process in the `examples` folder.
+
+1. Convert OCEL to EKG and infer aggregated views:
+   ```bash
+   uv run python examples/ocel/kuzudb/process_ocel_to_kuzudb.py path/to/your/ocel.json path/to/save/ekg.kuzu
+   ```
+2. Copy one of the example dashboards (e.g. 'examples/generic_ocel_viewer.py') script and modify it to point to your newly created EKG database. The line to change is where the database is initialized:
+    ```python
+    db = kuzu.Database("path/to/save/ekg.kuzu")
+    ```
+3. Run your modified dashboard:
+    ```bash
+    uv run python -m streamlit run path/to/your/custom_dashboard.py
+    ```
+
+# ObjektViz Proclet Metamodel (Work In Progress - Subject to Change)
+<p align="center">
+    <img src="assets/metamodel-objektviz.png" alt="Proclet Metamodel" width="550px" align='center'/>
+</p>
+

objektviz-0.2.2/README.md

@@ -0,0 +1,92 @@
+# 📦 ObjektViz
+
+<p align="center">
+    <img src="assets/objektviz.png" alt="ObjektViz Screenshot" width="550px" align='center'/>
+</p>
+
+> ObjektViz is a visualizer for object-centric process models that enables users to explore and analyze even _very complex_ processes involving multiple interacting objects.
+
+## Features
+- 🔍 **Interactive Visualization**: Explore object-centric process models with intuitive visualizations.
+- 🤝 **Multi-Object Support**: Analyze processes involving multiple interacting objects seamlessly.
+- ⚙️ **Customizable**: Every dataset, every process is different. ObjektViz allows you to customize visualizations to fit your data.
+- 🧩 **Manage Complexity**: Designed to handle very complex processes without overwhelming the user.
+- ▶️ **Token Replay**: Replay the flow of tokens through the process to understand dynamics and interactions, even for **multi-object** scenarios.
+- 🔄 **Morphing Visualizations**: Smoothly transition between different views and representations of the process model to understand various aspects of the data.
+
+## Quick Start
+ObjektViz has a lot of customization, and is built with the idea that you as a user will compose your own dashboard for the analysis you have at hand. However, to get you started quickly, we provide some example dashboards that you can run and explore.
+
+In the examples we use KuzuDB, which works fine for small examples and the setup is easy. For real-world datasets, you might use Neo4J, but that requires more setup.
+We have exported and processed some OCEL datasets into EKG and generated aggregated views (i.e. process models) for you to explore in the examples.
+
+1. Clone the repository:
+   ```bash
+   git clone git@github.com:mamiksik/ObjektViz.git
+2. Navigate to the project directory:
+   ```bash
+   cd ObjektViz
+3. Install the required dependencies (we use [uv](https://docs.astral.sh/uv/) to manage the Python environment and dependencies):
+   ```bash
+   uv sync
+
+4. Activate the virtual environment (bash shell):
+   ```bash
+   source .venv/bin/activate
+
+5. Run the example dashboard:
+    ```bash
+   streamlit run examples/generic_ocel_viewer.py
+   ```
+> INFO: Using Chrome is strongly recommended. Mozilla Firefox and Safari should also work. (Although Safari does not support token replay.)
+
+> INFO: Token Replay for now requires APOC library and is thus not available with KuzuDB
+
+6. [OPTIONAL] If you are planning on editing the objektviz source code, you can install the objektviz package it in editable mode:
+    ```bash
+   uv add --editable --dev objektviz
+   ```
+
+<p align="center">
+    <img src="assets/generic_ocel_visualizer.png" alt="Visualizer" width="750px" align='center'/>
+</p>
+
+## Feature spotlight 
+
+**Morphing and Animation** - ObjektViz supports smooth morphing between different process model views. This allows users to transition seamlessly from one perspective to another, this helps to manage complexity and understand different aspects of the process.
+<p align="center">
+    <img src="assets/morphing.gif" alt="Morphing" width="550px" align='center'/>
+</p>
+
+**Shaders** - color lightness and thickness of edges play critical role in making a proces s model understandable. ObjektViz supports a variety of shaders that can be applied to nodes and edges to highlight different aspects of the process model or to deal with skewed distributions.
+<p align="center">
+    <img src="assets/shader-types.png" alt="Custom Shaders" width="300px" align='center'/>
+</p>
+
+**Token Replay** - understand the dynamics of your process by replaying tokens through the process model. This feature allows you to visualize how different objects interact over time within the process.
+<p align="center">
+    <img src="assets/token-replay.gif" alt="Custom Shaders" width="550px" align='center'/>
+</p>
+
+## Import your own OCEL dataset
+To import your own OCEL dataset, you need to convert it into EKG format first and then generate aggregated views (i.e., process models) from it.
+We provide scripts to help you with this process in the `examples` folder.
+
+1. Convert OCEL to EKG and infer aggregated views:
+   ```bash
+   uv run python examples/ocel/kuzudb/process_ocel_to_kuzudb.py path/to/your/ocel.json path/to/save/ekg.kuzu
+   ```
+2. Copy one of the example dashboards (e.g. 'examples/generic_ocel_viewer.py') script and modify it to point to your newly created EKG database. The line to change is where the database is initialized:
+    ```python
+    db = kuzu.Database("path/to/save/ekg.kuzu")
+    ```
+3. Run your modified dashboard:
+    ```bash
+    uv run python -m streamlit run path/to/your/custom_dashboard.py
+    ```
+
+# ObjektViz Proclet Metamodel (Work In Progress - Subject to Change)
+<p align="center">
+    <img src="assets/metamodel-objektviz.png" alt="Proclet Metamodel" width="550px" align='center'/>
+</p>
+

objektviz-0.2.2/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=77.0.3", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "objektviz"
+version = "0.2.2"
+description = "ObjektViz is a visualizer for object-centric process models that enables users to explore and analyze even _very complex_ processes involving multiple interacting objects"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "graphviz>=0.21",
+    "kuzu>=0.11.3",
+    "matplotlib>=3.10.7",
+    "neo4j>=6.0.3",
+    "scikit-learn>=1.7.2",
+    "streamlit[charts]>=1.51.0",
+    "watchdog>=6.0.0",
+]
+
+[project.optional-dependencies]
+publish = ["build", "twine"]
+
+[project.urls]
+Homepage = "https://mamiksik.github.io/ObjektViz/"
+Repository = "https://github.com/mamiksik/ObjektViz.git"
+
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ['objektviz*']
+
+[tool.uv.sources]
+objektviz = { workspace = true, editable = true }
+
+
+[dependency-groups]
+dev = [
+    "objektviz",
+    "ruff>=0.14.13",
+]

objektviz-0.2.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

objektviz-0.2.2/src/objektviz/backend/BackendConfig.py

@@ -0,0 +1,145 @@
+import dataclasses
+from typing import Callable, Self, Literal
+
+from objektviz.backend.filters import AbstractFilter
+from objektviz.backend.shaders import AbstractShader
+
+
+@dataclasses.dataclass
+class LayoutPreferences:
+    """Subset of settings related to dot node and edge layout"""
+
+    # All classes with the same activity string are put on the same level
+    force_same_rank_for_event_class: bool = False
+
+    # Make rank exclusive
+    exclusive_event_class_ranks_experimental: bool = False
+
+    # Force that start/end nodes are on same rank (diff for start and end)
+    force_process_start_end_same_rank: bool = False
+
+    # Sort nodes based on frequency, this influences the order in which they are
+    # declared in the dot source code (this then influences the layout heuristics)
+    sort_event_classes_by_frequency: bool = True
+
+    # Sort edges based on frequency, this influences the order in which they are
+    # declared in the dot source code (this then influences the layout heuristics)
+    sort_connections_by_frequency: bool = True
+
+    # If set to an attribute name, the attribute values will be used as edge weights
+    # during layout computation. Higher weight means that the edge is "shorter" and "straighter"
+    weight_attribute: str | None = None
+
+    # List of keys used to create subgraph clusters, order matters!
+    # e.g. ['EntityType', 'Location'] will create big clusters for
+    # each entity type and within each it will create sub-clusters
+    # for each location
+    clustering_keys: list = dataclasses.field(default_factory=list)
+
+    # Minimal (horizontal) spacing between nodes on the same rank/level
+    node_separation: float = 0.5
+
+    # Minimal vertical spacing between ranks/levels
+    rank_separation: float = 0.5
+
+    # Direction of the graph layout
+    rank_direction: Literal["TB", "BT", "LR", "RL"] = "TB"  # Top to Bottom
+
+
+@dataclasses.dataclass
+class EventClassPreferences:
+    """Subset of settings related to dot node appearance and content"""
+
+    # Which (numeric) attributes is used to compute the shading range
+    shading_attr: str
+
+    # Attribute to be displayed as the node title
+    title: str
+
+    # Which attribute is used to display value on the left of the node
+    caption_left: str
+
+    # Which attribute is used to display value on the right of the node
+    caption_right: str
+
+    # In case the attribute value matches the value in the dict, the item
+    # will be used as prefix
+    # e.g. {"EntityType": {"Package": "📦","Contract": "📝"}}
+    icon_map: dict[str, dict[str, str]]
+
+
+@dataclasses.dataclass
+class DFCPreferences:
+    """Subset of settings related to dot edge appearance and content"""
+
+    # Which attribute is used to display value on top of the edge
+    caption: str
+
+    # Which (numeric) attributes is used to compute the shading range
+    shading_attr: str
+
+    # If true, xlabels are used for caption, this means the labels are not taking into account while computing layout
+    # It might prodice more compact and less convoluted routes for edges, but labels might not be visible
+    use_x_labels: bool
+
+    # Minimal and maximal edge line thickens. e.g (1, 15)
+    pen_width_range: tuple[int, int]
+
+    # If true, the edge will be shaded with the same color as the connected nodes,
+    # else plain green/red color will be used for start/end edges respectively
+    use_shading_color_on_start_end_edge: bool = False
+
+    # If true, the start/end edges will have lower opacity to not overpower the nodes and other edges
+    lower_start_end_edge_opacity: bool = False
+
+    # If true, the :SYNC edges will be hidden, this is useful when there are too many :SYNC edges that make the graph unreadable
+    hide_sync_edges: bool = False
+
+
+@dataclasses.dataclass
+class BackendConfig:
+    """Configuration of ObjektViz backend, used to generate dot source based"""
+
+    # What attribute is used group shaders
+    shader_groping_key: str
+
+    # Mapping of shader_grouping_key attr values to color map name (matplotlib.colors.Colormap) or hex color
+    # Matplot lib color maps are safer option since the luminosity change is precised uniformly,
+    # but that also means that there is only very few of them.
+    # e.g. {'Loan Application': ("hex", "#FF00FF"), "Workflow": ("cmap", "Reds")}
+    shader_groups_color: dict[str, tuple[str, str]]
+
+    # If true, process start/end nodes will be computed and visualized
+    # This requires that the :Class nodes have "StartCount" and "EndCount" attributes defined
+    show_start_end_nodes: bool
+
+    # If true, each cluster will have its own virtual start/end node
+    show_start_end_nodes_per_cluster: bool
+
+    # Root filter used to filter :Class nodes (to include all nodes, just pass instance of DummyFilter)
+    event_class_root_filter: AbstractFilter
+
+    # Root filter used to filter :DF_C edges (to include all edges, just pass instance of DummyFilter)
+    dfc_root_filter: AbstractFilter
+
+    # Global filter is applied to all elements including :SYNC edges
+    # this is useful for instance for element_id filter to remove any elements based on their id
+    # Also take into account not all elements have to have the same attribute, so use with caution
+    root_element_filter: AbstractFilter | None
+
+    layout_preferences: LayoutPreferences
+    dfc_preferences: DFCPreferences
+    event_class_preferences: EventClassPreferences
+
+    # Factory that creates the shader instances for event classes and connections
+    # The parameters are:
+    #   1) config (instance of this class),
+    #   2) leading_attribute (shading attributed),
+    #   3) cmap (matplotlib.colors.Colormap)
+    # The factory must return an instance of AbstractShader subclass
+    # e.g.
+    #
+    # lambda config, leading_attribute, cmap: NormalizedShader(
+    #   config=config, leading_attribute=leading_attribute, cmap=cmap
+    # )
+    shader_factory: Callable[[Self, str, str], AbstractShader]

objektviz-0.2.2/src/objektviz/backend/SessionState.py

@@ -0,0 +1,8 @@
+import dataclasses
+
+
+@dataclasses.dataclass
+class SessionState:
+    selected_edge: str = None
+    selected_class: str = None
+