diff --git a/examples/qoc_indicatorset.1.json b/examples/qoc_indicatorset.1.json index f64ddbd..3041567 100644 --- a/examples/qoc_indicatorset.1.json +++ b/examples/qoc_indicatorset.1.json @@ -1,125 +1,127 @@ { - "key": "ZOO-dm", - "name": "Diabetes Mellitus type 2", - "refDate": "2023-07-01", - "chapters": [ - { - "title": "Opbouw DM ketenzorg patiënten", - "indicators": [ - [ - { - "key": "ZOO-dm-prevalentie-1", - "title": "Prevalentie DM", - "index": 1, - "xMin": 0, - "xMax": 10.5, - "xLow": { - "pos": 2.0, - "legend": "2.0%" - }, - "xHigh": { - "pos": 8.2, - "legend": "8.2%" - }, - "style": "met", - "bars": [ - { - "legend": "Praktijk 2023Q3", - "value": 2818, - "parts": [ - { - "style": "concern", - "width": 9.297374, - "value": 262 - } - ] - }, - { - "legend": "ZEL 2023Q3", - "value": 325123, - "parts": [ - { - "style": "good", - "width": 4.919984, - "value": 15996 - } - ] - } - ] - } - ], - [ - { - "key": "ZOO-dm-prevalentie$-1", - "title": "DM types", - "basedOn": "ZOO-dm-prevalentie-1", - "index": 2, - "xMin": 0, - "xMax": 100, - "style": "normal", - "legend": { - "cat1": "T1", - "cat2": "T2", - "problem1": "Beide", - "problem2": "Onbekend" - }, - "bars": [ - { - "legend": "Praktijk 2023Q3", - "value": 262, - "parts": [ - { - "style": "cat1", - "width": 11.068702, - "value": 29 - }, - { - "style": "cat2", - "width": 86.64122137, - "value": 227 - }, - { - "style": "problem1", - "width": 2.29007634, - "value": 6 - }, - { - "style": "problem2", - "width": 0, - "value": 0 - } - ] - }, - { - "legend": "ZEL 2023Q3", - "value": 15996, - "parts": [ - { - "style": "cat1", - "width": 9.00225056, - "value": 1440 - }, - { - "style": "cat2", - "width": 86.996749, - "value": 13916, - }, - { - "style": "problem1", - "width": 2.313078, - "value" 370 - }, - { - "style": "problem2", - "width": 1.68792198, - "value": 270 - } - ] - } - ] - } - ] - ] - } - ] + "key": "ZOO-dm", + "name": "Diabetes Mellitus type 2", + "refDate": "2023-07-01", + "chapters": [ + { + "title": "Opbouw DM ketenzorg patiënten", + "indicators": [ + [ + { + "key": "ZOO-dm-prevalentie-1", + "title": "Prevalentie DM", + "index": 1, + "xMin": 0, + "xMax": 10.5, + "xLow": { + "pos": 2.0, + "legend": "2.0%", + "kind": "deviation" + }, + "xHigh": { + "pos": 8.2, + "legend": "8.2%", + "kind": "deviation" + }, + "style": "met", + "bars": [ + { + "legend": "Praktijk 2023Q3", + "value": 2818, + "parts": [ + { + "style": "concern", + "width": 9.297374, + "value": 262 + } + ] + }, + { + "legend": "ZEL 2023Q3", + "value": 325123, + "parts": [ + { + "style": "good", + "width": 4.919984, + "value": 15996 + } + ] + } + ] + } + ], + [ + { + "key": "ZOO-dm-prevalentie$-1", + "title": "DM types", + "basedOn": "ZOO-dm-prevalentie-1", + "index": 2, + "xMin": 0, + "xMax": 100, + "style": "normal", + "legend": { + "cat1": "T1", + "cat2": "T2", + "problem1": "Beide", + "problem2": "Onbekend" + }, + "bars": [ + { + "legend": "Praktijk 2023Q3", + "value": 262, + "parts": [ + { + "style": "cat1", + "width": 11.068702, + "value": 29 + }, + { + "style": "cat2", + "width": 86.64122137, + "value": 227 + }, + { + "style": "problem1", + "width": 2.29007634, + "value": 6 + }, + { + "style": "problem2", + "width": 0, + "value": 0 + } + ] + }, + { + "legend": "ZEL 2023Q3", + "value": 15996, + "parts": [ + { + "style": "cat1", + "width": 9.00225056, + "value": 1440 + }, + { + "style": "cat2", + "width": 86.996749, + "value": 13916 + }, + { + "style": "problem1", + "width": 2.313078, + "value": 370 + }, + { + "style": "problem2", + "width": 1.68792198, + "value": 270 + } + ] + } + ] + } + ] + ] + } + ] } diff --git a/schemas/Indicator.yaml b/schemas/Indicator.yaml index 9d77e63..7462f00 100644 --- a/schemas/Indicator.yaml +++ b/schemas/Indicator.yaml @@ -25,25 +25,66 @@ properties: type: number example: 1 xMin: - description: Numeric value of the far left of the bar. + description: |- + Numeric value of the far left of the bar; represents a percentage (i.e. 0-100). + Most indicators range from 0% to 100%, but for some, where the values to be shown represent only a small percentage, + the bar is 'zoomed in'; it represents only a slice of the total range. type: number example: 10.0 default: 0 xMax: - description: Numeric value of the far right of the bar. + description: |- + Numeric value of the far right of the bar; represents a percentage (i.e. 0-100). + Most indicators range from 0% to 100%, but for some, where the values to be shown represent only a small percentage, + the bar is 'zoomed in'; it represents only a slice of the total range. type: number - example: 80.0 + example: 20.0 default: 100.0 xLow: description: |- - *OPTIONAL* If present, draw a bar at this position indicating that this indicator can fall below this lower bound, but if it does, that is noteworthy. For example, because that is beyond 3 standard deviations of the dutch average, or, its a goal set by the practice, the insurer, or the care group and thus falling below it means the goal is not met. - type: number - example: 20.0 + *OPTIONAL* If present, draw a marker at this position indicating a lower bound. Values can be below it, but that is noteworthy, for example + because that deviates far from national averages, or this bound represents a goal set by the practice/insurer/care group and falling below it + means the goal is not met. + type: object + properties: + pos: + description: The percentage at which the marker is to be drawn. + type: number + example: 14.0 + legend: + description: A very short (dutch, *HTML*) description of what this marker represents. + type: string + example: "14%" + kind: + description: |- + What kind of bound is represented.
+
deviation
+
This marker represents X standard deviations above/below expected outcomes. Common for e.g. prevalence of a chronic illness.
+
goal
+
This marker represents a goal, for example, You should measure blood pressure for at least this % of your managed diabetes patients.
+
+ type: string + example: deviation + enum: + - deviation + - goal xHigh: description: |- - *OPTIONAL* If present, draw a bar at this position indicating that this indicator can fall above this upper bound, but if it does, that is noteworthy. For example, beyond 3 standard deviations of the dutch average, or, a goal for an indicator where lower is better. - type: number - example: 65.0 + Like `xLow`, but representing a higher limit instead (expectation is that nominal values would be _below_ this limit). + type: object + properties: + pos: + type: number + example: 18.0 + legend: + type: string + example: "18%" + kind: + type: string + example: deviation + enum: + - deviation + - goal unitDesc: description: |- *OPTIONAL* describes the unit that the stated legend values are in, in dutch, and *HTML*. For example, if showing blood pressure, `mmHg`. If missing, treat as the empty string (do not show unit at all). @@ -65,34 +106,77 @@ properties: - normal - met - focus + legend: + description: >- + *OPTIONAL* If present, render a legend box with the cart explaining what each kind of part (see `bars > parts`) represents. + Each key/value pair in this object maps a style (as used `bars > parts > style`) onto a very short, dutch, *HTML* description. + type: object + example: |- + { + "serious": "≥140", + "concern": "120-140", + "good": "≤120" + } bars: - description: |- - A series of numbers, each of which needs to be put on the bar in sequence. For some indicators, the sum of the values adds up to be equal to `xMax - xMin`, if it doesn't, the final part of the bar remains blank (white, for example). For example, given the usual xMin/xMax of 0/100, one could have 3 bars: 40-Good, 35-Concern, 25-Problematic. Which should be rendered as green/yellow/red sub-bars of the appropriate size across the indicator. type: array items: + description: >- + Each bar describes the calculated result for one entity at one measurement date. For example, an indicator box could contain 3 such entries: + + There is always at least one. The first one is the main bar, that is, what this report is reporting on; all further bars exist solely + to provide context. type: object properties: - style: - description: |- - Describes what kind of ratio this bar describes. - Individual bars represent some kind of ratio and this describes the nature of it. Each key should result in some style, generally, the color of the bar. For example, `serious` (indicating a group of patients whose lab result for this indicator is of serious concern, i.e. medically speaking quite bad news) should be rendered dark red. - type: string - example: concern - enum: - - good - - concern - - problem - - serious - - measured - - nonPrefMeasured - - 'TBD: There are many more.' legend: description: |- - *OPTIONAL* If present, render the title of this one bar like a legend for a chart. In dutch, *HTML*, and very short. + A short *HTML* (dutch) description of the entity+measurement date represented by this bar. + If only one bar is provided, can be blank. type: string - example: '≤ 120' + example: Praktijk 2023Q3 value: - description: |- - The 'size' of the described ratio. Relative to the range of the bar (as described by `xMax`-`xMin`). + description: >- + *OPTIONAL* A number indicating the absolute value of what the entire bar represents. For example, if the bar represents + the number of patients included in the diabetes care program that have a recent blood pressure value, this value would + contain the total number of patients included in the care program, which serves as the divisor for this indicator. type: number - example: 20.5 \ No newline at end of file + example: 262 + parts: + type: array + items: + description: >- + Each part represents a slice of the total population. For example, those patients in the diabetes care program with + a recent blood pressure measurement registration, or, for an indicator showing the distribution of blood pressure + values amongst those with a recent registration, the number of patients whose BP measurement is of serious health concern. + + For example, there could be 3 parts: 40-Good, 35-Concern, 25-Problematic. + + Place each part in sequence in the bar. They are guaranteed to fit. The values for each part are relative to `xMin`/`xMax`, e.g. + a percentage. + type: object + properties: + style: + description: |- + Describes what kind of ratio this part describes. + Each part represents some kind of ratio and this describes the nature of it. Each key should result in some style, generally, the color of the bar. For example, `serious` (indicating a group of patients whose lab result for this indicator is of serious concern, i.e. medically speaking quite bad news) should be rendered dark red. + type: string + example: concern + enum: + - good + - concern + - problem + - serious + - measured + - nonPrefMeasured + - 'TBD: There are many more.' + width: + description: The size of this part, in percentages (i.e. relative to `xMin`-`xMax`). + type: number + example: 11.068702 + value: + description: The absolute value (representing a number of patients), relative to the bar's `value` property. + type: number + example: 29