isZeroCodedCheckField: Identify Check Fields with a Zero Coded Option

In nutterb/redcapAPI: Interface to 'REDCap'

Identify Check Fields with a Zero Coded Option

Description

Check fields that have 0 as a coding option can confuse certain data processing steps because it can be difficult to differentiate if a 0 value represents an unchecked or checked option. Identifying these fields is important to handling them correctly.

Usage

isZeroCodedCheckField(field_name)

warnOfZeroCodedCheckCasting(field_name, x)

warnZeroCodedFieldPresent(field_names, warn_zero_coded)

Arguments

field_name	character(1) The name of a field to be tested.
x	atomic object.
field_names	character vector of field names.
warn_zero_coded	logical(1). Turn on or off warnings about zero coded fields. Defaults to TRUE.

Value

isZeroCodedCheckField returns a logical(1)

warnOfZeroCodedCheckCasting has no return and issues a warning if the field name appears to be zero-coded.

warnZeroCodedFieldPresent has no return and issues a warning if any of the fields passed appear to be zero-coded.

Zero-Coded Check Fields

A zero-coded check field is a field of the REDCap type checkbox that has a coding definition of ⁠0, [label]⁠. When exported, the field names for these fields is ⁠[field_name]___0⁠. As in other checkbox fields, the raw data output returns binary values where 0 represent an unchecked box and 1 represents a checked box. For zero-coded checkboxes, then, a value of 1 indicates that 0 was selected.

This coding rarely presents a problem when casting from raw values (as is done in exportRecordsTyped). However, casting from coded or labeled values can be problematic. In this case, it becomes indeterminate from context if the intent of 0 is 'false' or the coded value '0' ('true') ...

The situations in which casting may fail to produce the desired results are

Code	Label	Result
0	anything other than "0"	Likely to fail when casting from coded values
0	0	Likely to fail when casting from coded or labeled values

Because of the potential for miscast data, casting functions will issue a warning anytime a zero-coded check field is encountered. A separate warning is issued when a field is cast from coded or labeled values.

When casting from coded or labeled values, it is strongly recommended that the function castCheckForImport() be used. This function permits the user to state explicitly which values should be recognized as checked, avoiding the ambiguity resulting from the coding.

Examples

## Not run: 
isZeroCodedCheckField("check_field___x")

isZeroCodedCheckField("check_field___0")


x <- factor(c(1, 0, 1, 0, 0), 
            levels = 0:1)
warnOfZeroCodedCheckCasting(field_name = "check_field___0", 
                            x = x)
                       
 
warnZeroCodedFieldPresent(c("check_field___x", "check_field___0"), TRUE)

## End(Not run)

nutterb/redcapAPI documentation built on Feb. 11, 2024, 11:20 p.m.