HowToUse

How to Use ocean-lib

This page provides a guide on how to use ocean-lib to define and execute aggregation queries over Event Knowledge Graphs (EKGs).

---

1. Installation

Clone the repository and install the library in editable mode:

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

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

pip install -e .

2. Dataset Structure

Place the file related to your dataset in a unique folder:

<dataset_name>/
    ├── main.py
    ├── ekg_config.yaml
    └── log_config.yaml

• main.py defines the aggregation query

• ekg_config.yaml specifies the connection to the Neo4j EKG and EKG conventions

• log_config.yaml maps event and entity attributes

3. Configuring the EKG Connection

The file ekg_config.yaml defines how ocean-lib connects to the underlying Neo4j database and interprets entity types.

Configuration structure:

type_tag: "<TYPE_REF>"
entity_type_mode: "<label|property>"

neo4j:
  URI: "<NEO4J_URI>"
  username: "<USERNAME>"
  password: "<PASSWORD>"

Note

label = :Entity:EntityType property = :Entity (Type: 'EntityType')

4. Mapping Event Logs and Entities

The file log_config.yaml specifies how events and entities are mapped to the EKG.

Minimal configuration structure (if the dataset is already in Neo4j):

event_id: "<EVENT_ID_REF>"
event_activity: "<EVENT_ACTIVITY_REF>"
event_timestamp: "<EVENT_TIMESTAMP_REF>"

entity_id: "<ENTITY_ID_REF>"

Important

If the dataset is not already stored in Neo4j, paths to CSV files and attribute types must be specified (see the repository README for full examples).

5. Defining an Aggregation Query

Aggregation queries are defined as a sequence of aggregation steps (AggrStep), combined into an AggrSpecification.

A typical query structure written in the main.py is shown below:

from ocean_lib import pipeline, AggrSpecification, AggrStep
from ocean_lib.aggregation_lib import AttrAggr, AggregationFunction

@pipeline(first_load=False)
def build_aggr_spec(log, ekg):
    steps = [
        AggrStep(
            aggr_type="ENTITIES",
            ent_type="playerId",
            group_by=["role"],
            where=None,
            attr_aggrs=[]
        ),
        AggrStep(
            aggr_type="EVENTS",
            ent_type=None,
            where=None,
            group_by=[log.event_activity],
            attr_aggrs=[
                AttrAggr(
                    name=log.event_timestamp,
                    function=AggregationFunction.MINMAX
                )
            ]
        )
    ]
    return AggrSpecification(steps)

Each AggrStep specifies:

• the aggregation type (ENTITIES or EVENTS)

• the entity type (if applicable)

• grouping attributes

• optional filtering conditions

• optional attribute aggregation functions

6. Running an Aggregation

To execute the aggregation pipeline, run:

cd <dataset_name>
python main.py

The execution:

• Loads the EKG (if required: @pipeline(first_load=True))

• Applies the aggregation steps sequentially

• Finalizes the aggregated EKG

• Infers relationships between aggregated nodes

7. Output of the Aggregation

Depending on the configuration, the execution produces:

• An aggregated EKG stored in Neo4j

• Execution logs reporting processed nodes and execution times

• Optional visualizations (e.g., via Neo4j Bloom)