diff --git a/examples/qoc_indicatorset.1.json b/examples/qoc_indicatorset.1.json index 3041567..5e5b205 100644 --- a/examples/qoc_indicatorset.1.json +++ b/examples/qoc_indicatorset.1.json @@ -5,7 +5,7 @@ "chapters": [ { "title": "Opbouw DM ketenzorg patiënten", - "indicators": [ + "indicatorGroups": [ [ { "key": "ZOO-dm-prevalentie-1", @@ -13,37 +13,25 @@ "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" - }, + "markers": [2.0, 8.2], "style": "met", + "counts": [232, 2268], "bars": [ { "legend": "Praktijk 2023Q3", - "value": 2818, - "parts": [ + "segments": [ { - "style": "concern", - "width": 9.297374, - "value": 262 + "style": "measured", + "value": 9.28 } ] }, { "legend": "ZEL 2023Q3", - "value": 325123, - "parts": [ + "segments": [ { - "style": "good", - "width": 4.919984, - "value": 15996 + "style": "measured", + "value": 4.919984 } ] } @@ -65,56 +53,47 @@ "problem1": "Beide", "problem2": "Onbekend" }, + "counts": [25, 199, 8, 0], "bars": [ { "legend": "Praktijk 2023Q3", - "value": 262, - "parts": [ + "segments": [ { "style": "cat1", - "width": 11.068702, - "value": 29 + "value": 10.775862 }, { "style": "cat2", - "width": 86.64122137, - "value": 227 + "value": 85.775862 }, { "style": "problem1", - "width": 2.29007634, - "value": 6 + "value": 3.448276 }, { "style": "problem2", - "width": 0, "value": 0 } ] }, { "legend": "ZEL 2023Q3", - "value": 15996, - "parts": [ + "segments": [ { "style": "cat1", - "width": 9.00225056, - "value": 1440 + "value": 9.00225056 }, { "style": "cat2", - "width": 86.996749, - "value": 13916 + "value": 86.996749 }, { "style": "problem1", - "width": 2.313078, - "value": 370 + "value": 2.313078 }, { "style": "problem2", - "width": 1.68792198, - "value": 270 + "value": 1.68792198 } ] } diff --git a/paths/qoc_indicatorset_{setKey}.yaml b/paths/qoc_indicatorset_{setKey}.yaml index d91648d..f7fe9a6 100644 --- a/paths/qoc_indicatorset_{setKey}.yaml +++ b/paths/qoc_indicatorset_{setKey}.yaml @@ -9,7 +9,7 @@ get: required: true schema: type: string - example: ZEL-dm2 + example: ZEL-dm - name: refDate in: query description: |- diff --git a/schemas/Indicator.yaml b/schemas/Indicator.yaml index 7462f00..923819b 100644 --- a/schemas/Indicator.yaml +++ b/schemas/Indicator.yaml @@ -1,5 +1,3 @@ -description: |- - A single ratio or flat number; should be shown as one box with a chart (generally, a single fixed-size bar with each ratio element rendered on this bar). The numbers in this object are on some axis, generally, percentage. type: object properties: key: @@ -40,51 +38,16 @@ properties: type: number example: 20.0 default: 100.0 - xLow: + markers: description: |- - *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: |- - 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 + A marker is rendered on the percentage bar and represents a noteworthy boundary, for example, for a prevalence indicator, + one standard deviation up, respectively down, from the average, to provide context. Or, a goal as set forth by a zorggroep + or national standards body e.g. for how many diabetes patients should have a recent HbA1c measurement. If the indicator itself + is shown as a horizontal bar, this would be a small vertical line rendered on top of it. + type: array + items: + type: number + example: [25, 80] 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). @@ -106,10 +69,18 @@ properties: - normal - met - focus + counts: + description: >- + *OPTIONAL* If present, the actual values (i.e. number of patients) for each segment of the main bar; if the bar is not complete + (the values do not add up to 100), an extra value is included representing this remainder. + type: array + items: + type: number + example: [11, 157, 0, 2] 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. + *OPTIONAL* If present, render a legend box with the card explaining what each kind of segment (see `bars > segments`) represents. + Each key/value pair in this object maps a style (as used in `bars > segments > style`) onto a very short, dutch, *HTML* description. type: object example: |- { @@ -133,35 +104,32 @@ properties: properties: legend: description: |- - A short *HTML* (dutch) description of the entity+measurement date represented by this bar. - If only one bar is provided, can be blank. + *OPTIONAL* A short *HTML* (dutch) description of the entity+measurement date represented by this bar. + If only one bar is provided, can be missing (no legend is needed). type: string example: Praktijk 2023Q3 - value: - 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: 262 - parts: + default: '' + segments: type: array items: description: >- - Each part represents a slice of the total population. For example, those patients in the diabetes care program with + Each segment represents a slice of the measured 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 segment in sequence in the bar. They are guaranteed to fit. The values for each part are relative to `xMin`/`xMax`, e.g. + a percentage. They may not add up to 100 - in that case, leave the remainder blank. - 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. + For example: 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. + Describes what kind of ratio this segment describes. + Each segment represents some kind of ratio and this describes the nature of it. Render the segment according to its style. 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) could be rendered dark red. type: string example: concern enum: @@ -172,11 +140,9 @@ properties: - 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. + description: |- + The value (in percent). For example, if `xMin` is 10, `xMax` is 40, and this is 20, render this segment at 33% of + the total length (because 20 is a third of the way in, in the range 10-40). type: number - example: 29 + example: 29.72 diff --git a/schemas/IndicatorSet.yaml b/schemas/IndicatorSet.yaml index 285c60e..993a964 100644 --- a/schemas/IndicatorSet.yaml +++ b/schemas/IndicatorSet.yaml @@ -26,10 +26,10 @@ properties: description: In dutch, *HTML* formatted; should fit on one line. type: string example: Populatie - indicators: + indicatorGroups: description: |- A chapter contains 1 or more indicator groups. An indicator group is an array of indicators which should - always be shown together; they are each other's context. These arrays are not empty, but often contain + always be shown together; they are each other's context. These arrays are never empty, but often contain just one indicator. It is extremely rare for such a set to contain more than 2. type: array items: