# Introduction to gmoTree

#### Patricia F. Zauchner

#### 2023-08-24 (updated: 2024-09-30)

Handling data from online experiments made with oTree (Chen et al., 2016) can be challenging, especially when dealing with complex experimental designs that span multiple sessions and return numerous files that must be combined. This is where the gmoTree package comes in. It helps streamline the data processing workflow by providing tools designed to import, merge, and manage data from oTree experiments.

# Importing and cleaning up data

## Background information on the data downloaded by oTree

An oTree experiment is structured around one or more modular units called “apps,” which encompass one or multiple “pages.” Data generated from each app can be downloaded individually, offering the flexibility to analyze separate components of the experiment. For an all-encompassing view of the experiment, the data from all apps can also be downloaded in a comprehensive file labeled “all_apps_wide.”

In addition to the aforementioned app data and the cumulative all_apps_wide file, oTree generates a file with time stamps for every page. A file documenting all chat interactions is also provided if the experiment includes one or multiple chat rooms. In newer oTree versions, also custom data can be downloaded.

When an oTree experiment is run across different databases, this set of data files is downloaded for each database. This would include individual app data files, the all_apps_wide file, a file for the time stamps of every page, and a chat log file if a chat room was used in the experiment.

The gmoTree package’s functionality lies in its ability to load and aggregate all of these files with ease.

## import_otree()

We can import all oTree data and combine them into a list of data frames using the `import_otree()` function. Each data frame is named according to its associated app, and the function generates an accompanying info list that details essential information regarding the imported files, such as any deleted cases. This information list is updated as we use other functions within the package.

It is worth noting that even if we only use one all_apps_wide file, we should still load the data with `import_otree()` if we want to access other functions within the gmoTree package. Alternatively, we could reproduce the structure created by this function by hand. The following example shows how to import oTree data, the structure of the oTree list of data frames after importing the data, and all of the information provided in `oTree$info`.

    # Get path to the package data
    path <- system.file("extdata/exp_data_5.4.0", package = "gmoTree")

    # Import without specifications
    # Import all oTree files in this folder and its subfolders
    otree <- import_otree(path = path)
    ## Warning in import_otree(path = path): You have stored all_apps_wide globally
    ## but also room-specific. This function will import both of them. (Globally, the
    ## files are saved as "all_apps_wide_." Room-specific, the files are saved as "All
    ## apps - wide-" or "all_apps_wide-.") After importing the data, make sure nothing
    ## is there twice! (Advice: You may use delete_duplicate() to remove duplicate
    ## rows of all oTree data frames.

    # Check the structure of the list of data frames
    str(otree, 1)
    ## List of 8
    ##  $ all_apps_wide:'data.frame':   12 obs. of  60 variables:
    ##  $ info         :List of 2
    ##  $ chatapp      :'data.frame':   8 obs. of  24 variables:
    ##  $ dictator     :'data.frame':   48 obs. of  25 variables:
    ##  $ start        :'data.frame':   8 obs. of  24 variables:
    ##  $ survey       :'data.frame':   8 obs. of  29 variables:
    ##  $ Time         :'data.frame':   77 obs. of  10 variables:
    ##  $ Chats        :'data.frame':   6 obs. of  7 variables:

    # The initial info list
    otree$info
    ## $imported_files
    ## [1] "C:/Users/Lenovo/AppData/Local/Temp/Rtmp4mUHIN/Rinst3e905b6e63ea/gmoTree/extdata/exp_data_5.4.0/ChatMessages-2023-05-16.csv"
    ## [2] "C:/Users/Lenovo/AppData/Local/Temp/Rtmp4mUHIN/Rinst3e905b6e63ea/gmoTree/extdata/exp_data_5.4.0/PageTimes-2023-05-16.csv"
    ## [3] "C:/Users/Lenovo/AppData/Local/Temp/Rtmp4mUHIN/Rinst3e905b6e63ea/gmoTree/extdata/exp_data_5.4.0/survey_2023-05-16.csv"
    ## [4] "C:/Users/Lenovo/AppData/Local/Temp/Rtmp4mUHIN/Rinst3e905b6e63ea/gmoTree/extdata/exp_data_5.4.0/start_2023-05-16.csv"
    ## [5] "C:/Users/Lenovo/AppData/Local/Temp/Rtmp4mUHIN/Rinst3e905b6e63ea/gmoTree/extdata/exp_data_5.4.0/dictator_2023-05-16.csv"
    ## [6] "C:/Users/Lenovo/AppData/Local/Temp/Rtmp4mUHIN/Rinst3e905b6e63ea/gmoTree/extdata/exp_data_5.4.0/dictator_2023-05-00.csv"
    ## [7] "C:/Users/Lenovo/AppData/Local/Temp/Rtmp4mUHIN/Rinst3e905b6e63ea/gmoTree/extdata/exp_data_5.4.0/chatapp_2023-05-16.csv"
    ## [8] "C:/Users/Lenovo/AppData/Local/Temp/Rtmp4mUHIN/Rinst3e905b6e63ea/gmoTree/extdata/exp_data_5.4.0/all_apps_wide_2023-05-16.csv"
    ## [9] "C:/Users/Lenovo/AppData/Local/Temp/Rtmp4mUHIN/Rinst3e905b6e63ea/gmoTree/extdata/exp_data_5.4.0/all_apps_wide-2023-05-16.csv"
    ##
    ## $initial_n
    ## [1] 12

