How to Leverage Brim's Variable Library

If you've ever built a chart abstraction project from scratch, you know the blank-page problem. Before you can run a single abstraction, you have to define every variable: what it captures, what type of value it returns, and exactly how an abstractor (or an AI) should extract it from an unstructured clinical note. That last part is harder than it sounds.

The Brim Variable Library is a tool to solve this. It's a curated set of pre-built, instruction-rich variables that you can add to a project in a few clicks, then customize for your needs. But to understand what makes it useful (and what makes it different from other standards you may already be working with) it helps to start with what a Brim variable actually is.

‍

What Makes a Brim Variable Different from a Standard Data Element

‍

If your team works with REDCap or follows NIH Common Data Element standards, you're already familiar with the value of standardized field definitions. The NIH CDE Repository and REDCap's Shared Library offer a growing catalog of fields with defined names, data types, and allowable values. This represents a shared vocabulary that makes it easier to compare and pool data across studies.

Brim Library variables have a similar aim. But they go further.

Because Brim is built for abstraction from unstructured clinical notes, rather than structured form entry, a field definition alone isn't enough. A variable in Brim also carries detailed extraction instructions: the semantic nuances of what counts and what doesn't, how the concept tends to appear in clinical language, edge cases to watch for, and examples drawn from real note patterns. In this sense, a well-built Brim variable has something of an abstractor training manual built into it.

This matters because clinical notes are not uniform. The way a complication is documented at one institution may look very different from how it's documented at another. A variable's instructions need to account for that. Ideally, they should be tailored to reflect your site's specific note formatting and documentation patterns.

This is also why REDCap field definitions, while a useful starting point, aren't drop-in ready for Brim. You can import CDE fields from REDCap, and for teams with existing REDCap data dictionaries, that's a reasonable place to begin. Those fields will need Brim-style instruction enrichment before they're ready to drive accurate AI-guided abstraction. For a deeper look at how Brim structures variable metadata, see our post on the Brim Abstraction Metadata Model (or BAMM).

‍

What's in the Library (March 2026)

‍

The first release of the Brim Variable Library includes over 80 pre-built variables and dependent variables, organized into five thematic bundles:

• NSQIP: Common variables from the ACS NSQIP comprehensive surgical quality dataset, covering complications, outcomes, and perioperative factors
• Trauma: Core variables for trauma registry workflows, including injury characterization and clinical course
• Measurement: Common quantitative clinical measurements such as lab values, vitals, and scores
• Diagnosis: Common diagnosis variables spanning a range of clinical conditions
• Patient Characteristics: Patient-level attributes such as demographics, comorbidities, and baseline clinical status

A variable can belong to more than one bundle. Patient Characteristics variables, for instance, appear across multiple clinical contexts. And each variable comes with its full metadata: scope, data type, description, and last-updated date, so you can evaluate quality before adding anything to your project.

For the complete list of what's included, see the March 2026 release notes. For a walkthrough of how to browse, search, and add variables, see the Variable Library support article.

A quick word on quality: Library variables are built to use Brim best practices for variable design: the same standards described in our Variable Best Practices and embodied in the Variable Scorecard. 

Formal external validation of library variables is on the roadmap. If your institution would be interested in participating in that process, we'd love to hear from you at support@brimanalytics.com.

Now, let’s get into a couple of use case examples for how to use the Variable Library for more efficient and reliable abstraction.

‍

Use Case 1: Hit the Ground Running with a Full Bundle

‍

Best for: Teams with a well-defined, standard use case, e.g. NSQIP abstractors, trauma registrars, or anyone working within an established registry framework.

The fastest path to value in Brim is importing a bundle that matches your use case and running a pilot abstraction. This tells you two important things right away: how well the library variables perform on your notes as written, and where the gaps or mismatches are.

Here's the basic workflow:

1. Open the Variable Library from Project Setup and navigate to the bundle that fits your use case
2. Add the full bundle. Brim will automatically pull in the complete variable hierarchy, including any dependent or input variables, so you don't have to track dependencies manually.
3. Run an abstraction on a representative batch of your notes
4. Review the results and identify where variables need tuning. Examples might include instructions that don't match your site's documentation patterns, value ranges that need adjustment, and variables that aren't relevant to your specific project

From there, you're iterating rather than inventing. The library removes the blank-page problem and replaces it with a concrete, working starting point that reflects clinical best practices.

The NSQIP and Trauma bundles are particularly well-suited to this approach today. They're built around established, well-documented data collection standards, which means the variable definitions have a clear external reference point, and your team likely already has institutional knowledge about what those variables are supposed to capture. We plan to add additional bundles like this in the future, supporting registries and common data sets.

‍

Use Case 2: Use Library Variables as Templates for Custom Variables

‍

Best for: Researchers designing a specific study, teams whose workflow doesn't map cleanly to an existing bundle, and teams who want to draw from multiple bundles and add their own variables alongside.

One of the tensions in any standardization effort is the tradeoff between consistency and flexibility. Standard field definitions are valuable precisely because everyone uses them the same way, but your specific study may require variables that don't exist in any registry.

Brim handles this tension by making library variables explicitly designed to be modified. They're not locked templates; they're worked examples. When you find a library variable that's close to what you need but not quite right, you can add it to your project, open it in the Edit Variable screen, and adapt the instructions, examples, scope, or value definitions to match your requirements. When you save, Brim will ask you to confirm the conversion to a custom variable. Once confirmed, the variable is fully yours; its library origin is preserved in its history, but it behaves like any other project variable going forward.

This is especially useful for variables that are adjacent to standard ones. A surgical complication variable from the NSQIP bundle, for example, might capture the right concept but need its extraction instructions updated to reflect how complications are documented in your institution's operative notes. Or you might need a diagnosis variable that's scoped to a specific patient subpopulation that the standard definition doesn't account for.

For mixed custom projects, the Measurement, Diagnosis, and Patient Characteristics bundles work particularly well as building blocks. They cover common clinical concepts at a level of generality that makes them easy to adapt, and they can be combined with other variables without friction.

‍

What's Next for the Variable Library

‍

This is v1 of the Brim Variable Library. The library is intentionally designed to grow, and community input is a real part of how it will evolve.

If there's a dataset, registry, or variable grouping your team uses frequently that you'd like to see in the library, we want to know about it. Send suggestions to support@brimanalytics.com. We're especially interested in registry-based variable sets and reusable groupings that span multiple use cases.

Longer term, we're working toward formal external validation of library variables, broader specialty coverage, and tighter mapping to external CDE standards. The goal is a library that functions as a trusted shared resource for the clinical abstraction community, which we think would be a meaningful contribution to how structured data gets extracted from clinical notes at scale.

‍

Getting Started

‍

Whether you're adopting a full NSQIP bundle for a surgical quality program or assembling a custom variable set for a novel research study, the Variable Library gives you a strong starting point and the flexibility to make it yours.

The best way to evaluate it is to try it. Open the Variable Library from Project Setup, browse the bundles, and run a pilot abstraction. If you have questions, feedback, or ideas for what should be in the next release, reach out to support@brimanalytics.com.

‍