codebook {gmoTree} | R Documentation |
Create a codebook for the oTree code
Description
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. |
output |
Character string. |
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 |
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_open |
Logical. |
app_doc |
Logical. |
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 |
Character string or character vector.
Name of the excluded app(s).
Default is to exclude no apps.
Cannot be used simultaneously with |
doc_info |
Logical. |
sort |
Character vector. Vector that specifies the order of the apps in the codebook. |
settings_replace |
Character string or |
user_settings |
List. List of variables in the |
include_cons |
Logical.
|
include_subs |
Logical.
|
preamb |
Deprecated. |
encoding |
Character string. Encoding of the created Markdown file.
As in knitr::knit, this argument is
always assumed to be |
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 |
date |
Character string or |
splitvarname |
Logical. |
sep_list |
Character string. Determines how sub-lists are displayed
in the file output. Use |
initial |
Logical. |
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.
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.
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)
str(combined_codebook$bargaining$Player, 1)
# 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)
str(combined_codebook$bargaining$Player, 1)
# 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)
str(combined_codebook$bargaining$Player, 1)
# 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)
# Show the structure of the codebook
str(combined_codebook, 1)
# 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)
## Not run:
# 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")
## End(Not run)