redcap-manual.Rmd

---
title: "REDCap Manual"
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  echo = TRUE,
  error = TRUE,
  comment = "")
```

# REDCap Data Management

## Updating instruments in REDCap {#updates}

1. Should you need to make any ***IMMEDIATE*** changes on RedCap, create those alterations and then notify Dr. Petersen to push changes. 

## Adding new RAs to REDCap/tasks {#addPersonnel}

1. Go to "User Rights" on the left side (under "Applications").
1. In the text box labeled "Assign new user", type the new lab member's HawkID and click "Assign to Role" (e.g., "RA", "Grad Student").
   - "RA Analyst" is for RAs conducting honors projects who need to do data analysis.
   - "Project Manager" is for the Lab Coordinator.
   - "Add Measures" is for selected RAs who are deemed ready by Dr. Petersen to make edits/additions to measures in REDCap
   - After assigning them to the correct role, go to "DAGs" on the left side (under "Applications").
1.  To add an RA to their specific task, go to Project Home → Project Setup → Online Designer → click on name of required task in the left column
1. Select "Edit" on the "Coder Name" field.
1. Under "Choices (one choice per line)", add the subsequent number followed by a comma and the RA's name.
1. Click "Save".

## Adding fields to an instrument {#addFields}

1. To edit an instrument, go to: Project Home → Project Setup → Online Designer → click on name of required task in the left column
1. Select the correct location where question needs to be added and select "Add Field"
1. Select field type—the most frequently we use are:
   - Text Box
   - Multiple Choice
   - Yes/No
   - True/False
   - **Note**: For Multiple Choice Questions and Checkboxes, enter one answer choice per line in the box labeled "Choices"
1. Add variable name:
   - Variable names must be unique
   - Variable names within the same instrument should have the same beginning (e.g. all variables within the school information instrument start with "school_")
1. Indicate whether question is required
1. Add data validation (if possible) to reduce the possibility of human error in data entry
1. Questions within the same instrument may belong to different sections.
To add a new section:
   - Click "Add Field"
   - As field type select "Begin New Section (with optional text)
   - As field label, name the new section
   - Save

## Branching Logic {#branchingLogic}

Branching logic is a method to link two questions with each other.
The answer of Question A will determine whether Question B will be displayed.
Typically question A is a checkbox or multiple-choice question.
Follow the below steps to use branching logic:

1. Create all questions to be linked
1. Click on the green arrow to begin using branching logic
   - Use the drag and drop builder to create questions to be linked
   - Use the code to link questions together
      - Example: When, `[other_instrument_name] = '1'`, show this question

## Field Embedding {#fieldEmbedding}

Filed embedding is an advanced branching logic method which allows Question B to be directly embedded in Question A, if the relevant answer choice is selected.

1. Use branching logic to link Question B to Question A, so Question B will only appear if the participant selects "other" for Question A
(in our example, variable name for Question A would be college, variable name for Question B: college_other)
1. Make sure that answer choice "Other" is coded as "9" (see figure 1)
1.	Return to Question A and add several spaces behind the answer choice you would like to embed.
1. Insert variable you would like to embed in curly brackets {var_name} (in our example this would be {college_other}; see figure 1)
1. Save
1. When testing the instrument, a textbox should now appear directly behind the answer choice, when selecting "Other" (see below example)

![RedcapExample1](images/redcapExample1.png)
![RedcapExample2](images/redcapExample2.png)

## Designating Instruments as a Survey {#survey}

If an instrument is intended to be completed by participants as a survey (as opposed to a data entry instrument for entry of data by lab members), the instrument will need to be designated as a survey.
To designate an instrument as a survey, go to Project Home → Project Setup → Online Designer → click on "Enable" under the "Enabled as Survey" column for the relevant instrument.

## Designating Instruments to Events {#designateInstruments}

Most instruments in longitudinal studies will need to be desigated across events.
Instruments should already be created and approved before designating to events.

To designate events, follow the below steps:

1. Go to "Designer" → "Project Setup"
1. Under the *"Define your events and designate instruments for them"* section, select `Designate Instrument for my events`
1. Select, `begin editing` and select checkboxes for each event to designate the instrument to
1. **Important:** Update the roles in `User Rights` to be able to view and edit the newly designated instrument

## Designating Instruments as Repeatable {#repeatableInstrument}

Some instruments will be designated as repeatable.
These events will first need to be designated across events (See section on [designating events](#designateInstruments)).
Tasks that require multiple people to create the same form will often need to be repeatable.
For example, coding tasks that require multiple people to check across forms for reliability.

To designate forms as repeatable, follow the below steps:

1. Under *"Enable optional modules and customizations"*, select `Repeatable instruments and events`
1. Select instruments to be designated repeatable

# Creating Instruments in REDCap {#createInstrument}

## Steps to Add a New Instrument {#newInstrumentSteps}

1. Project Home → Project Setup → Online Designer
1. In grey box (Data Collection Instruments), click on "+ Create" to create a new instrument from scratch

However, an instrument will not show up for entry until:

1. The addition of the measure has been approved by Dr. Petersen.
1. The instrument has been [designated to an event](#designateInstruments).
1. (As necessary, the instrument has been [designated as a survey](#survey).)
1. (As necessary, the instrument has been [designated as repeatable](#repeatableInstrument)).
1. User rights are updated to allow users to view the instrument (i.e., "Read Only" or "View and Edit")

## Good Practices {#goodPractices}

-	Include relevant instructions where applicable
-	Omit "introductory" variables (e.g., date of birth) that are collected from other measures
-	Field Labels are the same across instruments where applicable
-	Choices are the same across instruments where applicable 
    - Include numbers (if relevant) in parentheses in row below column choices
-	Choices follow correct format: Number, Choice
    - (e.g., 1, female)
-	For yes/no questions, use the "Yes - No" question type (rather than multiple choice radio buttons)
    1. No = 0	
    1. Yes = 1
- For yes/no questions with additional options (e.g., "not applicable"), use multiple choice radio buttons where:
    1. No = 0	
    1. Yes = 1
    1. Other = 9
    1. Not applicable = -999

- Time questions
   - Specific time (e.g., What is the child's bedtime?):
      - **Begin question with instructions:** Below you will enter your child's bedtime. 
      Please specify in 12-hour time (AM/PM). 
      For example, if your child's bedtime is 10:30 PM, please enter 10 hours and 30 minutes like the example below. (show example image below)
      - Have three variables for every time question:	
         - AM/PM (Radio Button)
         - hours (text box), italicized
             - Validation: integer from 1–12
         - minutes (text box), italicized
             - Validation: integer from 0–59
      - Specify 12-hour time in the question
         - **Example**: What is the child's bedtime?
         Please specify in 12-hour time (AM/PM).
   - Duration: (e.g., How long does the child nap each day?)
      - Below you will enter how long your child naps each day.
      Please specify in hours and minutes. 
      For example, if your child naps 2 hours and 30 minutes each day, please enter 2 hours and 30 minutes like the example below (show example image below).
      - Have two variables for every time question:
         - hours (text box), italicized.
            - Validation: integer (minimum 0; maximum—case specific)
         - minutes (text box), italicized
            - Validation: integer (minimum 0; maximum 59)

## Creating Variables  {#creatingVariables}

- Variable names follow the lab conventions (measure_item): use abbreviated measure name, all lowercase, less than 26 characters
- **Validation is used wherever possible**
- For variables with identifying information (e.g., name, address), select the checkbox labeled "Identifier"
- Branching logic is used to give questions only to relevant participants
- A "Matrix of Fields" is used to group together items with common response options
- For "Matrix of Fields," only select "Ranking" if you want the participant to select only one response per column
-	Where helpful, "Sections" are used to break up the questions
-	Radio buttons are used rather than drop-down lists
-	For crucial variables, "Required" is selected
-	If necessary, piping is used
- Add the following verbatim to the end of every questionnaire (in italics): "Please be sure you answered all items."
   - Name the variable: measure_allitems (where "measure" is the abbreviated measure name)

## Adding Smart Variables to Questionnaires {#smartVariables}

In every surey, we want to add the following "Smart Variables". These variables automatically calculate the survey start time, survey start date, and duration survey was completed.
Variable names should follow the appropriate naming convention that is used for each survey.
After you have added variables, slack the Lab Coordinator for review.
**Do not add variables to more than three surveys at a time.**
These variables should be entered at the end of each survey. For each survey, follow the instructions below to add the required smart variables: 

### Timestamps {#timestamps}

1. "Date/Timestamp in the rater's timezone"
   - Add a "Text Box" field with validation "Datetime w/seconds (Y-M-D H:M:S)
   - Use variable name: `prefix_ratertimezone`
   - Add the following action tags: 
      - @HIDDEN-SURVEY
      - @NOW
      - @READONLY
1. "Date/Timestamp (REDCap server)"
   - Add a "Text Box" field with validation "Datetime w/seconds (Y-M-D H:M:S)
   - Use variable name: `prefix_servertimezone`
   - Add the following Action tags: 
      - @HIDDEN-SURVEY
      - @NOW-SERVER
      - @READONLY
1. "Date/Timestamp (UTC)"
   - Add a "Text Box" field with validation "Datetime w/seconds (Y-M-D H:M:S)
   - Use variable name: `prefix_centraltimezone`
   - Add the following Action tags: 
      - @HIDDEN-SURVEY
      - @NOW-UTC
      - @READONLY

### Date Completed, Time Completed and Survey Durations {#dateTimestampDuration}

In the below section, it is necessary to identify the `instrument_name` for each variable added.
In REDCap, open the `Designer` tab and navigate to the survey to be edited.
In the URL on the webpage, identify the instrument name for the given survey.
For example, the below URL corresponds to the *parenting_partner* instrument. 

- https://redcap.icts.uiowa.edu/redcap/redcap_v12.5.2/Design/online_designer.php?pid=5347&page=<mark>parenting_partner</mark>

1. "Survey Time Started:"
   - Add a "Text Box" field with no validation
   - Use variable name: `prefix_timestarted`
   - Add the following Action Tags 
      - @HIDDEN-SURVEY 
      - @READONLY 
      - @CALCTEXT([survey-time-started:instrument_name])
1. "Survey Date Started:"
   - Add a "Text Box" field with no validation
   - Use variable name: `prefix_datestarted`
   - Add the following Action Tags 
      - @HIDDEN-SURVEY 
      - @READONLY 
      - @CALCTEXT([survey-date-started:instrument_name])
1. "Survey Time Completed:"
   - Add a "Text Box" field with no validation
   - Use variable name: `prefix_timecompleted`
   - Add the following Action Tags 
      - @HIDDEN-SURVEY 
      - @READONLY 
      - @CALCTEXT([survey-time-completed:instrument_name])
1. "Survey Date Completed:"
   - Add a "Text Box" field with no validation
   - Use variable name: `prefix_datecompleted`
   - Add the following Action Tags 
      - @HIDDEN-SURVEY 
      - @READONLY 
      - @CALCTEXT([survey-date-completed:instrument_name])
1. "Survey Duration:"
   - Add a "Text Box" field with numeric validation
   - Use variable name: `prefix_surveyduration`
   - Add the following Action Tags
      - @HIDDEN-SURVEY
      - @READONLY
      - @CALCTEXT([survey-duration:instrument_name:m])
1. "Survey Duration Completed:"
   - Add a "Text Box" field with numeric validation
   - Use variable name: `prefix_surveydurationcompleted`
   - Add the following Action Tags
      - @HIDDEN-SURVEY
      - @READONLY
      - @CALCTEXT([survey-duration-completed:instrument_name:m])
1. Slack the Lab Coordinator for review

## Troubleshooting {#troubleshooting}

- When a field that will be hidden by branching logic has a value, REDCap offers to delete the value: "ERASE CURRENT VALUE OF THE FIELD?"
   - http://cri.uchicago.edu/wp-content/uploads/2016/04/REDCap-Avoid-Common-Pitfalls.pdf (archived at https://perma.cc/6NBY-3Y5R)
   - If you do not want the field hidden once it contains data, add the following as an "OR" condition on the existing branching      
      - logic: [field_name] <> ""
   - Note: The @DEFAULT action tag **cannot** be used for fields that are hidden by branching logic
- Sometimes REDCap may record incorrect values or may fail to record values at all.
You can check for this by:
1. Navigating to a project, then in the side bar clicking "Data Quality" under "Applications"
1. Under Rule #H "Incorrect values for calculated fields", click "Execute"
1. You will see a table with any incorrect calculated values (including missing values). Check the table to make sure the discrepant fields are what you expect. Also check to make sure there are no rows that suggest overwriting legitimate values. If a row looks like it is actually correct, click "exclude".
1. Click "Fix calcs now" to record the correct values in the data.

## How To {#howTo}

- Em dash (—):
   - `&mdash;`
- Line Break
   - `<br>`
- Italic font:
   - `<i>This is some text!</i>`
   - **Example**: <i>This is some text!</i>
- Change font size:
   - `<font size="6">This is some text!</font>`
   - **Example**: <font size="6">This is some text!</font>
- Change font color:
   - `<font color="red">This color will be red.</font>`
   - **Example**: <font color="red">This color will be red.</font>

## Lab Universal Notations {#labUniversalNotations}

- Yes = 1, No = 0
- True = 1, False = 0
- Sex: Male = 0, Female = 1
- Not Applicable = -999
- Coding Options
   - Correct = 2 (or 1, if there is no option for "initially incorrect, changed to correct")
   - Incorrect = 0
   - Initially incorrect, changed to correct = 1
   - No response = -9
   - Uncodeable = 9

For Likert scales:

- If there are numbers listed for the Likert scale options, use those numbers as the values
- If there are not numbers listed, check with Dr. Petersen for what numbers to use as the values
- In general, values start with number 1 (not 0—unless the value actually reflects complete absence of something)
- If there is an "Other" option, code it as "9", if possible
- If there is a "N/A" option, code it as "-999"

## Editing the Data Dictionary {#dataDictionary}

- If editing the data dictionary, do not use Excel!—Excel truncates values in cells
   - Instead, use LibreOffice with UTF-8 encoding