One of the things that I feel is missing from FHIR documentation is a UML-like diagram of the Resources and their relationships to each other. With over 100 resources, this is rather challenging to produce. Fortunately, due to the data driven nature of FHIR development, the production can be automated using layout tools like GraphViz (Grahame had a love-hate relationship with GraphViz during early FHIR development, which resulted in him using something else).
What I did was create an XSLT which produced a graphviz input file after processing all of the FHIR StructureDefinition inputs. To create a single XML file, I cheated a bit, and simply ran:
c:\build\publish> for /r %f in (*.profile.xml) type %f >>all.fhir.xml
After that, I edited all.fhir.xml and stripped all the extra XML declarations, and wrapped it in an element named FHIR (in the FHIR namespace). There are other ways to do that to automate that, but this was simple and easy. Note: The output will include some things that may have been part of the FHIR Build, but not part of the specification (e.g., Account in STU2). I dealt with that in a later step.
After that, I used a number of different layouts supported by GraphViz to see which worked. Just using the basic options produces a drawing about 30" x 150". That's not really easy to use. The best layout I could find was sfdp, which produces a clustered layout based on edge weights, using a force dependent spring model. The layout stilled looked dramatically ugly because the lines overlap the nodes, so I set the edges up to use orthogonal connectors.
That looked close enough to be useful, so the next thing I did was to color code the nodes based on the Resource categorization used on the Resources page. Clinical resources took on a range of purple colors (by subcategory), identification resources were red, workflow became cyan, infrastructure blue, conformance various shades of gray, and finance was green. The colors helped me to understand how things were clustering in the diagram, so that I could possibly hand tune it.
I plan on doing hand tuning with a graphics editing tool. Right now I'm checking out GraphVizio, a Visio plugin that lets me import GraphViz drawings. Running the compute on the graph through Visio is something that is worthy of a long coffee break (actually, the same is true for the various layout methods). I'm hoping Visio gets out of my way long enough to make this a worthwhile exercise, otherwise, I may have to revert to some other drawing tools. I still don't like all the stuff Visio added for connecting stuff. As soon as I move something a bit, it auto-reroutes stuff I've carefully positioned, screwing things up again. I haven't played around with it long enough to figure out how to turn that off.
While I'm messing around with the diagram, I thought I'd show my initial progress:
As you can see, there's still a ways to go. The diagram is still way too big, and you cannot even zoom it large enough to read. What is interesting is that in fact, the FHIR Resources do tend to cluster, and Patient, Practitioner, and RelatedPerson find themselves at the center of care, just like you might expect.
What I did was create an XSLT which produced a graphviz input file after processing all of the FHIR StructureDefinition inputs. To create a single XML file, I cheated a bit, and simply ran:
c:\build\publish> for /r %f in (*.profile.xml) type %f >>all.fhir.xml
After that, I edited all.fhir.xml and stripped all the extra XML declarations, and wrapped it in an element named FHIR (in the FHIR namespace). There are other ways to do that to automate that, but this was simple and easy. Note: The output will include some things that may have been part of the FHIR Build, but not part of the specification (e.g., Account in STU2). I dealt with that in a later step.
After that, I used a number of different layouts supported by GraphViz to see which worked. Just using the basic options produces a drawing about 30" x 150". That's not really easy to use. The best layout I could find was sfdp, which produces a clustered layout based on edge weights, using a force dependent spring model. The layout stilled looked dramatically ugly because the lines overlap the nodes, so I set the edges up to use orthogonal connectors.
That looked close enough to be useful, so the next thing I did was to color code the nodes based on the Resource categorization used on the Resources page. Clinical resources took on a range of purple colors (by subcategory), identification resources were red, workflow became cyan, infrastructure blue, conformance various shades of gray, and finance was green. The colors helped me to understand how things were clustering in the diagram, so that I could possibly hand tune it.
I plan on doing hand tuning with a graphics editing tool. Right now I'm checking out GraphVizio, a Visio plugin that lets me import GraphViz drawings. Running the compute on the graph through Visio is something that is worthy of a long coffee break (actually, the same is true for the various layout methods). I'm hoping Visio gets out of my way long enough to make this a worthwhile exercise, otherwise, I may have to revert to some other drawing tools. I still don't like all the stuff Visio added for connecting stuff. As soon as I move something a bit, it auto-reroutes stuff I've carefully positioned, screwing things up again. I haven't played around with it long enough to figure out how to turn that off.
While I'm messing around with the diagram, I thought I'd show my initial progress:
As you can see, there's still a ways to go. The diagram is still way too big, and you cannot even zoom it large enough to read. What is interesting is that in fact, the FHIR Resources do tend to cluster, and Patient, Practitioner, and RelatedPerson find themselves at the center of care, just like you might expect.
Teaser... How about dropping out the FMM 0 resources?
ReplyDeleteYour diagram looks about as useful as most other attempts. Which is why I haven't invested significant time in this
ReplyDeleteThanks!
ReplyDelete