Add item response data in long or wide format.

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

add_response_data(
  db,
  data,
  design = NULL,
  missing_value = "NA",
  auto_add_unknown_rules = FALSE
)

Arguments

db

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

x

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.

booklet_id

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

auto_add_unknown_rules

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

data

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)

design

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

missing_value

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

Value

A list with information about the recent import.

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 corresponding 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 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".

Examples

db = start_new_project(verbAggrRules, ":memory:", 
                       person_properties=list(gender="unknown"))
head(verbAggrData)
#>   gender anger S1DoCurse S1DoScold S1DoShout S1WantCurse S1WantScold
#> 1   Male    20         1         0         1           0           0
#> 2 Female    16         1         2         1           2           2
#> 3 Female    18         0         0         0           1           0
#> 4 Female    27         2         0         0           2           2
#> 5 Female    21         0         0         0           0           1
#> 6 Female    21         2         2         0           0           2
#>   S1WantShout S2DoCurse S2DoScold S2DoShout S2WantCurse S2WantScold S2WantShout
#> 1           0         1         0         0           0           0           0
#> 2           2         2         2         1           2           2           1
#> 3           0         0         0         0           1           0           0
#> 4           0         1         1         0           1           1           0
#> 5           0         0         0         0           0           1           0
#> 6           0         2         2         0           0           2           0
#>   S3DoCurse S3DoScold S3DoShout S3WantCurse S3WantScold S3WantShout S4DoCurse
#> 1         1         0         0           0           0           1         2
#> 2         0         0         0           1           0           1         1
#> 3         0         0         0           0           0           0         1
#> 4         1         0         0           2           0           0         1
#> 5         0         0         0           0           1           0         2
#> 6         1         1         0           2           1           0         2
#>   S4DoScold S4DoShout S4WantCurse S4WantScold S4WantShout
#> 1         2         2           2           0           0
#> 2         1         1           1           1           1
#> 3         0         0           1           0           0
#> 4         1         0           2           2           0
#> 5         0         0           2           0           0
#> 6         2         0           2           2           0
add_booklet(db, verbAggrData, "agg")      
#> no column `person_id` provided, automatically generating unique person id's
#> $items
#>  [1] "S1DoCurse"   "S1DoScold"   "S1DoShout"   "S1WantCurse" "S1WantScold"
#>  [6] "S1WantShout" "S2DoCurse"   "S2DoScold"   "S2DoShout"   "S2WantCurse"
#> [11] "S2WantScold" "S2WantShout" "S3DoCurse"   "S3DoScold"   "S3DoShout"  
#> [16] "S3WantCurse" "S3WantScold" "S3WantShout" "S4DoCurse"   "S4DoScold"  
#> [21] "S4DoShout"   "S4WantCurse" "S4WantScold" "S4WantShout"
#> 
#> $person_properties
#> [1] "gender"
#> 
#> $columns_ignored
#> [1] "anger"
#> 

close_project(db)