Skip to content

Commit 12a4c4b

Browse files
mbaudismbaudis
committed
Documentation & examples
This commit * creates a documentation page for structure & use of aggregations * aligns the aggr1-4 examples across different documents Update aggregations.md Update aggregations.md
1 parent 7d361a9 commit 12a4c4b

12 files changed

Lines changed: 686 additions & 180 deletions

File tree

‎docs/aggregations.md‎

Lines changed: 490 additions & 3 deletions
Large diffs are not rendered by default.

‎framework/json/requests/examples-sections/aggregationTerms-example.json‎

Lines changed: 21 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,21 +4,28 @@
44
{
55
"aggregationTerms": [
66
{
7-
"id": "Sex"
7+
"id": "SexAtBirth"
88
}
99
],
1010
"requestId": "aggr1"
1111
},
1212
{
1313
"aggregationTerms": [
1414
{
15-
"id": "Sex",
15+
"id": "SelectedCarcinomaDiagnoses",
16+
"label": "Selected diagnoses (some carcinoma entities)",
1617
"selectors": [
1718
{
18-
"value": "NCIT:C16576"
19+
"label": "Prostate Adenocarcinoma",
20+
"value": "NCIT:C2919"
1921
},
2022
{
21-
"value": "NCIT:C20197"
23+
"label": "Breast Ductal Carcinoma",
24+
"value": "NCIT:C4017"
25+
},
26+
{
27+
"label": "Lung Adenocarcinoma",
28+
"value": "NCIT:C3512"
2229
}
2330
]
2431
}
@@ -28,10 +35,18 @@
2835
{
2936
"aggregationTerms": [
3037
{
31-
"id": "SexAtBirth"
38+
"id": "SexAtBirth",
39+
"selectors": [
40+
{
41+
"value": "NCIT:C16576"
42+
},
43+
{
44+
"value": "NCIT:C20197"
45+
}
46+
]
3247
},
3348
{
34-
"id": "HistologicalDiagnoses",
49+
"id": "SelectedCarcinomaDiagnoses",
3550
"selectors": [
3651
{
3752
"label": "Prostate Adenocarcinoma",

‎framework/json/responses/beaconAggregationResponse.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"$schema": "https://json-schema.org/draft/2020-12/schema",
3-
"description": "Definition for a response that provides solely summaries of records in the beacon but not delivers individual records. While summaries might be also part of other response types (e.g. result set specific in `beaconResultsetResponse`) this response type specifically focuses on providing aggregated statistics of a beacon resource similarily to the `beaconBooleanResponse` and `beaconCountResponse`.",
3+
"description": "Definition for a response that provides solely aggregations of record properties in the beacon but does not delivers individual records. While aggregations might be also part of other response types (e.g. result set specific in `beaconResultsetResponse`) this response type specifically focuses on providing aggregated statistics of a beacon resource similarily to the `beaconBooleanResponse` and `beaconCountResponse`.",
44
"properties": {
55
"beaconHandovers": {
66
"$ref": "../common/beaconCommonComponents.json#/$defs/ListOfHandovers",

‎framework/json/responses/examples-fullDocuments/beaconAggregationTermsResponse-example.json‎

Lines changed: 86 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -13,36 +13,80 @@
1313
"response": {
1414
"aggregationTerms": [
1515
{
16-
"description": "Aggregation by the karyotypic sex of the individuals. The karyotypic sex is determined by the chromosomal composition of the individual.",
17-
"id": "karyotypicSex",
18-
"label": "karyotypic sex",
19-
"modelProperty": "individual.karyotypicSex"
16+
"id": "SexAtBirth",
17+
"selectors": [
18+
{
19+
"value": "NCIT:C16576"
20+
},
21+
{
22+
"value": "NCIT:C20197"
23+
},
24+
{
25+
"value": "NCIT:C1799"
26+
}
27+
]
2028
},
2129
{
22-
"description": "Aggregation by the sex ploidy of the individuals.",
23-
"id": "karyotypicSexPloidy",
24-
"label": "sex ploidy",
25-
"modelProperty": "individual.karyotypicSex",
30+
"id": "SelectedCarcinomaDiagnoses",
2631
"selectors": [
2732
{
28-
"label": "Diploid",
29-
"value": "diploid"
33+
"label": "Prostate Adenocarcinoma",
34+
"value": "NCIT:C2919"
3035
},
3136
{
32-
"label": "Aneuploid",
33-
"value": "aneuploid"
37+
"label": "Breast Ductal Carcinoma",
38+
"value": "NCIT:C4017"
3439
},
3540
{
36-
"label": "Polyploid",
37-
"value": "polyploid"
41+
"label": "Lung Adenocarcinoma",
42+
"value": "NCIT:C3512"
3843
}
3944
]
4045
},
4146
{
42-
"description": "Aggregation by the age of onset of the individuals. The age of onset is calculated as the difference between the date of onset and the date of birth of the individual.",
43-
"id": "ageOfOnset",
47+
"description": "Aggregation by the age of onset of the individuals providing pre-defined age ranges.",
48+
"id": "AgeOfOnset",
4449
"label": "Age of Onset",
4550
"modelProperty": "individual.diseases.ageofOnset",
51+
"selectors": [
52+
{
53+
"label": "birth to 18 months",
54+
"rangeBounds": [
55+
"P0D",
56+
"P18M"
57+
],
58+
"sortOrder": 1
59+
},
60+
{
61+
"label": "1.5 to 10 years",
62+
"rangeBounds": [
63+
"P18M",
64+
"P10Y"
65+
],
66+
"sortOrder": 2
67+
},
68+
{
69+
"label": "10 to 60 years",
70+
"rangeBounds": [
71+
"P10Y",
72+
"P60Y"
73+
],
74+
"sortOrder": 3
75+
},
76+
{
77+
"label": "60 years and older",
78+
"rangeBounds": [
79+
"P60Y"
80+
],
81+
"sortOrder": 4
82+
}
83+
]
84+
},
85+
{
86+
"description": "Aggregation by the age of onset of the individuals. The age of onset is calculated as the difference between the date of onset and the date of birth of the individual. This example for the age of onset is split into two categories using a splitValue of 65 years (P65Y).",
87+
"id": "RetirementAgeOfOnset",
88+
"label": "Age of Onset at Retirement Age",
89+
"modelProperty": "individual.diseases.ageofOnset",
4690
"selectors": [
4791
{
4892
"label": "younger than 65 years",
@@ -55,6 +99,32 @@
5599
"splitValue": "P150Y"
56100
}
57101
]
102+
},
103+
{
104+
"description": "Aggregation by the karyotypic sex of the individuals. The karyotypic sex is determined by the chromosomal composition of the individual.",
105+
"id": "KaryotypicSex",
106+
"label": "karyotypic sex",
107+
"modelProperty": "individual.karyotypicSex"
108+
},
109+
{
110+
"description": "Aggregation by the sex ploidy of the individuals.",
111+
"id": "KaryotypicSexPloidy",
112+
"label": "sex ploidy",
113+
"modelProperty": "individual.karyotypicSex",
114+
"selectors": [
115+
{
116+
"label": "Diploid",
117+
"value": "diploid"
118+
},
119+
{
120+
"label": "Aneuploid",
121+
"value": "aneuploid"
122+
},
123+
{
124+
"label": "Polyploid",
125+
"value": "polyploid"
126+
}
127+
]
58128
}
59129
]
60130
}

‎framework/json/responses/examples-sections/beaconAggregationResults-examples.json‎

Lines changed: 3 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,7 @@
33
{
44
"aggregationTerms": [
55
{
6-
"id": "sex",
7-
"label": "Selected Diagnoses"
6+
"id": "SexAtBirth"
87
}
98
],
109
"categoriesAndValues": [
@@ -41,8 +40,8 @@
4140
{
4241
"aggregationTerms": [
4342
{
44-
"id": "selectedDiagnoses",
45-
"label": "Selected Diagnoses"
43+
"id": "SelectedCarcinomaDiagnoses",
44+
"label": "Selected diagnoses (some carcinoma entities)"
4645
}
4746
],
4847
"categoriesAndValues": [
@@ -110,17 +109,6 @@
110109
"Prostate Adenocarcinoma"
111110
]
112111
},
113-
{
114-
"count": 0,
115-
"ids": [
116-
"NCIT:C1799",
117-
"NCIT:C2919"
118-
],
119-
"names": [
120-
"unknown",
121-
"Prostate Adenocarcinoma"
122-
]
123-
},
124112
{
125113
"count": 4,
126114
"ids": [
@@ -143,17 +131,6 @@
143131
"Breast Ductal Carcinoma"
144132
]
145133
},
146-
{
147-
"count": 18,
148-
"ids": [
149-
"NCIT:C1799",
150-
"NCIT:C4017"
151-
],
152-
"names": [
153-
"unknown",
154-
"Breast Ductal Carcinoma"
155-
]
156-
},
157134
{
158135
"count": 201,
159136
"ids": [
@@ -175,17 +152,6 @@
175152
"female",
176153
"Lung Adenocarcinoma"
177154
]
178-
},
179-
{
180-
"count": 51,
181-
"ids": [
182-
"NCIT:C1799",
183-
"NCIT:C3512"
184-
],
185-
"names": [
186-
"unknown",
187-
"Lung Adenocarcinoma"
188-
]
189155
}
190156
],
191157
"requestId": "aggr3"

‎framework/json/responses/sections/beaconAggregationTermsResults.json‎

Lines changed: 0 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -1,52 +1,6 @@
11
{
22
"$defs": {
33
"AggregationTermInResponse": {
4-
"examples": [
5-
{
6-
"description": "Aggregation by the karyotypic sex of the individuals. The karyotypic sex is determined by the chromosomal composition of the individual.",
7-
"id": "karyotypicSex",
8-
"label": "karyotypic sex",
9-
"modelProperty": "individual.karyotypicSex"
10-
},
11-
{
12-
"description": "Aggregation by the sex ploidy of the individuals.",
13-
"id": "karyotypicSexPloidy",
14-
"label": "sex ploidy",
15-
"modelProperty": "individual.karyotypicSex",
16-
"selectors": [
17-
{
18-
"label": "Diploid",
19-
"value": "diploid"
20-
},
21-
{
22-
"label": "Aneuploid",
23-
"value": "aneuploid"
24-
},
25-
{
26-
"label": "Polyploid",
27-
"value": "polyploid"
28-
}
29-
]
30-
},
31-
{
32-
"description": "Aggregation by the age of onset of the individuals. The age of onset is calculated as the difference between the date of onset and the date of birth of the individual.",
33-
"id": "ageOfOnset",
34-
"label": "Age of Onset",
35-
"modelProperty": "individual.diseases.ageofOnset",
36-
"selectors": [
37-
{
38-
"label": "younger than 65 years",
39-
"sortOrder": 1,
40-
"splitValue": "P65Y"
41-
},
42-
{
43-
"label": "65 years and older",
44-
"sortOrder": 2,
45-
"splitValue": "P150Y"
46-
}
47-
]
48-
}
49-
],
504
"properties": {
515
"description": {
526
"description": "Human readable description of the aggregation performed for this term.",

‎framework/src/requests/aggregationTerms.yaml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,7 @@ $defs:
6868
# Example of an aggregation with splits for the term "age of onset".
6969
aggregationTerms:
7070
- id: AgeOfOnset
71+
7172
AggregationTermInRequest:
7273
type: object
7374
description: >-

‎framework/src/requests/examples-sections/aggregationTerms-example.yaml‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,19 +2,27 @@ $schema: https://json-schema.org/draft/2020-12/schema
22
aggregators:
33
- requestId: aggr1
44
aggregationTerms:
5-
- id: Sex
5+
- id: SexAtBirth
66

77
- requestId: aggr2
88
aggregationTerms:
9-
- id: Sex
9+
- id: SelectedCarcinomaDiagnoses
10+
label: Selected diagnoses (some carcinoma entities)
1011
selectors:
11-
- value: NCIT:C16576
12-
- value: NCIT:C20197
12+
- value: NCIT:C2919
13+
label: Prostate Adenocarcinoma
14+
- value: NCIT:C4017
15+
label: Breast Ductal Carcinoma
16+
- value: NCIT:C3512
17+
label: Lung Adenocarcinoma
1318

1419
- requestId: aggr3
1520
aggregationTerms:
1621
- id: SexAtBirth
17-
- id: HistologicalDiagnoses
22+
selectors:
23+
- value: NCIT:C16576
24+
- value: NCIT:C20197
25+
- id: SelectedCarcinomaDiagnoses
1826
selectors:
1927
- value: NCIT:C2919
2028
label: Prostate Adenocarcinoma

‎framework/src/responses/beaconAggregationResponse.yaml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
$schema: https://json-schema.org/draft/2020-12/schema
22
description: >-
3-
Definition for a response that provides solely summaries of records in
4-
the beacon but not delivers individual records. While summaries might be also part
3+
Definition for a response that provides solely aggregations of record properties in
4+
the beacon but does not delivers individual records. While aggregations might be also part
55
of other response types (e.g. result set specific in `beaconResultsetResponse`)
66
this response type specifically focuses on providing aggregated statistics of
77
a beacon resource similarily to the `beaconBooleanResponse` and `beaconCountResponse`.

0 commit comments

Comments
 (0)