pm4py.read module#

The pm4py.read module contains all functionality related to reading files and objects from disk (or via URIs).

pm4py.read.read_xes(file_path: str, variant: str | None = None, return_legacy_log_object: bool = False, return_pl_lazyframe: bool = False, encoding: str = 'utf-8', **kwargs) → DataFrame | EventLog[source]#

Reads an event log stored in XES format (see xes-standard). Returns a table (pandas.DataFrame) view of the event log or an EventLog object.

Parameters:

  • file_path – Path/URI to the event log (.xes file).

  • variant –

    Variant of the importer to use. Options include:

    • ”iterparse” – traditional XML parser,

    • ”line_by_line” – text-based line-by-line importer,

    • ”chunk_regex” – chunk-of-bytes importer (default),

    • ”iterparse20” – XES 2.0 importer,

    • ”r4pm” – Rust-based importer via r4pm.df,

    • ”rustxes” – compatibility alias for the Rust-based importer.

  • return_legacy_log_object – Boolean indicating whether to return a legacy EventLog object (default: False).

  • return_pl_lazyframe – Returns a Polars LazyFrame (default: False).

  • encoding – Encoding to be used (default: utf-8).

  • **kwargs – Additional parameters to pass to the importer.

Return type:

pandas.DataFrame or pm4py.objects.log.obj.EventLog

import pm4py

log = pm4py.read_xes("<path_or_uri_to_xes_file>")
pm4py.read.read_pnml(file_path: str, auto_guess_final_marking: bool = False, encoding: str = 'utf-8') → Tuple[PetriNet, Marking, Marking][source]#

Reads a Petri net object from a .pnml file. The returned Petri net object is a tuple containing:

  1. PetriNet object (PetriNet)

  2. Initial Marking (Marking)

  3. Final Marking (Marking)

Parameters:

  • file_path – Path/URI to the Petri net model (.pnml file).

  • auto_guess_final_marking – Boolean indicating whether to automatically guess the final marking (default: False).

  • encoding – Encoding to be used (default: utf-8).

Return type:

Tuple[PetriNet, Marking, Marking]

import pm4py

pn = pm4py.read_pnml("<path_or_uri_to_pnml_file>")
pm4py.read.read_ptml(file_path: str, encoding: str = 'utf-8') → ProcessTree[source]#

Reads a process tree object from a .ptml file.

Parameters:

  • file_path – Path/URI to the process tree file on disk.

  • encoding – Encoding to be used (default: utf-8).

Return type:

ProcessTree

import pm4py

process_tree = pm4py.read_ptml("<path_or_uri_to_ptml_file>")
pm4py.read.read_dfg(file_path: str, encoding: str = 'utf-8') → Tuple[Dict[Tuple[str, str], int], Dict[str, int], Dict[str, int]][source]#

Reads a Directly-Follows Graph (DFG) from a .dfg file. The returned DFG object is a tuple containing:

  1. DFG (Dict[Tuple[str, str], int]): Maps pairs of activities to their occurrence count. For example, DFG[(‘a’, ‘b’)] = k indicates that activity ‘a’ is directly followed by activity ‘b’ a total of k times in the log.

  2. Start Activity Dictionary (Dict[str, int]): Maps activities to the number of traces they start. For example, S[‘a’] = k implies that activity ‘a’ starts k traces in the event log.

  3. End Activity Dictionary (Dict[str, int]): Maps activities to the number of traces they end. For example, E[‘z’] = k implies that activity ‘z’ ends k traces in the event log.

Parameters:

  • file_path – Path/URI to the DFG model file.

  • encoding – Encoding to be used (default: utf-8).

Return type:

Tuple[Dict[Tuple[str, str], int], Dict[str, int], Dict[str, int]]

import pm4py

dfg = pm4py.read_dfg("<path_or_uri_to_dfg_file>")
pm4py.read.read_bpmn(file_path: str, encoding: str = 'utf-8') → BPMN[source]#

Reads a BPMN model from a .bpmn file.

Parameters:

  • file_path – Path/URI to the BPMN model file.

  • encoding – Encoding to be used (default: utf-8).

Return type:

BPMN

import pm4py

bpmn = pm4py.read_bpmn('<path_or_uri_to_bpmn_file>')
pm4py.read.read_ocel(file_path: str, objects_path: str | None = None, encoding: str = 'utf-8') → OCEL[source]#

