Skip to contents

Create a codebook for the oTree code

Source: R/codebook.R
codebook.Rd

Create a codebook of your oTree code by automatically scanning your project folder and retrieving the information of the apps' Constants, Subsession, Group and Player variables.

Usage

codebook(
  path = ".",
  fsource = "init",
  output = "both",
  output_dir = NULL,
  output_file = "codebook",
  output_format = "pdf_document_simple",
  output_open = TRUE,
  app_doc = TRUE,
  app = NULL,
  app_rm = NULL,
  doc_info = TRUE,
  sort = NULL,
  settings_replace = "global",
  user_settings = NULL,
  include_cons = TRUE,
  include_subs = FALSE,
  preamb = FALSE,
  encoding = "UTF-8",
  title = "Codebook",
  subtitle = "created with gmoTree",
  params = NULL,
  date = "today",
  splitvarname = FALSE,
  sep_list = "newline",
  initial = TRUE
)

Arguments

path

Character string. Path of the oTree experiment.

fsource

Character string. "init" if information should be taken from the init.py files (newer oTree code with 5.x format). "models" (or "model") if the information should be taken from the models.py files (older oTree code with 3.x format).

output

Character string. "list" if the output should contain a list of variables and their information. "file" if the output should be a file such as a Word or PDF file. "both" if the output should contain a file and a list.

output_dir

Character string. The absolute path where the function's output will be saved. Only absolute paths are allowed for this parameter. Relative paths can be specified in the output_file parameter.

output_file

Character string. The name of the output file generated by the function. The file name can be provided with or without an extension. Relative paths are also allowed in the file name.

output_format

Character string. Specifies the format of the file output. This value is passed to the output_format argument of rmarkdown::render. Allowed options are: "html_document", "word_document", "odt_document", "rtf_document", "md_document", "latex_document", "pdf_document", "pdf_document_simple", or their short forms "html", "word", "odt", "rtf", "md", "latex", "pdf", "pdf_simple". Important: The "pdf_document" format uses xelatex for PDF generation. If your document does not require advanced LaTeX features, it is recommended to use "pdf_document_simple".

output_open

Logical. TRUE if file output should be opened after creation.

app_doc

Logical. TRUE if app documentation should be included in the output file.

app

Character string or character vector. Name of the included app(s). Default is to use all apps. Cannot be used simultaneously with app_rm.

app_rm

Character string or character vector. Name of the excluded app(s). Default is to exclude no apps. Cannot be used simultaneously with app.

doc_info

Logical. TRUE if a message with information on all variables without documentation should also be returned. FALSE if this message should be suppressed.

sort

Character vector. Vector that specifies the order of the apps in the codebook.

settings_replace

Character string or NULL. Specifies how to handle references to settings variables. Use "global" to replace references with the global settings variables defined in settings.py. Use "user" to replace references with the variables provided in the user_settings argument. Use NULL to leave references to settings variables unchanged. Caution: This function does not use variables defined in SESSION_CONFIGS. If you vary settings variables in SESSION_CONFIGS, set settings_replace to "user" and manually replace them using the user_settings argument.

user_settings

List. List of variables in the settings.py file that are used to replace setting variable references. This is only used if settings_replace = "user" and should be used when setting variables are defined within the SESSION_CONFIGS.

include_cons

Logical. TRUE if there should be a section for the Constants variables in the codebook.

include_subs

Logical. TRUE if there should be a section for the Subsession variables in the codebook.

preamb

Deprecated. preamb = TRUE is no longer supported. Please remove preambles from your old codebooks.

encoding

Character string. Encoding of the created Markdown file. As in knitr::knit, this argument is always assumed to be UTF-8 and ignored.

title

Character string. Title of output file.

subtitle

Character string. Subtitle of output file.

params

List. List of variable name and value pairs to be passed to the RmD file. Only relevant if argument output "file" or "both" if chosen.

date

Character string or NULL. Date that is passed to the Rmd file. Either "today", NULL, or a user defined date. Only relevant if argument output "file" or "both" if chosen.

splitvarname

Logical. TRUE if long variable names should be split across multiple lines in the output file tables. If FALSE, table columns should adjust to fit the longest variable names.

sep_list

Character string. Determines how sub-lists are displayed in the file output. Use "newline" to separate sub-lists with newline characters (\\n), or "vector" to display them as strings in c(...) format.

initial

Logical. TRUE if initial values should be included in the output file. FALSE if they should not be included.

Value

The function returns two main types of outputs:

(a) a list of variables along with their information

(b) a file containing the codebook for the experiment

If doc_info is TRUE it also returns a message containing the names of all variables that have no documentation.

Details

This code works only when dictionaries are not used (for example, in the session configurations in settings.py).

Caution 1: Multiline comments are ignored, meaning that all variables commented out in this manner will nevertheless be included in the codebook. In contrast, variables commented out with line comments will not appear in the codebook.

Caution 2: If there are commas in the value strings, they might be used to split the text. Please manually insert a backslash symbol in front of the commas to avoid that (i.e., escape them). E.g. "Yes, I will" -> "Yes\, I will".

Caution 3: This code cannot interpret variables that were imported from other files (for example CSV files) and that have special formatting included (e.g., special string formatting in Python such as float(1.4) to represent a float number).

Caution 4: This code was developed and tested with basic oTree codes and has not been verified for compatibility with oTree versions later than 5.4.0. If you experience issues with newer versions or more complex code structures, please open an issue on GitHub.

Caution 5: Custom exports and variables from the Participant Session classes are not part of the codebook. Also built-in variables are not presented in the codebook.

Further info: None values are presented as "None" (i.e. as a string) in the list and the file output.

Examples

# The examples use a slightly modified version of the official oTree
# sample codes.

