Test Derived Research Variables with Small Known Examples

Turn the definition into examples

A derived variable is a scientific definition implemented in code. Testing only that the code runs does not establish that it represents the definition. Start with a short specification: inputs, units, eligibility conditions, formula, missing-data behavior and boundary rules.

The Python unittest documentation provides assertions for checking expected behavior. The framework is optional; the important design choice is to calculate expected outputs independently rather than copying the implementation into the test and reproducing the same error twice.

Choose cases that can fail differently

Include an ordinary valid case, each boundary, an out-of-range value, a missing input and a case with incompatible units. For a date-derived variable, include a month or year transition. For a ratio, include a zero denominator and define whether that should produce an explicit error or unavailable result.

Test the smallest useful function before testing the full pipeline. Then add an integration check showing that the correct source columns reach the function and that outputs remain attached to the right participant identifiers.

Work through a hypothetical derivation

Suppose improvement is defined as baseline minus follow-up, with larger positive values meaning improvement. For baseline 12 and follow-up 8, the expected result is 4. Reversing those inputs gives −4. Equal values produce zero. A missing follow-up should not become an improvement of 12 merely because missing was converted to zero.

For a responder rule requiring improvement of at least four units, test 3.9, 4.0 and 4.1 explicitly. The middle case verifies the inclusive threshold. If the rule applies only to participants with baseline at least five, add a baseline-four case that remains ineligible even when its arithmetic change exceeds the responder threshold.

Keep tests connected to the protocol

Name tests after the rule they protect and record the protocol or dictionary version. When a definition changes, update the specification, expected examples and production derivation together. A previously passing test may correctly fail after an intended rule change; do not delete it without understanding why.

Run the tests on synthetic information, avoiding patient data in public code repositories. Preserve a summary of the checks with the analysis handoff. Passing a finite set of tests cannot prove the derivation correct for every possible input, but targeted boundary and missingness examples can expose errors that remain invisible in a plausible-looking mean or frequency table.

Source verification: 6 November 2026. Examples are hypothetical.