From a6c25197c372d74488a37c66c779faa45658c2f0 Mon Sep 17 00:00:00 2001 From: MarkusKonk Date: Thu, 16 Apr 2020 12:50:38 +0200 Subject: [PATCH 1/5] start bindings api specification --- docs/compendium/bindings.html | 485 ++++++++++++++++++++++++++++++++++ docs/compendium/bindings.md | 74 ++++++ 2 files changed, 559 insertions(+) create mode 100644 docs/compendium/bindings.html create mode 100644 docs/compendium/bindings.md diff --git a/docs/compendium/bindings.html b/docs/compendium/bindings.html new file mode 100644 index 0000000..4575aee --- /dev/null +++ b/docs/compendium/bindings.html @@ -0,0 +1,485 @@ + + + + + + + + + + + + + + +bindings.utf8.md + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + +
+

Bindings

+

A binding is an optional component of an Executable Research Compendium. It can be used to make static figures interactive, for example, to show how different parameter settings affect the result shown in the figure. A bindings stores information on the code lines needed to generate the corresponding figure, the parameter that should be made interactive, the data subset required for the figure, and the user interface (UI) widget (e.g. a slider or radio buttons).

+
+

Create a binding

+

POST /api/v1/bindings/binding

+

Request body for a new binding:

+
{
+  "id": "rDdFN",
+  "computationalResult": {
+    "type": "figure",
+    "result": "Figure 3"
+  },
+  "sourcecode": {
+    "file": "main.Rmd",
+    "codelines": [{
+      "start": 101,
+      "end": 503
+      }
+    ],
+    "parameter": [{
+      "text": "duration <- 24",
+      "name": "duration",
+      "val": 24,
+      "uiWidget": {
+        "minValue": 1,
+        "type": "slider",
+        "maxValue": 24,
+        "stepSize": 1,
+        "caption": "The duration parameter specifies the duration of the flood event in hours."
+        }
+      }]
+    }
+}
+
+

Request body properties

+
    +
  • id - ID of the compendium for which the bindings should be created
    • +
  • computationalResult - specification of the computational result that should be made interactive +
      +
    • type - type of the computational result, e.g. a figure or a table
      • +
    • result - the actual result as it is referred to in the text
      • +
    • +
  • sourcecode all code-related information needed to create a binding for result specified above +
      +
    • file - main file of the research compendium containing the R code
      • +
    • codelines - array of code chunks including the code needed to generate the result +
        +
      • start - start of the code chunk
        • +
      • end - end of the code chunk
        • +
      • +
    • parameter - array of parameters that should be made interactive +
        +
      • text - parameter as it is initialized in the code
        • +
      • name - the name of the parameter without the value
        • +
      • val - the value of the parameter without the name
        • +
      • uiWidget - specification of the UI widget, one per parameter, here examplified with a slider +
          +
        • type - widget type, e.g. a slider or radio buttons
          • +
        • minValue - minimum value of the slider
          • +
        • maxValue - maximum value of the slider
          • +
        • stepSize - step size when moving the slider
          • +
        • caption - caption for the result
          • +
        • +
      • +
    • +
