Metadata-Version: 2.3
Name: ocelescope
Version: 0.3.0
Summary: General tools for working with Object-Centric Event Logs and building Ocelescope plugins
Classifier: Typing :: Typed
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Dist: cachetools>=6.1.0
Requires-Dist: graphviz>=0.21
Requires-Dist: matplotlib>=3.10.9
Requires-Dist: numpy>=2.3.2
Requires-Dist: orjson>=3.11.7
Requires-Dist: pandas>=2.3.1
Requires-Dist: plotly>=6.3.1
Requires-Dist: pm4py~=2.7.22
Requires-Dist: polars>=1.40.1
Requires-Dist: pydantic>=2.11.7
Requires-Dist: r4pm[polars]>=0.5.3
Requires-Dist: more-itertools>=11.1.0 ; extra == 'plugin'
Requires-Dist: networkx>=3.5 ; extra == 'plugin'
Requires-Dist: scikit-learn>=1.9.0 ; extra == 'plugin'
Requires-Python: >=3.11
Project-URL: Homepage, https://www.ocelescope.org
Project-URL: Documentation, https://www.ocelescope.org
Project-URL: Repository, https://github.com/promi4s/ocelescope
Project-URL: Issues, https://github.com/promi4s/ocelescope/issues
Provides-Extra: plugin
Description-Content-Type: text/markdown

# ocelescope

General tools and building blocks for working with
[Object-Centric Event Logs (OCEL)](https://www.ocel-standard.org/) and for
building plugins for the [Ocelescope](https://github.com/promi4s/ocelescope)
framework.

## Installation

```bash
pip install ocelescope
```

To also install the optional dependencies used by plugins:

```bash
pip install "ocelescope[plugin]"
```

## Usage

### Loading an OCEL

`OCEL.read` loads an OCEL 2.0 log from a `.sqlite`, `.xml` or `.json` file:

```python
from ocelescope import OCEL

ocel = OCEL.read("order-management.sqlite")

# Structured access to the log via managers (each exposes a pandas DataFrame):
print(ocel.events.df.head())
print(ocel.objects.df.head())
print(ocel.e2o.df.head())   # event-to-object relations
print(ocel.o2o.df.head())   # object-to-object relations
```

### Filtering

`OCEL.filter` applies a pipeline of filters and returns a new, filtered `OCEL`:

```python
from ocelescope import OCEL, EventTypeFilter, ObjectTypeFilter

ocel = OCEL.read("order-management.sqlite")

filtered = ocel.filter(
    [
        EventTypeFilter(event_types=["place order", "pay order"], mode="include"),
        ObjectTypeFilter(object_types=["items"], mode="exclude"),
    ]
)

filtered.write("filtered.sqlite")
```

### Command line

The package also ships an `ocelescope` command-line entry point:

```bash
ocelescope --help
```

## Typing

This package is fully type-hinted and ships a [PEP 561](https://peps.python.org/pep-0561/)
`py.typed` marker, so type checkers such as mypy, pyright and ty pick up its
types automatically — no extra stubs required.

## About

Part of [Ocelescope](https://github.com/promi4s/ocelescope), a framework for
working with Object-Centric Event Logs developed at the Chair of Process and
Data Science (PADS), RWTH Aachen University.

📖 Documentation: <https://www.ocelescope.org>
