Add documentation.yaml for Helio extension builder

documentation.yaml

@@ -0,0 +1,370 @@
+extensionName: sr
+icon: logos:r-lang
+filesToIncludeInManual:
+- USING.md
+- CITATION.md
+- primitives
+- TRANSITION.md
+markdownTemplate: |
+  # NetLogo Simple R Extension
+
+  This NetLogo extension allows you to run R code from within NetLogo.
+
+  {{> BUILDING.md}}
+
+  {{> USING.md }}
+
+  {{> CITATION.md }}
+
+  ## Primitives
+
+  {{#contents}}{{#prims}}
+  [`{{name}}`](#{{primitive.extensionName}}{{primitive.name}})
+  {{/prims}}{{/contents}}
+
+  {{#primitives}}
+  {{> primTemplate}}
+  {{/primitives}}
+
+  {{> TRANSITION.md }}
+primTemplate: |2
+
+  ### `{{name}}`
+
+  ```NetLogo
+  {{#examples}}
+  {{#isOptional}}({{/isOptional}}{{primitive.fullName}}{{#args}} *{{argumentPlaceholder}}*{{/args}}{{#isOptional}}){{/isOptional}}
+  {{/examples}}
+  ```
+
+  {{{description}}}
+primitives:
+- description: |2
+
+    Create the R session that this extension will use to execute code.
+    This command *must* be run before running any other R extension primitive.
+    Running this command again will shutdown the current R environment and start a new one.
+  name: setup
+  type: command
+- alternateArguments:
+  - name: R-statement
+    type: string
+  - type: repeatable anything
+  arguments:
+  - name: R-statement
+    type: string
+  description: |2
+
+
+    Runs the given R statements in the current session.
+    To make multi-line R code easier to run, this command will take multiple strings,
+    each of which will be interpreted as a separate line of R code. This requires
+    putting the command in parentheses.
+
+    For instance:
+
+    ```NetLogo
+    (sr:run
+      "domain <- seq(-3.14, 3.14, 0.01)"
+      "range <- sin(domain)"
+      "png('my_file.png')"
+      "plot(domain, range, "
+      "     pch = 20,"
+      "     main = 'y = sin(x)',"
+      "     xlab = 'x',"
+      "     ylab = 'y')"
+      "dev.off()"
+    )
+    ```
+
+    `sr:run` will wait for the statements to finish before continuing.
+    If you have long-running R code, NetLogo may freeze for a bit while it runs.
+  name: run
+  type: command
+- arguments:
+  - name: R-expression
+    type: string
+  description: |2
+
+    Evaluates the given R expression and reports the result.
+    `rs:runresult` attempts to convert from R data types to NetLogo data types.
+
+
+    Numbers, strings, and booleans convert as you would expect, except for outliers
+    like Infinity and NaN which will be converted into the strings 'Inf' and 'NaN',
+    respectively.
+
+
+    R vectors and R lists will be converted to NetLogo lists. NA values will be
+    converted into the string 'NA'.
+
+
+    R matrices will be flattened into one-dimensional lists using column-major order.
+    If you want to convert a matrix into a list of lists before sending it to NetLogo,
+    use the R `asplit` command.
+    To convert into a list of column lists, use `asplit(<matrix>, 1)`;
+    for a list of row lists, use `asplit(<matrix>, 2)`.
+
+
+    An R DataFrame will be converted into a list of lists, where the first item in
+    each sublist is the name of the column and the second item is a list containing
+    all that row data.
+    For example, the first 6 rows of the `iris` dataset will be converted into NetLogo like so:
+    ```NetLogo
+    [
+      ["Sepal.Length" [5.1 4.9 4.7 4.6 5 5.4]]
+      ["Sepal.Width" [3.5 3 3.2 3.1 3.6 3.9]]
+      ["Petal.Length" [1.4 1.4 1.3 1.5 1.4 1.7]]
+      ["Petal.Width" [0.2 0.2 0.2 0.2 0.2 0.4]]
+      ["Species" ["setosa" "setosa" "setosa" "setosa" "setosa" "setosa"]]
+    ]
+    ```
+
+    Other objects will be converted to a string representation if possible and and may throw
+    an error if not.
+  name: runresult
+  returns: anything
+  type: reporter
+- arguments:
+  - name: variable-name
+    type: string
+  - name: value
+    type: anything
+  description: |2
+
+    Sets a variable in the R session with the given name to the given NetLogo value.
+    NetLogo objects will be converted to R objects as expected.
+
+
+    Note that lists in NetLogo are converted into lists in R if the elements are of different
+    types.  If all the elements of a NetLogo list are of the identical number, boolean, or
+    string type then the data will be automatically converted into a vector in R.
+
+    ```NetLogo
+    sr:set "x" 42
+    sr:run "print(x)" ;; prints `[1] 42` to the command center
+    sr:set "y" [1 2 3]
+    sr:run "print(typeof(y))" ;; prints `[1] "double"` to the command center
+    sr:run "print(typeof(list(y)))" ;; prints `[1] "list"` to the command center
+    sr:run "print(y)" ;; prints `[1] 1 2 3` to the command center
+    show sr:runresult "y" ;; reports [1 2 3]
+    ```
+
+    Agents are converted into lists with named elements for each agent variable.
+
+    Agentsets are converted into a list of the above lists. If you want to convert
+    agents to a data frame, see `sr:set-agent-data-frame`.  If you want to use `sr:set`
+    and do the conversion manually, try the following:
+
+    ```R
+    my_data_frame <- as.data.frame(do.call(rbind, <agentset-list-of-lists>))
+    ```
+
+    For example:
+    ```NetLogo
+    breed [goats goat]
+    goats-own [energy ]
+    create-goats 2 [ set color 75 ]
+    ask goat 0 [ set energy 42 set xcor 5]
+    ask goat 1 [ set energy -42 set xcor -5]
+
+    sr:set "goat" goat 0
+    sr:run "print(typeof(goat))" ;; prints `[1] "list"` to the command center
+    sr:run "print(goat)"
+    ;; Should output:
+    ;; $WHO
+    ;; [1] 0
+    ;;
+    ;; $COLOR
+    ;; [1] 75
+    ;; (etc.)
+
+    sr:set "goats_list_of_lists" goats
+    sr:run "goats_data_frame <- as.data.frame(do.call(rbind, goats_list_of_lists))"
+    sr:run "print(goats_data_frame)"
+    ;; Should output:
+    ;;   WHO COLOR HEADING XCOR YCOR   SHAPE LABEL LABEL-COLOR BREED HIDDEN? SIZE
+    ;; 1   0    75      82    5    0 default               9.9 GOATS   FALSE    1
+    ;; 2   1    75     200   -5    0 default               9.9 GOATS   FALSE    1
+    ;;   PEN-SIZE PEN-MODE ENERGY
+    ;; 1        1       up     42
+    ;; 2        1       up    -42
+    ;;
+    ```
+
+    Agents with variables containing references to agentsets will have those variables converted into the string representation of that agentset.
+  name: set
+  type: command
+- alternateArguments:
+  - name: r-variable-name
+    type: string
+  - type: agent or agentset
+  - name: agent-variable-name1
+    type: string
+  - name: agent-variable-name2...
+    type: repeatable string
+  arguments:
+  - name: r-variable-name
+    type: string
+  - type: agent or agentset
+  - name: agent-variable-name
+    type: string
+  description: |
+    Creates a new named list in R with the given variable name.  If you want multiple agent variables make sure to surround the command in parenthesis.
+
+    ```
+    clear-all
+    sr:setup
+    create-turtles 2
+    ask turtle 0 [ set color red set xcor 5]
+    ask turtle 1 [ set color blue set xcor -5]
+    (sr:set-agent "t0" turtle 0 "who" "color" "xcor" "hidden?")
+    sr:run "print(typeof(t0))"
+    ;; [1] "list"
+    sr:run "print(t0)"
+    ;; $who
+    ;; [1] 0
+    ;;
+    ;; $color
+    ;; [1] 15
+    ;;
+    ;; $xcor
+    ;; [1] 5
+    ;;
+    ;; $`hidden?`
+    ;; [1] FALSE
+    ```
+  name: set-agent
+  type: command
+- alternateArguments:
+  - name: r-variable-name
+    type: string
+  - name: agents
+    type: agent or agentset
+  - name: agent-variable-name1
+    type: string
+  - name: agent-variable-name2...
+    type: repeatable string
+  arguments:
+  - name: r-variable-name
+    type: string
+  - name: agents
+    type: agent or agentset
+  - name: agent-variable-name
+    type: string
+  description: |
+    Creates a new data frame in R with the given variable name.
+        The columns will have the names of the NetLogo agent variables used and each row will
+        be one agent's data.  If you want multiple agent variables make sure to surround
+        the command in parenthesis.
+
+    ```
+    clear-all
+    sr:setup
+    create-turtles 2
+    ask turtle 0 [ set color red set xcor 5]
+    ask turtle 1 [ set color blue set xcor -5]
+    (sr:set-agent-data-frame "turtles_data_frame" turtles "who" "color" "xcor" "hidden?")
+    sr:run "print(typeof(turtles_data_frame))"
+    ;; [1] "list"
+    sr:run "print(is.data.frame(turtles_data_frame))"
+    ;; [1] TRUE
+    sr:run "print(turtles_data_frame)"
+    ;;   who color xcor hidden?
+    ;; 1   0    15    5   FALSE
+    ;; 2   1   105   -5   FALSE
+    ```
+  name: set-agent-data-frame
+  type: command
+- alternateArguments:
+  - name: variable-name
+    type: string
+  - name: column-name1
+    type: string
+  - type: list or anything 1
+  - name: column-name2
+    type: string
+  - type: list or anything 2...
+  arguments:
+  - name: r-variable-name
+    type: string
+  - name: column-name
+    type: string
+  - type: list or anything
+  description: |
+    Creates a new data frame in R with the given variable name.  The columns will have the names given.  If the value for a column is a list, those will be the values for that column.  If the value is a non-list, it will be used as the single item in that column.  You can add additional column names and values by surrounding the command in parenthesis.
+
+    ```
+    clear-all
+    sr:setup
+    let l1 [10 20 30 40]
+    let l2 [false true false false]
+    let l3 ["orange" "green" "blue" "purple"]
+    (sr:set-data-frame "df1" "score" l1 "enabled" l2 "color" l3)
+    sr:run "print(typeof(df1))"
+    ;; [1] "list"
+    sr:run "print(is.data.frame(df1))"
+    ;; [1] TRUE
+    sr:run "print(df1)"
+    ;;   score enabled  color
+    ;; 1    10   FALSE orange
+    ;; 2    20    TRUE  green
+    ;; 3    30   FALSE   blue
+    ;; 4    40   FALSE purple
+    ```
+  name: set-data-frame
+  type: command
+- alternateArguments:
+  - name: r-variable-name
+    type: string
+  - type: anything1
+  - type: anything2...
+  arguments:
+  - name: r-variable-name
+    type: string
+  - type: anything
+  description: Creates a new list in R with the given variable name.  You can add additional values by surrounding the command in parenthesis.
+  name: set-list
+  type: command
+- alternateArguments:
+  - name: r-variable-name
+    type: string
+  - name: column-name1
+    type: string
+  - type: list or anything 1
+  - name: column-name2
+    type: string
+  - type: list or anything 2...
+  arguments:
+  - name: r-variable-name
+    type: string
+  - name: column-name
+    type: string
+  - type: list or anything
+  description: Creates a new named list in R with the given variable name.  The columns will have the names given.  If the value for a column is a list, those will be the values for that column.  If the value is a non-list, it will be used as the single item in that column.  You can add additional column names and values by surrounding the command in parenthesis.
+  name: set-named-list
+  type: command
+- arguments: []
+  description: Activates the visual plot device for R, popping open a window if one is not already open.
+  name: set-plot-device
+  type: command
+- description: |2
+
+
+    Outputs the R home directory which is the top-level directory of the R installation
+    being run.
+
+    ```netlogo
+    observer> sr:setup
+    observer> show sr:r-home
+    observer: "/Library/Frameworks/R.framework/Resources"
+    ```
+  name: r-home
+  returns: string
+  type: reporter
+- description: |2
+
+
+    Opens the R console. This console can be opened via the menu bar under the SimpleR heading.
+  name: show-console
+  type: command