Skip to content

Commit 995c27c

Browse files
mbaudismbaudis
committed
first pass at results from 2026-06-30 discussion
2026-06-30 Jordi, Oriol, Michael To Do: · Selectors – name and formats o Do we need splits right now? o Binning value? · Endpoint examples o /datasets, /cohorts Changes today by Michael · selectors => categories · removed odd weight example leftover · modelProperty => fixed example in documentation since “required” (the example yaml/json had it ...) · removed `KaryotypicSexPloidy` example (from Jordi) since ploidy not defined for `individual.karyotypicSex` · changed label => name in categories · added `sortOrder` to `AggregationCategoriesResult` ... but see below · changed definition in `AggregationCategoriesResult` from ids, names to the categories objects in aggregationTerms · Added `scope`, but so far only to `AggregationResultsInstance` scope: description: >- Optional scope of the aggregation, e.g. `individuals`, `biosamples`, `analyses`, etc. This main use is specifying aggregations at `collection` type endpoints (datasets or cohorts), to indicate the entity the aggregations were counted against. If not specified, the scope is assumed to be the entry type. type: string New/remaining questions: · removed `sorted` from AggregationConcept and now `sortOrder` in `AggregationCategoriesResult` - but this then only applies to the first dimension => ? (most standard case for e.g. X-value sorting *but* potential clashes with sorted second dimension etc.) · `SplitCategories` have not been discussed => remove? · add `scope` property to requests and responses · DistinctValuesCount, AnyValueCount in requests => solution?
1 parent 7eb7fd5 commit 995c27c

15 files changed

Lines changed: 703 additions & 627 deletions

‎docs/aggregations.md‎

Lines changed: 142 additions & 132 deletions
Large diffs are not rendered by default.

‎framework/json/requests/aggregationTerms.json‎

