REDCap Logic Hub

Branching Logic, Calculations, Syntax, Testing, and Troubleshooting:
A Clear Guide to How Logic Works Across Your REDCap Project

 

Logic is one of the most powerful features in REDCap. It controls when fields appear, how values are calculated, how reports are filtered, when notifications are triggered, and how workflows behave across classic, longitudinal, and repeating projects. This page provides a centralized guide to the core logic concepts used throughout REDCap.

This guide is designed to help you make sense of branching logic, calculated fields, and the core logic patterns used throughout REDCap. Whether you are building a new project or troubleshooting an existing one, this page provides a practical framework for understanding how logic works and how to use it effectively.

Core Principle: In REDCap, logic always evaluates to true or false. The key is to build logic that is clear, testable, and appropriate for the field type and project structure.
Important: The same general logic language is used across many REDCap features, but the behavior may differ depending on where the logic is used. Branching logic, calculated fields, ASIs, Alerts, Survey Queue, reports, and dashboards all use related syntax, but not always in exactly the same way.

Where Logic Is Used in REDCap

Logic is used across multiple parts of REDCap, not just branching logic and calculations. It can be used in:

  • Branching logic
  • Calculated fields
  • Automated Survey Invitations
  • Alerts & Notifications
  • Survey Queue
  • Data Quality rules
  • Report filters
  • Project dashboards
Simple rule: Before writing logic, make sure you know where the logic will be used, because that affects how the logic behaves and what features are compatible.

Logic Building Blocks

Most REDCap logic uses the same core syntax elements:

  • Variables: [variable_name]
  • Operators: =, <>, >, <, >=, <=
  • Boolean logic: and, or
  • Parentheses: used to group statements

Strings vs Numbers

Use quotes when comparing strings or coded values that should be treated as strings. Leave quotes off for true numeric comparisons.

[gender] = '1'
[weight] > 100
[last_name] <> ""
Important: Use the "" pattern with no spaces when checking for blank or null values. A space inside the quotes changes the meaning.

Combining Statements

Use parentheses to control grouping and make complex logic easier to read.

([variable1] = '1' or [variable2] = '1') and [variable3] = '2'

Branching Logic

Branching logic hides or shows a field based on conditions. In REDCap, the logic is placed on the destination field — the field you want to show or hide — not on the source field.

What Branching Logic Can Do

  • Show a field only if a prior answer meets certain criteria
  • Hide irrelevant questions
  • Create cleaner, more dynamic instruments

What It Cannot Do

  • It cannot skip or hide an entire instrument
  • It cannot be applied at the section level
  • It must be applied field by field
Important: Section headers are hidden only when all fields in that section are hidden. Entire instruments remain visible even if every field on the form is hidden by branching logic.

Checkbox Logic

Checkbox fields use different syntax because each answer choice behaves like its own yes/no field.

[race(2)] = '1'   checked
[race(4)] = '0'   unchecked
Design Tip: For more complex branching logic, it can help to build the basic statement with the drag-and-drop builder and then refine it manually using advanced syntax.

Calculated Fields

Calculated fields perform real-time numeric calculations on forms and surveys. They use variable names in brackets and mathematical functions similar to Excel.

Core Rules

  • Calculated fields can return numbers only
  • They cannot directly return text or dates
  • Use mathematical order of operations carefully
[bpi_q1] + [bpi_q2]
sum([q1],[q2],[q3],[q4])
if([weight] > 100, 44, 11)

Use sum() vs + Carefully

  • sum() ignores blank values
  • + requires all fields to have values
Important: Which one to use depends on how the instrument should be scored. A missing value may need to be ignored or may need to invalidate the total.

Checkbox Calculations

Checkbox calculations are more complex because each answer choice is scored as checked or unchecked rather than by its visible choice code.

if([exercise(1)] = 1, 1, 0)
Important: If possible, avoid using complex calculations on checkbox fields unless the scoring structure is very clear.

Special Functions

REDCap supports many functions in calculated fields, including:

  • round(), roundup(), rounddown()
  • sqrt(), abs()
  • min(), max(), mean(), median(), sum(), stdev()

Working with Dates and Time

Dates are commonly used in both branching logic and calculations. The most common function is datediff().

datediff([dob],[visit_date],"y","mdy")
datediff("today",[screen_date],"M")

Common Units

  • "y" years
  • "M" months
  • "d" days
  • "h" hours
  • "m" minutes
  • "s" seconds
Important: Both dates must match the format you specify in the function. Test carefully whenever dates are part of logic or calculations.
Important: While "today" can be used, it should be used carefully in calculated fields because the result changes whenever the form is re-opened and saved. A fixed project date field is often safer.

Longitudinal, Repeating, and Smart Variables

Longitudinal Event References

In longitudinal projects, fields from other events must include the unique event name.

[baseline_arm_1][weight]

Repeating Instruments

You can reference a specific repeating instance by appending the instance number to the variable.

[variable1][4]

Smart Variables

Smart Variables make logic more flexible by referencing contextual concepts such as first event, previous event, or first instance.

[first-event-name][variable]
[variable][first-instance]
Design Tip: Event names and smart variables are powerful, but they add complexity quickly. Use them intentionally and test them thoroughly.

Logic and Action Tags

Logic can interact with action tags, but action tags do not always behave like branching logic or calculations.

Important Interactions

  • @HIDDEN overrides branching logic and hides the field regardless of logic result
  • @DEFAULT works only if the field is shown when the form first loads
  • @IF allows conditional action-tag behavior
  • @CALCDATE and @CALCTEXT allow text/date outputs that standard calculated fields cannot return
Important: Action tags generally work when the form first loads and may not update in real time as data are entered.

Testing and Troubleshooting

Logic should always be tested with real test records, not just by previewing a form.

  • Preview mode does not fully test branching logic or calculations
  • Use realistic test records and enter data directly
  • Use reports or Data Quality rules to validate complex logic
  • Diagram complicated logic flows before building them
Best Practice: For complex logic, draw out the logic in a flow chart before building it. This makes troubleshooting much easier.

Common Troubleshooting Points

  • Wrong variable name or wrong event reference
  • Using a checkbox field as if it were a radio field
  • Blank value behavior not handled properly
  • Calculated field hidden by branching logic but still returning data
Important: If a calculated field is hidden by branching logic but still evaluates to a value, REDCap may show an error or warning. The fix is often to build the branching condition into the calculation itself using an if() statement that returns "" when hidden.

Updating Calculation Values

When a calculated field is added or changed, the new calculation may appear on screen, but the values are not automatically saved to the server. This is why updated values may not appear in reports or exports right away.

How to Update Saved Values

  • Go to Data Quality
  • Run Rule H
  • Review the listed fields and values
  • Use Fix calcs now if appropriate
Important: Rule H updates all listed calculation values unless you explicitly exclude specific items first. Review carefully before fixing values in bulk.
Best Practice: Run Rule H soon after adding or changing calculated fields so the list stays short and easier to review.

Key Best Practices

  • Use clear variable names and consistent coding
  • Keep logic as simple as possible
  • Use parentheses intentionally in multi-part statements
  • Know whether your field is a regular multiple-choice field or a checkbox field
  • Test with realistic records and actual saved data
  • Use event references and smart variables carefully in longitudinal or repeating projects
  • Do not overuse calculated fields, especially on large forms
  • Run Rule H after adding or changing calculations
Final Takeaway: Good logic should be readable, predictable, and easy to test. If the logic is difficult to explain, it is usually worth simplifying before putting it into production.

Take a Deeper Dive