Skip Navigation Bar

U.S. Department of Health & Human Services

NLM logo

VSAC Support Center

Create Value Sets

How to Create, Save, and Edit Value Sets

The following tutorial supports any Authors who need to create value sets as well as the measure developers and value set developers for the annual updates of the electronic Clinical Quality Measure (eCQM) value sets. This tutorial is useful for other purposes as well, beyond the eCQM value set annual updates.

Before you can create value sets, you need VSAC Authoring Permissions. It is helpful to understand the the roles of value set authors and stewards. It is also helpful to review the VSAC Authoring Best Practices.

Once you obtain authoring permissions, sign into VSAC with your UMLS account.

sign in
  • Select the Authoring tab.
  • Select the enumerated list (extensional) in the definition method drop-down menu.
extensional value set navigation

A tab entitled, New Def… appears. Under that tab, there are three sub tabs: Metadata, Definition, and Expansion/Publication. You will need to complete the information in each sub tab sequentially:

  1. the Metadata sub tab
  2. the Definition sub tab
  3. the Expansion/Publication sub tab, if needed

Three tabs under new value set

Add Metadata

Mandatory fields : OID, Name, Author, Steward, Purpose fields

OID
  • Object Identifier (OID) Assignment - we recommend the auto generate default setting in which VSAC automatically generates an OID for your value set once you have entered all the information in the other fields, and have selected the "Save" button. If the automatic OID assignment does not meet your purpose, you will need to to enter your own OID manually.
  • Manual Entry of OID (Rare) - The only case in which you should manually enter your own OID is when you have an established pre-existing OID that you have published in another context external to VSAC and the OID is already used by the community, and the value set you create will have the same content and purpose of the pre-existing OID.
    • To manually enter your pre-existing OID, uncheck the Auto Generate box under the OID field, and follow the instructions in the tool tiptoolpitimage.jpgto correctly enter your OID before selecting the Save button.
    • If you need to enter an OID manually, the following rules apply:
      • OID Consists of all digits [1-9] or 0 if a single digit number, but no leading zeros if multiple digit number
      • Numbers may be separated by dots
      • NLM OID name space: Any OID entered MUST NOT start with 2.16.840.1.113 762.1.4
    OID.jpg
Purpose fields

Follow VSAC Authoring Best Practices to write your purpose statements.

Save

When finished entering metadata, click the "Save" button.

extensionalmetadata.jpg

Create Definition

  1. Select a code system for your value set.
    extensionalcodesys.jpg
  2. Select codes to add to your value set.
    1. Enter a term or code to search for codes in code system.
    2. Add selected codes to a value set.
    3. Save the value set definition.
    extgetcodes.jpg
  3. Submit the value set to the steward to approve or reject.
    extsubmit.jpg

When the steward approves the value set definition, you value set is in Ready to Publish status. VSAC will publish a snapshot/temporary expansion, called Latest, of the definition at midnight based on the most recent code system. VSAC will publish subsequent "Latest" expansions when code systems update.

Expand/Publish Value Set

If you require non-default expansion settings, like a specific code system version (Setting A Example), or a date for expansion (Setting B Example) proceed to the Expansion/Publication sub tab after you have submitted, saved, and you or the steward has approved your value set definition. Make the selections for the non-default expansion settings as illustrated below.

extexpandpublish.jpg

Topics

Select Intensional Value Set Option

Once you obtain authoring permissions, sign into VSAC with your UMLS account.

sign in
  • Select the Authoring tab.
  • Select the rule-based intensional option in the definition method drop-down menu.
intensional value set navigation

A tab entitled, New Def… appears. Under that tab, there are three sub tabs: Metadata, Definition, and Expansion/Publication. You will need to complete the information in each sub tab sequentially:

  1. the Metadata sub tab
  2. the Definition sub tab
  3. the Expansion/Publication sub tab, if needed

Back to Topics

Add Metadata

Mandatory fields : OID, Name, Author, Steward, Purpose fields

OID
  • Object Identifier (OID) Assignment - we recommend the auto generate default setting in which VSAC automatically generates an OID for your value set once you have entered all the information in the other fields, and have selected the "Save" button. If the automatic OID assignment does not meet your purpose, you will need to to enter your own OID manually.
  • Manual Entry of OID (Rare) - The only case in which you should manually enter your own OID is when you have an established pre-existing OID that you have published in another context external to VSAC and the OID is already used by the community, and the value set you create will have the same content and purpose of the pre-existing OID.
    • To manually enter your pre-existing OID, uncheck the Auto Generate box under the OID field, and follow the instructions in the tool tiptoolpitimage.jpgto correctly enter your OID before selecting the Save button.
    • If you need to enter an OID manually, the following rules apply:
      • OID Consists of all digits [1-9] or 0 if a single digit number, but no leading zeros if multiple digit number
      • Numbers may be separated by dots
      • NLM OID name space: Any OID entered MUST NOT start with 2.16.840.1.113 762.1.4
    OID.jpg
