Update aggregations.md

Author: mbaudis

docs/aggregations.md

@@ -196,6 +196,81 @@ description: >-
 property: biosample.sample_origin_detail.id
 ```
 
+Aggregation concepts can have additional modifiers:
+
+* `filters` - to limit the aggregation to a subset of the data, e.g. to a selection of disease codes
+    - the usual filter definitions apply; _i.e._ if an ontology term is used as filter value the count will include all records with this term or any of its child terms (unless the filter's `includeDescendantTerms` flag is set to `False`)
+* `splits` - to partition continuous data such as age values, followup times or other numeric measurements into countable bins
+    - Note: `splits` are upper & exclusive boundaries of bins, following established practices (_cf._ `$split` use in [MongoDB aggregation pipelines](https://www.mongodb.com/docs/manual/reference/operator/aggregation/split/))
+
+* a `sorted` flag, to indicate that the aggregation results are returned in a
+pre-sorted order with some inherent meaning (e.g. age bins)
+* a `format` property to indicate the format of the values, e.g. for age splits provided in ISO8601 duration format
+
+#### `filters` Example
+
+```yaml
+selectedDiseases:
+  id: selectedDiseases
+  label: Selected Diagnostic Classes (by NCIT)
+  property: individual.diseases.disease_code.id
+  filters:
+    - id: NCIT:C2919
+      label: Prostate Adenocarcinoma
+    - id: NCIT:C4017
+      label: Breast Ductal Carcinoma
+    - id: NCIT:C3512
+      label: Lung Adenocarcinoma
+```
+
+#### `splits` Example
+
+```yaml
+ageAtSampleCollection:
+  id: ageAtSampleCollection
+  label: Age at sample collection
+  description: >-
+    Age at diagnosis (sample collection...)
+  property: biosample.collection_moment
+  format: iso8601duration
+  splits:
+    - value: P18Y
+      label: < 18 years
+    - value: P65Y
+      label: < 65 years
+    - value: P120Y
+      label: 65+ years
+  sorted: True
+```
+
+## Requesting Aggregations
+
+To request specific aggregations, clients can use the `aggregators` query parameter which itself is an array of arrays of concepts. 
+
+=== "POST Request Example"
+
+    ```json
+    "aggregators": [
+      [
+        {"id": "sampleOriginDetails"}
+      ],
+      [
+        {"id": "selectedDiseases"},
+        {"id": "sexAtBirth"}
+      ]
+    ]
+    ```
+
+=== "GET Request Example"
+
+    The **non normative** `GET` example uses a standard comma concatenation for
+    the outer `aggregators` list and a double colon `::` to separate `id` values
+    of intersecting concepts.
+
+    ```
+    ?aggregators=sampleOriginDetails,selectedDiseases::sexAtBirth
+    ```
+