add_booklet: Add response data to a project

View source: R/dexter.R

add_bookletR Documentation

Add response data to a project


Add item response data in long or wide format.


add_booklet(db, x, booklet_id, auto_add_unknown_rules = FALSE)

  design = NULL,
  missing_value = "NA",
  auto_add_unknown_rules = FALSE



a connection to a dexter database, i.e. the output of start_new_project or open_project


A data frame containing the responses and, optionally, person_properties. The data.frame should have one row per respondent and the column names should correspond to the item_id's in the rules or the names of the person_properties. See details.


A (short) string identifying the test form (booklet)


If FALSE (the default), an error will be generated if one or more responses do not appear in the scoring rules. If TRUE, unknown responses will be assumed to have a score of 0 and will be added to your scoring rules


response data in normalized (long) format. Must contain columns person_id, booklet_id, item_id and response and optionally item_position (useful if your data contains new booklets, see details)


data.frame with columns booklet_id, item_id and optionally item_position specifying the design of any _new_ booklets in your data.


value to use for responses in missing rows in your data, see details


It is a common practice to keep response data in tables where each row contains the responses from a single person. add_booklet is provided to input data in that form, one booklet at a time.

If the dataframe x contains a variable named person_id this variable will be used to identify unique persons. It is assumed that a single person will only make a single booklet once, otherwise an error will be generated.

If a person_id is not supplied, dexter will generate unique person_id's for each row of data.

Any column whose name has an exact match in the scoring rules inputted with function start_new_project will be treated as an item; any column whose name has an exact match in the person_properties will be treated as a person property. If a name matches both a person_property and an item_id, the item takes precedence. Columns other than items, person properties and person_id will be ignored.

add_response_data can be used to add data that is already normalized. This function takes a data.frame in long format with columns person_id, booklet_id, item_id and response such as can usually be found in databases for example. For booklets that are not already known in your project, you need to specify the design via the design argument. Failure to do so will result in an error. Responses to items that should be there according to the design but which do not have a correpsoning row in data will be added with missing_value used for the response. If this missing value is not defined in your scoring rules and and auto_add_unknown_rules is set to FALSE, this will lead to an error message.

Note that responses are always treated as strings (in both functions), and NA values are transformed to the string "NA".


A list with information about the recent import.


db = start_new_project(verbAggrRules, ":memory:", 
add_booklet(db, verbAggrData, "agg")      


dexter documentation built on May 25, 2022, 9:10 a.m.