Purpose fields

Follow VSAC Authoring Best Practices to write your purpose statements.

Save

When finished entering metadata, click the "Save" button.

intensionalmetadata.jpg

Back to Topics

Create Definition

  1. Select a code system for your value set.
    codesystem.jpg
  2. Get codes for your Include and Exclude clauses.
    1. If you already know a code you want to include, type (Method 1) or copy/paste the code into a clause. Alternatively, if you have already collected your codes in a local text file, you can import your codes into the Code Clipboard as a holding place for you to then select which codes go into which clause.
    2. If you know you need to use descriptors to find codes, you can either use "Search for Codes" (Method 2), as a simple and direct search and filter function, or you can use Browse Code Systems if you need to first study your terminology’s hierarchy and relationship details, and then select codes based on your discovery. Browse Code Systems will open in a separate tab or window depending on your browser settings.
    3. Add your desired codes to your Code Clipboard (Add to Code Clipboard), or directly add your code into your checkbox-selected clause (Method 3) when you use the simple "Search Code" or the more advanced Browse Code Systems. Your Code Clipboard is a temporary place for you to gather multiple codes to later include them in specific definition clauses. This separate Code Clipboard becomes especially important when you are gathering several codes for multiple clauses as it gives you control over which codes you specify for your clauses within your value set definition.
    intgetcodes.jpg
  3. Create your logical clauses. You can do this either before or after you get your codes (step 2).
    1. Select your desired operator and code for your first clause, in either the Include or Exclude Codes sections. See the blue button Glossary to review the function of each operator.
    2. Add more clauses to create unions (+OR) or intersections (+AND) of your codes.
    3. If you already know a code you want to include, type or copy/paste the code into a clause. Otherwise, to enter a code from your Code Clipboard into a specific clause, select the checkbox of the clause you want to modify, then select the checkbox of the code in your Code Clipboard, and then select Search Code "Add to Clause".
    4. If you need to do advanced code editing within your Code Clipboard for a clause, for example, if you are working with the IN operator, select the checkbox of your desired clause, and then click the blue button "Advanced Code Editor".
  4. Preview Expansion of your entire constructed definition, or of any sub-clause within the definition, to review the results of your expanded code list. The Preview Expansion function presents a sample view using default settings, and you can change these settings using the dropdown choices in the section “Calculate trial expansion based on:”

    previewexpansion
  5. When you are satisfied with your value set definition: Save, Submit, and Approve your value set definition to enable public access of the value set’s expansion.

Back to Topics

Code Clipboard

Your Code Clipboard is a temporary place for you to gather multiple codes so you can later include them in specific definition clauses. Code Clipboard becomes especially important when you are gathering several codes for multiple clauses as it gives you control over which codes you specify for your clauses within your value set definition. Code Clipboard is currently available to assist you with intensional value set definitions.

You can find your Code Clipboard in three places within the VSAC Authoring environment: the "Search for Codes" tab, "Browse Code Systems," and the "Advanced Code Editor."

Search for Codes tab
searchforcodes

Displays your gathered codes only from your currently selected code system.

You can gather more codes from the Search Code panel: select the checkboxes of codes you like and then click Add to Code Clipboard. You can also use the Import feature to import your own local text file of codes into your Code Clipboard.

Add to Clause: select the checkboxes of Code Clipboard codes you need for a specific clause, select the checkbox of that clause, and then click Add to Clause at the top of your Code Clipboard.

Browse Code Systems
browsecodesystems

Displays all of your gathered codes from all code systems. Only those codes from the code system with which you are currently working will be selectable; codes you have gathered previously from other code systems will be greyed out.

You can gather more codes from any of the Browse Code System panels: select the checkboxes of codes you like and then Add to Code Clipboard. You can also use the Import feature to import your own local text file of codes into your Code Clipboard.

Your Code Clipboard will persist when you switch back to your VSAC Authoring window, where you can select the checkboxes of codes you like, select the checkbox of your target clause, and then click Add to Clause.

Advanced Code Editor
advcodeedit3

Use the Advanced Code Editor to add more codes to your clause.

Select the checkbox next to the clause for which you would like to add codes, and then select the Advanced Code Editor button.

advcodeedit2

Displays your gathered codes only from your currently selected code system.

You can gather more codes from the Search Code panel within the Advanced Code Editor: select the checkboxes of codes you like and then click Add to Code Clipboard.

You can select the checkboxes of any of your Code Clipboard codes and then click the centrally located orange arrow to place those codes into your selected clause. Then click the [Save Changes to Clause] button, click the Cancel button to close the Advanced Code Editing dialog window and return to your intensional value set definition to see your changes.

Back to Topics

Valid Operators for Each Code System

