ocelescope 0.1.1b1__tar.gz

ocelescope-0.1.1b1/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.3
+Name: ocelescope
+Version: 0.1.1b1
+Summary: General tools for working with Object-Centric Event Logs and building Ocelescope plugins
+Requires-Dist: cachetools>=6.1.0
+Requires-Dist: networkx>=3.5
+Requires-Dist: numpy>=2.3.2
+Requires-Dist: pandas>=2.3.1
+Requires-Dist: pm4py~=2.7.15.3
+Requires-Dist: pydantic>=2.11.7
+Requires-Python: ~=3.13
+Description-Content-Type: text/markdown
+
+# oceloscope-tools-grkmr
+
+General tools and building blocks for working with [Object-Centric Event Logs (OCEL)](https://ocel-standard.org/) and writing plugins for the [OCELoscope](https://github.com/rwth-pads/ocelescope) framework.
+
+---
+
+## 📦 Installation
+
+Install directly from Git:
+
+```bash
+pip install git+https://github.com/grkmr/ocelescope-tools.git
+

ocelescope-0.1.1b1/README.md

@@ -0,0 +1,13 @@
+# oceloscope-tools-grkmr
+
+General tools and building blocks for working with [Object-Centric Event Logs (OCEL)](https://ocel-standard.org/) and writing plugins for the [OCELoscope](https://github.com/rwth-pads/ocelescope) framework.
+
+---
+
+## 📦 Installation
+
+Install directly from Git:
+
+```bash
+pip install git+https://github.com/grkmr/ocelescope-tools.git
+

ocelescope-0.1.1b1/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "ocelescope"
+version = "0.1.1b1"
+description = "General tools for working with Object-Centric Event Logs and building Ocelescope plugins"
+readme = "README.md"
+requires-python = "~=3.13"
+dependencies = [
+  "cachetools>=6.1.0",
+  "networkx>=3.5",
+  "numpy>=2.3.2",
+  "pandas>=2.3.1",
+  "pm4py~=2.7.15.3",
+  "pydantic>=2.11.7",
+]
+
+[tool.uv]
+package = true
+
+[dependency-groups]
+dev = ["black>=25.1.0", "pre-commit>=4.2.0", "ruff>=0.12.7"]
+
+[build-system]
+requires = ["uv_build>=0.8.4,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.black]
+line-length = 100
+
+[tool.ruff]
+line-length = 100
+fix = true
+lint.ignore = ["E731", "E501"]

ocelescope-0.1.1b1/src/ocelescope/__init__.py

@@ -0,0 +1,60 @@
+from ocelescope.ocel import (
+    E2OCountFilter,
+    EventAttributeFilter,
+    EventTypeFilter,
+    O2OCountFilter,
+    ObjectAttributeFilter,
+    TimeFrameFilter,
+    OCELFilter,
+    OCELExtension,
+    ObjectTypeFilter,
+    OCEL,
+    RelationCountSummary,
+    AttributeSummary,
+)
+from ocelescope.visualization import Visualization
+from ocelescope.resource import PetriNet, Resource, DirectlyFollowsGraph
+from ocelescope.plugin import (
+    ResourceAnnotation,
+    OCELAnnotation,
+    Plugin,
+    PluginMeta,
+    PluginMethod,
+    COMPUTED_SELECTION,
+    OCEL_FIELD,
+    PluginInput,
+    PluginResult,
+    plugin_method,
+)
+import matplotlib
+
+matplotlib.use("Agg")
+
+__all__ = [
+    "OCEL",
+    "OCELExtension",
+    "E2OCountFilter",
+    "EventAttributeFilter",
+    "EventTypeFilter",
+    "O2OCountFilter",
+    "ObjectAttributeFilter",
+    "ObjectTypeFilter",
+    "TimeFrameFilter",
+    "OCELFilter",
+    "RelationCountSummary",
+    "AttributeSummary",
+    "Visualization",
+    "PetriNet",
+    "DirectlyFollowsGraph",
+    "Resource",
+    "ResourceAnnotation",
+    "OCELAnnotation",
+    "Plugin",
+    "PluginMeta",
+    "PluginMethod",
+    "COMPUTED_SELECTION",
+    "OCEL_FIELD",
+    "PluginInput",
+    "PluginResult",
+    "plugin_method",
+]

ocelescope-0.1.1b1/src/ocelescope/ocel/__init__.py

@@ -0,0 +1,32 @@
+from ocelescope.ocel.ocel import OCEL
+
+from ocelescope.ocel.extension import OCELExtension
+from ocelescope.ocel.filter import (
+    E2OCountFilter,
+    EventAttributeFilter,
+    EventTypeFilter,
+    O2OCountFilter,
+    ObjectAttributeFilter,
+    TimeFrameFilter,
+    OCELFilter,
+    ObjectTypeFilter,
+)
+from ocelescope.ocel.util import AttributeSummary, RelationCountSummary
+
+from ocelescope.ocel.constants import OCELFileExtensions
+
+__all__ = [
+    "OCEL",
+    "OCELExtension",
+    "E2OCountFilter",
+    "EventAttributeFilter",
+    "EventTypeFilter",
+    "O2OCountFilter",
+    "ObjectTypeFilter",
+    "ObjectAttributeFilter",
+    "TimeFrameFilter",
+    "AttributeSummary",
+    "RelationCountSummary",
+    "OCELFilter",
+    "OCELFileExtensions",
+]

ocelescope-0.1.1b1/src/ocelescope/ocel/constants.py

@@ -0,0 +1,4 @@
+from typing import Literal
+
+
+OCELFileExtensions = Literal[".xmlocel", ".jsonocel", ".sqlite"]

ocelescope-0.1.1b1/src/ocelescope/ocel/extension.py

@@ -0,0 +1,44 @@
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import TYPE_CHECKING, TypeVar
+
+from ocelescope.ocel.constants import OCELFileExtensions
+
+if TYPE_CHECKING:
+    from ocelescope.ocel.ocel import OCEL
+
+T = TypeVar("T", bound="OCELExtension")
+
+
+class OCELExtension(ABC):
+    """
+    Abstract base class for OCEL extensions that can be imported/exported from a file path.
+    """
+
+    name: str
+    description: str
+    version: str
+    supported_extensions: list[OCELFileExtensions]
+
+    @staticmethod
+    @abstractmethod
+    def has_extension(path: Path) -> bool:
+        """
+        Check if the extension data exists at the given path.
+        """
+        pass
+
+    @classmethod
+    @abstractmethod
+    def import_extension(cls: type[T], ocel: "OCEL", path: Path) -> T:
+        """
+        Create the extension by reading from the given path.
+        """
+        pass
+
+    @abstractmethod
+    def export_extension(self, path: Path) -> None:
+        """
+        Write the extension data to the given path.
+        """
+        pass

ocelescope-0.1.1b1/src/ocelescope/ocel/filter/__init__.py

@@ -0,0 +1,25 @@
+from ocelescope.ocel.filter.apply import apply_filters
+
+from .filters import (
+    E2OCountFilter,
+    EventAttributeFilter,
+    EventTypeFilter,
+    O2OCountFilter,
+    ObjectAttributeFilter,
+    TimeFrameFilter,
+    OCELFilter,
+    ObjectTypeFilter,
+)
+
+
+__all__ = [
+    "apply_filters",
+    "OCELFilter",
+    "ObjectTypeFilter",
+    "EventTypeFilter",
+    "ObjectAttributeFilter",
+    "EventAttributeFilter",
+    "O2OCountFilter",
+    "E2OCountFilter",
+    "TimeFrameFilter",
+]

ocelescope-0.1.1b1/src/ocelescope/ocel/filter/apply.py

@@ -0,0 +1,55 @@
+from typing import Optional, cast, TYPE_CHECKING
+
+import pandas as pd
+import pm4py
+
+
+from ocelescope.ocel.filter.base import BaseFilter, FilterResult
+
+from ocelescope.ocel.filter.filters import OCELFilter
+
+if TYPE_CHECKING:
+    from ocelescope.ocel.ocel import OCEL
+
+
+def compute_combined_masks(ocel: "OCEL", filters: OCELFilter) -> FilterResult:
+    combined = FilterResult(
+        events=pd.Series(True, index=ocel.events.index),
+        objects=pd.Series(True, index=ocel.objects.index),
+    )
+
+    for filter in filters.values():
+        filter_list = cast(list[BaseFilter], filter if isinstance(filter, list) else [filter])
+
+        for filter in filter_list:
+            combined = combined.and_merge(filter.filter(ocel))
+
+    return combined
+
+
+def apply_filters(ocel: "OCEL", filters: OCELFilter) -> "OCEL":
+    from ..ocel import OCEL
+
+    masks = compute_combined_masks(ocel, filters)
+
+    filtered_event_ids: Optional[pd.Series] = (
+        cast(pd.Series, ocel.events[ocel.ocel.event_id_column][masks.events])
+        if masks.events is not None
+        else None
+    )
+
+    filtered_object_ids: Optional[pd.Series] = (
+        cast(pd.Series, ocel.objects[ocel.ocel.object_id_column][masks.objects])
+        if masks.objects is not None
+        else None
+    )
+
+    filtered_ocel = ocel.ocel
+
+    if filtered_event_ids is not None:
+        filtered_ocel = pm4py.filter_ocel_events(filtered_ocel, filtered_event_ids, positive=True)
+
+    if filtered_object_ids is not None:
+        filtered_ocel = pm4py.filter_ocel_objects(filtered_ocel, filtered_object_ids, positive=True)
+
+    return OCEL(filtered_ocel, ocel.id)

ocelescope-0.1.1b1/src/ocelescope/ocel/filter/base.py

@@ -0,0 +1,38 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Optional, TYPE_CHECKING
+
+from pandas import Series
+from pydantic import BaseModel
+
+
+if TYPE_CHECKING:
+    from ocelescope import OCEL
+
+
+@dataclass()
+class FilterResult:
+    events: Optional[Series] = None
+    objects: Optional[Series] = None
+
+    def and_merge(self, other: "FilterResult") -> "FilterResult":
+        def _and(a, b):
+            if a is not None and b is not None:
+                return a & b
+            elif a is not None:
+                return a
+            elif b is not None:
+                return b
+            else:
+                return None
+
+        return FilterResult(
+            events=_and(self.events, other.events),
+            objects=_and(self.objects, other.objects),
+        )
+
+
+class BaseFilter(ABC, BaseModel):
+    @abstractmethod
+    def filter(self, ocel: "OCEL") -> FilterResult:
+        pass

ocelescope-0.1.1b1/src/ocelescope/ocel/filter/filters/__init__.py

@@ -0,0 +1,32 @@
+from typing import TypedDict
+
+
+from ocelescope.ocel.filter.filters.attribute import EventAttributeFilter, ObjectAttributeFilter
+from ocelescope.ocel.filter.filters.entity_type import (
+    EventTypeFilter,
+    ObjectTypeFilter,
+)
+from ocelescope.ocel.filter.filters.relation_count import E2OCountFilter, O2OCountFilter
+from ocelescope.ocel.filter.filters.time_range import TimeFrameFilter
+
+
+class OCELFilter(TypedDict, total=False):
+    object_types: ObjectTypeFilter
+    event_type: EventTypeFilter
+    time_range: TimeFrameFilter
+    o2o_count: list[O2OCountFilter]
+    e2o_count: list[E2OCountFilter]
+    event_attributes: list[EventAttributeFilter]
+    object_attributes: list[ObjectAttributeFilter]
+
+
+__all__ = [
+    "OCELFilter",
+    "ObjectTypeFilter",
+    "EventTypeFilter",
+    "ObjectAttributeFilter",
+    "EventAttributeFilter",
+    "O2OCountFilter",
+    "E2OCountFilter",
+    "TimeFrameFilter",
+]

ocelescope-0.1.1b1/src/ocelescope/ocel/filter/filters/attribute.py

@@ -0,0 +1,100 @@
+from typing import Optional, Tuple, Union, cast
+
+import pandas as pd
+from pandas.api.types import is_datetime64_any_dtype, is_numeric_dtype
+from pandas.core.frame import DataFrame
+from pandas.core.series import Series
+from pydantic.main import BaseModel
+
+from ocelescope.ocel.util.attributes import get_objects_with_object_changes
+
+from ..base import BaseFilter, FilterResult
+
+
+class AttributeFilterConfig(BaseModel):
+    target_type: str
+    attribute: str
+
+    # Range filters
+    time_range: Optional[Tuple[Optional[str], Optional[str]]] = None
+    number_range: Optional[Tuple[Optional[Union[int, float]], Optional[Union[int, float]]]] = None
+
+    # Nominal filters
+    values: Optional[list[Union[str, int, float]]] = None
+    regex: Optional[str] = None
+
+
+def filter_by_attribute(attribute_df: DataFrame, type_column: str, config: AttributeFilterConfig):
+    df = attribute_df
+    col = config.attribute
+
+    if col not in df.columns:
+        raise ValueError(f"Attribute '{col}' not found in {config.target_type} data")
+
+    series = cast(Series, df[col])
+    mask = pd.Series(True, index=series.index)
+
+    # Handle numeric filtering
+    if config.number_range is not None:
+        if is_numeric_dtype(series):
+            numeric_series = series
+        else:
+            numeric_series = pd.to_numeric(series, errors="coerce")
+
+        if config.number_range[0] is not None:
+            mask &= numeric_series >= float(config.number_range[0])  # type:ignore
+        if config.number_range[1] is not None:
+            mask &= numeric_series <= float(config.number_range[1])  # type:ignore
+
+    # Handle date filtering
+    elif config.time_range is not None:
+        if is_datetime64_any_dtype(series):
+            date_series = series
+        else:
+            date_series = pd.to_datetime(series, errors="coerce")
+
+        if config.time_range[0] is not None:
+            mask &= date_series >= pd.to_datetime(config.time_range[0])
+        if config.time_range[1] is not None:
+            mask &= date_series <= pd.to_datetime(config.time_range[1])
+
+    # Handle nominal filtering
+    if config.values is not None:
+        mask &= series.isin(config.values)
+
+    if config.regex is not None:
+        mask &= series.astype(str).str.contains(config.regex, regex=True, na=False)
+
+    is_not_target_type = attribute_df[type_column] != config.target_type
+
+    final_mask = cast(Series, is_not_target_type | mask)
+    return final_mask
+
+
+class EventAttributeFilter(BaseFilter, AttributeFilterConfig):
+    def filter(self, ocel):
+        return FilterResult(
+            events=filter_by_attribute(
+                ocel.events,
+                ocel.ocel.event_activity,
+                config=AttributeFilterConfig(**self.model_dump()),
+            )
+        )
+
+
+class ObjectAttributeFilter(BaseFilter, AttributeFilterConfig):
+    def filter(self, ocel):
+        enriched_objects = get_objects_with_object_changes(ocel.ocel)
+
+        filtered_rows = enriched_objects[
+            filter_by_attribute(
+                enriched_objects,
+                ocel.ocel.object_type_column,
+                config=AttributeFilterConfig(**self.model_dump()),
+            )
+        ]
+        valid_ids = filtered_rows[ocel.ocel.object_id_column].unique()  # type:ignore
+
+        return FilterResult(
+            objects=ocel.ocel.objects[ocel.ocel.object_id_column].isin(valid_ids)  # type:ignore
+        )

ocelescope-0.1.1b1/src/ocelescope/ocel/filter/filters/entity_type.py

@@ -0,0 +1,31 @@
+from typing import Literal, cast
+
+import pandas as pd
+
+
+from ocelescope.ocel.filter.base import BaseFilter, FilterResult
+
+
+class EventTypeFilter(BaseFilter):
+    event_types: list[str]
+    mode: Literal["exclude", "include"] = "include"
+
+    def filter(self, ocel):
+        mask = cast(pd.Series, ocel.events["ocel:activity"].isin(self.event_types))
+        if self.mode == "exclude":
+            mask = ~mask
+
+        return FilterResult(events=mask)
+
+
+class ObjectTypeFilter(BaseFilter):
+    object_types: list[str]
+    mode: Literal["exclude", "include"] = "include"
+
+    def filter(self, ocel):
+        mask = cast(pd.Series, ocel.objects["ocel:type"].isin(self.object_types))
+
+        if self.mode == "exclude":
+            mask = ~mask
+
+        return FilterResult(objects=mask)

ocelescope-0.1.1b1/src/ocelescope/ocel/filter/filters/relation_count.py

@@ -0,0 +1,142 @@
+from typing import Literal, Optional, cast
+
+import pandas as pd
+from pandas.core.frame import DataFrame
+from pandas.core.series import Series
+from pydantic import BaseModel
+
+from ocelescope.ocel.util.relations import getO2OWithTypes
+
+from ocelescope.ocel.filter.base import BaseFilter, FilterResult
+
+
+class RelationCountFilterConfig(BaseModel):
+    source: str
+    target: str
+    mode: Optional[Literal["include", "exclude"]] = "include"
+    range: tuple[Optional[int], Optional[int]]
+    qualifier: Optional[str] = None
+
+
+def filter_by_relation_counts(
+    relation_table: pd.DataFrame,
+    source_id_column: str,
+    source_column: str,
+    target_column: str,
+    qualifier_column: str,
+    entity_id_column: str,
+    entity_type_column: str,
+    source_df: pd.DataFrame,
+    config: RelationCountFilterConfig,
+):
+    # Get o2o with types if not provided
+    relation_table = cast(
+        DataFrame,
+        relation_table[
+            (relation_table[source_column] == config.source)
+            & (relation_table[target_column] == config.target)
+        ],
+    )
+
+    if config.qualifier is not None:
+        relation_table = cast(
+            DataFrame,
+            relation_table[relation_table[qualifier_column] == config.qualifier],
+        )
+
+    # Count how many times each target appears
+    entity_counts = cast(Series, relation_table.groupby(source_id_column).size()).reset_index(
+        name="entity_count"
+    )
+
+    min_count, max_count = config.range
+
+    if min_count is not None:
+        entity_counts = entity_counts[entity_counts["entity_count"] >= min_count]
+    if max_count is not None:
+        entity_counts = entity_counts[entity_counts["entity_count"] <= max_count]
+    entity_counts = cast(Series, entity_counts[source_id_column])
+
+    if min_count == 0:
+        merged = pd.merge(
+            source_df[source_df[entity_type_column] == config.source],
+            relation_table,
+            left_on=entity_id_column,
+            right_on=source_id_column,
+            how="left",
+            indicator=True,
+        )
+        entities_with_no_relations = merged.loc[merged["_merge"] == "left_only", entity_id_column]
+
+        entity_counts = pd.concat([entity_counts, entities_with_no_relations])
+
+    # Mask for non-target-type objects (always kept)
+    is_not_target_type = source_df[entity_type_column] != config.source
+
+    # Mask for objects meeting the relation count condition
+    is_in_filtered_ids = source_df[entity_id_column].isin(entity_counts)
+
+    # Invert if in exclude mode
+    if config.mode == "exclude":
+        is_in_filtered_ids = ~is_in_filtered_ids
+
+    # Final mask: keep non-target-type or qualifying objects
+    final_mask = cast(Series, is_not_target_type | is_in_filtered_ids)
+
+    return final_mask
+
+
+class E2OCountFilter(BaseFilter, RelationCountFilterConfig):
+    direction: Literal["source", "target"] = "source"
+
+    def filter(self, ocel):
+        source_column = (
+            ocel.ocel.event_activity if self.direction == "source" else ocel.ocel.object_type_column
+        )
+        target_column = (
+            ocel.ocel.object_type_column if self.direction == "source" else ocel.ocel.event_activity
+        )
+        source_id_column = (
+            ocel.ocel.event_id_column if self.direction == "source" else ocel.ocel.object_id_column
+        )
+        entity_id_column = source_id_column
+        qualifier_column = ocel.ocel.qualifier
+        entity_type_column = source_column
+
+        mask = filter_by_relation_counts(
+            relation_table=ocel.relations,
+            source_column=source_column,
+            target_column=target_column,
+            source_id_column=source_id_column,
+            qualifier_column=qualifier_column,
+            entity_id_column=entity_id_column,
+            entity_type_column=entity_type_column,
+            source_df=ocel.events if self.direction == "source" else ocel.objects,
+            config=RelationCountFilterConfig(**self.model_dump()),
+        )
+
+        return FilterResult(
+            events=mask if self.direction == "source" else None,
+            objects=mask if self.direction == "target" else None,
+        )
+
+
+class O2OCountFilter(BaseFilter, RelationCountFilterConfig):
+    direction: Literal["source", "target"] = "source"
+
+    def filter(self, ocel):
+        o2oTable = getO2OWithTypes(ocel.ocel, direction=self.direction)
+
+        mask = filter_by_relation_counts(
+            relation_table=o2oTable,
+            source_column="source_type",
+            target_column="target_type",
+            source_id_column="source",
+            qualifier_column="qualifier",
+            entity_id_column=ocel.ocel.object_id_column,
+            entity_type_column=ocel.ocel.object_type_column,
+            source_df=ocel.objects,
+            config=RelationCountFilterConfig(**self.model_dump()),
+        )
+
+        return FilterResult(objects=mask)

ocelescope-0.1.1b1/src/ocelescope/ocel/filter/filters/time_range.py

@@ -0,0 +1,30 @@
+from typing import Literal, Optional
+
+import pandas as pd
+
+from ocelescope.ocel.filter.base import BaseFilter, FilterResult
+
+
+class TimeFrameFilter(BaseFilter):
+    time_range: tuple[Optional[str], Optional[str]]
+    mode: Literal["exclude", "include"] = "include"
+
+    def filter(self, ocel):
+        start_time, end_time = self.time_range
+
+        if start_time is not None:
+            start_time = pd.Timestamp(start_time, tz="UTC")
+        if end_time is not None:
+            end_time = pd.Timestamp(end_time, tz="UTC")
+
+        events_df = ocel.events
+
+        mask = pd.Series([True] * len(events_df), index=events_df.index)
+        if start_time is not None:
+            mask &= events_df["ocel:timestamp"] >= start_time
+        if end_time is not None:
+            mask &= events_df["ocel:timestamp"] <= end_time
+        if self.mode == "exclude":
+            mask = ~mask
+
+        return FilterResult(events=mask)