Value Sets and Lookup Tables

Ursa Studio is designed to serve as a central repository for a team’s various metadata assets, including classification systems, groupers, and crosswalks. Value Sets -- lists of values of a certain type representing the same concept, such as a list of ICD-10 diagnosis codes associated with a particular chronic condition -- and Lookup Tables -- lists of key-value pairs, such as the travel distances from some central point to a set of provider practice locations -- are flexible data structures that can capture many different types of metadata. These data structures can be used to store either external or internal metadata.

Manual Creation of Value Sets / Lookup Tables

Users can create new Value Sets or Lookup Tables in Metadata Manager. To create a Value Set or Lookup Table, a user must first supply the following high-level information:

• Namespace: A namespace is the conceptual domain in which the Value Set name must be unique. It identifies who is responsible for defining and maintaining the contents of the Value Set or Lookup Table as well as what type of contents the Value Set contains. For example, the URSA-CKD namespace indicates a Value Set is managed by Ursa Health and that its contents pertain to Chronic Kidney Disease (CKD). Namespaces are used with various data assets throughout Ursa Studio. 
• Value Type: The value type identifies the code type associated with a value set. For example, ICD10CM or HCPCS codes. You can select from an existing list of value types or generate a new one by typing into the field. User generated tokens are often used to identify value types specific to your organization.
• Value Set / Lookup Table Name: The Value Set Name is the official identifier used to reference the Value Set or Lookup Table within Ursa Studio. It is a unique name for the value set. Value sets created by the Ursa Health team are described as being consistent with or specific to, a concept. For example, a value set that directly identifies physician office visits, would be considered a value set specific to office visits. Alternatively, a value set containing codes that could plausibly be performed at an office visit is an example of a value set that is consistent with office visits.
• Cluster: Clusters are groups of value sets that can be referenced as a lookup table, though this functionality is unrelated to the Lookup Table feature. For example, a cluster related to Behavioral Health ICD10CM codes might include individual value sets for things like anxiety or depression, but the cluster would encompass all value sets with ICD10CM codes concerning behavioral health.
• Value Set Name: The Value Set Name is the official identifier used to reference the Value Set or Lookup Table within Ursa Studio. It is a unique name for the value set. Value sets created by the Ursa Health team are described as being consistent with or specific to, a concept. For example, a value set that directly identifies physician office visits, would be considered a value set specific to office visits. Alternatively, a value set containing codes that could plausibly be performed at an office visit is an example of a value set that is consistent with office visits.
• Value Set Description: The description is any notation about the value set that will explains its purpose.

Adding Values and Value Descriptions

Once the Value Set has been named, it is then defined by adding a list of values of the specified value type. These values and their descriptions can be entered in three ways:

(1) Users can manually enter each value and an optional description. After each entry, a new row will appear below.

(2) Users can upload a value set by pasting the values from a spread sheet or document using the clipboard icon. When pasting values and descriptions, the list can be space delimited for single-word descriptions or tab delimited for multi-word descriptions.

(3) Users can upload CSVs directly via the upload icon. This is the preferred means to import very large value sets. This import mechanism can be used both for creating new value sets and for editing existing value sets. When editing existing value sets, users will have the option to overwrite the existing values or append to them.

Saving Value Sets

When saving a new value set, the system will notify you of any duplicate values, which must be avoided. Relatedly, Lookup Tables should not have duplicate entries for the same key. For most databases, this is enforced by means of a unique constraint. For those databases that do not support unique constraints, any duplicate value sets will be noted in a warning panel at the top of the screen. Duplicate values must be cleared up as they may cause an unwarranted grain-size explosion if referenced downstream.

Once the value set has been created, you are redirected back to the Value Set screen. To retrieve the value set just created, search for it using a keyword.

Value-level Features

Comments for Specific Values

Users can enter a comment alongside certain values by clicking the comment icon to the right of each value set. Comments are often added to values to indicate the reason the value was included in the value set.

Adding Value Ranges and Wildcards

In addition to listing individual values associated with a set, users can also specify ranges of values with dashes and asterisks. The special characters dash (-) and asterisk (*), when used in value-set values, default to the assumption that these characters are to be taken literally and not to denote a range or a wildcard (e.g., in the LOINC code 5792-7).

By unclicking the “Is Literal Value” checkbox, users can designate the values as instead meaning a range or wildcard. When such value sets are invoked in Object Workshop or Measure Workshop, Query Builder will construct the appropriate range and wildcard SQL. Dashes represent a range of values; for example, “F40-F50” would mean that values such as F41 and F49 should also be considered matches. Ranges are inclusive on the bottom and super-inclusive on the top, so that F40-F50 would match on F40, F50, and F50.5, but not F51 or F500. Range superinclusivity is only used for value sets, not lookup tables. 

Range comparisons are always alphabetical, never strictly numeric, which means for example that "500" would be considered to be within "1-9", and "5" would not be considered to be within "1-10". Users that want a lookup based on a pure numeric comparison should use a CASE WHEN pattern instead.

Asterisks represent wildcard characters, such that F4* would be the same as F40-49.

All asterisks and dashes from programmatically loaded data are taken literally.

View Mode and Edit Mode

When users first drill down into a value set, they will be shown the value set in read-only mode. For large value sets, lookup tables, and affiliations, only the first 1000 values will be shown in the initial fetch. Users can fetch the full list if they want. Users will not be allowed to edit values unless the set is fully populated.

Value sets that are programmatically maintained, such as via the Value Sets object in Object Workshop, are not allowed to be edited in the value set screen. For these value sets, the pencil icon will not be visible. However, certain read-only actions are still possible for read-only value sets.

Action icons available in read-only mode include:

• The view reference review icon is available for value sets that have matching values within one of Ursa's reference data sets.
• Select the export icon to export the value list to a .CSV file.
• Select the pencil icon to edit the value set, if editing is allowed.

Action icons available in edit mode include:

• Select the cancel icon to cancel any changes made to the set and to return to read-only mode.
• Select the eraser icon to clear all values for the set and start over. Please note, some value sets, such as those defined by third parties like AHRQ, are read-only and cannot be edited or erased.
• Select the clipboard icon to append values via copy/paste from a spreadsheet, as described above
• Select the upload icon to directly import a .CSV file, as described above.
• The edit reference review icon is available for value sets that have matching values within one of Ursa's reference data sets.
• Select the trashcan icon to delete a value set. Once a value set has been deleted, it is not recoverable.

Description Enrichment from Reference Tables for Value Sets

Ursa Health maintains a number of reference tables for commonly used codes such as HCPCS and ICD-10-CM. As a user enters such codes into value sets, Metadata Manager will automatically look up the corresponding code descriptions and populate them into the value set screen, where users can override them as desired. The descriptions will also be visible in the Analytics Portal definition popups for measures that use these value sets.

Logging and Recovery

Each change to a Value Set or Lookup Table, whether to its defining fields or its constituent values, is logged. Users can see the entire history of edits and can recover back to any previously saved point. Doing so will recover the historical values but not any set-level field migrations. The recovered version is immediately saved, overwriting the “current” version; however, the overwritten version is still available for recovery itself in the history. 

Use in Measure Workshop

A variety of patterns in the Object Workshop and Measure Workshop zones of Ursa Studio make use of profiled Value Sets or Lookup Tables. For example, users can filter measure results based on “Is In Value Set,” or “Lookup Value Set Using Cluster.” Such objects and measures will consult the value set data at the moment of ELT or report instantiation.