aggregations doc stub

Author: mbaudis

docs/aggregations.md

@@ -0,0 +1,107 @@
+# Beacon Aggregations for Data Summaries
+
+!!! warn "WiP"
+
+    Beacon aggregations are currently in preview and may change without deprecation.
+    Use with caution and follow related PRs.
+
+## Overview and Use Cases
+
+While the `Beacon` API provides different ways to discover and potentially retrieve
+data in biomedical genomics resources, with version 2.n responses were limited to
+global content (boolean or overall count of matched data and static collection information)
+or full record level access which for most resources would not be possible in a
+public context. Responses under the new `aggregated` granularity level allow to:
+
+* provide granular data overwiews about the content of resources and their collections,
+  e.g. numbers of samples with individual features or combinations of features
+* profile query responses for multiple (single or intersected) parameters
+
+## Response Format
+
+Aggregation are provided inside the `responseAggregation` property of the response and consist
+of array of objects with the following structure:
+
+* a required, ordered list of one or more `concepts` objects, describing the
+parameters for which the aggregation is provided
+* summaries for the single or interssected concepts
+    - a count of the distinct values for single or intersected concepts and/or
+    - a count for all records with existing values and/or
+    - a distribution of all distinct values/combinations with the count of their occurrence
+* an optional `scope` parameter to indicate the entity the results refer to (usually the current entry type but might be variable for collection and overview aggregations)
+
+### Examples
+
+The following examples display different aggregation objects (which would be items in the `responseAggregation` array). Note that **id values are for demonstration only** and do not have a normative function.
+
+**Aggregations and Queries:** For most of the example cases one can envision both a use in "data overview context" (e.g. to profile the content of a resource or collection) and in "query context" (e.g. to profile the response for a specific query).
+
+#### Minimal Representation of Distinct Values Count `distinctValuesCount`
+
+How many different diseases are represented in the data?
+
+```json
+{
+  "concepts": [
+    {"id": "disease", "label": "Disease"}
+  ],
+  "distinctValuesCount": 89
+}
+```
+
+#### Informative Values `anyValueCount`
+
+How many individuals in the data have a follow-up time?
+
+```json
+{
+  "scope": "individual",
+  "concepts": [
+    {"id": "followUpTime", "label": "Follow-up time"}
+  ],
+  "anyValueCount": 1200
+}
+```
+
+#### Value Distribution `distribution`, Single Concept
+
+What is the distribution of diseases in the samples?
+
+```json
+{
+  "scope": "biosample",
+  "concepts": [
+    {
+      "id": "sampleDiagnoses",
+      "label": "Diagnoses of selected carcinoma types",
+      "property": "biosample.histologicalDiagnosis.id"
+    }
+  ],
+  "distribution": [
+    {
+      "conceptValues": [
+        {"id": "NCIT:C2919", "label": "Prostate Adenocarcinoma"}
+      ],
+      "count": 426
+    },
+    {
+      "conceptValues": [
+        {"id": "NCIT:C4017", "label": "Breast Ductal Carcinoma"}
+      ],
+      "count": 423
+    },
+    {
+      "conceptValues": [
+        {"id": "NCIT:C3512", "label": "Lung Adenocarcinoma"}
+      ],
+      "count": 317
+    }
+  ]
+}
+```
+
+
+
+
+
+

mkdocs.yaml

@@ -31,6 +31,7 @@ nav:
             - Biosamples, Variants...: records
             - Data Handovers: handovers
             - REST API: rest-api
+        - Data Aggregations: aggregations
     - 'Creating Beacons':
         - Implementations Options: implementations-options
         - Implementation Examples: