bupaR Docs | Create Logs (2024)

Transactional lifecycle?

An event is an atomic registration related to an activity instance. It thus contains one (and only one) timestamp. Additionally, the event should include a reference to a lifecycle transition. More specifically, multiple events can describe different lifecycle transitions of a single activity instance. For example, one event might record when a surgery is scheduled, another when it is started, yet another when it is completed, etc.

Scenario 1

If each row in your data.frame is already an activityinstance, the activitylog format is the best way to go.Consider the data sample below.

As each row contains multiple timestamps, i.e.activity_started andactivity_ended, it is clear that each row represents an activityinstance. Turning this dataset in an activitylog requiresthe following steps:

1. Timestamp variables should be named in correspondence with thestandard Transactional lifecycle.
2. Timestamp variables should be of type Date orPOSIXct.
3. Use the activitylog constructor function.

data %>% # rename timestamp variables appropriately dplyr::rename(start = activity_started,  complete = activity_ended) %>% # convert timestamps to  convert_timestamps(columns = c("start", "complete"), format = ymd_hms) %>% activitylog(case_id = "patient", activity_id = "handling", timestamps = c("start", "complete"))

## # Log of 12 events consisting of:## 1 trace ## 1 case ## 6 instances of 6 activities ## 0 resources ## Events occurred from 2018-03-20 19:07:17 until 2018-04-12 21:41:01 ## ## # Variables were mapped as follows:## Case identifier: patient ## Activity identifier: handling ## Resource identifier: employee ## Timestamps: start, complete ## ## # A tibble: 6 × 5## patient handling start complete .order## <chr> <fct> <dttm> <dttm> <int>## 1 464 Blood test 2018-04-06 20:04:09 2018-04-07 01:18:17 1## 2 464 Check-out 2018-04-12 19:02:11 2018-04-12 21:41:01 2## 3 464 Discuss Results 2018-04-12 11:00:16 2018-04-12 13:59:44 3## 4 464 MRI SCAN 2018-04-07 06:30:56 2018-04-07 09:37:26 4## 5 464 Registration 2018-03-20 19:07:17 2018-03-20 21:15:41 5## 6 464 Triage and Assessment 2018-03-21 15:58:55 2018-03-22 05:21:56 6

Note that in case a resource identifier is available, thisinformation can be added in the activitylog call.

Scenario 2

If each row in your data.frame is an event, but allevents that belong to the same activity instance share the sameattribute values, the activitylog format is again the bestway to go. Consider the data sample below.

The resource identifier (employee) has been added as an additionalattribute. Note that though each row is an event, they can be groupedinto activity instances using the handling_id column, which we will callthe activity instance id. Using the latter, we can see that the resourceattribute is the same within each activity instance, which allows us tocreate an activitylog. The steps to do so are thefollowing.

1. Lifecycle variable should be named in correspondence with thestandard Transactional lifecycle.
2. Timestamp variable should be of type Date orPOSIXct.
3. Use the eventlog constructor function.
4. Convert to activitylog usingto_activitylog for reduced memory usage and improvedperformance.

data %>% # recode lifecycle variable appropriately dplyr::mutate(registration_type = forcats::fct_recode(registration_type,  "start" = "started", "complete" = "completed")) %>% convert_timestamps(columns = "time", format = ymd_hms) %>% eventlog(case_id = "patient", activity_id = "handling", activity_instance_id = "handling_id", lifecycle_id = "registration_type", timestamp = "time", resource_id = "employee") %>% to_activitylog() -> tmp_act

Note that the resource identifier is optional, and can be left out ofthe eventlog call if such an attribute does not exist inyour data. If the activity instance id does not exist, some heuristicsare available to generate it: [Missing activity instanceidentifier].

Scenario 3

If each row is an event, and events of the same activity instancehave differing attribute values, the flexibility ofeventlog objects is required. Consider the data samplebelow.

In this example, different resources (employees) sometimes performthe start and complete event of the same activity instance. Therefore,we resort to the eventlog format which has no problemsstoring this. The steps to take are the following:

1. Lifecycle variable should be named in correspondence with thestandard Transactional lifecycle.
2. Timestamp variable should be of type Date orPOSIXct.
3. Use the eventlog constructor function.

data %>% # recode lifecycle variable appropriately dplyr::mutate(registration_type = forcats::fct_recode(registration_type,  "start" = "started", "complete" = "completed")) %>% convert_timestamps(columns = "time", format = ymd_hms) %>% eventlog(case_id = "patient", activity_id = "handling", activity_instance_id = "handling_id", lifecycle_id = "registration_type", timestamp = "time", resource_id = "employee") 

## Warning in validate_eventlog(eventlog): The following activity instances are## connected to more than one resource: 1054,116,1291,1850,2345,616

## # Log of 12 events consisting of:## 1 trace ## 1 case ## 6 instances of 6 activities ## 6 resources ## Events occurred from 2017-04-29 03:24:59 until 2017-05-03 06:16:03 ## ## # Variables were mapped as follows:## Case identifier: patient ## Activity identifier: handling ## Resource identifier: employee ## Activity instance identifier: handling_id ## Timestamp: time ## Lifecycle transition: registration_type ## ## # A tibble: 12 × 7## patient handling employee handling_id registration_type time ## <chr> <fct> <fct> <chr> <fct> <dttm> ## 1 116 Registrat… r2 116 start 2017-04-29 03:24:59## 2 116 Registrat… r6 116 complete 2017-04-29 06:23:09## 3 116 Triage an… r1 616 start 2017-04-29 15:41:27## 4 116 Triage an… r7 616 complete 2017-04-30 03:04:21## 5 116 Blood test r4 1054 start 2017-04-30 15:13:28## 6 116 Blood test r6 1054 complete 2017-04-30 21:24:18## 7 116 MRI SCAN r1 1291 start 2017-05-01 01:12:51## 8 116 MRI SCAN r4 1291 complete 2017-05-01 05:32:37## 9 116 Discuss R… r3 1850 start 2017-05-01 09:44:20## 10 116 Discuss R… r7 1850 complete 2017-05-01 14:00:48## 11 116 Check-out r3 2345 start 2017-05-03 04:02:35## 12 116 Check-out r2 2345 complete 2017-05-03 06:16:03## # ℹ 1 more variable: .order <int>