# Make a codebook and resort the apps
combined_codebook <- codebook(
  path = system.file("extdata/ocode_new", package = "gmoTree"),
  output = "list",
  fsource = "init",
  doc_info = FALSE)

# Show the structure of the codebook
str(combined_codebook, 1)
#> List of 16
#>  $ settings            :List of 10
#>  $ bargaining          :List of 5
#>  $ bertrand            :List of 5
#>  $ common_value_auction:List of 5
#>  $ cournot             :List of 5
#>  $ dictator            :List of 5
#>  $ guess_two_thirds    :List of 5
#>  $ matching_pennies    :List of 5
#>  $ payment_info        :List of 5
#>  $ prisoner            :List of 5
#>  $ public_goods_simple :List of 4
#>  $ survey              :List of 4
#>  $ traveler_dilemma    :List of 5
#>  $ trust               :List of 4
#>  $ trust_simple        :List of 4
#>  $ volunteer_dilemma   :List of 5
str(combined_codebook$bargaining$Player, 1)
#> List of 4
#>  $ request:List of 6
#>  $ level2 :List of 3
#>  $ level3 :List of 3
#>  $ level  :List of 3

# Make a codebook with only the "bargaining" app
combined_codebook <- codebook(
  path = system.file("extdata/ocode_new", package = "gmoTree"),
  output = "list",
  fsource = "init",
  app = "bargaining",
  doc_info = FALSE)

# Show the structure of the codebook
str(combined_codebook, 1)
#> List of 2
#>  $ settings  :List of 10
#>  $ bargaining:List of 5
str(combined_codebook$bargaining$Player, 1)
#> List of 4
#>  $ request:List of 6
#>  $ level2 :List of 3
#>  $ level3 :List of 3
#>  $ level  :List of 3

# Make a codebook with all but the "bargaining" app
combined_codebook <- codebook(
  path = system.file("extdata/ocode_new", package = "gmoTree"),
  output = "list",
  fsource = "init",
  app_rm = "bargaining",
  doc_info = FALSE)

# Show the structure of the codebook
str(combined_codebook, 1)
#> List of 15
#>  $ settings            :List of 10
#>  $ bertrand            :List of 5
#>  $ common_value_auction:List of 5
#>  $ cournot             :List of 5
#>  $ dictator            :List of 5
#>  $ guess_two_thirds    :List of 5
#>  $ matching_pennies    :List of 5
#>  $ payment_info        :List of 5
#>  $ prisoner            :List of 5
#>  $ public_goods_simple :List of 4
#>  $ survey              :List of 4
#>  $ traveler_dilemma    :List of 5
#>  $ trust               :List of 4
#>  $ trust_simple        :List of 4
#>  $ volunteer_dilemma   :List of 5
str(combined_codebook$bargaining$Player, 1)
#>  NULL

# Use oTree code in 3.x format
combined_codebook <- codebook(
  path = system.file("extdata/ocode_z", package = "gmoTree"),
  fsource = "model",
  output = "list",
  doc_info = FALSE)
#> Warning: Some variables or code parts contain code that is too complex for this function. Hence, this function might have overseen important variables and references to them. Found in:
#> > $rankaversion$Constants (read_csv)
#> > $rankend$Constants (read_csv)
#> > $settings$showupToken (float)
#> > $end$Constants$showupToken (float)
#> > $end$Constants$showupTokenTest (float)

# Show the structure of the codebook
str(combined_codebook, 1)
#> List of 4
#>  $ settings    :List of 20
#>  $ end         :List of 4
#>  $ rankaversion:List of 4
#>  $ rankend     :List of 4

# Show information on missing documentation or complex code
combined_codebook <- codebook(
  path = system.file("extdata/ocode_new", package = "gmoTree"),
  fsource = "init",
  output = "list",
  app_rm = "bargaining",
  doc_info = TRUE)
#> Variables without documentation, label, or verbose name:
#> > $bertrand$Group$winning_price
#> > $bertrand$Player$is_winner
#> > $common_value_auction$Group$highest_bid
#> > $cournot$Group$unit_price
#> > $dictator$Player$gender
#> > $guess_two_thirds$Group$two_thirds_avg
#> > $guess_two_thirds$Group$best_guess
#> > $guess_two_thirds$Group$num_winners
#> > $guess_two_thirds$Player$is_winner
#> > $matching_pennies$Player$is_winner
#> > $public_goods_simple$Group$total_contribution
#> > $public_goods_simple$Group$individual_share
#> > $traveler_dilemma$Group$lower_claim
#> > $traveler_dilemma$Player$adjustment
#> > $volunteer_dilemma$Group$num_volunteers

if (FALSE) { # \dontrun{

# Create a codebook PDF with authors' names and todays' date
codebook(
  path = system.file("extdata/ocode_z", package = "gmoTree"),
  fsource = "init",
  doc_info = FALSE,
  output = "file",
  output_format = "pdf_document",
  date = "today",
  title = "My Codebook",
  subtitle = "codebook created with gmoTree",
  params = list(author = c("Max Mustermann", "John Doe"))
  )

# Create a codebook PDF and save it in a subfolder of the
# current folder:
# "C:/Users/username/folder/R_analyses/cb/cb.pdf"
getwd() # "C:/Users/username/folder/R_analyses"
dir.create("cb")
combined_codebook <- gmoTree::codebook(
  path = "C:/Users/username/folder/R_analyses/oTree",
  fsource = "models",
  output = "both",
  output_file = "cb/cb.pdf",
  output_format = "pdf_document")

# You can also omit *.pdf after the file name
combined_codebook <- gmoTree::codebook(
  path = "C:/Users/username/folder/R_analyses/oTree",
  fsource = "models",
  output = "both",
  output_file = "cb/cb",
  output_format = "pdf_document")
} # }