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.


The meaning of each of the variable fields is laid out below. You can find tips for building more effective variables here.

Fields

Basic

Name.

This name should be descriptive.

Include variable in generation.

If you uncheck this option, this variable will not be generated. This is a way to temporarily "disable" variables.

Instrument.

Choose which instrument the variable belongs to. Instruments are useful for organizing related variables into logical groups (e.g., Demographics, Labs). To assign, either

  • Select from the dropdown to add the variable to an existing instrument. The variable will start at the end of the selected instrument.
  • Select "Create New Instrument...", and type in the name of the Instrument you'd like to create.

Variables in the same instrument are shown together in project views and can be ordered relative to one another.

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.
  • Timestamp. The value is a date or date and time.

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.

Instruction.

This is the most important part of the variable definition. It tells the AI how 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.

You can reference other variables in the instruction by using an open curly bracket (" { ") and selecting the variable you want to reference from the list. This will allow the LLM to understand exactly how to use the input variables you specify below.


Semantics

Option definitions.

If your variable has a limited set of options (for example, "Stage I", "Stage II", and "Stage III"), define them here.

Default value for empty response.

  • The default value for empty response determines what the LLM should respond for a patient when it finds no relevant evidence.
  • This defaults to "No evidence", but could be "False", "None", or another value depending on your application.

Reference today's date.

If your variable needs to know today's date to be computed correctly, check this box.

Enable for: Variables that need today's date specifically

Disable for: Most variables.

Reference raw text from notes.

Most variables need to reference the raw text to compute correctly.

You can uncheck this box if you want a variable that only references input variables.

Enable for: Most variables

Disable for: Variables that only need to reference input variables.

Restrict by Document Name.

If you know that this variable should only read from certain document types, you can limit that here.

  • No restriction: the variable will not be restricted by document type.
  • Include certain documents: the variable will only read from documents with one of the note titles entered.
  • Exclude certain documents: the variable will read from all documents except those with one of the note titles entered.

Restrict by Document Date.

If you know that this variable should only read from documents in a certain date range, you can limit that here.

  • No restriction: the variable will not be restricted by document date.
  • After a certain date: the variable will only read from notes with dates after the date you enter.
  • Before a certain date: the variable will only read from notes with dates before the date you enter.
  • Between dates: the variable will only read from notes with dates in between the two dates you enter.

Aggregation

Aggregation strategy.

For variables requiring aggregation over a note or the whole patient, this tells Brim how to summarize into one value.

We recommend choosing one of the included Aggregation strategies if one of them fits. These are deterministic and performed without AI.

You can also define a Custom aggregation instruction, which will instruct the LLM to perform aggregation as you specify.

Only use true value in aggregation.

When this is checked, Brim will only consider values labeled as “True” (affirmative) when aggregating across documents. This is useful for boolean-style variables like "History of Smoking."

Enable for: binary variables where "True" carries meaning, and "False" should be excluded from the aggregate output.


References

Variables.

A variable can reference the values of other variables along with the note text to determine its own value. How this works depends on scope:

  • If the variable you're editing is one_per_patient, it will reference all of the values of any input variables that relate to that patient.
  • If the variable you're editing is one_per_note, it will attempt to access values related to that note and patient:
    • All values related to this document of any many_per_note input variables
    • The value for this document of any one_per_note input variables
    • The patient value for any one_per_patient input variables
  • If the variable you're editing is many_per_note, it will attempt to access values related to that note and patient:
    • All values related to this document of any many_per_note input variables
    • The value for this document of any one_per_note input variables
    • The patient value for any one_per_patient input variables.

If blank, this variable doesn't reference other variables.


Here's an example of using a variable as input for another variable:

If you use a variable as input, we recommend explictly referencing it in the instructions as well to make it clear how to handle the input. You can do this by typing "{" and then selecting the variable you want to reference.

Advanced Settings

You can find more advanced variable settings and how to use them here.

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.


Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Related Articles