0
# Reading and Writing Operations
1

2
Comprehensive I/O operations for process mining data formats. PM4PY supports traditional event logs, process models, and Object-Centric Event Logs (OCEL) with various file formats and encoding options.
3

4
## Capabilities
5

6
### XES Event Log I/O
7

8
Read and write event logs in the XES (eXtensible Event Stream) standard format, supporting multiple parser variants and encoding options.
9

10
```python { .api }
11
def read_xes(file_path, variant=None, return_legacy_log_object=False, encoding='utf-8', **kwargs):
12
    """
13
    Read XES event log files.
14
    
15
    Parameters:
16
    - file_path (str): Path/URI to XES file
17
    - variant (Optional[str]): Parser variant ('iterparse', 'line_by_line', 'chunk_regex', 'rustxes')
18
    - return_legacy_log_object (bool): Whether to return EventLog object vs DataFrame
19
    - encoding (str): File encoding (default: 'utf-8')
20
    
21
    Returns:
22
    Union[DataFrame, EventLog]: Event log data
23
    """
24

25
def write_xes(log, file_path, case_id_key='case:concept:name', extensions=None, encoding='utf-8', variant_str=None, **kwargs):
26
    """
27
    Write event logs to XES format.
28
    
29
    Parameters:
30
    - log (Union[EventLog, pd.DataFrame]): Event log to write
31
    - file_path (str): Target file path
32
    - case_id_key (str): Case identifier column
33
    - extensions (Optional[List]): XES extensions to include
34
    - encoding (str): File encoding
35
    
36
    Returns:
37
    None
38
    """
39
```
40

41
### Process Model I/O
42

43
Read and write various process model formats including Petri nets (PNML), process trees (PTML), and BPMN models.
44

45
```python { .api }
46
def read_pnml(file_path, auto_guess_final_marking=False, encoding='utf-8'):
47
    """
48
    Read Petri net models from PNML files.
49
    
50
    Parameters:
51
    - file_path (str): Path to PNML file
52
    - auto_guess_final_marking (bool): Auto-detect final marking
53
    - encoding (str): File encoding
54
    
55
    Returns:
56
    Tuple[PetriNet, Marking, Marking]: (petri_net, initial_marking, final_marking)
57
    """
58

59
def write_pnml(petri_net, initial_marking, final_marking, file_path, encoding='utf-8'):
60
    """
61
    Write Petri nets to PNML format.
62
    
63
    Parameters:
64
    - petri_net (PetriNet): Petri net model
65
    - initial_marking (Marking): Initial marking
66
    - final_marking (Marking): Final marking
67
    - file_path (str): Target file path
68
    - encoding (str): File encoding
69
    
70
    Returns:
71
    None
72
    """
73

74
def read_ptml(file_path, encoding='utf-8'):
75
    """
76
    Read process tree models from PTML files.
77
    
78
    Parameters:
79
    - file_path (str): Path to PTML file
80
    - encoding (str): File encoding
81
    
82
    Returns:
83
    ProcessTree: Process tree model
84
    """
85

86
def write_ptml(tree, file_path, auto_layout=True, encoding='utf-8'):
87
    """
88
    Write process trees to PTML format.
89
    
90
    Parameters:
91
    - tree (ProcessTree): Process tree model
92
    - file_path (str): Target file path
93
    - auto_layout (bool): Apply automatic layout
94
    - encoding (str): File encoding
95
    
96
    Returns:
97
    None
98
    """
99
```
100

101
### BPMN Model I/O
102

103
Read and write Business Process Model and Notation (BPMN) files with layout support.
104

105
```python { .api }
106
def read_bpmn(file_path, encoding='utf-8'):
107
    """
108
    Read BPMN models from BPMN files.
109
    
110
    Parameters:
111
    - file_path (str): Path to BPMN file
112
    - encoding (str): File encoding
113
    
114
    Returns:
115
    BPMN: BPMN model object
116
    """
117

118
def write_bpmn(model, file_path, auto_layout=True, encoding='utf-8'):
119
    """
120
    Write BPMN models to file.
121
    
122
    Parameters:
123
    - model (BPMN): BPMN model to write
124
    - file_path (str): Target file path
125
    - auto_layout (bool): Apply automatic layout
126
    - encoding (str): File encoding
127
    
128
    Returns:
129
    None
130
    """
131
```
132

133
### Directly-Follows Graph I/O
134

135
Read and write Directly-Follows Graphs (DFGs) which represent direct successor relationships between activities.
136