Note that we need an eventlog irrespective of whichattribute values are differing, i.e.it can be resources, but also anyadditional variables you have in your data set. For the special case ofresource values, it might be that a different resource executing eventsin the same activity instance is a data quality issue. If so, somefunctions can help you to identify this issue: Inconsistent Resources.

Again, if the activity instance id does not exist, some heuristicsare available to generate it: [Missing activity instanceidentifier].

Missing activity instance id

In order to be able to correlate events which belong to the sameactivity instance, an activity instance identifier is required. Forexample, in the data shown below, it is possible that a patient has gonethrough different surgeries, each with their own start- and completeevent. The activity instance identifier will then allow to distinguishwhich events belong together and which do not. It is important to notethat this instance identifier should be unique, also among differentcases and activities.

If the activity instance identifier is not available you can use theassign_instance_id() function, which uses an heuristic tocreate the missing identifier. Alternatively, you can try to create theidentifier on your own using dplyr::mutate() and othermanipulation functions.

Large Datasets and Validation

By default, bupaR validates certain properties of theactivity instances that is supplied when creating an event log:

• a single activity instance identifier must not be connected tomultiple cases,
• a single activity instance identifier must not be connected tomultiple activity labels,

However, these checks are not efficient and may lead to considerableperformance issues for large data frames. It is possible to deactivatethe validation in case you already know that your data fulfills all therequirements, using the argument validate = FALSE whencreating the eventlog. Note that when the activity instanceid was created with the assign_instance_id() function, youcan assume the above properties hold.

Inconsistent Resources

Each event can contain the notion of a resource. It can be so thatdifferent events belonging to the same activity instance are executed bydifferent resources, as in the eventlog below.

If you have a large dataset, and want to have an overview of theactivity instances that have more than one resource connected to them,you can use the detect_resource_inconsistences()function.

log %>% detect_resource_inconsistencies()

## # A tibble: 6 × 5## patient handling handling_id complete start## <chr> <fct> <chr> <chr> <chr>## 1 206 Blood test 1100 r3 r1 ## 2 206 Check-out 2435 r7 r1 ## 3 206 Discuss Results 1940 r4 r2 ## 4 206 MRI SCAN 1337 r2 r6 ## 5 206 Registration 206 r3 r4 ## 6 206 Triage and Assessment 706 r7 r6

If you want to remove these inconsistencies, a quick fix is to mergethe resource labels together withfix_resource_inconsistencies(). Note that this is notneeded for eventlog, but it is foractivitylog. While the creation of theeventlog will emit a warning when resource inconsistenciesexist, this should mostly be seen as a data quality warning. That said,there might be analysis related to the counting of resources where suchinconsistencies might lead to odd results.

log %>% fix_resource_inconsistencies()

## *** OUTPUT ***

## A total of 6 activity executions in the event log are classified as inconsistencies.

## They are spread over the following cases and activities:

## # A tibble: 6 × 5## patient handling handling_id complete start## <chr> <fct> <chr> <chr> <chr>## 1 206 Blood test 1100 r3 r1 ## 2 206 Check-out 2435 r7 r1 ## 3 206 Discuss Results 1940 r4 r2 ## 4 206 MRI SCAN 1337 r2 r6 ## 5 206 Registration 206 r3 r4 ## 6 206 Triage and Assessment 706 r7 r6

## Inconsistencies solved succesfully.

## # Log of 12 events consisting of:## 1 trace ## 1 case ## 6 instances of 6 activities ## 6 resources ## Events occurred from 2017-07-19 15:48:14 until 2017-07-28 03:55:13 ## ## # Variables were mapped as follows:## Case identifier: patient ## Activity identifier: handling ## Resource identifier: employee ## Activity instance identifier: handling_id ## Timestamp: time ## Lifecycle transition: registration_type ## ## # A tibble: 12 × 7## patient handling employee handling_id registration_type time ## <chr> <fct> <chr> <chr> <fct> <dttm> ## 1 206 Registrat… r3 - r4 206 start 2017-07-19 15:48:14## 2 206 Triage an… r7 - r6 706 start 2017-07-19 17:03:44## 3 206 Registrat… r3 - r4 206 complete 2017-07-19 17:03:44## 4 206 Triage an… r7 - r6 706 complete 2017-07-20 07:28:53## 5 206 Blood test r3 - r1 1100 start 2017-07-25 03:02:14## 6 206 Blood test r3 - r1 1100 complete 2017-07-25 08:14:46## 7 206 MRI SCAN r2 - r6 1337 start 2017-07-25 12:37:36## 8 206 MRI SCAN r2 - r6 1337 complete 2017-07-25 16:52:16## 9 206 Discuss R… r4 - r2 1940 start 2017-07-26 07:36:36## 10 206 Discuss R… r4 - r2 1940 complete 2017-07-26 11:08:03## 11 206 Check-out r7 - r1 2435 start 2017-07-28 02:54:17## 12 206 Check-out r7 - r1 2435 complete 2017-07-28 03:55:13## # ℹ 1 more variable: .order <int>

Read more: