pm4py.util.pandas_utils module#

PM4Py – A Process Mining Library for Python Copyright (C) 2026 Process Intelligence Solutions GmbH

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see this software project’s root or visit <https://www.gnu.org/licenses/>.

Website: https://processintelligence.solutions Contact: info@processintelligence.solutions

pm4py.util.pandas_utils.get_default_dataframe_environment()[source]#
pm4py.util.pandas_utils.to_dict_records(df)[source]#

Pandas dataframe to dictionary (records method)

Parameters:

df – Dataframe

Returns:

List containing a dictionary for each row

Return type:

list_dictio

pm4py.util.pandas_utils.to_dict_index(df)[source]#

Pandas dataframe to dictionary (index method)

Parameters:

df – Dataframe

Returns:

dict like {index -> {column -> value}}

Return type:

dict

pm4py.util.pandas_utils.insert_index(df, column_name='@@index', copy_dataframe=True, reset_index=True)[source]#

Inserts the dataframe index in the specified column

Parameters:

  • df – Dataframe

  • column_name – Name of the column that should host the index

  • copy_dataframe – Establishes if the original dataframe should be copied before inserting the column

Returns:

Dataframe with index

Return type:

df

pm4py.util.pandas_utils.insert_case_index(df, column_name='@@case_index', case_id='case:concept:name', copy_dataframe=True)[source]#

Inserts the case number in the dataframe

Parameters:

  • df – Dataframe

  • column_name – Name of the column that should host the case index

  • case_id – Case identifier

  • copy_dataframe – Establishes if the original dataframe should be copied before inserting the column

Returns:

Dataframe with case index

Return type:

df

pm4py.util.pandas_utils.insert_ev_in_tr_index(df: DataFrame, case_id: str = 'case:concept:name', column_name: str = '@@index_in_trace', copy_dataframe=True) → DataFrame[source]#

Inserts a column that specify the index of the event inside the case

Parameters:

  • df – Dataframe

  • case_id – Column that hosts the case identifier

  • column_name – Name of the column that should host the index

Returns:

Dataframe with index

Return type:

df

pm4py.util.pandas_utils.format_unique(values)[source]#
pm4py.util.pandas_utils.insert_feature_activity_position_in_trace(df: DataFrame, case_id: str = 'case:concept:name', activity_key: str = 'concept:name', prefix='@@position_')[source]#

Inserts additional columns @@position_ACT1, @@position_ACT2 … which are populated for every event having activity ACT1, ACT2 respectively, with the index of the event inside its case.

Parameters:

  • df – Pandas dataframe

  • case_id – Case idntifier

  • activity_key – Activity

  • prefix – Prefix of the “activity position in trace” feature (default: @@position_)

Returns:

Pandas dataframe

Return type:

df

pm4py.util.pandas_utils.insert_case_arrival_finish_rate(log: DataFrame, case_id_column='case:concept:name', timestamp_column='time:timestamp', start_timestamp_column=None, arrival_rate_column='@@arrival_rate', finish_rate_column='@@finish_rate') → DataFrame[source]#

Inserts the arrival/finish rate in the dataframe.

Parameters:

log – Pandas dataframe

Returns:

Pandas dataframe enriched by arrival and finish rate

Return type:

log

pm4py.util.pandas_utils.insert_case_service_waiting_time(log: DataFrame, case_id_column='case:concept:name', timestamp_column='time:timestamp', start_timestamp_column=None, diff_start_end_column='@@diff_start_end', service_time_column='@@service_time', sojourn_time_column='@@sojourn_time', waiting_time_column='@@waiting_time') → DataFrame[source]#

Inserts the service/waiting/sojourn time in the dataframe.

Parameters:

  • log – Pandas dataframe

  • parameters – Parameters of the method

Returns:

Pandas dataframe with service, waiting and sojourn time

Return type:

log

pm4py.util.pandas_utils.check_is_pandas_dataframe(log)[source]#

Checks if a log object is a dataframe

Parameters:

log – Log object

Returns:

Is dataframe?

Return type:

boolean

pm4py.util.pandas_utils.is_polars_lazyframe(df)[source]#

Return True if the provided dataframe is a Polars LazyFrame.

pm4py.util.pandas_utils.instantiate_dataframe(*args, **kwargs)[source]#
pm4py.util.pandas_utils.instantiate_dataframe_from_dict(*args, **kwargs)[source]#
pm4py.util.pandas_utils.instantiate_dataframe_from_records(*args, **kwargs)[source]#
pm4py.util.pandas_utils.get_grouper(*args, **kwargs)[source]#
pm4py.util.pandas_utils.get_total_seconds(difference)[source]#
pm4py.util.pandas_utils.convert_to_seconds(dt_column)[source]#
pm4py.util.pandas_utils.dataframe_column_string_to_datetime(*args, **kwargs)[source]#
pm4py.util.pandas_utils.read_csv(*args, **kwargs)[source]#
pm4py.util.pandas_utils.concat(*args, **kwargs)[source]#
pm4py.util.pandas_utils.merge(*args, **kwargs)[source]#
pm4py.util.pandas_utils.check_pandas_dataframe_columns(df, activity_key=None, case_id_key=None, timestamp_key=None, start_timestamp_key=None)[source]#

Checks if the dataframe contains all the required columns. If not, raise an exception

Parameters:

df – Pandas dataframe

pm4py.util.pandas_utils.get_traces(log, case_id_key, activity_key)[source]#
pm4py.util.pandas_utils.get_attribute_values_count(log, attribute)[source]#
pm4py.util.pandas_utils.df_row_count(log)[source]#
pm4py.util.pandas_utils.get_pivot_timestamp_distribution(dataframe: DataFrame, frequency_alias='M', case_id_col='case:concept:name', timestamp_col='time:timestamp') → DataFrame[source]#

Creates a pivot table showing the distribution of timestamp occurrences for each case, grouped by a specified time frequency.

Parameters:

  • dataframe (pd.DataFrame) – The input event log as a pandas DataFrame, with at least case and timestamp columns.

  • frequency_alias (str, default ‘M’) – The frequency at which to group (bin) the timestamps. This value should be a valid pandas frequency alias, such as:

    • ‘A’ or ‘Y’ : Yearly (e.g., 2024)

    • ‘Q’ : Quarterly (e.g., 2024Q2)

    • ‘M’ : Monthly (e.g., 2024-06)

    • ‘W’ : Weekly (e.g., 2024-06-17/2024-06-23)

    • ‘D’ : Daily (e.g., 2024-06-18)

    • ‘H’ : Hourly (e.g., 2024-06-18 15:00)

    • ‘T’, ‘min’ : Minutely (e.g., 2024-06-18 15:30)

    • ‘S’ : Secondly (e.g., 2024-06-18 15:30:00) For a complete list, see: https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#dateoffset-objects case_id_col : str, default ‘case:concept:name’ The name of the column identifying each case. timestamp_col : str, default ‘time:timestamp’ The name of the column containing the event timestamps (must be pandas datetime dtype).

Returns:

A pivot table where each row represents a case, columns represent time bins (according to the frequency), and values are the counts of events in each bin.

Return type:

pd.DataFrame

Example

get_pivot_timestamp_distribution(df, frequency_alias=’D’)