Variable Options & the Default Value

Variable Options let you define exactly which values a text variable is allowed to return. By constraining output to a curated set of choices, you help your variable generate cleaner data, reduce ambiguity, and simplify downstream analysis.

This article explains how Options work, how Brim filters model output, how the default value behaves, and how Options differ from Aggregation Options.

How do I specify options for a variable?

Only text variables in Brim can have options.

You'll find them in Project Setup > Edit Variable > Semantics. More about how to define and format variable options here.

What Happens When Brim Generates a Value?

1. The model generates a candidate value

When Brim processes the text in scope for your variable, the LLM proposes a value based on the variable definition (which includes your specified options).

Poor fit: If the LLM encounters a value that does not fit the options well, the LLM may either 1) make a "best guess" and choose an option that does not fit that well or 2) return a value that is not in the option set.

2. Brim filters the output against your Options list

If the model returns something not included in your Options list and it is not the default value, Brim will automatically filter it out.

This protects your dataset from typos, synonyms, ambiguous language, or hallucinated categories.

3. If Brim has no valid value for the variable's scope, it returns the default value.

How the Default Value Works

Every variable has a default value.

Common default values include:

• “False” or "No evidence" for boolean variables
• “Not Mentioned” or "No evidence" for clinical status variables
• “None” for medication lists or symptoms

The default value is returned when there is no evidence in scope. This can happen when:

• A "One per patient" variable has no valid values for this patient.
• A "One per note" variable has no valid values for this note.

If the default value is also one of your Options:

In this case, the default value can appear in two situations:

1. There is no evidence in scope (as above).
2. There is evidence that directly supports the default value (e.g., explicit documentation of absence)

When defining your default value and options, think about whether you need "No evidence" to be a unique value or not.

Example 1: "Is Pathology Note"

I want this to be return "Yes" if this note shows evidence of being a Pathology Note, and otherwise "No".

• Options: "Yes", "No"
• Default Value: "No"

Example 2: "Has Cancer"

I want this to be "Yes" if there is evidence of cancer, "No" if there is evidence of no cancer, and "No evidence" if there is no indication either way.

• Options: "Yes", "No"
• Default Value: "No evidence"

Best Practices

• Keep Options short and mutually exclusive
• Include synonyms in the instruction, not the Options
• Use a default that accurately reflects “no evidence”
• Test your variable with multiple examples to ensure outputs match your intent.