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 all variables' information.

Usage

codebook(
  path = ".",
  fsource = "init",
  output = "both",
  output_dir = getwd(),
  output_file = "codebook",
  output_format = "pdf_document",
  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,
  preamb = FALSE,
  encoding = "UTF-8",
  title = "Codebook",
  subtitle = "created with gmoTree",
  params = NULL,
  date = "today"
)

Arguments

path

Character. Path of the oTree experiment.

fsource

Character. "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. "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. 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. 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. Format of the file output. This is the format that is passed to the output_format argument of rmarkdown::render. You must use either "pdf_document", "html_document", "word_document", "odt_document", "rtf_document", "md_document", or "latex_document".

output_open

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

app_doc

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

app

Character. Name of the included app(s). Default is to use all apps. This argument can not be used simultaneously as the argument app_rm.

app_rm

Character. Name of the excluded app(s). Default is to exclude no apps. This argument can not be used simultaneously as the argument app.

doc_info

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

sort

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

settings_replace

Character 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 in the codebook.

preamb

Logical. TRUE if a preamble should be printed that explains how oTree saves variables.

encoding

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

title

Character. Title of output file.

subtitle

Character. 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

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.

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 there are no dictionaries 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. 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.

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 4
#>  $ bertrand            :List of 4
#>  $ common_value_auction:List of 4
#>  $ cournot             :List of 4
#>  $ dictator            :List of 3
#>  $ guess_two_thirds    :List of 4
#>  $ matching_pennies    :List of 4
#>  $ payment_info        :List of 4
#>  $ prisoner            :List of 4
#>  $ public_goods_simple :List of 3
#>  $ survey              :List of 3
#>  $ traveler_dilemma    :List of 4
#>  $ trust               :List of 3
#>  $ trust_simple        :List of 3
#>  $ volunteer_dilemma   :List of 4
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 4
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 4
#>  $ common_value_auction:List of 4
#>  $ cournot             :List of 4
#>  $ dictator            :List of 3
#>  $ guess_two_thirds    :List of 4
#>  $ matching_pennies    :List of 4
#>  $ payment_info        :List of 4
#>  $ prisoner            :List of 4
#>  $ public_goods_simple :List of 3
#>  $ survey              :List of 3
#>  $ traveler_dilemma    :List of 4
#>  $ trust               :List of 3
#>  $ trust_simple        :List of 3
#>  $ volunteer_dilemma   :List of 4
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 = TRUE)
#> Variables without documentation, label, or verbose name:
#> > rankaversion$Player$choicenumber
#> > rankend$Player$done_distribution
#> 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. Check the output carefully! Found in:
#> > App rankaversion(Constants) (read_csv)
#> > App 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

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/pzauchner/Nextcloud/R_analyses/cb/cb.pdf"
getwd() # "C:/Users/pzauchner/Nextcloud/R_analyses"
dir.create("cb")
combined_codebook <- gmoTree::codebook(
  path = "C:/Users/pzauchner/Nextcloud/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/pzauchner/Nextcloud/R_analyses/oTree",
  fsource = "models",
  output = "both",
  output_file = "cb/cb",
  output_format = "pdf_document")
} # }