Reads an object-centric event log from a file (see: http://www.ocel-standard.org/). Returns an OCEL object.

Parameters:

  • file_path – Path/URI to the object-centric event log file.

  • objects_path – [Optional] Path/URI to the objects dataframe file.

  • encoding – Encoding to be used (default: utf-8).

Return type:

OCEL

import pm4py

ocel = pm4py.read_ocel("<path_or_uri_to_ocel_file>")
pm4py.read.read_ocel_csv(file_path: str, objects_path: str | None = None, encoding: str = 'utf-8') → OCEL[source]#

Reads an object-centric event log from a CSV file (see: http://www.ocel-standard.org/). Returns an OCEL object.

Parameters:

  • file_path – Path/URI to the object-centric event log file (.csv).

  • objects_path – [Optional] Path/URI to the objects dataframe file.

  • encoding – Encoding to be used (default: utf-8).

Return type:

OCEL

import pm4py

ocel = pm4py.read_ocel_csv("<path_or_uri_to_ocel_file.csv>")
pm4py.read.read_ocel_json(file_path: str, encoding: str = 'utf-8') → OCEL[source]#

Reads an object-centric event log from a JSON-OCEL file (see: http://www.ocel-standard.org/). Returns an OCEL object.

Parameters:

  • file_path – Path/URI to the object-centric event log file (.jsonocel).

  • encoding – Encoding to be used (default: utf-8).

Return type:

OCEL

import pm4py

ocel = pm4py.read_ocel_json("<path_or_uri_to_ocel_file.jsonocel>")
pm4py.read.read_ocel_xml(file_path: str, encoding: str = 'utf-8') → OCEL[source]#

Reads an object-centric event log from an XML-OCEL file (see: http://www.ocel-standard.org/). Returns an OCEL object.

Parameters:

  • file_path – Path/URI to the object-centric event log file (.xmlocel).

  • encoding – Encoding to be used (default: utf-8).

Return type:

OCEL

import pm4py

ocel = pm4py.read_ocel_xml("<path_or_uri_to_ocel_file.xmlocel>")
pm4py.read.read_ocel_sqlite(file_path: str, encoding: str = 'utf-8') → OCEL[source]#

Reads an object-centric event log from a SQLite database (see: http://www.ocel-standard.org/). Returns an OCEL object.

Parameters:

  • file_path – Path/URI to the SQLite database file (.sqlite).

  • encoding – Encoding to be used (default: utf-8).

Return type:

OCEL

import pm4py

ocel = pm4py.read_ocel_sqlite("<path_or_uri_to_ocel_file.sqlite>")
pm4py.read.read_ocel2(file_path: str, variant_str: str | None = None, encoding: str = 'utf-8') → OCEL[source]#

Reads an OCEL 2.0 event log.

Parameters:

  • file_path – Path/URI to the OCEL 2.0 event log file.

  • variant_str – [Optional] Specification of the importer variant to be used.

  • encoding – Encoding to be used (default: utf-8).

Return type:

OCEL

Supported file formats based on extension:

  • .ocel.zip – bundled CSV/Parquet archive,

  • .sqlite – SQLite database,

  • .csv – compact OCEL 2.0 CSV file,

  • .xml, .xmlocel, .xml.gz, or .xmlocel.gz – XML file,

  • .json, .jsonocel, .json.gz, or .jsonocel.gz – JSON file.

import pm4py

ocel = pm4py.read_ocel2("<path_or_uri_to_ocel_file>")
pm4py.read.read_ocel2_bundle(file_path: str, encoding: str = 'utf-8') → OCEL[source]#

Reads an OCEL 2.0 event log from the bundled CSV/Parquet format.

The input can be a .ocel.zip archive or an uncompressed bundle directory containing ocel-meta.json.

Parameters:

  • file_path – Path/URI to the bundled OCEL 2.0 archive or directory.

  • encoding – Encoding to be used for metadata and CSV files (default: utf-8).

Return type:

OCEL

import pm4py

ocel = pm4py.read_ocel2_bundle("<path_to_bundle.ocel.zip>")
pm4py.read.read_ocel2_csv(file_path: str, encoding: str = 'utf-8') → OCEL[source]#

Reads an OCEL 2.0 event log from a compact CSV file.

Parameters:

  • file_path – Path/URI to the OCEL 2.0 CSV file (.csv).

  • encoding – Encoding to be used (default: utf-8).

Return type:

OCEL

import pm4py

ocel = pm4py.read_ocel2_csv("<path_or_uri_to_ocel_file.csv>")
pm4py.read.read_ocel2_json(file_path: str, encoding: str = 'utf-8') → OCEL[source]#

Reads an OCEL 2.0 event log from a JSON-OCEL2 file.

Parameters:

  • file_path – Path/URI to the JSON file (.json, .jsonocel, or their .gz variants).

  • encoding – Encoding to be used (default: utf-8).

Return type:

OCEL

import pm4py

ocel = pm4py.read_ocel2_json("<path_or_uri_to_ocel_file.jsonocel>")
pm4py.read.read_ocel2_sqlite(file_path: str, variant_str: str | None = None, encoding: str = 'utf-8') → OCEL[source]#

Reads an OCEL 2.0 event log from a SQLite database.

Parameters:

  • file_path – Path/URI to the OCEL 2.0 SQLite database file (.sqlite).

  • variant_str – [Optional] Specification of the importer variant to be used.

  • encoding – Encoding to be used (default: utf-8).

Return type:

OCEL

import pm4py

ocel = pm4py.read_ocel2_sqlite("<path_or_uri_to_ocel_file.sqlite>")
pm4py.read.read_ocel2_xml(file_path: str, encoding: str = 'utf-8') → OCEL[source]#

Reads an OCEL 2.0 event log from an XML file.

Parameters:

  • file_path – Path/URI to the OCEL 2.0 XML file (.xml, .xmlocel, or their .gz variants).

  • encoding – Encoding to be used (default: utf-8).

Return type:

OCEL

import pm4py

ocel = pm4py.read_ocel2_xml("<path_or_uri_to_ocel_file.xmlocel>")