+
+
+
+ + + + +
+ + + + + + + + + + + + + + + diff --git a/docs/compendium/bindings.md b/docs/compendium/bindings.md new file mode 100644 index 0000000..c594a78 --- /dev/null +++ b/docs/compendium/bindings.md @@ -0,0 +1,74 @@ +# Bindings + +A binding is an optional component of an Executable Research Compendium. +It can be used to make static figures interactive, for example, to show how different parameter settings affect the result shown in the figure. +A bindings stores information on the code lines needed to generate the corresponding figure, the parameter that should be made interactive, the data subset required for the figure, and the user interface (UI) widget (e.g. a slider or radio buttons). + +## Create a binding + +`POST /api/v1/bindings/binding` + +Request body for a new binding: + +```json +{ + "id": "rDdFN", + "computationalResult": { + "type": "figure", + "result": "Figure 3" + }, + "sourcecode": { + "file": "main.Rmd", + "codelines": [{ + "start": 101, + "end": 503 + } + ], + "parameter": [{ + "text": "duration <- 24", + "name": "duration", + "val": 24, + "uiWidget": { + "minValue": 1, + "type": "slider", + "maxValue": 24, + "stepSize": 1, + "caption": "The duration parameter specifies the duration of the flood event in hours." + } + }] + } +} +``` + +### Request body properties + +- `id` - ID of the compendium for which the bindings should be created +- `computationalResult` - specification of the computational result that should be made interactive + - `type` - type of the computational result, e.g. a figure or a table + - `result` - the actual result as it is referred to in the text +- `sourcecode` all code-related information needed to create a binding for result specified above + - `file` - main file of the research compendium containing the R code + - `codelines` - array of code chunks including the code needed to generate the result + - `start` - start of the code chunk + - `end` - end of the code chunk + - `parameter` - array of parameters that should be made interactive + - `text` - parameter as it is initialized in the code + - `name` - the name of the parameter without the value + - `val` - the value of the parameter without the name + - `uiWidget` - specification of the UI widget, one per parameter, here examplified with a slider + - `type` - widget type, e.g. a slider or radio buttons + - `minValue` - minimum value of the slider + - `maxValue` - maximum value of the slider + - `stepSize` - step size when moving the slider + - `caption` - caption for the result + +### Response + +```json +200 Ok + +{ + "callback": "ok", + "data": binding +} +``` \ No newline at end of file From 81525614baeb3cfdca53e64abc9c7207aa5d8e3d Mon Sep 17 00:00:00 2001 From: MarkusKonk Date: Thu, 16 Apr 2020 14:38:02 +0200 Subject: [PATCH 2/5] update bindings api --- docs/compendium/bindings.html | 485 ---------------------------------- docs/compendium/bindings.md | 84 +++++- 2 files changed, 81 insertions(+), 488 deletions(-) delete mode 100644 docs/compendium/bindings.html diff --git a/docs/compendium/bindings.html b/docs/compendium/bindings.html deleted file mode 100644 index 4575aee..0000000 --- a/docs/compendium/bindings.html +++ /dev/null @@ -1,485 +0,0 @@ - - - - - - - - - - - - - - -bindings.utf8.md - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - -
-

Bindings

-

A binding is an optional component of an Executable Research Compendium. It can be used to make static figures interactive, for example, to show how different parameter settings affect the result shown in the figure. A bindings stores information on the code lines needed to generate the corresponding figure, the parameter that should be made interactive, the data subset required for the figure, and the user interface (UI) widget (e.g. a slider or radio buttons).

-
-

Create a binding

-

POST /api/v1/bindings/binding

-

Request body for a new binding:

-
{
-  "id": "rDdFN",
-  "computationalResult": {
-    "type": "figure",
-    "result": "Figure 3"
-  },
-  "sourcecode": {
-    "file": "main.Rmd",
-    "codelines": [{
-      "start": 101,
-      "end": 503
-      }
-    ],
-    "parameter": [{
-      "text": "duration <- 24",
-      "name": "duration",
-      "val": 24,
-      "uiWidget": {
-        "minValue": 1,
-        "type": "slider",
-        "maxValue": 24,
-        "stepSize": 1,
-        "caption": "The duration parameter specifies the duration of the flood event in hours."
-        }
-      }]
-    }
-}
-
-

Request body properties

