What is a variable?
A variable is the primary communication method in Brim Analytics. You can think of it as similar to a protocol you'd give to a human curator, where you describe what you'd like extracted and the limitations around that abstraction.
IMPORTANT: It's best practice to make variables as narrow and specific as possible. For example, if you want to find every date of a specific type of surgery, you might be tempted to do something like:
❌ instance_of_surgery: return the type of the surgery and its date in one variable.
But we recommend making this two variables, something like:
✅ surgery_type: many_per_note, return all instances of this surgery
✅ surgery_date: many_per_note, return the date of surgeries mentioned.
Making variables smaller makes it easier to compute and troubleshoot them, and means you can use them flexibly in Dependent Variables.
Fields
Name.
This name should be descriptive.
Scope.
This tells Brim what text to use while computing a label, and what to aggregate values over. The options are:
- Many Labels Per Note: Generate multiple values in each note.
- One Label Per Note: There should be at most one value per note generated.
- One Label Per Patient: There should be at most one value per patient generated.
Variable type.
This describes the type of data the system should return. The options are:
- Text. No restrictions on format.
- Boolean. The value must be True or False.
- Integer. The value must be a whole integer or number.
- Float. The value is a number that could be whole or fractional.
Instruction.
This is the most important part of the variable definition. It tells the AI what it means to correctly label the variable. A good instruction includes:
- A clear definition of the variable.
- Semantics necessary to guide how to abstract values
- Temporal considerations. Is this historical? Current?
- One or more examples.
Default value for empty response.
- Dependent variables return one value per patient. The default value for empty response determines what the LLM should respond for a patience when it finds no relevant evidence. This defaults to "None", but could be "False", "No evidence", or another value depending on your application.
Optional Fields
Option definitions.
If your variable has a limited set of options (for example, "Stage I", "Stage II", and "Stage III"), define them here. Don't forget to include options for unknown or not found.
Aggregation strategy.
For variables requiring aggregation over a note or the whole patient, this tells Brim how to summarize into one value. You can choose one of the popular aggregation strategies, or choose "Custom" and write your own Aggregation instructions.
More about Variables
You can create variables directly in Brim Analytics, import them via a CSV, or import from REDCap.
We recommend optimizing your variable instructions immediately after importing or creating them, and then again after you've labeled results for a few patients. Learn more in How to Optimize Variable Instructions.
Brim also allows for complex reasoning with Dependent Variables, which can apply an instruction to the values of several variables (or dependent variables) to abstract a value.