Caution: This function only works if the oTree data is saved using the typical oTree file pattern!

## delete_duplicate()

Sometimes, the same data is imported several times. This could happen for several reasons. First, one data set might be part of another because of the download of temporarily stored data before downloading the final data frame. Second, if room-specific and global data is imported, the data in the `$all_apps_wide` data frame are there two times. Third, the same data is stored in several imported folders. The function `delete_duplicate()` deletes duplicate data from all apps and `$all_apps_wide`. It, however, does not change the `$Time` and `$Chats` data frames.

Before running the function, let us first check the number of participant codes and the initial count before executing the `delete_duplicate()` function. In the imported `$all_apps_wide` data frame, we have 12 participant codes. However, among these, only 8 are unique, which indicates the presence of duplicate data. The `$info` data frame suggests that there are initially 12 entries.

    # Initial check before deletion
    length(otree$all_apps_wide$participant.code)
    ## [1] 12
    length(unique(otree$all_apps_wide$participant.code))
    ## [1] 8
    otree$info$initial_n
    ## [1] 12

To remove these duplicates, we employ the `delete_duplicate()` function:

    # Delete duplicate cases
    otree <- delete_duplicate(otree)

Please note that details about the deleted rows are not added to a list of deleted cases. This is because the list might be used for analysis, and this function mainly focuses on cleaning up an untidy data import. However, the count in `$info$initial_n` is adjusted accordingly.

After the deletion operation, we should find that all participant codes are unique, and the count `$info$initial_n` matches the number of unique participant codes.

    # Check participant codes and initial_n after deletion
    length(otree$all_apps_wide$participant.code)
    ## [1] 8
    length(unique(otree$all_apps_wide$participant.code))
    ## [1] 8
    otree$info$initial_n
    ## [1] 8

## Dealing with messy Chats and Time data frames

If we combine data from experiments that ran on different versions of oTree, it might happen that there are several variables referring to the same attribute in the `$Time` and in the `$Chats` data frames. The functions `messy_chat()` and `messy_time()` integrate the corresponding variables if used with the argument `combine = TRUE`.

To show an example, let us first load data from different versions of oTree.

    # Import data from different oTree versions
    otree_all <- import_otree(
      path = system.file("extdata", package = "gmoTree"))
    ## Warning in import_otree(path = system.file("extdata", package = "gmoTree")):
    ## You have stored all_apps_wide globally but also room-specific. This function
    ## will import both of them. (Globally, the files are saved as "all_apps_wide_."
    ## Room-specific, the files are saved as "All apps - wide-" or "all_apps_wide-.")
    ## After importing the data, make sure nothing is there twice! (Advice: You may
    ## use delete_duplicate() to remove duplicate rows of all oTree data frames.

    # Check names of Time data frame
    names(otree_all$Time)
    ##  [1] "session_code"              "participant_id_in_session"
    ##  [3] "participant_code"          "page_index"
    ##  [5] "app_name"                  "page_name"
    ##  [7] "epoch_time_completed"      "round_number"
    ##  [9] "timeout_happened"          "is_wait_page"

    # Check names of Chats data frame
    names(otree_all$Chats)
    ## [1] "session_code"     "id_in_session"    "participant_code" "channel"
    ## [5] "nickname"         "body"             "timestamp"

