FHIR🔥 API Extensions

Boosting

The Extension URI http://ontoserver.csiro.au/profiles/boost can be added to the ValueSet.compose.include element to adjust the ranking up (value > 1.0) or down (value < 1.0) of codes when performing an $expand with filter.

For example, consider the following example ValueSet which includes AMT codes for “Trade Product Packs”, “Medicinal Product Packs”, and “Trade Products” - ie branded medications, unbranded medications, and simple brands.

{
   "resourceType" : "ValueSet",
   "url" : "http://csiro.au/example/ValueSet/drugs",
   "compose" : {
      "include" : [ {
         "system" : "http://snomed.info/sct",
         "filter" : [
            { "property" : "concept", "op" : "is-a", "value" : "30560011000036108" }
         ]
      }, {
         "system" : "http://snomed.info/sct",
         "filter" : [
            { "property" : "concept", "op" : "is-a", "value" : "30404011000036106" }
         ]
      }, {
         "valueSet": [ "http://snomed.info/sct?fhir_vs=refset/30513011000036104" ]
      } ]
   }
}

Now, we really want people to be as specific as possible when recording medication, so we prefer branded things over unbranded things over brands. This means we'd like this preference to be accounted for when ranking the matching codes in a ValueSet/$expand?filter=... operation. (The value for the filter parameter would be a search string entered by the user.)

We can achieve this by adding the following “boost” extension to the ValueSet.compose.include clauses. Then after Ontoserver has computed a ranking score for each concept, it is scaled by the appropriate factor depending on which clause matched the concept.

Note that the scaling factors here are somewhat arbitrary. In this case they are large, so have a big impact on scoring to the extent that the three clauses are likely scored in completely disjoint ranges. For boost values closer to 1, the effect is more subtle. Determining the best values is somewhat of an experiemental art.

{
   "resourceType" : "ValueSet",
   "url" : "http://csiro.au/example/ValueSet/boost1",
   "compose" : {
      "include" : [ {
         "system" : "http://snomed.info/sct",
         "filter" : [
            { "property" : "concept", "op" : "is-a", "value" : "30560011000036108" }
         ]
         // Reduce the significance of codes matching this filter
         "extension" : [ {
            "url" : "http://ontoserver.csiro.au/profiles/boost",
            "valueDecimal" : 0.01
         } ]
      }, {
         "system" : "http://snomed.info/sct",
         "filter" : [
            { "property" : "concept", "op" : "is-a", "value" : "30404011000036106" }
         ]
         "extension" : [ {
            // Increase the significance of codes matching this filter
            "url" : "http://ontoserver.csiro.au/profiles/boost",
            "valueDecimal" : 10.0
         } ]
      }, {
         "valueSet": [ "http://snomed.info/sct?fhir_vs=refset/30513011000036104" ],
         "extension" : [ {
            // Increase the significance of codes in the imported ValueSet, but not by as much as the above
            "url" : "http://ontoserver.csiro.au/profiles/boost",
            "valueDecimal" : 5.0
         } ]
      } ]
   }
}

The x-boost $expand Parameter

As an alternative (or in addition) to embedding boost extensions in the ValueSet definition, Ontoserver supports an x-boost parameter on ValueSet/$expand. This is useful when the boosting is call-site specific (e.g. based on the current user, clinical context, or previously used codes) and so cannot be baked into the ValueSet itself.

The x-boost parameter is a string of the form value;URI, where:

  • value is a decimal boost factor (as with the extension above - > 1.0 increases ranking, < 1.0 decreases it), and
  • URI is the canonical URL of a ValueSet whose members should have their scores scaled by value when they appear in the expansion of the target ValueSet.

The parameter may be repeated to apply multiple boosts against different ValueSets.

For example, to expand a ValueSet http://example.org/vs/drugs while boosting the scores of any codes that also appear in http://example.org/vs/preferred-drugs by a factor of 10:

GET [base]/ValueSet/$expand?url=http://example.org/vs/drugs&filter=asp&x-boost=10;http://example.org/vs/preferred-drugs

Or via POST:

{
   "resourceType" : "Parameters",
   "parameter" : [
      { "name" : "url",     "valueUri"    : "http://example.org/vs/drugs" },
      { "name" : "filter",  "valueString" : "asp" },
      { "name" : "x-boost", "valueString" : "10;http://example.org/vs/preferred-drugs" }
   ]
}

If the referenced boost ValueSet cannot be resolved, the operation returns a ResourceNotFound error. If the parameter value is not of the form value;URI, the operation returns an IllegalArgument error.