diff --git a/documentation.yaml b/documentation.yaml new file mode 100644 index 0000000..536cf7e --- /dev/null +++ b/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(, 1)`; + for a list of row lists, use `asplit(, 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, )) + ``` + + 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