pm4py.ml module#

The pm4py.ml module contains the machine learning features offered in pm4py.

pm4py.ml.split_train_test(log: EventLog | DataFrame, train_percentage: float = 0.8, case_id_key: str = 'case:concept:name') → Tuple[EventLog, EventLog] | Tuple[DataFrame, DataFrame][source]#

Splits an event log into a training log and a test log for machine learning purposes.

This function separates the provided log into two parts based on the specified training percentage. It ensures that entire cases are included in either the training set or the test set.

Parameters:

  • log – The event log or Pandas DataFrame to be split.

  • train_percentage – Fraction of cases to be included in the training log (between 0.0 and 1.0).

  • case_id_key – Attribute to be used as the case identifier.

Returns:

A tuple containing the training and test event logs or DataFrames.

Return type:

Union[Tuple[EventLog, EventLog], Tuple[pd.DataFrame, pd.DataFrame]]

import pm4py

train_df, test_df = pm4py.split_train_test(dataframe, train_percentage=0.75)
pm4py.ml.get_prefixes_from_log(log: EventLog | DataFrame, length: int, case_id_key: str = 'case:concept:name') → EventLog | DataFrame[source]#

Retrieves prefixes of traces in a log up to a specified length.

The returned log contains prefixes of each trace: - If a trace has a length less than or equal to the specified length, it is included as-is. - If a trace exceeds the specified length, it is truncated to that length.

Parameters:

  • log – The event log or Pandas DataFrame from which to extract prefixes.

  • length – The maximum length of prefixes to extract.

  • case_id_key – Attribute to be used as the case identifier.

Returns:

A log containing the prefixes of the original log.

Return type:

Union[EventLog, pd.DataFrame]

import pm4py

trimmed_df = pm4py.get_prefixes_from_log(dataframe, length=5, case_id_key='case:concept:name')
pm4py.ml.extract_outcome_enriched_dataframe(log: EventLog | DataFrame, activity_key: str = 'concept:name', timestamp_key: str = 'time:timestamp', case_id_key: str = 'case:concept:name', start_timestamp_key: str = 'time:timestamp') → DataFrame[source]#

Enriches a dataframe with additional outcome-related columns computed from the entire case.

This function adds columns that model the outcome of each case by computing metrics such as arrival rates and service waiting times.

Parameters:

  • log – The event log or Pandas DataFrame to be enriched.

  • activity_key – Attribute to be used for the activity.

  • timestamp_key – Attribute to be used for the timestamp.

  • case_id_key – Attribute to be used as the case identifier.

  • start_timestamp_key – Attribute to be used as the start timestamp.

Returns:

An enriched Pandas DataFrame with additional outcome-related columns.

Return type:

pd.DataFrame

import pm4py

enriched_df = pm4py.extract_outcome_enriched_dataframe(
    log,
    activity_key='concept:name',
    timestamp_key='time:timestamp',
    case_id_key='case:concept:name',
    start_timestamp_key='time:timestamp'
)
pm4py.ml.extract_features_dataframe(log: EventLog | DataFrame, str_tr_attr: List[str] | None = None, num_tr_attr: List[str] | None = None, str_ev_attr: List[str] | None = None, num_ev_attr: List[str] | None = None, str_evsucc_attr: List[str] | None = None, activity_key: str = 'concept:name', timestamp_key: str = 'time:timestamp', case_id_key: str | None = None, resource_key: str = 'org:resource', include_case_id: bool = False, **kwargs) → DataFrame[source]#

Extracts a dataframe containing features for each case in the provided log object.

This function processes the log to generate a set of features that can be used for machine learning tasks. Features can include both case-level and event-level attributes, with options for one-hot encoding.

Parameters:

  • log – The event log or Pandas DataFrame from which to extract features.

  • str_tr_attr – (Optional) List of string attributes at the case level to extract as features.

  • num_tr_attr – (Optional) List of numeric attributes at the case level to extract as features.

  • str_ev_attr – (Optional) List of string attributes at the event level to extract as features (one-hot encoded).

  • num_ev_attr – (Optional) List of numeric attributes at the event level to extract as features (uses the last value per attribute in a case).

  • str_evsucc_attr – (Optional) List of string successor attributes at the event level to extract as features.

  • activity_key – Attribute to be used as the activity identifier.

  • timestamp_key – Attribute to be used for timestamps.

  • case_id_key – (Optional) Attribute to be used as the case identifier. If not provided, the default is used.

  • resource_key – Attribute to be used as the resource identifier.

  • include_case_id – Whether to include the case identifier column in the features table.

  • **kwargs –

    Additional keyword arguments to pass to the feature extraction algorithm.

Returns:

A Pandas DataFrame containing the extracted features for each case.

Return type:

pd.DataFrame

import pm4py

features_df = pm4py.extract_features_dataframe(
    dataframe,
    activity_key='concept:name',
    case_id_key='case:concept:name',
    timestamp_key='time:timestamp'
)
pm4py.ml.extract_ocel_features(ocel: OCEL, obj_type: str, enable_object_lifecycle_paths: bool = True, enable_object_work_in_progress: bool = False, object_str_attributes: Collection[str] | None = None, object_num_attributes: Collection[str] | None = None, include_obj_id: bool = False, debug: bool = False) → DataFrame[source]#

