ValueSet editor in clinFHIR

I’ve been working on the profiling abilities of clinFHIR recently. As I’ve said before, although there is the official tool for creating profiles – Forge – I think there is a place for a simple profiling tool primarily aimed at clinicians, with the goal to help them understand how FHIR profiling works.

One of the big things that keeps coming up is ValueSets – and how to create them.

As a short recap – recall that the purpose of profiling is to take the core resources and make them more suitable for real-world Use Cases by adding new elements (extensions) and removing the ones that are not needed. As part of this process you often want to specify a particular set of values for coded elements that is different to the one in the spec and the ValueSet is the mechanism that you use to specify those. The problem is that there isn’t currently any widely available tooling to create ValueSets (outside of the tooling used to build the specification itself) – especially ones for clinicians to use, so over the weekend I decided to write a simple ValueSet Editor.

Like the profiling in clinFHIR – the ValueSet Editor is intended to allow the creation of simple valueSets rather than as a comprehensive tool. At the moment, a number of the functions are really geared towards SNOMED – although it should work with other terminologies (if supported by the terminology server). It will allow you create a ValueSet and to edit them – but won’t allow you to edit other ValueSets – eg ones from the spec – for fairly obvious reasons. But you can make a copy of these and edit those if you want to use them as a starting point for your own.

Having selected the editor, the first thing to do is to select the Terminology server where you want the ValueSet to be saved. This is displayed in the menu bar at the top of the screen. The editor does require that the server implement a number of the STU-3 terminology services – namely:

• Concept lookup – used when viewing the hierarchy of concepts
• ValueSet expansion – used to find a concept by name.

(Having said that – at the moment the only server that supports v3 of terminology services that I am aware of is Grahames server. But hopefully there will be more available shortly!)

Once the Terminology server has been selected, you can either view existing ValueSets on that server (either just to have a play with them or to use them as the basis for your own ValueSet) or go straight ahead and create your own from scratch.

To view an existing ValueSet, enter some filter text (like ‘condition’) into the search box and click the ‘find’ link. Matching ValueSets (based on the ValueSet name) will be listed and you can either preview them (which shows the Json representation of the ValueSet resource) or select them – which will take you to the editor – though in a View mode initially. Here’s a screen shot with a ValueSet previewed.

The Editor is where the action is, and is displayed when you ‘select’ a ValueSet (or create/edit one as we will see shortly.

On the left side are 4 tabs.

• The Contents tab shows the concepts that are included in this ValueSet. There are 2 types that are supported by the tool – either a list of specific concepts, or a filter that describes a SNOMED ‘is-a’ relationship. (We’ll see how to find these in a minute)
• The Description tab shows information about the ValueSet – the description, requirements, publisher and the like. You can update this data when creating a new ValueSet (or editing an existing one) – otherwise it’s read only.
• The Expansion tab allow you to perform an expansion against the ValueSet – this is the same that occurs in the resource builder – you enter in some search text and the Terminology server then ‘expands’ the contents of the ValueSet – finding all the concepts whose display matches the text you entered. This is a really great way of testing the ValueSet. Note that the expansion occurs against the copy of the ValueSet on the server, so if you make any changes then save them first!
• The JSON tab simply displays the Json view of the ValueSet – same as the ‘preview’ when performing the search.

Here’s an example:

This shows one of my test ValueSets containing 3 specified concepts, plus an ‘is-a’ concept – which we’ll discuss in a minute.

The right hand side (which is empty in the example above) is where you can add concepts to a ValueSet you are able to update – so let’s take a look at how to do that. There are 2 ways: You can make a copy of an existing one, or create a brand new one from scratch. The copy function is convenient – but remember that clinFHIR only supports a small subset of the overall capabilities of ValueSets so if you select one of the more complex ValueSets then there will be functionality that you cannot modify. You’ll be able to see it in the json view, and it will still work (ie expand) – but your ability to make changes is limited.

Both copy and create are activated from buttons in the top right hand side of the menu bar.

• The ‘new‘ button is displayed from the front page
• The ‘copy‘ button is  displayed when an existing ValueSet is being viewed.

In both cases you need to enter a name for the new ValueSet. This name needs to be unique on the terminology server as it will also be the ‘id’ of the ValueSet resource. Enter a name into the dialog that appears after clicking the button, then click the ‘check’ button. If the name is new, then a ‘select’ button appears in the dialog at the top right – otherwise you’ll get an error and need to re-try.

Once a valid name has been selected, then you will be returned to the editor, and this time the ‘add concept’ pane to the right will be displayed.

There are 2 ways to add a new concepts to the ValueSet – and 2 roles that they can fulfill.

• The first role a concept can fulfill is as a simple list of codes. The ValueSet is comprised of that list and you will be able to select one of them in the resource builder
• The second is where the concept acts as an ‘is-a’ filter. When expanded, the list can include the concept and any of its children

To select a concept you can either use the ‘select from binding’ tab or the ‘enter directly’ tab – or a combination of the two. The ‘select from binding’ option is the same as in the resource builder – the terminology server will locate all matching concepts using the expansion against the bound ValueSet. (More on that later).

Heres a view with asthma selected (and note that the selection will auto-populate if you pause for a second – just like the Resource Builder):

The second tab is rather more interesting. This tab allows you to enter the code directly (it is pre-filled when you select a concept from the first tab) – but as well as the details of the selected concept, it will also display the parents and immediate child concepts as well. In addition, the parent and children concepts are clickable – selecting them will then display their immediate relations thus allowing you to traverse up and down the hierarchy.

Here’s a view of the second tab – filled in with values from the first – ie ‘pneumonia’

To add the selected concept to the ValueSet – click on either the “Add” or the “Add as ‘is-a'” buttons. The difference is:

• The ‘Add‘ button adds that single concept only. If the ValueSet as empty then it would only have a single value.
• The “Add as ‘is-a’” button adds the concept as an ‘is-a’ filter. This means that the concept and all its children become part of the ValueSet. In the example above, then the concept ‘Abscess of Lung with pneumonia’ would be a member of the set.

The screen shot above also shows  quite nicely shows how (in SNOMED at least) a concept can have multiple parents – ie it is an ‘is-a’ of multiple things.

So there you go – a simple ValueSet editor, developed to help with Clinician profiling. In the next post, I’ll talk about how it fits in with the enhanced clinFHIR profiling (I just have to finish that first 🙂 )

Hope you find it useful!

Some known issues & notes:

• The tool will automatically add a contact of ‘clinfhir’ to all ValueSets – which is how it recognizes the ones it has created, and will allow to be edited.
• The search works on the name in the ValueSet, so make sure you enter something sensible for that value (on the ‘description’ tab in the editor). It will default to the name entered when the ValueSet is created – which will also be the id on the server.
• When you start the editor, the server name might be ‘undefined’. It will still work OK, but to correct this, start up the Resource Builder, and select ‘reset config’ from the gear menu to the upper right. If you re-load the ValueSet editor, then the name should be ‘Grahames Server’.
• If you’re creating a new ValueSet from scratch – it’s best to reload the application first – just to clear all the internal variables (there are a few gremlins left to swot)
• Every now and the Grahames server gets a ‘deadlock’ error from the database. If you get an error message that mentions this, just try again.
• When you are looking up a concept based on the name (like in Resorce Builder) the tool uses the ValueSet http://hl7.org/fhir/ValueSet/condition-cause as the base – because that just references all of snomed. This is a temporary situation, as I intend to allow you to specify the Root concepts as a way of restricting the search – I just haven’t had a chance to do that yet.