ergminer 0.2.0__py3-none-any.whl

ergminer/ERGML_converter.py

@@ -0,0 +1,229 @@
+"""
+ERGML Converter
+
+Converts an ERG (Event Relationship Graph) model to ERGML (ERG Markup Language),
+an XML-based format inspired by PNML (Petri Net Markup Language).
+
+ERGML Schema overview
+---------------------
+<ergml version="1.0">
+  <erg id="..." >
+    <name> ... </name>
+
+    <parameters>
+      <simTime>...</simTime>
+      <start_events> <event ref="..."/> ... </start_events>
+      <end_events>   <event ref="..."/> ... </end_events>
+      <statistics>
+        <stat name="..." value="..."/> ...
+      </statistics>
+    </parameters>
+
+    <states>
+      <stateVariable id="...">
+        <name>...</name>
+        <type>...</type>
+        <resource>...</resource>
+        <initialValue>...</initialValue>
+      </stateVariable>
+      ...
+    </states>
+
+    <nodes>
+      <node id="..." type="...">
+        <name>...</name>
+        <eventType>...</eventType>
+        <originalActivity>...</originalActivity>
+        <resource>...</resource>
+        <frequency>...</frequency>
+        <stateUpdateEquations>
+          <equation>...</equation>
+          ...
+        </stateUpdateEquations>
+      </node>
+      ...
+    </nodes>
+
+    <arcs>
+      <arc id="..." source="..." target="...">
+        <probability>...</probability>
+        <guardCondition>...</guardCondition>
+        <isImmediate>...</isImmediate>
+        <delayDistribution>...</delayDistribution>
+        <distributionParams>
+          <param name="..." value="..."/> ...
+        </distributionParams>
+        <meanDelay>...</meanDelay>
+      </arc>
+      ...
+    </arcs>
+
+  </erg>
+</ergml>
+"""
+
+import xml.etree.ElementTree as ET
+from xml.dom import minidom
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _sub(parent, tag, text=None):
+    """Create a child element, optionally setting its text."""
+    el = ET.SubElement(parent, tag)
+    if text is not None:
+        el.text = str(text)
+    return el
+
+
+def _set_text(element, value):
+    """Set element text; leave empty if value is None."""
+    if value is not None:
+        element.text = str(value)
+
+
+def _prettify(element):
+    """Return a pretty-printed XML string for *element*."""
+    raw = ET.tostring(element, encoding="unicode")
+    reparsed = minidom.parseString(raw)
+    return reparsed.toprettyxml(indent="  ", encoding=None)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def erg_to_ergml(erg, sim_time=5000.0):
+    """
+    Convert an ERG object to an ERGML XML string.
+
+    Parameters
+    ----------
+    erg : ERG
+        The ERG model to convert.
+    sim_time : float
+        Simulation horizon to embed in the ERGML (default 5000.0).
+
+    Returns
+    -------
+    str
+        Pretty-printed ERGML XML string.
+    """
+    # Root
+    root = ET.Element("ergml", attrib={"version": "1.0"})
+
+    # <erg id="..." >
+    erg_el = ET.SubElement(root, "erg", attrib={"id": erg.name})
+
+    # ------------------------------------------------------------------
+    # <name>
+    # ------------------------------------------------------------------
+    _sub(erg_el, "name", erg.name)
+
+    # ------------------------------------------------------------------
+    # <parameters>
+    # ------------------------------------------------------------------
+    params_el = _sub(erg_el, "parameters")
+
+    # sim_time
+    _sub(params_el, "simTime", sim_time)
+
+    # start_events
+    start_el = _sub(params_el, "start_events")
+    for ev in sorted(erg.start_events):
+        ET.SubElement(start_el, "event", attrib={"ref": ev})
+
+    # end_events
+    end_el = _sub(params_el, "end_events")
+    for ev in sorted(erg.end_events):
+        ET.SubElement(end_el, "event", attrib={"ref": ev})
+
+    # statistics
+    stats = erg.get_statistics()
+    stats_el = _sub(params_el, "statistics")
+    for stat_name, stat_value in stats.items():
+        ET.SubElement(stats_el, "stat",
+                      attrib={"name": stat_name, "value": str(stat_value)})
+
+    # ------------------------------------------------------------------
+    # <states>
+    # ------------------------------------------------------------------
+    states_el = _sub(erg_el, "states")
+    for sv in erg.state_variables.values():
+        sv_el = ET.SubElement(states_el, "stateVariable", attrib={"id": sv.name})
+        _sub(sv_el, "name", sv.name)
+        _sub(sv_el, "type", sv.variable_type)
+        _sub(sv_el, "resource", sv.resource)
+        _sub(sv_el, "initialValue", sv.initial_value)
+
+    # ------------------------------------------------------------------
+    # <nodes>
+    # ------------------------------------------------------------------
+    nodes_el = _sub(erg_el, "nodes")
+    for node in erg.nodes.values():
+        node_el = ET.SubElement(nodes_el, "node",
+                                attrib={"id": node.name, "type": node.event_type})
+        _sub(node_el, "name", node.original_activity)  # clean name without resource suffix
+        _sub(node_el, "eventType", node.event_type)
+        _sub(node_el, "originalActivity", node.original_activity)
+        res_el = _sub(node_el, "resource")
+        _set_text(res_el, node.resource)
+        _sub(node_el, "frequency", node.frequency)
+        eqs_el = _sub(node_el, "stateUpdateEquations")
+        for eq in node.state_update_equations:
+            _sub(eqs_el, "equation", eq)
+
+    # ------------------------------------------------------------------
+    # <arcs>
+    # ------------------------------------------------------------------
+    arcs_el = _sub(erg_el, "arcs")
+
+    # Track arc IDs — guard against duplicate source→target pairs
+    arc_id_counter = {}
+    for arc in erg.arcs:
+        base_id = f"arc_{arc.source}_{arc.target}"
+        count = arc_id_counter.get(base_id, 0)
+        arc_id = base_id if count == 0 else f"{base_id}_{count}"
+        arc_id_counter[base_id] = count + 1
+
+        arc_el = ET.SubElement(arcs_el, "arc",
+                               attrib={"id": arc_id,
+                                       "source": arc.source,
+                                       "target": arc.target})
+        _sub(arc_el, "probability", arc.probability)
+        guard_el = _sub(arc_el, "guardCondition")
+        _set_text(guard_el, arc.guard_condition)
+        _sub(arc_el, "arcType", getattr(arc, 'arc_type', 'DF'))
+        _sub(arc_el, "isImmediate", str(arc.is_immediate).lower())
+        _sub(arc_el, "delayDistribution", arc.delay_distribution)
+
+        # distributionParams
+        dp_el = _sub(arc_el, "distributionParams")
+        if arc.distribution_params:
+            for param_name, param_val in arc.distribution_params.items():
+                ET.SubElement(dp_el, "param",
+                              attrib={"name": param_name, "value": str(param_val)})
+
+        _sub(arc_el, "meanDelay", arc.mean_delay)
+
+    return _prettify(root)
+
+
+def save_ergml(erg, filepath, sim_time=5000.0):
+    """
+    Convert an ERG model to ERGML and write it to *filepath*.
+
+    Parameters
+    ----------
+    erg : ERG
+        The ERG model to export.
+    filepath : str
+        Destination file path (conventionally ending in .ergml).
+    sim_time : float
+        Simulation horizon to embed in the ERGML (default 5000.0).
+    """
+    xml_str = erg_to_ergml(erg, sim_time=sim_time)
+    with open(filepath, "w", encoding="utf-8") as fh:
+        fh.write(xml_str)