Extracts a set of features from an object-centric event log (OCEL) for objects of a specified type.

This function computes various features based on the lifecycle paths and work-in-progress metrics of objects within the OCEL. It also supports encoding of string and numeric object attributes.

The approach is based on: Berti, A., Herforth, J., Qafari, M.S. et al. Graph-based feature extraction on object-centric event logs. Int J Data Sci Anal (2023). https://doi.org/10.1007/s41060-023-00428-2

Parameters:

  • ocel – The object-centric event log from which to extract features.

  • obj_type – The object type to consider for feature extraction.

  • enable_object_lifecycle_paths – Whether to enable the “lifecycle paths” feature.

  • enable_object_work_in_progress – Whether to enable the “work in progress” feature, which has a high computational cost.

  • object_str_attributes – (Optional) Collection of string attributes at the object level to one-hot encode.

  • object_num_attributes – (Optional) Collection of numeric attributes at the object level to encode.

  • include_obj_id – Whether to include the object identifier as a column in the features DataFrame.

  • debug – Whether to enable debugging mode to track the feature extraction process.

Returns:

A Pandas DataFrame containing the extracted features for the specified object type.

Return type:

pd.DataFrame

import pm4py

ocel = pm4py.read_ocel('log.jsonocel')
fea_df = pm4py.extract_ocel_features(ocel, "item")
pm4py.ml.extract_temporal_features_dataframe(log: EventLog | DataFrame, grouper_freq: str = 'W', activity_key: str = 'concept:name', timestamp_key: str = 'time:timestamp', case_id_key: str | None = None, start_timestamp_key: str = 'time:timestamp', resource_key: str = 'org:resource') → DataFrame[source]#

Extracts temporal features from a log object and returns them as a dataframe.

This function computes temporal metrics based on the specified grouping frequency, which can be daily (D), weekly (W), monthly (M), or yearly (Y). These features are useful for analyzing system dynamics and simulation in the context of process mining.

The approach is based on: Pourbafrani, Mahsa, Sebastiaan J. van Zelst, and Wil MP van der Aalst. “Supporting automatic system dynamics model generation for simulation in the context of process mining.” International Conference on Business Information Systems. Springer, Cham, 2020.

Parameters:

  • log – The event log or Pandas DataFrame from which to extract temporal features.

  • grouper_freq – The frequency to use for grouping (e.g., ‘D’ for daily, ‘W’ for weekly, ‘M’ for monthly, ‘Y’ for yearly).

  • activity_key – Attribute to be used as the activity identifier.

  • timestamp_key – Attribute to be used for timestamps.

  • case_id_key – (Optional) Attribute to be used as the case identifier. If not provided, the default is used.

  • start_timestamp_key – Attribute to be used as the start timestamp.

  • resource_key – Attribute to be used as the resource identifier.

Returns:

A Pandas DataFrame containing the extracted temporal features.

Return type:

pd.DataFrame

import pm4py

temporal_features_df = pm4py.extract_temporal_features_dataframe(
    dataframe,
    activity_key='concept:name',
    case_id_key='case:concept:name',
    timestamp_key='time:timestamp'
)
pm4py.ml.extract_target_vector(log: EventLog | DataFrame, variant: str, activity_key: str = 'concept:name', timestamp_key: str = 'time:timestamp', case_id_key: str = 'case:concept:name') → Tuple[Any, List[str]][source]#

Extracts the target vector from a log object for a specific machine learning use case.

Supported variants include: - ‘next_activity’: Predicts the next activity in a case. - ‘next_time’: Predicts the timestamp of the next activity. - ‘remaining_time’: Predicts the remaining time for the case.

Parameters:

  • log – The event log or Pandas DataFrame from which to extract the target vector.

  • variant – The variant of the algorithm to use. Must be one of: ‘next_activity’, ‘next_time’, ‘remaining_time’.

  • activity_key – Attribute to be used as the activity identifier.

  • timestamp_key – Attribute to be used for timestamps.

  • case_id_key – Attribute to be used as the case identifier.

Returns:

A tuple containing the target vector and a list of class labels (if applicable).

Return type:

Tuple[Any, List[str]]

Raises:

Exception – If an unsupported variant is provided.

import pm4py

vector_next_act, class_next_act = pm4py.extract_target_vector(
    log,
    'next_activity',
    activity_key='concept:name',
    timestamp_key='time:timestamp',
    case_id_key='case:concept:name'
)
vector_next_time, class_next_time = pm4py.extract_target_vector(
    log,
    'next_time',
    activity_key='concept:name',
    timestamp_key='time:timestamp',
    case_id_key='case:concept:name'
)
vector_rem_time, class_rem_time = pm4py.extract_target_vector(
    log,
    'remaining_time',
    activity_key='concept:name',
    timestamp_key='time:timestamp',
    case_id_key='case:concept:name'
)