Working with Event Logs¶
An event log is the fundamental input for process mining. It records events that happened during the execution of a business process, where each event belongs to a case (process instance) and represents an activity at a given timestamp.
The EventLog object¶
synamine's EventLog is a DataFrame-backed data structure. It wraps a pandas DataFrame with a schema that maps column names to their roles:
import synamine
log = synamine.read_csv("events.csv")
print(type(log)) # <class 'synamine.models.log.EventLog'>
print(type(log.df)) # <class 'pandas.core.frame.DataFrame'>
print(log.schema) # EventLogSchema(case_id='case_id', activity='activity', timestamp='timestamp')
Key properties¶
| Property | Description |
|---|---|
log.df |
The underlying pandas DataFrame |
log.schema |
Column name mapping (EventLogSchema) |
log.num_cases |
Number of distinct cases |
log.num_events |
Total number of events |
log.activities |
Set of distinct activity names |
Iterating over traces¶
for trace in log:
print(f"Case {trace.case_id}: {len(trace.events)} events")
for event in trace.events:
print(f" {event.activity} at {event.timestamp}")
Reading event logs¶
From CSV¶
From XES (IEEE 1849)¶
From a pandas DataFrame¶
If you already have a DataFrame (e.g. in a Jupyter notebook), use read_dataframe directly -- no file I/O needed:
import pandas as pd
import synamine
df = pd.read_sql("SELECT * FROM events", conn)
log = synamine.read_dataframe(df)
Custom column names¶
By default, synamine expects columns named case_id, activity, and timestamp. Override for any read function:
log = synamine.read_csv(
"events.csv",
case_id="order_id",
activity="step",
timestamp="ts",
)
# Same for read_dataframe
log = synamine.read_dataframe(df, case_id="order_id", activity="step", timestamp="ts")