-
    -
  • id - ID of the compendium for which the bindings should be created
    • -
  • computationalResult - specification of the computational result that should be made interactive -
      -
    • type - type of the computational result, e.g. a figure or a table
      • -
    • result - the actual result as it is referred to in the text
      • -
    • -
  • sourcecode all code-related information needed to create a binding for result specified above -
      -
    • file - main file of the research compendium containing the R code
      • -
    • codelines - array of code chunks including the code needed to generate the result -
        -
      • start - start of the code chunk
        • -
      • end - end of the code chunk
        • -
      • -
    • parameter - array of parameters that should be made interactive -
        -
      • text - parameter as it is initialized in the code
        • -
      • name - the name of the parameter without the value
        • -
      • val - the value of the parameter without the name
        • -
      • uiWidget - specification of the UI widget, one per parameter, here examplified with a slider -
          -
        • type - widget type, e.g. a slider or radio buttons
          • -
        • minValue - minimum value of the slider
          • -
        • maxValue - maximum value of the slider
          • -
        • stepSize - step size when moving the slider
          • -
        • caption - caption for the result
          • -
        • -
      • -
    • -
-
-
-
- - - - -
- - - - - - - - - - - - - - - diff --git a/docs/compendium/bindings.md b/docs/compendium/bindings.md index c594a78..5affedf 100644 --- a/docs/compendium/bindings.md +++ b/docs/compendium/bindings.md @@ -3,6 +3,8 @@ A binding is an optional component of an Executable Research Compendium. It can be used to make static figures interactive, for example, to show how different parameter settings affect the result shown in the figure. A bindings stores information on the code lines needed to generate the corresponding figure, the parameter that should be made interactive, the data subset required for the figure, and the user interface (UI) widget (e.g. a slider or radio buttons). +The resulting JSON object including the binding is stored in the metadata tag `interaction`. +For this reason, the compendium must be at least a `candidate` where the metadata extraction is completed. ## Create a binding @@ -22,8 +24,7 @@ Request body for a new binding: "codelines": [{ "start": 101, "end": 503 - } - ], + }], "parameter": [{ "text": "duration <- 24", "name": "duration", @@ -71,4 +72,81 @@ Request body for a new binding: "callback": "ok", "data": binding } -``` \ No newline at end of file +``` + +## Extract R code + +`POST /api/v1/bindings/extractR` + +Request body for extracting those code lines needed to generate a specific result: + +```json +{ + "id": "rDdFN", + "file": "main.Rmd", + "plot": "plotFigure1()" +} +``` + +### Request body properties + +- `id` - ID of the compendium for which the bindings should be created +- `file` - main file of the research compendium containing the R code +- `plot` - function that outputs the result used as starting point for the backtracking algorithm + +### Response + +```json +200 Ok + +{ + "callback": "ok", + "codelines": [{ + "start": 101, + "end": 503 + }], +} +``` + +## Proxy for binding + +`GET /api/v1/compendium/:compendium/binding/:binding` + +... + +## Run binding + +`POST /api/v1/compendium/:compendium/binding/:binding` + +... + +## Search for a binding + +`POST /api/v1/bindings/searchBinding` + +Request body for finding bindings that include a certain code snippet: + +```json +{ + "term": "processData(input)", + "metadata": {o2r.metadata} +} +``` + +### Request body properties + +- `term` - search for bindings including the this code snippet +- `metadata` - whole metadata object of the corresponding compendium + +### Response + +```json +200 Ok + +{ + "callback": "ok", + "data": ["result"] +} +``` + +- `data` - array of results for which bindings exist that include the corresponding code snippet \ No newline at end of file From 128bddb1ac45914318c78619fd47ca9a845b7343 Mon Sep 17 00:00:00 2001 From: NJaku01 <46575458+NJaku01@users.noreply.github.com> Date: Fri, 19 Mar 2021 15:45:25 +0100 Subject: [PATCH 3/5] Update Bindings description --- docs/compendium/bindings.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/compendium/bindings.md b/docs/compendium/bindings.md index 5affedf..287e181 100644 --- a/docs/compendium/bindings.md +++ b/docs/compendium/bindings.md @@ -22,8 +22,8 @@ Request body for a new binding: "sourcecode": { "file": "main.Rmd", "codelines": [{ - "start": 101, - "end": 503 + "first_line": 101, + "last_line": 503 }], "parameter": [{ "text": "duration <- 24", @@ -50,8 +50,8 @@ Request body for a new binding: - `sourcecode` all code-related information needed to create a binding for result specified above - `file` - main file of the research compendium containing the R code - `codelines` - array of code chunks including the code needed to generate the result - - `start` - start of the code chunk - - `end` - end of the code chunk + - `first_line` - start of the code chunk + - `last_line` - end of the code chunk - `parameter` - array of parameters that should be made interactive - `text` - parameter as it is initialized in the code - `name` - the name of the parameter without the value @@ -74,7 +74,11 @@ Request body for a new binding: } ``` -## Extract R code +## Extract R code -- Deprected + + +### code lines extraction works now on the front end + `POST /api/v1/bindings/extractR` @@ -149,4 +153,4 @@ Request body for finding bindings that include a certain code snippet: } ``` -- `data` - array of results for which bindings exist that include the corresponding code snippet \ No newline at end of file +- `data` - array of results for which bindings exist that include the corresponding code snippet From b12706085efca1c7b08336778914a025bb0d3fff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20N=C3=BCst?= Date: Thu, 1 Jul 2021 17:24:17 +0200 Subject: [PATCH 4/5] Update bindings.md --- docs/compendium/bindings.md | 85 ++++++++++++------------------------- 1 file changed, 27 insertions(+), 58 deletions(-) diff --git a/docs/compendium/bindings.md b/docs/compendium/bindings.md index 287e181..7a9acf7 100644 --- a/docs/compendium/bindings.md +++ b/docs/compendium/bindings.md @@ -1,16 +1,23 @@ -# Bindings +# UI Bindings -A binding is an optional component of an Executable Research Compendium. -It can be used to make static figures interactive, for example, to show how different parameter settings affect the result shown in the figure. -A bindings stores information on the code lines needed to generate the corresponding figure, the parameter that should be made interactive, the data subset required for the figure, and the user interface (UI) widget (e.g. a slider or radio buttons). -The resulting JSON object including the binding is stored in the metadata tag `interaction`. -For this reason, the compendium must be at least a `candidate` where the metadata extraction is completed. +A user interface binding (UI binding) is an optional component of an ERC. +It can be used to make static figures interactive. +For example, authors can show how different parameter settings of a computational model affect the result shown in a figure. +A UI binding stores information on -## Create a binding +- the code lines needed to generate the corresponding figure, +- the variable/parameter in the code that should be made interactive, +- the data subset required for the figure, and +- the UI widget (e.g., a slider or radio buttons). + +The UI binding configuration is a JSON object tored in the property `interaction` of the ERC metadata. +For this reason, the compendium must be at least a `candidate` where the metadata extraction is completed before a UI binding can be created. + +## Create a UI binding `POST /api/v1/bindings/binding` -Request body for a new binding: +Example request body for a new UI binding, here using with a slider: ```json { @@ -43,20 +50,20 @@ Request body for a new binding: ### Request body properties -- `id` - ID of the compendium for which the bindings should be created +- `id` - ID of the compendium for which the UI binding should be created - `computationalResult` - specification of the computational result that should be made interactive - - `type` - type of the computational result, e.g. a figure or a table - - `result` - the actual result as it is referred to in the text -- `sourcecode` all code-related information needed to create a binding for result specified above + - `type` - type of the computational result, e.g., a figure or a table + - `result` - the name of the result as it is referred to in the text +- `sourcecode` all code-related information needed to create a UI binding for result specified above - `file` - main file of the research compendium containing the R code - - `codelines` - array of code chunks including the code needed to generate the result + - `codelines` - array of code chunks with the code needed to generate the result - `first_line` - start of the code chunk - `last_line` - end of the code chunk - `parameter` - array of parameters that should be made interactive - `text` - parameter as it is initialized in the code - `name` - the name of the parameter without the value - - `val` - the value of the parameter without the name - - `uiWidget` - specification of the UI widget, one per parameter, here examplified with a slider + - `val` - the value of the parameter without the name as it is set in the code + - `uiWidget` - specification of the UI widget, one per parameter - `type` - widget type, e.g. a slider or radio buttons - `minValue` - minimum value of the slider - `maxValue` - maximum value of the slider @@ -74,61 +81,23 @@ Request body for a new binding: } ``` -## Extract R code -- Deprected - - -### code lines extraction works now on the front end - - -`POST /api/v1/bindings/extractR` - -Request body for extracting those code lines needed to generate a specific result: - -```json -{ - "id": "rDdFN", - "file": "main.Rmd", - "plot": "plotFigure1()" -} -``` - -### Request body properties - -- `id` - ID of the compendium for which the bindings should be created -- `file` - main file of the research compendium containing the R code -- `plot` - function that outputs the result used as starting point for the backtracking algorithm - -### Response - -```json -200 Ok - -{ - "callback": "ok", - "codelines": [{ - "start": 101, - "end": 503 - }], -} -``` - -## Proxy for binding +## Proxy for UI binding `GET /api/v1/compendium/:compendium/binding/:binding` ... -## Run binding +## Run UI binding `POST /api/v1/compendium/:compendium/binding/:binding` ... -## Search for a binding +## Search for a UI binding `POST /api/v1/bindings/searchBinding` -Request body for finding bindings that include a certain code snippet: +Request body for finding UI bindings that include a certain code snippet: ```json { @@ -139,7 +108,7 @@ Request body for finding bindings that include a certain code snippet: ### Request body properties -- `term` - search for bindings including the this code snippet +- `term` - search for UI bindings including the given code snippet - `metadata` - whole metadata object of the corresponding compendium ### Response From c06799f734a5c0af70050f69252326d186021631 Mon Sep 17 00:00:00 2001 From: NJaku01 <46575458+NJaku01@users.noreply.github.com> Date: Fri, 2 Jul 2021 17:24:41 +0200 Subject: [PATCH 5/5] Update bindings.md --- docs/compendium/bindings.md | 70 ++++++++++++++++++++++++++++++++++--- 1 file changed, 65 insertions(+), 5 deletions(-) diff --git a/docs/compendium/bindings.md b/docs/compendium/bindings.md index 7a9acf7..262df8a 100644 --- a/docs/compendium/bindings.md +++ b/docs/compendium/bindings.md @@ -77,21 +77,81 @@ Example request body for a new UI binding, here using with a slider: { "callback": "ok", - "data": binding + "data": { + "id": "rDdFN", + "computationalResult": { + "type": "figure", + "result": "Figure 3" + }, + "sourcecode": { + "file": "main.Rmd", + "codelines": [{ + "first_line": 101, + "last_line": 503 + }], + "parameter": [{ + "text": "duration <- 24", + "name": "duration", + "val": 24, + "uiWidget": { + "minValue": 1, + "type": "slider", + "maxValue": 24, + "stepSize": 1, + "caption": "The duration parameter specifies the duration of the flood event in hours." + } + }] + } +} } ``` -## Proxy for UI binding +## Get changed Image from UI binding `GET /api/v1/compendium/:compendium/binding/:binding` -... +### Request parameters -## Run UI binding +- `:compendium` - ID of the compendium for which the UI binding server should be started +- `:binding` - name of the binding in context for which the UI binding server should be started + +#### Add changed bynding parameters as query parameters + +'?newValue0=&newValue1= ...' + + - 'newValue0' The value which should be assigned to the first changeable UI parameter + +### Response + +200 Ok - Image of updated Figure/Table + + +## Start server for one UI Binding `POST /api/v1/compendium/:compendium/binding/:binding` -... +### Request parameters + +- `:compendium` - ID of the compendium for which the UI binding server should be started +- `:binding` - name of the binding in context for which the UI binding server should be started + +### Request body properties + +- Optional + +### Response + + +```json +200 Ok + +{ + "callback": "ok", + "data": { + request.body + } +} +``` ## Search for a UI binding