137
```python { .api }
138
def read_dfg(file_path, encoding='utf-8'):
139
    """
140
    Read Directly-Follows Graphs from DFG files.
141
    
142
    Parameters:
143
    - file_path (str): Path to DFG file
144
    - encoding (str): File encoding
145
    
146
    Returns:
147
    Tuple[Dict[Tuple[str, str], int], Dict[str, int], Dict[str, int]]: 
148
        (dfg_dict, start_activities, end_activities)
149
    """
150

151
def write_dfg(dfg, start_activities, end_activities, file_path, encoding='utf-8'):
152
    """
153
    Write DFGs to file.
154
    
155
    Parameters:
156
    - dfg (Dict[Tuple[str, str], int]): DFG dictionary
157
    - start_activities (Dict[str, int]): Start activities and frequencies
158
    - end_activities (Dict[str, int]): End activities and frequencies
159
    - file_path (str): Target file path
160
    - encoding (str): File encoding
161
    
162
    Returns:
163
    None
164
    """
165
```
166

167
### OCEL 1.0 I/O
168

169
Read and write Object-Centric Event Logs in various formats (CSV, JSON, XML, SQLite) with automatic format detection.
170

171
```python { .api }
172
def read_ocel(file_path, objects_path=None, encoding='utf-8'):
173
    """
174
    Read object-centric event logs (auto-detects format).
175
    
176
    Parameters:
177
    - file_path (str): Path to OCEL file
178
    - objects_path (Optional[str]): Path to objects file (for CSV format)
179
    - encoding (str): File encoding
180
    
181
    Returns:
182
    OCEL: Object-centric event log
183
    """
184

185
def read_ocel_csv(file_path, objects_path=None, encoding='utf-8'):
186
    """
187
    Read OCEL from CSV format.
188
    
189
    Parameters:
190
    - file_path (str): Path to events CSV file
191
    - objects_path (Optional[str]): Path to objects CSV file
192
    - encoding (str): File encoding
193
    
194
    Returns:
195
    OCEL: Object-centric event log
196
    """
197

198
def read_ocel_xml(file_path, encoding='utf-8'):
199
    """
200
    Read OCEL from XML format.
201
    
202
    Parameters:
203
    - file_path (str): Path to OCEL XML file
204
    - encoding (str): File encoding
205
    
206
    Returns:
207
    OCEL: Object-centric event log
208
    """
209

210
def read_ocel_json(file_path, encoding='utf-8'):
211
    """
212
    Read OCEL from JSON format.
213
    
214
    Parameters:
215
    - file_path (str): Path to OCEL JSON file
216
    - encoding (str): File encoding
217
    
218
    Returns:
219
    OCEL: Object-centric event log
220
    """
221

222
def read_ocel_sqlite(file_path, encoding='utf-8'):
223
    """
224
    Read OCEL from SQLite database.
225
    
226
    Parameters:
227
    - file_path (str): Path to SQLite database file
228
    - encoding (str): File encoding
229
    
230
    Returns:
231
    OCEL: Object-centric event log
232
    """
233
```
234

235
### OCEL 1.0 Writing
236

237
Write Object-Centric Event Logs in multiple formats with consistent interface.
238

239
```python { .api }
240
def write_ocel(ocel, file_path, objects_path=None, encoding='utf-8'):
241
    """
242
    Write OCEL to various formats (CSV, JSON, XML, SQLite).
243
    Format determined by file extension.
244
    
245
    Parameters:
246
    - ocel (OCEL): Object-centric event log
247
    - file_path (str): Target file path
248
    - objects_path (Optional[str]): Path for objects file (CSV format)
249
    - encoding (str): File encoding
250
    
251
    Returns:
252
    None
253
    """
254

255
def write_ocel_csv(ocel, file_path, objects_path, encoding='utf-8'):
256
    """
257
    Write OCEL to CSV format.
258
    
259
    Parameters:
260
    - ocel (OCEL): Object-centric event log
261
    - file_path (str): Path for events CSV file
262
    - objects_path (str): Path for objects CSV file
263
    - encoding (str): File encoding
264
    
265
    Returns:
266
    None
267
    """
268

269
def write_ocel_json(ocel, file_path, encoding='utf-8'):
270
    """
271
    Write OCEL to JSON format.
272
    
273
    Parameters:
274
    - ocel (OCEL): Object-centric event log
275
    - file_path (str): Target JSON file path
276
    - encoding (str): File encoding
277
    
278
    Returns:
279
    None
280
    """
281

282
def write_ocel_xml(ocel, file_path, encoding='utf-8'):
283
    """
284
    Write OCEL to XML format.
285
    
286
    Parameters:
287
    - ocel (OCEL): Object-centric event log
288
    - file_path (str): Target XML file path
289
    - encoding (str): File encoding
290
    
291
    Returns:
292
    None
293
    """
294

295
def write_ocel_sqlite(ocel, file_path, encoding='utf-8'):
296
    """
297
    Write OCEL to SQLite database.
298
    
299
    Parameters:
300
    - ocel (OCEL): Object-centric event log
301
    - file_path (str): Target SQLite database path
302
    - encoding (str): File encoding
303
    
304
    Returns:
305
    None
306
    """
307
```
308