Now we can run the functions `messy_time()` and `messy_chat()`. The warning messages are part of the expected output, indicating precisely which variables were combined. There is no need for concern when we see them. However, you can also turn them off using `info = FALSE`.

    otree_all <- messy_time(otree_all,
                            combine = TRUE,
                            info = TRUE)

    otree_all <- messy_chat(otree_all,
                            combine = TRUE,
                            info = TRUE)

    # Check names of Time data frame again
    names(otree_all$Time)
    ##  [1] "session_code"              "participant_id_in_session"
    ##  [3] "participant_code"          "page_index"
    ##  [5] "app_name"                  "page_name"
    ##  [7] "epoch_time_completed"      "round_number"
    ##  [9] "timeout_happened"          "is_wait_page"

    # Check names of Chats data frame again
    names(otree_all$Chats)
    ## [1] "session_code"     "id_in_session"    "participant_code" "channel"
    ## [5] "nickname"         "body"             "timestamp"

# Dealing with dropouts and deleting cases

## show_dropouts()

Sometimes, participants drop out of experiments. To get an overview of the dropouts, we can use the function `show_dropouts()`. It creates three data frames/tables with information on the participants that did not finish at (a) certain app(s) or page(s).

First, the function `show_dropouts()` creates a data frame `$full` that provides specific information on the apps and pages where participants left the experiment prematurely. Additionally, this data frame indicates which apps were affected by the participants who dropped out.

    # Show everyone that has not finished with the app "survey"
    dropout_list <- show_dropouts(otree, "survey")

    head(dropout_list$full)
    ##   participant.code session.code  end_app        end_page
    ## 1         1k58kgm7     jk9ekpl0 dictator ResultsWaitPage
    ## 2         1k58kgm7     jk9ekpl0 dictator ResultsWaitPage
    ## 3         1k58kgm7     jk9ekpl0 dictator ResultsWaitPage
    ## 4         1k58kgm7     jk9ekpl0 dictator ResultsWaitPage
    ## 5         1k58kgm7     jk9ekpl0 dictator ResultsWaitPage
    ## 6         dhgisush     2wlrl5kb dictator           Offer
    ##                                                reason
    ## 1 Experiment not completed. Noticed at: all_apps_wide
    ## 2       Experiment not completed. Noticed at: chatapp
    ## 3      Experiment not completed. Noticed at: dictator
    ## 4         Experiment not completed. Noticed at: start
    ## 5        Experiment not completed. Noticed at: survey
    ## 6 Experiment not completed. Noticed at: all_apps_wide

Second, the function `show_dropouts()` also generates a smaller data frame `$unique` that only includes information on each person once.

    dropout_list$unique
    ##    participant.code session.code  end_app        end_page
    ## 1          1k58kgm7     jk9ekpl0 dictator ResultsWaitPage
    ## 6          dhgisush     2wlrl5kb dictator           Offer
    ## 11         j2g9mcaf     jk9ekpl0 dictator    Introduction
    ## 16         p6m495xi     2wlrl5kb dictator    Introduction
    ##                      reason
    ## 1  Experiment not completed
    ## 6  Experiment not completed
    ## 11 Experiment not completed
    ## 16 Experiment not completed

Third, the function `show_dropouts()` furthermore creates a table `$all_end`, which contains information on all participants and where they ended the experiment. The columns contain the names of the pages of the experiment; the rows contain the names of the apps.

    dropout_list$all_end
    ##
    ##            Demographics Introduction Offer ResultsWaitPage
    ##   dictator            0            2     1               1
    ##   survey              4            0     0               0

## delete_dropouts()

The function `delete_dropouts()` removes all data related to participants who prematurely terminated the experiment from the data frames in the oTree list, with the exception of data in the info list and the `$Chats` data frame. I highly recommend to manually delete the chat data, because it can occasionally become unintelligible once one person’s input is removed. Therefore, this function does not delete the chat input of the participants who dropped out of the experiment.