Lines changed: 42 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,20 @@
33
"AggregationTermInRequest": {
44
"description": "An object representing an individual term to be aggregated, e.g. a term corresponding to `sexAtBirth` or `diagnosis`. The `id` property is required and identifies the term to be aggregated, while the `filters` and `splits` properties are optional modifiers of the aggregation term. Note: The request object does not specifiy the property or scope of the aggregation.",
55
"properties": {
6+
"categories": {
7+
"description": "List of categories to select specific values of the given property for aggregation, as a modifier of the aggregation term. For example, for an aggregation term of `diagnosis` categories could be used to specify a subset of diagnoses to be aggregated.",
8+
"oneOf": [
9+
{
10+
"$ref": "#/$defs/ValueCategories"
11+
},
12+
{
13+
"$ref": "#/$defs/RangeCategories"
14+
},
15+
{
16+
"$ref": "#/$defs/SplitCategories"
17+
}
18+
]
19+
},
620
"id": {
721
"description": "The `id` of the aggregation term as provided by the beacon. It is used to select the aggregation term, _i.e._ usually corresponding to a property in the data model. ",
822
"examples": [
@@ -20,20 +34,6 @@
2034
}
2135
],
2236
"type": "string"
23-
},
24-
"selectors": {
25-
"description": "List of selectors to select specific values of the given property for aggregation, as a modifier of the aggregation term. For example, for an aggregation term of `diagnosis` selectors could be used to specify a subset of diagnoses to be aggregated.",
26-
"oneOf": [
27-
{
28-
"$ref": "#/$defs/ValueSelectors"
29-
},
30-
{
31-
"$ref": "#/$defs/RangeSelectors"
32-
},
33-
{
34-
"$ref": "#/$defs/SplitSelectors"
35-
}
36-
]
3737
}
3838
},
3939
"required": [
@@ -55,15 +55,15 @@
5555
{
5656
"aggregationTerms": [
5757
{
58-
"id": "Sex",
59-
"selectors": [
58+
"categories": [
6059
{
6160
"value": "NCIT:C16576"
6261
},
6362
{
6463
"value": "NCIT:C20197"
6564
}
66-
]
65+
],
66+
"id": "Sex"
6767
}
6868
],
6969
"requestId": "aggr2"
@@ -74,8 +74,7 @@
7474
"id": "SexAtBirth"
7575
},
7676
{
77-
"id": "HistologicalDiagnoses",
78-
"selectors": [
77+
"categories": [
7978
{
8079
"value": "NCIT:C2919"
8180
},
@@ -85,7 +84,8 @@
8584
{
8685
"value": "NCIT:C3512"
8786
}
88-
]
87+
],
88+
"id": "HistologicalDiagnoses"
8989
}
9090
],
9191
"requestId": "aggr3"
@@ -118,10 +118,17 @@
118118
],
119119
"type": "object"
120120
},
121+
"RangeCategories": {
122+
"items": {
123+
"$ref": "#/$defs/RangeForAggregation"
124+
},
125+
"minItems": 1,
126+
"type": "array"
127+
},
121128
"RangeForAggregation": {
122129
"examples": [
123130
{
124-
"label": "birth to 18 months",
131+
"name": "birth to 18 months",
125132
"rangeBounds": [
126133
"P0M",
127134
"P18M"
@@ -130,7 +137,7 @@
130137
}
131138
],
132139
"properties": {
133-
"label": {
140+
"name": {
134141
"type": "string"
135142
},
136143
"rangeBounds": {
@@ -145,7 +152,7 @@
145152
"type": "array"
146153
},
147154
"sortOrder": {
148-
"description": "Integer to specify the intended order of splits. This is required to ensure the correct order of bins in the results, or for the client to be able to reconstruct the expected order in case any of the intermediate steps reorders them.",
155+
"description": "Integer to specify the intended order of ranges. This is required to ensure the correct order of bins in the results, or for the client to be able to reconstruct the expected order in case any of the intermediate steps reorders them.",
149156
"type": "integer"
150157
}
151158
},
@@ -155,9 +162,9 @@
155162
],
156163
"type": "object"
157164
},
158-
"RangeSelectors": {
165+
"SplitCategories": {
159166
"items": {
160-
"$ref": "#/$defs/RangeForAggregation"
167+
"$ref": "#/$defs/SplitForAggregation"
161168
},
162169
"minItems": 1,
163170
"type": "array"
@@ -166,24 +173,19 @@
166173
"description": "A split item for partitioning the values during aggregation.",
167174
"examples": [
168175
{
169-
"label": "younger than 65 years",
176+
"name": "younger than 65 years",
170177
"sortOrder": 1,
171178
"splitValue": "P65Y"
172179
},
173180
{
174-
"label": "65 years and older",
181+
"name": "65 years and older",
175182
"sortOrder": 2,
176183
"splitValue": "P150Y"
177-
},
178-
{
179-
"label": "25kg or higher",
180-
"sortOrder": 3,
181-
"splitValue": 25
182184
}
183185
],
184186
"properties": {
185-
"label": {
186-
"description": "A human readable label for the bin resulting from the split.",
187+
"name": {
188+
"description": "A human readable name for the bin resulting from the split.",
187189
"type": "string"
188190
},
189191
"sortOrder": {
@@ -204,9 +206,10 @@
204206
],
205207
"type": "object"
206208
},
207-
"SplitSelectors": {
209+
"ValueCategories": {
210+
"description": "Selectors array prototypes guarantee that all individual selector values are of the same type.",
208211
"items": {
209-
"$ref": "#/$defs/SplitForAggregation"
212+
"$ref": "#/$defs/ValueForAggregation"
210213
},
211214
"minItems": 1,
212215
"type": "array"
@@ -216,15 +219,15 @@
216219
"properties": {
217220
"examples": [
218221
{
219-
"label": "Kidney Carcinoma",
222+
"name": "Kidney Carcinoma",
220223
"value": "NCIT:C9384"
221224
},
222225
{
223226
"value": "female"
224227
}
225228
],
226-
"label": {
227-
"description": "An optional label for the value, e.g. to allow the service to return in an informative response.",
229+
"name": {
230+
"description": "An optional name for the value, e.g. to allow the service to return in an informative response.",
228231
"type": "string"
229232
},
230233
"required": [
@@ -236,14 +239,6 @@
236239
}
237240
},
238241
"type": "object"
239-
},
240-
"ValueSelectors": {
241-
"description": "Selectors array prototypes guarantee that all individual selector values are of the same type.",
242-
"items": {
243-
"$ref": "#/$defs/ValueForAggregation"
244-
},
245-
"minItems": 1,
246-
"type": "array"
247242
}
248243
},
249244
"$schema": "https://json-schema.org/draft/2020-12/schema",

‎framework/json/requests/examples-fullDocuments/beaconRequestBody-MAX-example.json‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -17,21 +17,21 @@
1717
"id": "SexAtBirth"
1818
},
1919
{
20-
"id": "HistologicalDiagnoses",
21-
"selectors": [
20+
"categories": [
2221
{
23-
"label": "Prostate Adenocarcinoma",
22+
"name": "Prostate Adenocarcinoma",
2423
"value": "NCIT:C2919"
2524
},
2625
{
27-
"label": "Breast Ductal Carcinoma",
26+
"name": "Breast Ductal Carcinoma",
2827
"value": "NCIT:C4017"
2928
},
3029
{
31-
"label": "Lung Adenocarcinoma",
30+
"name": "Lung Adenocarcinoma",
3231
"value": "NCIT:C3512"
3332
}
34-
]
33+
],
34+
"id": "HistologicalDiagnoses"
3535
}
3636
],
3737
"requestId": "aggr3"

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

Lines changed: 32 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -12,106 +12,104 @@
1212
{
1313
"aggregationTerms": [
1414
{
15-
"id": "SelectedCarcinomaDiagnoses",
16-
"label": "Selected diagnoses (some carcinoma entities)",
17-
"selectors": [
15+
"categories": [
1816
{
19-
"label": "Prostate Adenocarcinoma",
17+
"name": "Prostate Adenocarcinoma",
2018
"value": "NCIT:C2919"
2119
},
2220
{
23-
"label": "Breast Ductal Carcinoma",
21+
"name": "Breast Ductal Carcinoma",
2422
"value": "NCIT:C4017"
2523
},
2624
{
27-
"label": "Lung Adenocarcinoma",
25+
"name": "Lung Adenocarcinoma",
2826
"value": "NCIT:C3512"
2927
}
30-
]
28+
],
29+
"id": "SelectedCarcinomaDiagnoses",
30+
"label": "Selected diagnoses (some carcinoma entities)"
3131
}
3232
],
3333
"requestId": "aggr2"
3434
},
3535
{
3636
"aggregationTerms": [
3737
{
38-
"id": "SexAtBirth",
39-
"selectors": [
38+
"categories": [
4039
{
4140
"value": "NCIT:C16576"
4241
},
4342
{
4443
"value": "NCIT:C20197"
4544
}
46-
]
45+
],
46+
"id": "SexAtBirth"
4747
},
4848
{
49-
"id": "SelectedCarcinomaDiagnoses",
50-
"selectors": [
49+
"categories": [
5150
{
52-
"label": "Prostate Adenocarcinoma",
51+
"name": "Prostate Adenocarcinoma",
5352
"value": "NCIT:C2919"
5453
},
5554
{
56-
"label": "Breast Ductal Carcinoma",
55+
"name": "Breast Ductal Carcinoma",
5756
"value": "NCIT:C4017"
5857
},
5958
{
60-
"label": "Lung Adenocarcinoma",
59+
"name": "Lung Adenocarcinoma",
6160
"value": "NCIT:C3512"
6261
}
63-
]
62+
],
63+
"id": "SelectedCarcinomaDiagnoses"
6464
}
6565
],
6666
"requestId": "aggr3"
6767
},
6868
{
6969
"aggregationTerms": [
7070
{
71-
"id": "AgeOfOnset",
72-
"selectors": [
71+
"categories": [
7372
{
74-
"label": "birth to 18 months",
73+
"name": "birth to 18 months",
7574
"rangeBounds": [
7675
"P0D",
7776
"P18M"
7877
],
7978
"sortOrder": 1
8079
},
8180
{
82-
"label": "1.5 to 10 years",
81+
"name": "1.5 to 10 years",
8382
"rangeBounds": [
8483
"P18M",
8584
"P10Y"
8685
],
8786
"sortOrder": 2
8887
},
8988
{
90-
"label": "10 to 60 years",
89+
"name": "10 to 60 years",
9190
"rangeBounds": [
9291
"P10Y",
9392
"P60Y"
9493
],
9594
"sortOrder": 3
9695
},
9796
{
98-
"label": "60 years and older",
97+
"name": "60 years and older",
9998
"rangeBounds": [
10099
"P60Y"
101100
],
102101
"sortOrder": 4
103102
}
104-
]
103+
],
104+
"id": "AgeOfOnset"
105105
}
106106
],
107107
"requestId": "aggr4"
108108
},
109109
{
110110
"aggregationTerms": [
111111
{
112-
"id": "CancerPanelGeneIds",
113-
"label": "Cancer Panel Genes",
114-
"selectors": [
112+
"categories": [
115113
{
116114
"value": "CDKN2A"
117115
},
@@ -124,20 +122,22 @@
124122
{
125123
"value": "MYCN"
126124
}
127-
]
125+
],
126+
"id": "CancerPanelGeneIds",
127+
"label": "Cancer Panel Genes"
128128
},
129129
{
130-
"id": "VariantVRSCNVtype",
131-
"selectors": [
130+
"categories": [
132131
{
133-
"label": "high-level loss",
132+
"name": "high-level loss",
134133
"value": "EFO:0020073"
135134
},
136135
{
137-
"label": "high-level gain",
136+
"name": "high-level gain",
138137
"value": "EFO:0030072"
139138
}
140-
]
139+
],
140+
"id": "VariantVRSCNVtype"
141141
}
142142
],
143143
"requestId": "aggr5"

0 commit comments

Comments
 (0)