Heraclitus

A Python library aimed at making Process Mining accessible to new users. Works well with PM4PY but adds additional features for analysis and visualization.

Features

• EventLog Management: Easy to use interface for loading, filtering, and manipulating process event data
• Process Visualization:
  • Static process maps and activity frequency charts
  • Interactive visualizations with Plotly
  • Timeline visualizations and bottleneck dashboards
• Time Metrics: Calculate cycle times, waiting times, and processing times
• Statistical Analysis:
  • Compare process variants and identify bottlenecks
  • Distribution fitting and hypothesis testing
• Large Dataset Support:
  • DuckDB integration for handling datasets larger than memory
  • Efficient querying and filtering of large process logs
• Machine Learning:
  • Predictive models for process outcomes
  • Duration prediction with regression and classification
  • Feature engineering tools for process data
• Anomaly Detection:
  • Identify unusual process behaviors
  • Detect outlier cases and process variants
  • Visualize anomalies for investigation
• Process Discovery:
  • Custom process discovery algorithms
  • Conformance checking capabilities
  • BPMN export functionality
• PM4PY Integration:
  • Seamless conversion between Heraclitus and PM4PY formats
  • Use PM4PY algorithms with Heraclitus EventLogs
  • Enhanced visualizations for process models
• Performance Optimization:
  • Vectorized operations for metrics
  • Caching for repeated calculations
• XES Format Support (NEW in v0.3.0):
  • IEEE 1849-2016 standard compliant XES import/export
  • Extended EventLog class with XES methods
  • Support for XES extensions and global attributes
• Improved Documentation (NEW in v0.3.0):
  • Comprehensive Jupyter notebook tutorials
  • More detailed examples

Installation

# Install from PyPI
pip install heraclitus

# Install with PM4PY integration
pip install heraclitus[pm4py]

# Install with machine learning features
pip install heraclitus[ml]

# Install with all optional dependencies
pip install heraclitus[pm4py,ml,dev]

Or install from source:

git clone https://github.com/srepho/heraclitus.git
cd heraclitus
pip install -e .

Quick Start

import pandas as pd
from heraclitus.data import EventLog
from heraclitus.visualization import create_interactive_process_map
from heraclitus.metrics import calculate_cycle_time

# Create an event log from a DataFrame
df = pd.read_csv("your_data.csv")
event_log = EventLog(df)

# Analyze cycle time
avg_time = calculate_cycle_time(event_log, unit="hours")
print(f"Average cycle time: {avg_time:.2f} hours")

# Create an interactive visualization
fig = create_interactive_process_map(event_log)
fig.write_html("process_map.html")  # Interactive HTML file

Working with Large Datasets

from heraclitus.data import DuckDBConnector

# Initialize DuckDB connector
db = DuckDBConnector("process_data.duckdb")

# Load large CSV file
db.load_csv("large_event_log.csv", table_name="events")

# Query and convert to EventLog
filtered_log = db.query_to_eventlog("""
    SELECT * FROM events 
    WHERE timestamp >= '2023-01-01' 
    AND activity = 'Process Application'
""")

# Analyze the filtered log
print(f"Filtered log contains {filtered_log.case_count()} cases")

Machine Learning and Anomaly Detection

from heraclitus.ml import OutcomePredictor, ProcessAnomalyDetector, FeatureExtractor

# Extract features from event log
feature_extractor = FeatureExtractor(event_log)
features_df = feature_extractor.extract_case_features()

# Train a prediction model
predictor = OutcomePredictor()
model_info = predictor.train(event_log, model_type="random_forest")
predictions = predictor.predict(features_df)

# Detect process anomalies
anomaly_detector = ProcessAnomalyDetector()
anomaly_detector.train(event_log, method="isolation_forest")
anomalies = anomaly_detector.detect_anomalies(features_df)

Requirements

• Python 3.10-3.12
• pandas
• matplotlib
• numpy
• scipy
• plotly
• duckdb
• scikit-learn (for ML features)

Examples

Check out the examples directory for detailed usage examples:

• basic_usage.py: Simple EventLog operations
• statistical_analysis.py: Statistical comparisons and bottleneck analysis
• interactive_visualization.py: Interactive Plotly visualizations
• duckdb_large_datasets.py: Working with large datasets
• machine_learning.py: Predictive modeling and anomaly detection
• process_discovery.py: Process discovery and conformance checking
• xes_format.py: XES format import and export (NEW)

Documentation

Heraclitus offers comprehensive documentation to help you get started and maximize your process mining capabilities:

• Getting Started: Main documentation entry point
• Guides:
  • Data Guide: Working with event logs and large datasets
  • Metrics Guide: Analyzing process performance metrics
  • Visualization Guide: Creating static and interactive visualizations
  • Statistics Guide: Statistical analysis and bottleneck detection
  • Machine Learning Guide: Predictive modeling and anomaly detection
• Tutorials:
  • Basic Process Analysis: Step-by-step tutorial for beginners
• Reference:
  • API Reference: Complete API documentation

Development

See the Developer Guide for detailed information on the architecture and design principles.

Run tests:

pytest tests/

Roadmap

See ROADMAP.md for planned features and improvements.

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

License

MIT License