Before running the example, let us first check the row numbers of some data frames.

    # First, check some row numbers
    nrow(otree$all_apps_wide)
    ## [1] 8
    nrow(otree$survey)
    ## [1] 8
    nrow(otree$Time)
    ## [1] 77
    nrow(otree$Chats)
    ## [1] 6

When we run the function `delete_dropouts()` and check the row numbers again, we see that cases were deleted in each data frame but not in the `$Chats` data frame.

    # Delete all cases that didn't end the experiment on the page "Demographics"
    # within the app "survey"
    otree2 <- delete_dropouts(otree,
                             final_apps = "survey",
                             final_pages = "Demographics",
                             info = TRUE)
    ## 4 case(s) deleted
    ## Dropouts are deleted from all data frames. Except: The list of oTree data frames includes a chat. As the interpretation of chat data depends on how participants engage with each other, the data must be deleted with more care than deleting data in other apps. Hence, this function does not delete data in this data frame. Please do this manually if necessary!

    # Check row numbers again
    nrow(otree2$all_apps_wide)
    ## [1] 4
    nrow(otree2$survey)
    ## [1] 4
    nrow(otree2$Time)
    ## [1] 66
    nrow(otree2$Chats)
    ## [1] 6

Just as `show_dropouts()`, the `delete_dropouts()` function also gives detailed information on all the deleted cases.

    head(otree2$info$deleted_cases$full)
    ##   participant.code session.code  end_app        end_page
    ## 1         1k58kgm7     jk9ekpl0 dictator ResultsWaitPage
    ## 2         1k58kgm7     jk9ekpl0 dictator ResultsWaitPage
    ## 3         1k58kgm7     jk9ekpl0 dictator ResultsWaitPage
    ## 4         1k58kgm7     jk9ekpl0 dictator ResultsWaitPage
    ## 5         1k58kgm7     jk9ekpl0 dictator ResultsWaitPage
    ## 6         dhgisush     2wlrl5kb dictator           Offer
    ##                           reason
    ## 1        ENC. Noticed at: survey
    ## 2         ENC. Noticed at: start
    ## 3      ENC. Noticed at: dictator
    ## 4       ENC. Noticed at: chatapp
    ## 5 ENC. Noticed at: all_apps_wide
    ## 6        ENC. Noticed at: survey

    otree2$info$deleted_cases$unique
    ##    participant.code session.code  end_app        end_page reason
    ## 1          1k58kgm7     jk9ekpl0 dictator ResultsWaitPage    ENC
    ## 6          dhgisush     2wlrl5kb dictator           Offer    ENC
    ## 11         j2g9mcaf     jk9ekpl0 dictator    Introduction    ENC
    ## 16         p6m495xi     2wlrl5kb dictator    Introduction    ENC

    otree2$info$deleted_cases$all_end
    ##
    ##            Demographics Introduction Offer ResultsWaitPage
    ##   dictator            0            2     1               1
    ##   survey              4            0     0               0

Caution: This function does not delete any data from the original CSV and Excel files!

## delete_cases()

Sometimes, participants ask for their data to be deleted. The `delete_cases()` function can delete a person from each app’s data frame, `$all_apps_wide`, and the `$Time` data frame. Again, data in the `$Chats` data frame must be deleted by hand.

    # First, check some row numbers
    nrow(otree2$all_apps_wide)
    ## [1] 4
    nrow(otree2$survey)
    ## [1] 4
    nrow(otree2$Time)
    ## [1] 66
    nrow(otree2$Chats)
    ## [1] 6

    # Delete one participant
    person <- otree2$all_apps_wide$participant.code[1]
    otree2 <- delete_cases(otree2,
                           pcodes = person,
                           reason = "requested",
                           saved_vars = "participant._index_in_pages",
                           info = TRUE)
    ## 1 case(s) deleted. Cases are deleted from all data frames. Except: The list of oTree data frames includes a chat. As the interpretation of chat data depends on how participants engage with each other, the data must be deleted with more care than deleting data in other apps. Hence, this function does not delete data in this data frame. Please do this manually if necessary!

    # Check row numbers again
    nrow(otree2$all_apps_wide)
    ## [1] 3
    nrow(otree2$survey)
    ## [1] 3
    nrow(otree2$Time)
    ## [1] 48
    nrow(otree2$Chats)
    ## [1] 6