309
### OCEL 2.0 I/O
310

311
Read and write the next generation OCEL 2.0 format with enhanced capabilities and performance.
312

313
```python { .api }
314
def read_ocel2(file_path, variant_str=None, encoding='utf-8'):
315
    """
316
    Read OCEL 2.0 format (auto-detects format).
317
    
318
    Parameters:
319
    - file_path (str): Path to OCEL 2.0 file
320
    - variant_str (Optional[str]): Specific variant to use
321
    - encoding (str): File encoding
322
    
323
    Returns:
324
    OCEL: Object-centric event log
325
    """
326

327
def read_ocel2_sqlite(file_path, variant_str=None, encoding='utf-8'):
328
    """
329
    Read OCEL 2.0 from SQLite.
330
    
331
    Parameters:
332
    - file_path (str): Path to SQLite database
333
    - variant_str (Optional[str]): Specific variant to use
334
    - encoding (str): File encoding
335
    
336
    Returns:
337
    OCEL: Object-centric event log
338
    """
339

340
def read_ocel2_json(file_path, encoding='utf-8'):
341
    """
342
    Read OCEL 2.0 from JSON.
343
    
344
    Parameters:
345
    - file_path (str): Path to JSON file
346
    - encoding (str): File encoding
347
    
348
    Returns:
349
    OCEL: Object-centric event log
350
    """
351

352
def read_ocel2_xml(file_path, encoding='utf-8'):
353
    """
354
    Read OCEL 2.0 from XML.
355
    
356
    Parameters:
357
    - file_path (str): Path to XML file
358
    - encoding (str): File encoding
359
    
360
    Returns:
361
    OCEL: Object-centric event log
362
    """
363

364
def write_ocel2(ocel, file_path, encoding='utf-8'):
365
    """
366
    Write OCEL 2.0 format.
367
    
368
    Parameters:
369
    - ocel (OCEL): Object-centric event log
370
    - file_path (str): Target file path
371
    - encoding (str): File encoding
372
    
373
    Returns:
374
    None
375
    """
376

377
def write_ocel2_sqlite(ocel, file_path, encoding='utf-8'):
378
    """
379
    Write OCEL 2.0 to SQLite.
380
    
381
    Parameters:
382
    - ocel (OCEL): Object-centric event log
383
    - file_path (str): Target SQLite database path
384
    - encoding (str): File encoding
385
    
386
    Returns:
387
    None
388
    """
389

390
def write_ocel2_xml(ocel, file_path, encoding='utf-8'):
391
    """
392
    Write OCEL 2.0 to XML.
393
    
394
    Parameters:
395
    - ocel (OCEL): Object-centric event log
396
    - file_path (str): Target XML file path
397
    - encoding (str): File encoding
398
    
399
    Returns:
400
    None
401
    """
402

403
def write_ocel2_json(ocel, file_path, encoding='utf-8'):
404
    """
405
    Write OCEL 2.0 to JSON.
406
    
407
    Parameters:
408
    - ocel (OCEL): Object-centric event log
409
    - file_path (str): Target JSON file path
410
    - encoding (str): File encoding
411
    
412
    Returns:
413
    None
414
    """
415
```
416

417
## Usage Examples
418

419
### Basic Event Log Reading
420

421
```python
422
import pm4py
423

424
# Read XES file
425
log = pm4py.read_xes('event_log.xes')
426

427
# Read with specific parser variant for large files
428
log = pm4py.read_xes('large_log.xes', variant='rustxes')
429

430
# Return as DataFrame instead of EventLog object
431
df = pm4py.read_xes('event_log.xes', return_legacy_log_object=False)
432
```
433

434
### Process Model I/O
435

436
```python
437
import pm4py
438

439
# Read Petri net
440
net, initial_marking, final_marking = pm4py.read_pnml('model.pnml')
441

442
# Read process tree
443
tree = pm4py.read_ptml('process_tree.ptml')
444

445
# Write models
446
pm4py.write_pnml(net, initial_marking, final_marking, 'output_model.pnml')
447
pm4py.write_ptml(tree, 'output_tree.ptml')
448
```
449

450
### OCEL I/O Operations
451

452
```python
453
import pm4py
454

455
# Read OCEL (auto-detect format)
456
ocel = pm4py.read_ocel('ocel_data.csv', objects_path='objects.csv')
457
ocel = pm4py.read_ocel('ocel_data.json')
458

459
# Read OCEL 2.0
460
ocel2 = pm4py.read_ocel2('ocel2_data.sqlite')
461

462
# Write OCEL in different formats
463
pm4py.write_ocel_json(ocel, 'output.json')
464
pm4py.write_ocel_sqlite(ocel, 'output.sqlite')
465
pm4py.write_ocel2(ocel, 'output_v2.sqlite')
466
```