How to Upload Variables via CSV

Defining your variables in a "Comma-separated values file" or CSV and uploading the CSV is an easy way to create and edit a system of variables.

Brim has different CSV files and formats for the two different types of variable uploads:

• Normal Variables. These variables use only what is available in the medical record and the instructions you provide to generate labels.
• Dependent Variables. These variables use the values of other variables and the instructions you provide to generate labels.

The fields for these also differ (slightly).

CSV Format for Variables

Basic CSV Header (in any order):
                    variable_name,instruction,aggregation_instruction,variable_type,scope,option_definitions,aggregation_option_definitions,default_value_for_empty_response


Fields:                        
Variable Name: Name of the variable.


Variable Type: Type of data to extract.
     Options: boolean, text, integer, float, timestamp


Scope: Granularity to extract data.
    Options:
        "one_per_note" - one value per note.
        "many_per_note" - many values per note.
        "one_per_patient" - one value per patient (from all notes).
                        

Instruction: Instructions on how to extract the variable.


Aggregation Instruction: Instructions to aggregate values. Only needed variables with ONE_PER_PATIENT or ONE_PER_NOTE scope.
                        


Option Definitions: For text fields. List of allowed values (e.g. for categorical data). Brim will filter out all values that are not in this list.
    Format: Python dictionary"
    Example: "{""option 1"": ""option 1 details"", ""option 2"": ""option 2 details""}"
    Note the double quotes needed to escape.


Aggregation Option Definitions: Same as Option Definitions above, but only used for aggregation results. Brim will filter out all values that are not in this list.
    Often Aggregate Option Definitions will be the same as Option Definitions.


Default Value For Empty Response: If Brim does not find any relevant data in the notes, it will return this value. 


Notes:
Formatting Options: The following variables can be used in the template.
    {name} - Variable name
    {instruction} - Variable instructions
    {var_type} - Variable Type  

There are additional optional fields describing advanced variable behavior, but due to high potential for error, we recommend configuring those in the tool and exporting rather than writing them from scratch in a CSV. These include:

• General
  • Include variable in generation
• Semantics
  • Include today's day in prompt
  • Document start date
  • Document end date
  • Restrict variable to specific documents
  • Restrict by document name more
  • Restrict by document date mode
• Aggregation
  • Short circuit results
  • Only use true value in aggregation
• References
  • Input Variables
  • Preconditions for Conditional Generation
• Advanced Settings
  • Use Advanced LLM Model
  • Prompt Template
  • Aggregation Prompt Template

More on all of these settings here.

CSV Format for Dependent Variables

NOTE: Dependent variables and decisions refer to the same thing.

Basic CSV Header (in any order):
decision_name,instruction,decision_type,variables,dependent_variables,default_value_for_empty_response
   


Fields: 
Decision Name: Name of the dependent variable (or outcome) to extract.
    

Instructions: Instructions on how to extract the dependent variable from variable input.
    

Decision Type: Type of data to extract.
Options: boolean, text, integer, float, timestamp
    

Variables: List of variables to feed as input.
Expected Format: "[variable_name_1, variable_name_2]"


Dependent Variables: List of dependent variables to feed as input.
Expected Format: "[dv_name_1, dv_name_2]"


Default Value For Empty Response: If Brim does not find any relevant data in the notes, it will return this value. 


Notes:
Formatting Options: The following variables can be used in the template.
    {name} - Dependent variable name
    {instruction} - Dependent variable instructions
    {decision_type} - Dependent variable data type
    

There are additional optional fields describing advanced behavior, but due to high potential for error, we recommend configuring those in the tool and exporting rather than writing them from scratch in a CSV. These include:

• Include decision in generation
• Include today's day in prompt
• Use Advanced LLM Model
• Prompt Template

More on these settings here.

To upload data:

1. Access Project Setup on your Project Dashboard.
   • Click on the first section, which should be named "Project Setup".
2. Preparing a CSV
   • Scroll down to the "Variables" section of the page.
   • Click on the "Upload Variables" option.
   • You'll see two places to "Choose a File:" one for each of Variables and Dependent Variables. You can click on "Example Format" to see the required fields in each type of CSV, some formatting notes, and a link to a Sample CSV file.
   • Each variable CSV file should have a row for each variable with the details for how Brim should extract labels for that variable.
3. Select File
   • Click "Choose File", and then choose the CSV file you want to upload from your desktop.
   • You can upload two files at once, or just one.
4. Upload File
   • Click on the "Upload" button to upload the selected file.
   • Depending on the size of the file, this might take a few seconds, a few minutes, or longer for very long files. You'll see the status in the table change to "Complete" when the variables are ready.
5. Preview Data
   • After the upload is complete, you can see the variables update in the table at the bottom of the screen, with some in the "Variables" tab and some in the "Dependent Variables" tab.