This function adds the information of all these deleted cases to the previously created information on all deleted cases.

    # Check for all deleted cases (also dropouts):
    tail(otree2$info$deleted_cases$full)
    ##    participant.code session.code  end_app     end_page
    ## 16         p6m495xi     2wlrl5kb dictator Introduction
    ## 17         p6m495xi     2wlrl5kb dictator Introduction
    ## 18         p6m495xi     2wlrl5kb dictator Introduction
    ## 19         p6m495xi     2wlrl5kb dictator Introduction
    ## 20         p6m495xi     2wlrl5kb dictator Introduction
    ## 21         sdh9ar2m         <NA>
    ##                            reason  session participant._index_in_pages
    ## 16        ENC. Noticed at: survey     <NA>                          NA
    ## 17         ENC. Noticed at: start     <NA>                          NA
    ## 18      ENC. Noticed at: dictator     <NA>                          NA
    ## 19       ENC. Noticed at: chatapp     <NA>                          NA
    ## 20 ENC. Noticed at: all_apps_wide     <NA>                          NA
    ## 21                      requested jk9ekpl0                          18

Caution: This function does not delete any data from the original CSV and Excel files!

## delete_sessions()

While we certainly hope that it never becomes necessary, there may be instances where an entire session needs to be removed from the data set due to unforeseen issues. However, if that occurs, we can use the function `delete_sessions()`. This function removes not only the sessions’ data in all apps, `$all_apps_wide`, and the `$Time` data frame but also the sessions’ chat data in the `$Chats` data frame because chatting is usually restricted within a session.

In the following, we see the row numbers before deletion, the application of the function, and the row numbers after deletion. Apart from the other functions, the sessions’ entries in the `$Chats` data frame are destroyed here since chat data occurs just once per session and may thus be eliminated without impacting the comprehensibility of the chat data.

    # First, check some row numbers
    nrow(otree2$all_apps_wide)
    ## [1] 3
    nrow(otree2$survey)
    ## [1] 3
    nrow(otree2$Time)
    ## [1] 48
    nrow(otree2$Chats)
    ## [1] 6

    # Delete one session
    otree2 <- delete_sessions(otree,
      scodes = "jk9ekpl0",
      reason = "Only tests",
      info = TRUE)
    ## 4 case(s) deleted

    # Check row numbers again
    nrow(otree2$all_apps_wide)
    ## [1] 4
    nrow(otree2$survey)
    ## [1] 4
    nrow(otree2$Time)
    ## [1] 38
    nrow(otree2$Chats)
    ## [1] 3

# Deleting sensitive information

## delete_pabels()

It is not uncommon for the participant.label variable to contain sensitive information like an MTurk worker ID. This can raise serious privacy concerns. The function `delete_plabels()` automatically removes the variable from all data frames. Additionally, the function has the option to delete all MTurk-related variables.

In the following, we see the application of the `delete_plabels()` function, preceded by information on the sensitive variables before running the function and followed by information on the sensitive variables after running the function.

    # Check variables
    head(otree2$all_apps_wide$participant.label)
    ## [1] ""        ""        "Person1" "Person2"
    head(otree2$all_apps_wide$participant.mturk_worker_id)
    ## [1] NA NA NA NA
    head(otree2$survey$participant.label)
    ## [1] ""        ""        "Person1" "Person2"

    # Delete all participant labels
    otree2 <- delete_plabels(otree2, del_mturk = TRUE)

    # Check variables
    head(otree2$all_apps_wide$participant.label)
    ## NULL
    head(otree2$all_apps_wide$participant.mturk_worker_id)
    ## NULL
    head(otree2$survey$participant.label)
    ## NULL

Caution: This function does not delete the variable from the original CSV and Excel files!

# Making IDs

## make_ids()

