Creating models with the Logical Modeler

It’s been a while since we talked about the clinFHIR Logical Modeler, and I’ve had a few questions about it, so I thought an update might be in order.

The term ‘Logical Model’ can be used in different ways (much like ‘Profile’) so let’s first define just what we are talking about. Basically, it’s just a hierarchical model of data – much like you see in any of the core FHIR resource types – with the exception that the model does not have to align with any of the core types. Other than the requirement that you must use the FHIR datatypes, there are no limits on the complexity of the model you create (though overly complex models can be hard to understand – or use).

In this post we’ll talk about the general aspects of using the modeler – subsequent posts will go into more detail about how to build them.

Technically the modeler creates and updates a StructureDefinition resource, preferably Release 3, though STU2 is also supported. It can be used for a number of purposes, such as:

• An Information model
• A single resource model
• A multi resource model

(Note that these model types are particular to clinFHIR – they are not ‘official’ FHIR terms. And it’s very much a work in progress – comments/suggestions are welcomed!)

The Information Model is used as an analysis tool, to collect requirements from Clinicians about what information is needed to be exchanged in some Use Case, and so is not aligned with any specific resource type. As an example of its use, in New Zealand we have a project to collect information about an Adverse Event which may (or may not) represent a medication allergy. The information is entered by a Practitioner or Patient, and sent to a repository, where it is examined by Subject Matter Experts (eventually AI we hope) to determine if this represents an actual allergy, or whether it has some other cause.

So the data includes things like the reaction/s that occurred, current medications and problem list, and is more than a simple AllergyIntolerance resource.

We first created a model, based on our understanding of the Use Case, then had a face to face meeting with the domain experts where we reviewed the model in real-time (we projected it on a screen), updating it with all the information that the clinical experts felt should be collected. For each element we focused on things like the data type (at a high level – e.g. should a particular element be coded, is it always a number or sometimes text etc.), multiplicity, documentation and possible sources of content for coded elements (which will become ValueSets – sometimes we could already find one).

There was no attempt to align this with FHIR (though at times we did look at core resources when clarifying certain points). Because this was a requirements capture exercise, we made the model in a way that made sense to the Clinician –  for example there was a patient node with demographics, a reporter node, a substance node, a reaction node and so forth.

Note that none of the participants needed to have any particular FHIR knowledge – though understanding the datatypes really helps. We found that the clinicians picked this up pretty quickly, and it was actually a really good way for them to learn more about FHIR resources – and about Terminology, especially ValueSets.

Having done this, the next step was to create a new model that had the same data, but was aligned with FHIR. This step does require FHIR knowledge. In this case, we determined that a FHIR Document was the best way to represent this report, though we considered the QuestionnaireResponse resource. Because this is a Document, which references multiple resources, we decided to create a Multi-Resource model. Had we decided that there was a good match between the information and a single resource type (eg AllergyIntolerance), then we would have created a Single-resource model.

Unlike the Information model, both single and multi resource models are based on a core resource type, and the elements in the model are mapped to specific resource elements (including extensions). In this case we based it on the Composition resource, as we wanted to be able to include all of the ‘referenced’ resources in the same model, and how they were referenced from the Composition.section elements. We also wanted to be able to indicate what elements of those resources we wanted to include, . The idea is that the multi-resource model will identify all of the resource types we need to include in our document – including extensions – in a way that will still be understandable to the Clinicians (they can see all of the data they identified in the Information model) so they can ‘sign off’ that it is correct, but has everything in the right place to allow the FHIR experts to create the profiles that will be needed in the final Implementation Guide.

The layout of the multi-resource model was quite similar to the Information model as it turned out, but we made sure that every element was mapped to a core resource type element (we’ll discuss how to do that in a subsequent post), or to an extension if there was no existing element on the resource we decided on. For example, it was determined that patient ethnicity was required, so we mapped this to an extension, and made a note that it needed to be matched to the New Zealand standard for ethnicities. Of course, the next time we need to do this, this extension will already have been created and we’d be able to map it directly to the relevant extension.

One quirk which is a limitation of the tooling is that when a particular element could be of different resource types (eg the report author could be a Patient or a Practitioner), then we needed a separate element for each one.

Another purpose of this model is to identify all of the coded elements, and the ValueSets that describe the contents. In some cases these already exist (eg from the core spec), and in others there do exist standards that we can use (like the ethnicity example above) but they are not yet in a proper FHIR  ValueSet. So there’s going to be work to create them, but like the extensions some of them will be re-usable in future projects (of course, many will be specific to this project). The nice part about using the model is that it’s easy to identify the ones we need – there’s actually a view in the modeler that lists all the coded elements and the associated ValueSet.

The next step in the project will be to validate the multi-resource model with a wider group – hopefully through a connectathon, and/or the usual public review processes for standards in New Zealand – and then we will be able to create the actual conformance resources we need. This will include profiles for the resource types that we identified, as well as Extensions and ValueSets. We’ll probably have to create them all, but with an eye on re-use for next time.  It’s likely that we’ll use Forge for the Profiles, though it might be possible to use clinFHIR if the profiles are straightforward. (See the section on single resource models for a discussion of this). We’ll likely use clinFHIR for the Extension Definitions.

And, of course, we’ll publish all of our profiles and extension definitions to the FHIR Registry – as well as our own.

Finally, we’ll create an ImplementationGuide that will bind all this together. It would be good to include examples in this guide (maybe created during the connectathon), and we’ll want to reference all of the background material as well.

Whew!

In this example we haven’t yet had the occasion to use the single resource model. The purpose of this type of model is to identify all the components of a profile on a single resource type. Say you wanted to create a profile on Condition to represent a diagnosis in an ED department. Create your model with a base type of Condition. Then remove the elements you don’t want, make changes to existing ones (eg different ValueSet bindings or multiplicity) and add any extensions you need. Provided that your extensions are properly linked to an Extension Definition, then you should be able to create a real profile using the export option in the tab to the top right.

Do note that the profiles are quite simple – it may be better to use clinFHIR to define what you want, then use Forge to actually build it.

So that’s a brief run through of the models you can create with the modeler. To summarize:

• If you want an Information model to capture requirements in an orderly fashion in a way that is easy for domain experts to understand, create a model without a base type, and add whatever nodes and elements you want using FHIR datatypes.
• If you want to take an information model and represent it as real FHIR resources, whether as a document, message or other, then create a model with an appropriate base type (Composition, MessageHeader) and map all the elements to the paths of the resources (we’ll talk about some helpful tips for this in a forthcoming post). Actually, you can still do this without a base resource if you wanted to – it’s not a requirement, though I’m not sure what the use case would be.
• If you want to define a profile on a single resource, then create a model with a base of that type and modify as necessary. The modeler can export a real profile – though limited compared to Forge.

And a reminder that these terms are not official FHIR terms – I’m still trying to figure out the best way to use the app, so any comments appreciated!

In the next post we’ll dig a bit further into the modeler functionality.