This table displays the valid operators for each code system. The "all" operator can be used in just a few smaller code systems (CDCREC, CVX, HL7, HSLOC, NUCCPT, and SOP). Large code systems like SNOMED CT, CPT, etc. are either too large to use all codes or have copyright restrictions. Future development will include intensional value set authoring functionality for RxNorm and LOINC, as well as the ability to convert existing extensional value sets to logically defined intensional value sets as desired by the author.

Code Systems all equal in descendantOf descendantOrSelfOf childOf ancestorOf ancestororSelfOf parentOf leafOf
All concepts in the code system The specified concept All concepts in the specified concept list All descendants of the specified concept All descendants of the specified concept plus the specified concept itself All children of the specified concept All ancestors of the specified concept All ancestors of the specified concept plus the specified concept itself All parents of the specified concept Terminal descendant codes of the specified header code
CDCREC x x x x x x x x x
CDT x x x x x x x x x
CPT x x x x x x x x x
CVX x x x
HCPCS x x
HL7 x x x x x x x x x
HSLOC x x x
ICD10CM x x x x x x x x x
ICD10PCS x x
ICD9CM x x x x x x x x x
LOINC x x
MED-RT x x x x x x x x
NCI x x x x x x x x
NDFRT x x x x x x x x
NUCCPT x x x
RxNorm x x
SNOMED CT x x x x x x x x
SOP x x x x x x x x x
UCUM x x x
UNII x x

Back to Topics

Other Examples of Intensional Value Sets

All direct descendants (children) of Race as illustrated in the image below.

  • Code System: CDCREC
  • Include: childOf 1000-9
CDCREC Race

All codes in the CDCREC terminology as illustrated in the image below.

  • Code System: CDCREC
  • Include: All (to get 966 codes)
CDCREC All

Back to Topics

Expand/Publish Value Set

If you require non-default expansion settings, like a specific code system version (Setting A Example), or a date for expansion (Setting B Example) proceed to the Expansion/Publication sub tab after you have submitted, saved, and you or the steward has approved your value set definition. Make the selections for the non-default expansion settings as illustrated below.

extexpandpublish.jpg

Back to Topics

Once you obtain authoring permissions, sign into VSAC with your UMLS account.

sign in
  • Select the Authoring tab.
  • Select the group existing value set definitions (grouping) option in the definition method drop-down menu.
grouping value set navigation

A tab entitled, New Def… appears. Under that tab, there are three sub tabs: Metadata, Definition, and Expansion/Publication. You will need to complete the information in each sub tab sequentially:

  1. the Metadata sub tab
  2. the Definition sub tab
  3. the Expansion/Publication sub tab, if needed

Three tabs under new value set

Add Metadata

Mandatory fields : OID, Name, Author, Steward, Purpose fields

OID
  • Object Identifier (OID) Assignment - we recommend the auto generate default setting in which VSAC automatically generates an OID for your value set once you have entered all the information in the other fields, and have selected the "Save" button. If the automatic OID assignment does not meet your purpose, you will need to to enter your own OID manually.
  • Manual Entry of OID (Rare) - The only case in which you should manually enter your own OID is when you have an established pre-existing OID that you have published in another context external to VSAC and the OID is already used by the community, and the value set you create will have the same content and purpose of the pre-existing OID.
    • To manually enter your pre-existing OID, uncheck the Auto Generate box under the OID field, and follow the instructions in the tool tiptoolpitimage.jpgto correctly enter your OID before selecting the Save button.
    • If you need to enter an OID manually, the following rules apply:
      • OID Consists of all digits [1-9] or 0 if a single digit number, but no leading zeros if multiple digit number
      • Numbers may be separated by dots
      • NLM OID name space: Any OID entered MUST NOT start with 2.16.840.1.113 762.1.4
    OID.jpg
Purpose fields

Follow VSAC Authoring Best Practices to write your purpose statements.

Save

When finished entering metadata, click the "Save" button.

groupingmetadata.jpg

Create Definition

  1. Select value sets or OIDs to add to your value set.
    grpgetcodes.jpg

  2. Select codes to add to your value set.
    1. Enter a term or code to search for codes in code system.
    2. Add selected codes to a value set.
    3. Save the value set definition.
  3. Submit the value set to the steward to approve or reject.
    grpsubmit.jpg

When the steward approves the value set definition, you value set is in Ready to Publish status. VSAC will publish a snapshot/temporary expansion, called Latest, of the definition at midnight based on the most recent code system. VSAC will publish subsequent "Latest" expansions when code systems update.

Expand/Publish Value Set

If you require non-default expansion settings, like a specific code system version (Setting A Example), or a date for expansion (Setting B Example) proceed to the Expansion/Publication sub tab after you have submitted, saved, and you or the steward has approved your value set definition. Make the selections for the non-default expansion settings as illustrated below.

grpexpandpublish.jpg