When working with oTree, participant codes, session codes, and group IDs are used to identify the cases. However, often, researchers prefer a streamlined, consecutive numbering system that spans all sessions, beginning with the first participant, session, or group and concluding with the last. The `make_ids()` function provides a way to achieve this goal. Before using the function, let us inspect the underlying variables first.

    # Check variables first
    otree2$all_apps_wide$participant.code
    ## [1] "dhgisush" "p6m495xi" "c9inx5wl" "kr8yd7f3"
    otree2$all_apps_wide$session.code
    ## [1] "2wlrl5kb" "2wlrl5kb" "mz2r27bk" "mz2r27bk"
    otree2$all_apps_wide$dictator.1.group.id_in_subsession
    ## [1] 1 1 1 1

    # Make session IDs only
    otree2 <- make_ids(otree2)

This function returns the following variables.

    # Check variables
    otree2$all_apps_wide$participant_id
    ## [1] 1 2 3 4
    otree2$all_apps_wide$session_id
    ## [1] 1 1 2 2

In the prior example, Group IDs were not calculated because group IDs must be called specifically. Since the group IDs per app in our data do not match (groups are only relevant in the dictator app), just using `group_id = TRUE` would lead to an error message.

For cases where the group IDs vary among apps, it can be specified in `make_ids()` which app or variable should be used for extracting group information. For instance, the following syntax can be used to obtain group IDs from the variable `dictator.1.group.id_in_subsession` in `$all_apps_wide`.

    # Get IDs from "from_variable" in the data frame "all_apps_wide"
    otree2 <- make_ids(otree2,
                       # gmake = TRUE,  # Not necessary if from_var is not NULL
                       from_var = "dictator.1.group.id_in_subsession")
    ## Warning in make_ids(otree2, from_var = "dictator.1.group.id_in_subsession"):
    ## The group variable values are constant. Group IDs now correspond to session
    ## IDs.

    # Check variables
    otree2$all_apps_wide$participant_id
    ## [1] 1 2 3 4
    otree2$all_apps_wide$group_id
    ## [1] 1 1 2 2
    otree2$all_apps_wide$session_id
    ## [1] 1 1 2 2

# Measuring the time

## apptime()

If we need to determine how much time the participants spent on a specific app, the `apptime()` function is a powerful tool that can help. This function calculates summary statistics such as the mean, minimum, and maximum time spent on each page, as well as a detailed list of durations for each participant in the app. The following example shows how much time the participants spent on the app “survey” in minutes.

    # Calculate the time all participants spent on app "survey"
    apptime(otree2, apps = "survey", digits = 3)
    ## $mean_duration
    ## [1] 0.242
    ##
    ## $min_duration
    ## [1] 0.233
    ##
    ## $max_duration
    ## [1] 0.25
    ##
    ## $single_durations
    ##   participant  session duration
    ## 1    c9inx5wl mz2r27bk    0.250
    ## 2    kr8yd7f3 mz2r27bk    0.233
    ##
    ## $warnings
    ## [1] "dhgisush" "p6m495xi"
    ##
    ## $messages
    ## [1] "For some participants, no duration could be calculated. See list in $warnings."

We can also get the time for specific participants only. Without specifying the applications, we get the duration for all applications individually.

    # Calculate the time one participant spent on app "dictator"
    apptime(otree2, pcode = "c9inx5wl", digits = 3)
    ## $chatapp
    ## [1] 0.267
    ##
    ## $dictator
    ## [1] 0.5
    ##
    ## $start
    ## [1] 0.017
    ##
    ## $survey
    ## [1] 0.25

## extime()

If we need to determine how much time participants spent on the complete experiment, we can use the `extime()` function. This function calculates summary statistics such as the mean, minimum, and maximum time spent on the experiment, as well as a detailed list of durations for each participant. (Note that these min, max, and mean values only have two digits because of the underlying data.)

    # Calculate the time that all participants spent on the experiment
    extime(otree2, digits = 3)
    ## $mean_duration
    ## [1] 0.525
    ##
    ## $min_duration
    ## [1] 0.05
    ##
    ## $max_duration
    ## [1] 1.033
    ##
    ## $single_durations
    ##   participant  session duration
    ## 2    p6m495xi 2wlrl5kb    0.050
    ## 1    dhgisush 2wlrl5kb    0.117
    ## 4    kr8yd7f3 mz2r27bk    0.900
    ## 3    c9inx5wl mz2r27bk    1.033

