documentation.conf

extensionName = "sr"

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 = """
### `{{name}}`

```NetLogo
{{#examples}}
{{#isOptional}}({{/isOptional}}{{primitive.fullName}}{{#args}} *{{argumentPlaceholder}}*{{/args}}{{#isOptional}}){{/isOptional}}
{{/examples}}
```

{{{description}}}
"""


primitives = [
  {
    name: setup,
    type: command,
    description: """
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: run,
    type: command,
    arguments: [ {name: R-statement, type: string} ],
    alternateArguments: [ {name: R-statement, type: string}, {type: repeatable anything} ],
    description: """

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: runresult,
    type: reporter,
    arguments: [ {name: R-expression, type: string} ],
    returns: anything,

    description: """
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: set,
    type: command,
    arguments: [ {name: variable-name, type: string}, {name: value, type: anything} ],
    description: """
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-agent,
    type: command,
    arguments: [ {name: r-variable-name, type: string}, {type: agent or agentset}, {name: agent-variable-name, type: string} ],
    alternateArguments: [ {name: r-variable-name, type: string}, {type: agent or agentset}, {name: agent-variable-name1, type: string}, {name: agent-variable-name2..., type: repeatable 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-data-frame,
    type: command,
    arguments: [ {name: r-variable-name, type: string}, {name: agents, type: agent or agentset}, {name: agent-variable-name, type: string} ],
    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} ],
    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-data-frame,
    type: command,
    arguments: [ {name: r-variable-name, type: string}, {name: column-name, type: string}, {type: list or anything} ],
    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..."} ],
    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-list,
    type: command,
    arguments: [ {name: r-variable-name, type: string}, {type: anything} ],
    alternateArguments: [ {name: r-variable-name, type: string}, {type: "anything1"}, {type: "anything2..."} ],
    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-named-list,
    type: command,
    arguments: [ {name: r-variable-name, type: string}, {name: column-name, type: string}, {type: list or anything} ],
    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..."} ],
    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-plot-device,
    type: command,
    arguments: [],
    description: "Activates the visual plot device for R, popping open a window if one is not already open."
  },
  {
    name: r-home,
    type: reporter,
    returns: string,
    description: """

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: show-console,
    type: command,
    description: """

Opens the R console. This console can be opened via the menu bar under the SimpleR heading.
"""
}
]