Merge branch 'PMPY-2117' into 'integration'

PMPY-2117 Replay prefix using TBR (to obtain a marking)

Closes PMPY-2117

See merge request process-mining/pm4py/pm4py-core!1019

docs/source/api.rst

@@ -107,6 +107,7 @@ Among procedural process models, ``pm4py`` currently supports:
   * :meth:`pm4py.conformance.fitness_alignments`; evaluation of the fitness between an event log and a *Petri net* using alignments.
   * :meth:`pm4py.conformance.precision_token_based_replay`; evaluation of the precision between an event log and a *Petri net* using token-based replay.
   * :meth:`pm4py.conformance.precision_alignments`; evaluation of the precision between an event log and a *Petri net* using alignments.
+  * :meth:`pm4py.conformance.replay_prefix_tbr`; replays a prefix (list of activities) on a given *Petri net*, using Token-Based Replay.
 
 Among declarative process models, ``pm4py`` currently supports:
 
@@ -440,6 +441,7 @@ Overall List of Methods
    pm4py.conformance.fitness_alignments
    pm4py.conformance.precision_token_based_replay
    pm4py.conformance.precision_alignments
+   pm4py.conformance.replay_prefix_tbr
    pm4py.conformance.conformance_temporal_profile
    pm4py.conformance.conformance_log_skeleton
    pm4py.vis

pm4py/__init__.py

@@ -25,7 +25,7 @@
     fitness_alignments, precision_token_based_replay, \
     precision_alignments, conformance_diagnostics_footprints, \
     fitness_footprints, precision_footprints, check_is_fitting, conformance_temporal_profile, \
-    conformance_log_skeleton
+    conformance_log_skeleton, replay_prefix_tbr
 from pm4py.ocel import ocel_objects_interactions_summary, ocel_temporal_summary, ocel_objects_summary, ocel_get_object_types, ocel_get_attribute_names, ocel_flattening, ocel_object_type_activities, ocel_objects_ot_count, \
                         discover_ocdfg, discover_oc_petri_net, discover_objects_graph, sample_ocel_objects, ocel_drop_duplicates, ocel_merge_duplicates, ocel_sort_by_additional_column, \
                         ocel_add_index_based_timedelta, sample_ocel_connected_components, ocel_o2o_enrichment, ocel_e2o_lifecycle_enrichment, cluster_equivalent_ocel

pm4py/conformance.py

@@ -368,6 +368,42 @@ def precision_alignments(log: Union[EventLog, pd.DataFrame], petri_net: PetriNet
     return result
 
 
+def replay_prefix_tbr(prefix: List[str], net: PetriNet, im: Marking, fm: Marking, activity_key: str = "concept:name") -> Marking:
+    """
+    Replays a prefix (list of activities) on a given accepting Petri net, using Token-Based Replay.
+
+    :param prefix: list of activities
+    :param net: Petri net
+    :param im: initial marking
+    :param fm: final marking
+    :param activity_key: attribute to be used as activity
+    :rtype:  ``Marking``
+
+    .. code-block:: python3
+
+        import pm4py
+
+        net, im, fm = pm4py.read_pnml('tests/input_data/running-example.pnml')
+        marking = pm4py.replay_prefix_tbr(['register request', 'check ticket'], net, im, fm)
+    """
+    purpose_log = EventLog()
+    trace = Trace()
+    for act in prefix:
+        trace.append(Event({activity_key: act}))
+    purpose_log.append(trace)
+
+    from pm4py.algo.conformance.tokenreplay.variants import token_replay
+    parameters_tr = {
+        token_replay.Parameters.CONSIDER_REMAINING_IN_FITNESS: False,
+        token_replay.Parameters.TRY_TO_REACH_FINAL_MARKING_THROUGH_HIDDEN: False,
+        token_replay.Parameters.STOP_IMMEDIATELY_UNFIT: True,
+        token_replay.Parameters.WALK_THROUGH_HIDDEN_TRANS: True,
+        token_replay.Parameters.ACTIVITY_KEY: activity_key
+    }
+    res = token_replay.apply(purpose_log, net, im, fm, parameters=parameters_tr)[0]
+    return res["reached_marking"]
+
+
 @deprecation.deprecated(deprecated_in="2.3.0", removed_in="3.0.0", details="conformance checking using footprints will not be exposed in a future release")
 def __convert_to_fp(*args) -> Union[List[Dict[str, Any]], Dict[str, Any]]:
     """