We can also get the duration for just one participant.

    # Calculate the time one participant spent on the experiment
    extime(otree2, pcode = "c9inx5wl", digits = 3)
    ## [1] 1.033

## pagesec()

The older versions of oTree included a variable called `seconds_on_page` in the `$Time` data frame. Although there is a good reason to omit it, we sometimes want to have more detailed information on the time spent on one page. Therefore, I created the function `pagesec()` that adds a new variable `seconds_on_page2` to the `$Time` data frame.

    # Create two new columns: seconds_on_page2 and minutes_on_page
    otree2 <- pagesec(otree2, rounded = TRUE, minutes = TRUE)
    tail(otree2$Time)
    ##    timeout_happened is_wait_page group_id session_id participant_id
    ## 72                0            0        2          2              3
    ## 73                0            0        2          2              4
    ## 74                0            0        2          2              4
    ## 75                0            0        2          2              3
    ## 76                0            0        2          2              4
    ## 77                0            0        2          2              3
    ##    session_code participant_id_in_session participant_code page_index app_name
    ## 72     mz2r27bk                         1         c9inx5wl         15   survey
    ## 73     mz2r27bk                         2         kr8yd7f3         15   survey
    ## 74     mz2r27bk                         2         kr8yd7f3         16   survey
    ## 75     mz2r27bk                         1         c9inx5wl         16   survey
    ## 76     mz2r27bk                         2         kr8yd7f3         17   survey
    ## 77     mz2r27bk                         1         c9inx5wl         17   survey
    ##                  page_name epoch_time_completed round_number minutes_on_page
    ## 72 CognitiveReflectionTest           1684258104            1            0.05
    ## 73 CognitiveReflectionTest           1684258108            1            0.13
    ## 74                   Offer           1684258109            1            0.02
    ## 75                   Offer           1684258110            1            0.10
    ## 76            Demographics           1684258114            1            0.08
    ## 77            Demographics           1684258116            1            0.10

# Transferring variables between the apps

## assignv()

The function `assignv()` copies a variable from the `$all_apps_wide` data frame to the data frames of all other apps. In the following example, the variable `survey.1.player.gender` is copied from `$all_apps_wide` to all other app data frames; in all of these data frames, the new variable is named `gender`. It also copies the variable to `$all_apps_wide` to keep some degree of consistency.

    # Assign variable "survey.1.player.gender" and name it "gender"
    otree2 <- assignv(oTree = otree2,
                     variable = "survey.1.player.gender",
                     newvar = "gender")
    # Control
    otree2$dictator$gender
    ##  [1] ""       ""       ""       ""       ""       ""       "Female" "Male"
    ##  [9] "Female" "Male"   "Female" "Male"
    otree2$chatapp$gender
    ## [1] ""       ""       "Female" "Male"
    # In app "survey", the variable is now twice because it is taken from here
    otree2$survey$gender
    ## [1] ""       ""       "Female" "Male"
    otree2$survey$player.gender
    ## [1] ""       ""       "Female" "Male"
    # In app "all_apps_wide," the variable is also there twice
    # (This can be avoided by calling the new variable the same
    # as the old variable)
    otree2$all_apps_wide$gender
    ## [1] ""       ""       "Female" "Male"
    otree2$all_apps_wide$survey.1.player.gender
    ## [1] ""       ""       "Female" "Male"

## assignv_to_aaw()

The function `assignv_to_aaw()` copies a variable from one of the data frames to the `$all_apps_wide` data frame. In the following example, a variable from the `$survey` data frame is copied to `$all_apps_wide` and placed directly after the variable `survey.1.player.age`.

    # Create a new variable
    otree2$survey$younger30 <- ifelse(otree2$survey$player.age < 30, 1, 0)

    # Get variable younger30 from survey to all_apps_wide
    # and put the new variable right behind the old age variable
    otree2 <- assignv_to_aaw(otree2,
                            app = "survey",
                            variable = "younger30",
                            newvar = "younger30",
                            resafter = "survey.1.player.age")

    # Control
    otree2$all_apps_wide$survey.1.player.age
    ## [1] NA NA 66 33

    # Check the position of the old age variable and the new variable
    match("survey.1.player.age", colnames(otree2$all_apps_wide))
    ## [1] 52
    match("younger30", colnames(otree2$all_apps_wide))
    ## [1] 53

