OCEAN Library

A query library supporting the OCEAN (Object-Centric Event AggregatioN) language for specifying and executing EKG aggregation queries.

Note

Evaluation results are available in the project Wiki

🛠️ Setup

Clone the repo:

git clone https://github.com/SaraPettinari/ocean-lib.git

Navigate inside the repo:

cd <YOUR_PATH>/ocean_lib

Create a virtual environment and activate it:

python3 -m venv .venv
source .venv/bin/activate

Next, install the package in editable mode:

pip install -e .

⚙️ Run

Navigate into a dataset folder:

cd datasets/<dataset_name>

Set up the aggregation steps inside main.py, then run it:

python main.py

Make sure you configure the required .yaml files before running the script, as described in the Configuration section.

Query Specification Pattern

The library is used by defining a list of AggrStep(...) and returning an AggrSpecification(...) (see examples in the wiki).

Typical skeleton:

@pipeline(first_load=<True/False>)
def build_aggr_spec(log, ekg):
    steps = [
        # AggrStep(...),
        # AggrStep(...),
    ]
    return AggrSpecification(steps)

🔧 Configuration

Important

Before running the application, you must customize the YAML configuration files with your own data.

Required Configuration Files:

• ekg_config.yaml: Defines database connections, and EKG properties.

• log_config.yaml: Manages event data configurations (paths, attributes, etc.).

Templates

log_config.yaml

event_id: "<EVENT_ID_REF>"    # unique identifier attribute for the event
event_activity: "<EVENT_ACTIVITY_REF>"   # activity attribute name of the event
event_timestamp: "<EVENT_TIME_REF>"    # timestamp attribute name of the event

entity_id: "<ENTITY_ID_REF>"   # unique identifier attribute for the entity

### OPTIONAL! Not needed if the dataset is already in Neo4j ### 
events:
  path: "<YOUR_PATH_TO_EVENTS_CSV>"    # path to the event table
  attr: ["<EVENT_ATTRS>"]   # attributes to retrieve from the event table
  attr_types: # not needed if the attribute is of string type
  # supported types so far: String, Integer, Datetime, Float, Boolean
    attr_1: "<TYPE_1>"
    attr_2: "<TYPE_2>"
    # add more attributes as needed
    # attr_name: "<TYPE>"

# entities data: type, path (absolute), and attributes
entities:
  entity_1:
    type: "<ENTITY_TYPE_1>"
    path: "<YOUR_PATH_TO_ENTITY_1>"
    attr: ["<ENTITY_1_ATTRS>"]
    attr_types: 
      attr_1: "<TYPE_1>"
      attr_2: "<TYPE_2>" 
  entity_2:
    type: "<ENTITY_TYPE_2>"
    path: "<YOUR_PATH_TO_ENTITY_2>"
    attr: ["<ENTITY_2_ATTRS>"]
    attr_types: 
      attr_1: "<TYPE_1>"
      attr_2: "<TYPE_2>"

ekg_config.yaml

type_tag: "<TYPE_REF>"    # how the Type of an entity, df, class, etc. is called

entity_type_mode: '<label/property>'  # specify if the entity type is represented as a label or as a property in the graph database  
# label = :Entity:EntityType
# property = :Entity (Type: 'EntityType')

# Neo4j configuration
neo4j:
  URI: "<Neo4j-URI>"
  username: "<USERNAME>"
  password: "<PASSWORD>"

📦 Package Structure

query_library/
├── src/
│   ├── aggregation_lib/
│   │   ├── aggregate_ekg.py
│   │   ├── collect_info_decorator.py    
│   │   ├── grammar.py         
│   │   └── init_ekg.py               
│   ├── __init__.py  
├── datasets/
│   ├── {dataset}/
│   │   ├── config.py
│   │   ├── main.py           # Executable file
│   │   ├── ekg_config.yaml
│   │   └──  log_config.yaml 
├── setup.py                  # Python setup configuration
└── README.md                 

Datasets

• Soccer Matches Dataset: available on github.

• OCEL2.0 Datasets: downloaded from ocelot, based on the ocel-standard ➡️ logistics, order management, procure-to-pay (p2p).

• BPIC 2017 Dataset: available on PromG.