ergminer/__init__.py

@@ -0,0 +1,119 @@
+"""
+ERGminer - Event Relationship Graph Mining from Event Logs
+
+Mines Event Relationship Graphs (ERGs) from event logs using process mining,
+state variable identification, and statistical analysis.
+"""
+
+__version__ = "0.2.0"
+__author__  = "Zach Eyde"
+
+# ── Submodules (ergminer.read, ergminer.discovery, etc.) ─────────────────────
+from ergminer import read
+from ergminer import utils
+from ergminer import filtering
+from ergminer import discovery
+from ergminer import write
+from ergminer import sim
+from ergminer import conformance as conformance_module
+
+# ── ergminer.read ─────────────────────────────────────────────────────────────
+from ergminer.read import (
+    read_csv,
+    read_xes,
+    read_dataframe,
+)
+
+# ── ergminer.utils ────────────────────────────────────────────────────────────
+from ergminer.utils import (
+    format_dataframe,
+    get_start_activities,
+    get_end_activities,
+    get_variants,
+    get_activity_labels,
+)
+
+# ── ergminer.filtering ────────────────────────────────────────────────────────
+from ergminer.filtering import (
+    filter_start_activities,
+    filter_end_activities,
+    filter_case_size,
+    filter_variants,
+)
+
+# ── ergminer.discovery ────────────────────────────────────────────────────────
+from ergminer.discovery import (
+    discover_erg,
+)
+
+# ── ergminer.write ────────────────────────────────────────────────────────────
+from ergminer.write import (
+    write_ergml,
+    write_erg_json,
+    write_dot,
+)
+
+# ── ergminer.sim ──────────────────────────────────────────────────────────────
+from ergminer.sim import (
+    play_out,
+)
+
+# ── ergminer.conformance ──────────────────────────────────────────────────────
+from ergminer.conformance import (
+    conformance_erg,
+)
+
+# ── Data classes and configuration (backward-compatible) ─────────────────────
+from ergminer.erg_miner     import ERGMiner, DelayConfig
+from ergminer.erg_structure  import ERG, ERGNode, ERGArc, ERGStateVariable
+from ergminer.conformance_testing import ConformanceResult
+
+# Backward-compatible top-level aliases (deprecated in favour of write.*)
+from ergminer.ERGML_converter import erg_to_ergml, save_ergml
+from ergminer.erg_playback    import run_simulations
+from ergminer.conformance_testing import conformance_testing
+
+# ── ergminer.vis (optional — requires matplotlib + networkx) ──────────────────
+try:
+    from ergminer.vis import view_erg, save_vis_erg
+    from ergminer import vis
+    _vis_available = True
+except ImportError:
+    _vis_available = False
+
+# ── ergminer.erg_plotter alias (backward-compatible) ─────────────────────────
+try:
+    from ergminer.erg_plotter import plot_erg
+except ImportError:
+    pass
+
+# ── __all__ ──────────────────────────────────────────────────────────────────
+__all__ = [
+    # Submodules
+    'read', 'utils', 'filtering', 'discovery', 'write', 'sim',
+    # Read
+    'read_csv', 'read_xes', 'read_dataframe',
+    # Utils
+    'format_dataframe', 'get_start_activities', 'get_end_activities',
+    'get_variants', 'get_activity_labels',
+    # Filtering
+    'filter_start_activities', 'filter_end_activities',
+    'filter_case_size', 'filter_variants',
+    # Discovery
+    'discover_erg',
+    # Visualisation
+    'view_erg', 'save_vis_erg',
+    # Write
+    'write_ergml', 'write_erg_json', 'write_dot',
+    # Simulation
+    'play_out',
+    # Conformance
+    'conformance_erg',
+    # Data classes
+    'ERGMiner', 'DelayConfig', 'ERG', 'ERGNode', 'ERGArc',
+    'ERGStateVariable', 'ConformanceResult',
+    # Backward-compatible
+    'erg_to_ergml', 'save_ergml', 'run_simulations',
+    'conformance_testing', 'plot_erg',
+]
+

