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/yourusername/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

See the Documentation for comprehensive guides and tutorials.

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