# Before running the experiment

## show_constant()

When programming experiments, we often add variables that later prove unnecessary. If we forget to remove them, especially in multi-round experiments, the resulting data frames can become disproportionately large.

The `show_constant()` function helps identify unused variables, enabling their removal before running the experiment. To use this function, you should create a sample data frame from your oTree code, e.g., by using bots, that can then be checked for variables without variation.

In the following example, a variable named `constant` is created, which does not vary. The `show_constant()` function highlights this variable, along with several others that also lack variation. However, the other variables cannot be easily deleted from your oTree code as they are built-in variables automatically generated by oTree. Therefore, we can only delete the `constant` variable from our original oTree code.

    # Make a constant column (this variable is usually created in oTree)
    otree2$dictator$constant <- 3

    # Show all columns that contain columns containing only one specified value
    show_constant(oTree = otree2)
    ## $all_apps_wide
    ##  [1] "participant._is_bot"
    ##  [2] "participant._max_page_index"
    ##  [3] "participant.visited"
    ##  [4] "session.label"
    ##  [5] "session.comment"
    ##  [6] "session.config.real_world_currency_per_point"
    ##  [7] "session.config.name"
    ##  [8] "session.config.participation_fee"
    ##  [9] "start.1.player.role"
    ## [10] "start.1.player.payoff"
    ## [11] "start.1.group.id_in_subsession"
    ## [12] "start.1.subsession.round_number"
    ## [13] "dictator.1.player.role"
    ## [14] "dictator.1.group.id_in_subsession"
    ## [15] "dictator.1.subsession.round_number"
    ## [16] "dictator.2.player.role"
    ## [17] "dictator.2.group.id_in_subsession"
    ## [18] "dictator.2.subsession.round_number"
    ## [19] "dictator.3.player.role"
    ## [20] "dictator.3.group.id_in_subsession"
    ## [21] "dictator.3.subsession.round_number"
    ## [22] "chatapp.1.player.role"
    ## [23] "chatapp.1.player.payoff"
    ## [24] "chatapp.1.group.id_in_subsession"
    ## [25] "chatapp.1.subsession.round_number"
    ## [26] "survey.1.player.role"
    ## [27] "survey.1.player.payoff"
    ## [28] "survey.1.group.id_in_subsession"
    ## [29] "survey.1.subsession.round_number"
    ##
    ## $chatapp
    ## [1] "session.comment"             "participant._is_bot"
    ## [3] "participant._max_page_index" "participant.visited"
    ## [5] "player.role"                 "player.payoff"
    ## [7] "group.id_in_subsession"      "subsession.round_number"
    ## [9] "session.label"
    ##
    ## $dictator
    ## [1] "session.comment"             "participant._is_bot"
    ## [3] "participant._max_page_index" "participant.visited"
    ## [5] "player.role"                 "group.id_in_subsession"
    ## [7] "session.label"               "constant"
    ##
    ## $start
    ## [1] "session.comment"             "participant._is_bot"
    ## [3] "participant._max_page_index" "participant.visited"
    ## [5] "player.role"                 "player.payoff"
    ## [7] "group.id_in_subsession"      "subsession.round_number"
    ## [9] "session.label"
    ##
    ## $survey
    ## [1] "session.comment"             "participant._is_bot"
    ## [3] "participant._max_page_index" "participant.visited"
    ## [5] "player.role"                 "player.payoff"
    ## [7] "group.id_in_subsession"      "subsession.round_number"
    ## [9] "session.label"
    ##
    ## $Time
    ## character(0)
    ##
    ## $Chats
    ## [1] "group_id"     "session_id"   "session_code" "channel"

## codebook()

Thorough documentation of your experiment is essential. For detailed guidance on generating a codebook from your oTree code, refer to the vignette gmoTree Codebooks. I recommend creating this codebook before running the experiment, as it can help identify incomplete documentation or other potential issues within your code.

# References

Chen, D. L., Schonger, M., & Wickens, C. (2016). oTree—An open-source platform for laboratory, online, and field experiments. Journal of Behavioral and Experimental Finance, 9, 88–97. https://doi.org/10.1016/j.jbef.2015.12.001