Logical models in FHIR

So one of the capabilities that has been added to FHIR reasonably recently is the capability to use the conformance infrastructure (like StructureDefinitions, ValueSets etc) to produce logical models – rather than defining resource types and such like.

The purpose of the logical model is to gather requirements from clinicians and other folk that can subsequently feed into the design process for profiles and Implementation Guides. While it’s possible to create profiles directly during this process (and one of the goals of clinFHIR is to support this) – there’s no doubting that it does require some understanding of FHIR and the structure/purpose of the existing resource types, so the Logical Model ‘bridges the gap’ by documenting the requirements in a computable fashion without placing any constraints on the model structure.

Because it is computable, it makes the task of generating the formal profiles that much simpler (and recall that a single Logical model may result in multiple profiles – in fact it’s closer to an Implementation Guide) – and also enables the creation of specialized tools like the clinFHIR Logical Modeler that this post describes to create the model in the first place. It also makes it simpler to generate examples, which are both helpful for understanding the domain, but also for testing the model.

So the overall flow from requirement to Implementation Guide would be as follows:

1. Build the Logical Model. This requires significant interaction with the clinical and business community – multiple meetings and refinement of the model, but should require minimal knowledge of FHIR (though a certain amount is needed – like an understanding of the datatypes). An output of this stage would be the Logical Model and the ValueSets required (or at least their identification)
2. Generate the Implementation Guide that has all the FHIR artifacts such as Profiles and the ones generated in the first step (e.g. ValueSets). This step will require better understanding of FHIR – but at the ‘business’ level rather than deep technical level so should be well within the capabilities of Business Analysts and motivated clinicians.

With that background, let’s take a look at the new  clinFHIR Logical Modeler.

(Currently it will only work against Grahames STU-3 server (as it uses some of the newest conformance resource change) so if you select that server as the conformance server, you’ll find a link to the modeler in the ‘gear’ menu.)

When the modeler loads, it will read all existing models from the server and present them in the list. Selecting one of them will display the main screen:

(This model is the openEHR Blood Pressure archetype adapted (mostly) to the logical model structure).

There are 3 main panes:

• To the left is the model selector – currently this will show all models on the server
• In the middle is the editing pane.
• To the right is the details pane – the model and the currently selected element.

Most of the action is in the editing pane, which has 5 tabs:

• The Designer shows a tree view of the model. Selecting an element will show the details of that element in the details pane. The tree can be expanded and collapsed as required.
• The Mind Map (technically it’s more of a graph, but I’ve been told that clinicians will better understand what a Mind Map is than a graph) gives a hierarchical representation of the components of the model. Like the designer, you can select a node and see the details in the detail pane. You can click and drag nodes, and move/zoom the graph as well.
• The Table lists each element in a row. It’s similar to the designer, but is a more compact representation. Again you can select an element to see the details of that element.
• The Json tab shows the StructureDefinition resource that holds the details of the Model. Useful if you want to know the details of the FHIR representation, but intended for geeks rather than ordinary folk.
• And finally the TreeData tab is really only for me during development of the tool. It will probably disappear in due course.

Here’s what the MindMap looks like:

And here’s the Table:

As described above, the Details tab has 2 main parts.

At the top are details about the overall model. This has 2 tabs:

• The Summary tab has the model details. You can edit them by clicking the edit tab to the upper right (There’s not a lot of information right now – that will likely change).
• The History tab will show previous versions of the model. Each version shows when it was created. If you select one of these versions, then the details of that version are displayed in the Editing pane, and you can view the details as you would a Model being edited (though the editing options are disabled). There’s a notification above the Editing pane that tells you that you are viewing history, and gives you 2 options:
  • ‘Back to Current’ re-loads the Model you were editing before you viewed the history (and re-enables editing)
  • ‘Revert to this version’ will make this version the current one. It’s useful if you’ve gone down the wrong track and want to go back to a previous version.

Below this is the details of the selected element. It also has 2 parts:

• The value for the main elements (description, comments, datatype etc.)
• Action links that apply to this element. These include:
  • Up arrow. Moves the selected element (and its children) higher in the hierarchy (unless it is already at the top)
  • Down arrow. Moves the selected element (and its children) downthe hierarchy (unless it is already at the bottom). There still appears to be some flakiness about these movement options – they are surprisingly tricky to implement.
  • Edit Element. Display the edit screen for this element and allows you to make changes
  • Add Element. Allows you to add a child element to this one. Uses the element edit screen to get the details
  • Remove Element. Removes this element – and all the child elements as well.

Note that the action links will work for the different views in the Editing pane (Designer, Mind Map & Table) – and all views will be updated in real time with edits as they occur.

Here’s the new and edit element screen:

The ‘eye’ icon to the right of the dataType dropdown will show the details of that datatype in the spec.

If you make a change to the model, a ‘Save’ button will appear in the Designer tab. Clicking that will save a new version of the model, but you can carry on editing. As you can always revert to a previous version, this means you can do ‘what if’ changes, and then easily revert. If there are errors during saving, then an error tab will appear in the Editing pane. More advanced users can use that to fix errors. It is suggested that you save frequently.

To create a new model, click the ‘New Model’ link in the left pane and the model details screen is displayed:

Enter a name for the model – it needs to be a single word and not too long, then click the ‘Check button’. ClinFHIR will make sure that there isn’t already a model with that name – if there is you’ll get a warning, if not then the Save button will appear and you can enter the remaining information and save.

So there’s probably a few more things to do before this becomes a useful tool.

• The UI needs refinement – which will probably only become apparent after use. For example, it’d be nice to be able to hide the model selector to give more space to the editor tabs, and the mind map definitely needs some UX love.
• Each element can only have a single datatype – we need to allow multiple types. There are other elements we need to capture as well – for example the ‘units’ for a quantity, or the system for an Identifier
• We need the ability to reference between models – that way you could have common models that can be re-used like a custom patient or provider.
• A library of common sub-models to jump start design. These would be incorporated into the model.
• Generating the Implementation Guide from the model. This is a biggie, and unlikely to ever be fully automated, but there are ways to make it easier. For example you could indicate in the model what conformance artifact (and path) that it would map to, and then use Grahames declarative mapping tooling to generate the IG (including profiles and extension definitions).
• The ‘security’ definately needs enhancement. Currently anyone can update any model so we probably need to think in terms of ‘projects’ that ‘own’ a model and can update it. Likely we’ll have the concept of ‘editors’ – specific people who can udpate models, but it would be nice if anyone can copy a model and then adapt that to their needs. Even nicer would be the ability to ‘merge’ models – picking branches from multiple models to create a new one.
• The ‘social’ aspect could also use a bit of attention. While I’m imagining that you could use the tool in a meeting to document the discussion, it would be nice for people to make comments at any time from anywhere. Some kind of threaded conversation attached to a model element would be nice.

But it’s a start.