REDCap Calculated Fields: Syntax, Limits, and the Recalculation Trap

A REDCap calculated field runs a formula against other fields on the same record and stores the result — a BMI computed from height and weight, an age computed from a birth date, a total score summed across several item fields. There are three variants that share the same expression language but differ in what they return: the native Calculated Field type (numeric output, selected as the field type in the Online Designer), the @CALCDATE action tag (returns a date), and @CALCTEXT (returns text). This guide covers the syntax that all three share, the functions most projects actually use, and the recalculation behavior that causes the majority of “my calculation is wrong” tickets — which is almost never a formula bug.

nn

Core syntax: field references and operators

n

A field is referenced in square brackets by its underlying variable name, never its on-screen label: [weight_kg] / (([height_cm]/100)^2). The comparison and arithmetic conventions match REDCap’s branching logic syntax exactly: =, <> for not-equal (REDCap does not accept !=), <, >, <=, >=, and and/or rather than &&/||. Standard arithmetic operators (+, -, *, /, ^ for exponents) and parentheses for precedence work as in any expression language.

n

Checkbox fields need the same (code) referencing that branching logic requires — a checkbox option is stored as its own binary sub-variable, so [symptoms(3)] = '1' checks whether choice 3 was selected, while referencing it like a radio field ([symptoms] = '3') silently evaluates to a wrong or blank result rather than throwing an error.

nn

Common functions: round, sum, min/max, if, and datediff

n

REDCap’s calculation engine supports a small set of functions that cover most real projects:

n

n
• round([field], n) — rounds to n decimal places, e.g. round([bmi_raw], 1).

n

• sum([field1], [field2], [field3]) — adds a list of fields, useful for scale/index totals.

n

• min(...) / max(...) — smallest or largest of a list of values.

n

• if(condition, value_if_true, value_if_false) — REDCap’s only conditional function; nest it for more than two branches, e.g. a three-category severity score built from two nested if() calls.

n

• datediff([date1], [date2], "units", "date_format", return_signed_value) — the date-difference function covered below.

n

n

Every field referenced inside a calculation must already have a value for that record, or the calculation returns blank rather than an error — a calc that depends on a field further down the same form, or on a form not yet completed, silently produces nothing until that dependency is filled in.

nn

datediff(): the function almost every project needs at least once

n

The syntax is datediff([date1], [date2], "units", "date_format", return_signed_value). units is one of "y" (years), "M" (months), "d" (days), "h" (hours), "m" (minutes), or "s" (seconds); date_format must match the format the two date fields are actually stored in (commonly "ymd"); and the final argument, if set to true, returns a negative number when date1 is later than date2 instead of REDCap’s default of always returning a positive difference. A common age-at-enrollment calculation looks like datediff([dob], [enrollment_date], "y", "ymd").

n

REDCap also allows the reserved values "today" and "now" in place of a field reference inside datediff() or elsewhere in a calculation. This works, but it is documented as poor practice for a stored calculated field or branching logic: because "today" re-evaluates to the actual current date every time the calculation runs, a field calculated against it produces a different stored value depending on when the form was last opened and saved — not a fixed property of the record. For anything that needs to be a permanent, reproducible value (age at consent, days since a fixed index date), calculate against a real stored date field, not "today".

nn

The recalculation trap: why exported data can be stale

n

This is the single most consequential thing to understand about REDCap calculated fields, and it is not obvious from the field-building interface: a calculation is only re-evaluated when someone opens the specific form containing it, for that specific record, in a browser. REDCap does not run calculations as a background batch process, and it does not retroactively apply a calculation to records that already existed before the field was added or the formula was edited.

n

That produces three concrete failure modes:

n

n
• New calculated field, old records. Add a calculated field to a project that already has enrolled records, and every existing record shows a blank or stale value for that field until someone opens its form.

n

• Edited formula, unrevisited records. Fix a typo or change the logic in an existing calculation, and only the records whose form gets opened again after the edit pick up the corrected value — every other record keeps computing (or keeps showing) the old result.

n

• Cross-form dependency lag. If a calculation on Form B depends on a field entered on Form A, Form B’s stored value can lag behind Form A’s current data until Form B is specifically reopened, even though nothing about Form B itself changed.

n

n

REDCap’s Data Quality module includes a built-in rule for exactly this: Rule H, “Incorrect values for calculated fields,” scans every record in the project, compares the stored calculated value against what the formula would currently produce, and flags every mismatch. Running Rule H and using its “Fix calcs now” option forces a full-project recalculation without opening each record by hand — the only project-wide way to guarantee every record’s calculated fields reflect the current formula and current underlying data. Run it before any data export or analysis pull on a project with calculated fields, not only when something looks obviously wrong; a mismatch produced by an edited formula or a late data-entry correction gives no visible signal on its own. After running it, spot-check a handful of the flagged records by hand — REDCap’s own documentation notes that a typo in a reworked formula is easy to miss, and Rule H will happily and silently apply a wrong formula to every record just as efficiently as it applies a correct one.

nn

Practical limits and gotchas

n

n
• No error feedback. Like branching logic, a malformed or misreferenced calculation does not throw a visible error to the person building the project — it returns blank or an unexpected number. Test a new or edited calculation against a handful of known records before trusting it project-wide.

n

• Blank-propagation, not error-propagation. A calculation referencing an empty upstream field returns blank rather than a computed default — decide deliberately whether a blank result is the correct behavior for a given formula, or whether the formula needs an if() guard against a missing value.

n

• Calculated fields are not editable by the person entering data. The field displays a read-only computed value; if a data-entry correction requires a different result, the correction has to happen on the underlying field(s) the formula reads from, then the form re-opened (or Rule H run) to refresh the calculation.

n

• Longitudinal/repeating-event projects need the same event-name prefix convention as branching logic when a calculation references a field on a different event: [unique_event_name][field_name], using the internal event name rather than its display label.

n

nn

Frequently asked questions

n

Why does my calculated field show blank instead of a number?

n

Almost always one of: a referenced field on the same record is still empty, a checkbox field is referenced without its (code) suffix, or the record’s form containing this calculation has never been opened since the formula was added or edited — see the recalculation trap above.

n

Do I need to run Rule H on every project?

n

Only on projects that use calculated fields, @CALCDATE, or @CALCTEXT at all. A project with none of those has nothing for Rule H to check.

n

Can a calculated field reference another calculated field?

n

Yes — REDCap evaluates dependent calculations within the same form load, but a chain of calculations makes the recalculation trap’s cross-form and old-record failure modes compound, since a stale upstream calculated value produces a stale downstream one. Keep dependency chains short and verify with Rule H after any change.

nn

For the related mechanism that controls whether a field is shown at all rather than what value it stores, see REDCap branching logic syntax. For pulling calculated values out via automation rather than the web interface, see the REDCap API guide. For where a calculated field’s type and formula are actually configured and documented, see REDCap’s data dictionary. Background on the platform itself is in the REDCap dictionary entry.

n