ergminer/conformance.py

@@ -0,0 +1,187 @@
+"""
+conformance.py — ERG conformance checking functions for ERGminer.
+
+Analogous to pm4py.conformance.
+"""
+
+from __future__ import annotations
+
+import tempfile
+import os
+from typing import TYPE_CHECKING, Dict, Optional
+
+import numpy as np
+import pandas as pd
+
+from .conformance_testing import (
+    ConformanceResult,
+    ERGConformanceChecker,
+    CHECK_GROUPS,
+)
+from .ERGML_converter import erg_to_ergml
+from .erg_playback import parse_ergml
+from .sim import play_out
+
+if TYPE_CHECKING:
+    from .erg_structure import ERG
+    from .conformance_testing import ConformanceResult
+
+
+def conformance_erg(
+    log: pd.DataFrame,
+    erg: 'ERG',
+    sim_log: Optional[pd.DataFrame] = None,
+    n_simulations: int = 10,
+    sim_time: float = 5000.0,
+    seed: int = 42,
+    case_id_col: str = 'case_id',
+    activity_col: str = 'activity_name',
+    timestamp_col: str = 'timestamp',
+    resource_col: str = 'resource_id',
+    verbose: bool = False,
+) -> 'ConformanceResult':
+    """Run conformance checking between *log* and *erg*.
+
+    Compares the observed behaviour in *log* against the ERG model using
+    twelve complementary fitness metrics.  If *sim_log* is not provided,
+    ``play_out()`` is called automatically to generate simulation replications.
+
+    Args:
+        log:           Original event log DataFrame (user column names).
+        erg:           The ``ERG`` model to check against.
+        sim_log:       Pre-computed simulation log from ``play_out()`` (optional).
+                       Must contain ``_erg_run`` column. If ``None``, simulations
+                       are run automatically.
+        n_simulations: Number of simulation replications (used only when
+                       *sim_log* is ``None``).
+        sim_time:      Simulation horizon passed to ``play_out()`` (used only
+                       when *sim_log* is ``None``).
+        seed:          Base random seed for simulations (used only when
+                       *sim_log* is ``None``).
+        case_id_col:   Column name for case identifiers in *log*.
+        activity_col:  Column name for activity names in *log*.
+        timestamp_col: Column name for timestamps in *log*.
+        resource_col:  Column name for resource identifiers in *log*.
+        verbose:       Print progress to stdout.
+
+    Returns:
+        ``ConformanceResult`` with all check scores and a printable report.
+    """
+   
+
+    # ── 1. Generate sim log if not provided ──────────────────────────────────
+    if sim_log is None:
+        if verbose:
+            print(f"Running {n_simulations} simulation(s) for conformance …")
+        sim_log = play_out(
+            erg,
+            n=n_simulations,
+            sim_time=sim_time,
+            seed=seed,
+            verbose=verbose,
+        )
+        actual_n = n_simulations
+    else:
+        actual_n = sim_log['_erg_run'].nunique() if '_erg_run' in sim_log.columns else 1
+
+    # ── 2. Serialise ERG to temp ERGML and parse nodes/arcs ─────────────────
+    ergml_xml = erg_to_ergml(erg, sim_time=sim_time)
+    tmp_file = tempfile.NamedTemporaryFile(
+        suffix='.ergml', delete=False, mode='w', encoding='utf-8'
+    )
+    try:
+        tmp_file.write(ergml_xml)
+        tmp_file.close()
+        tmp_path = tmp_file.name
+
+        erg_name, nodes, arcs_from, start_events, end_events, res_caps, _ = parse_ergml(tmp_path)
+    finally:
+        try:
+            os.remove(tmp_path)
+        except OSError:
+            pass
+
+    # ── 3. Rename original log columns to internal standard names ────────────
+    # The sim log always uses fixed internal column names (case_id, timestamp,
+    # activity_name, resource_id).  Rename the original log to match so both
+    # DataFrames use the same column names when passed to ERGConformanceChecker.
+    rename_map = {
+        case_id_col:   'case_id',
+        activity_col:  'activity_name',
+        timestamp_col: 'timestamp',
+    }
+    if resource_col and resource_col in log.columns:
+        rename_map[resource_col] = 'resource_id'
+    orig_log = log.rename(columns=rename_map).copy()
+
+    # Drop incomplete cases from orig (mirror of conformance_testing behaviour)
+    if end_events:
+        completed_cases = orig_log.loc[
+            orig_log['activity_name'].isin(end_events), 'case_id'
+        ].unique()
+        orig_log = orig_log[orig_log['case_id'].isin(completed_cases)]
+
+    # ── 4. Build combined sim log with globally unique case IDs ─────────────
+    # play_out() restarts case_ids from 1 each run, so prefix them per run.
+    combined_parts = []
+    run_col = '_erg_run' if '_erg_run' in sim_log.columns else None
+    if run_col:
+        for run_idx, run_df in sim_log.groupby('_erg_run', sort=True):
+            part = run_df.copy()
+            part['case_id'] = part['case_id'].astype(str).apply(
+                lambda x: f"run{run_idx}_case{x}"
+            )
+            combined_parts.append(part)
+    else:
+        combined_parts = [sim_log.copy()]
+    combined_sim_log = pd.concat(combined_parts, ignore_index=True)
+
+    # ── 5. Run conformance checker ────────────────────────────────────────────
+    if verbose:
+        print("Running ERG conformance checks …")
+
+    checker = ERGConformanceChecker(
+        original_log  = orig_log,
+        sim_log       = combined_sim_log,
+        nodes         = nodes,
+        arcs_from     = arcs_from,
+        case_id_col   = 'case_id',
+        activity_col  = 'activity_name',
+        timestamp_col = 'timestamp',
+        resource_col  = 'resource_id',
+    )
+    checker.run_all_checks()
+
+    # ── 6. Build ConformanceResult ────────────────────────────────────────────
+    summary_df    = checker.summary()
+    overall_score = round(float(np.mean([
+        r['score'] for r in checker.results.values()
+        if isinstance(r.get('score'), (int, float))
+    ])), 4)
+
+    group_scores: Dict = {}
+    for grp, check_keys in CHECK_GROUPS.items():
+        grp_vals = [
+            checker.results[k]['score']
+            for k in check_keys
+            if k in checker.results and isinstance(checker.results[k].get('score'), (int, float))
+        ]
+        if grp_vals:
+            grp_score = round(float(np.mean(grp_vals)), 4)
+            grp_pass  = grp_score >= 0.8
+            group_scores[grp] = {
+                'score':  grp_score,
+                'pass':   grp_pass,
+                'checks': len(grp_vals),
+            }
+
+    result = ConformanceResult()
+    result.erg_name        = erg_name or getattr(erg, 'name', 'ERG')
+    result.n_simulations   = actual_n
+    result.checker_results = checker.results
+    result.summary_df      = summary_df
+    result.overall_score   = overall_score
+    result.group_scores    = group_scores
+
+    return result
+