Skip to content

Commit 1478998

Browse files
omargfhomargfh
committed
add documentation.yaml
1 parent 66d40c6 commit 1478998

File tree

1 file changed

+370
-0
lines changed

1 file changed

+370
-0
lines changed

‎documentation.yaml‎

Lines changed: 370 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,370 @@
1+
extensionName: sr
2+
icon: logos:r-lang
3+
filesToIncludeInManual:
4+
- USING.md
5+
- CITATION.md
6+
- primitives
7+
- TRANSITION.md
8+
markdownTemplate: |
9+
# NetLogo Simple R Extension
10+
11+
This NetLogo extension allows you to run R code from within NetLogo.
12+
13+
{{> BUILDING.md}}
14+
15+
{{> USING.md }}
16+
17+
{{> CITATION.md }}
18+
19+
## Primitives
20+
21+
{{#contents}}{{#prims}}
22+
[`{{name}}`](#{{primitive.extensionName}}{{primitive.name}})
23+
{{/prims}}{{/contents}}
24+
25+
{{#primitives}}
26+
{{> primTemplate}}
27+
{{/primitives}}
28+
29+
{{> TRANSITION.md }}
30+
primTemplate: |2
31+
32+
### `{{name}}`
33+
34+
```NetLogo
35+
{{#examples}}
36+
{{#isOptional}}({{/isOptional}}{{primitive.fullName}}{{#args}} *{{argumentPlaceholder}}*{{/args}}{{#isOptional}}){{/isOptional}}
37+
{{/examples}}
38+
```
39+
40+
{{{description}}}
41+
primitives:
42+
- description: |2
43+
44+
Create the R session that this extension will use to execute code.
45+
This command *must* be run before running any other R extension primitive.
46+
Running this command again will shutdown the current R environment and start a new one.
47+
name: setup
48+
type: command
49+
- alternateArguments:
50+
- name: R-statement
51+
type: string
52+
- type: repeatable anything
53+
arguments:
54+
- name: R-statement
55+
type: string
56+
description: |2
57+
58+
59+
Runs the given R statements in the current session.
60+
To make multi-line R code easier to run, this command will take multiple strings,
61+
each of which will be interpreted as a separate line of R code. This requires
62+
putting the command in parentheses.
63+
64+
For instance:
65+
66+
```NetLogo
67+
(sr:run
68+
"domain <- seq(-3.14, 3.14, 0.01)"
69+
"range <- sin(domain)"
70+
"png('my_file.png')"
71+
"plot(domain, range, "
72+
" pch = 20,"
73+
" main = 'y = sin(x)',"
74+
" xlab = 'x',"
75+
" ylab = 'y')"
76+
"dev.off()"
77+
)
78+
```
79+
80+
`sr:run` will wait for the statements to finish before continuing.
81+
If you have long-running R code, NetLogo may freeze for a bit while it runs.
82+
name: run
83+
type: command
84+
- arguments:
85+
- name: R-expression
86+
type: string
87+
description: |2
88+
89+
Evaluates the given R expression and reports the result.
90+
`rs:runresult` attempts to convert from R data types to NetLogo data types.
91+
92+
93+
Numbers, strings, and booleans convert as you would expect, except for outliers
94+
like Infinity and NaN which will be converted into the strings 'Inf' and 'NaN',
95+
respectively.
96+
97+
98+
R vectors and R lists will be converted to NetLogo lists. NA values will be
99+
converted into the string 'NA'.
100+
101+
102+
R matrices will be flattened into one-dimensional lists using column-major order.
103+
If you want to convert a matrix into a list of lists before sending it to NetLogo,
104+
use the R `asplit` command.
105+
To convert into a list of column lists, use `asplit(<matrix>, 1)`;
106+
for a list of row lists, use `asplit(<matrix>, 2)`.
107+
108+
109+
An R DataFrame will be converted into a list of lists, where the first item in
110+
each sublist is the name of the column and the second item is a list containing
111+
all that row data.
112+
For example, the first 6 rows of the `iris` dataset will be converted into NetLogo like so:
113+
```NetLogo
114+
[
115+
["Sepal.Length" [5.1 4.9 4.7 4.6 5 5.4]]
116+
["Sepal.Width" [3.5 3 3.2 3.1 3.6 3.9]]
117+
["Petal.Length" [1.4 1.4 1.3 1.5 1.4 1.7]]
118+
["Petal.Width" [0.2 0.2 0.2 0.2 0.2 0.4]]
119+
["Species" ["setosa" "setosa" "setosa" "setosa" "setosa" "setosa"]]
120+
]
121+
```
122+
123+
Other objects will be converted to a string representation if possible and and may throw
124+
an error if not.
125+
name: runresult
126+
returns: anything
127+
type: reporter
128+
- arguments:
129+
- name: variable-name
130+
type: string
131+
- name: value
132+
type: anything
133+
description: |2
134+
135+
Sets a variable in the R session with the given name to the given NetLogo value.
136+
NetLogo objects will be converted to R objects as expected.
137+
138+
139+
Note that lists in NetLogo are converted into lists in R if the elements are of different
140+
types. If all the elements of a NetLogo list are of the identical number, boolean, or
141+
string type then the data will be automatically converted into a vector in R.
142+
143+
```NetLogo
144+
sr:set "x" 42
145+
sr:run "print(x)" ;; prints `[1] 42` to the command center
146+
sr:set "y" [1 2 3]
147+
sr:run "print(typeof(y))" ;; prints `[1] "double"` to the command center
148+
sr:run "print(typeof(list(y)))" ;; prints `[1] "list"` to the command center
149+
sr:run "print(y)" ;; prints `[1] 1 2 3` to the command center
150+
show sr:runresult "y" ;; reports [1 2 3]
151+
```
152+
153+
Agents are converted into lists with named elements for each agent variable.
154+
155+
Agentsets are converted into a list of the above lists. If you want to convert
156+
agents to a data frame, see `sr:set-agent-data-frame`. If you want to use `sr:set`
157+
and do the conversion manually, try the following:
158+
159+
```R
160+
my_data_frame <- as.data.frame(do.call(rbind, <agentset-list-of-lists>))
161+
```
162+
163+
For example:
164+
```NetLogo
165+
breed [goats goat]
166+
goats-own [energy ]
167+
create-goats 2 [ set color 75 ]
168+
ask goat 0 [ set energy 42 set xcor 5]
169+
ask goat 1 [ set energy -42 set xcor -5]
170+
171+
sr:set "goat" goat 0
172+
sr:run "print(typeof(goat))" ;; prints `[1] "list"` to the command center
173+
sr:run "print(goat)"
174+
;; Should output:
175+
;; $WHO
176+
;; [1] 0
177+
;;
178+
;; $COLOR
179+
;; [1] 75
180+
;; (etc.)
181+
182+
sr:set "goats_list_of_lists" goats
183+
sr:run "goats_data_frame <- as.data.frame(do.call(rbind, goats_list_of_lists))"
184+
sr:run "print(goats_data_frame)"
185+
;; Should output:
186+
;; WHO COLOR HEADING XCOR YCOR SHAPE LABEL LABEL-COLOR BREED HIDDEN? SIZE
187+
;; 1 0 75 82 5 0 default 9.9 GOATS FALSE 1
188+
;; 2 1 75 200 -5 0 default 9.9 GOATS FALSE 1
189+
;; PEN-SIZE PEN-MODE ENERGY
190+
;; 1 1 up 42
191+
;; 2 1 up -42
192+
;;
193+
```
194+
195+
Agents with variables containing references to agentsets will have those variables converted into the string representation of that agentset.
196+
name: set
197+
type: command
198+
- alternateArguments:
199+
- name: r-variable-name
200+
type: string
201+
- type: agent or agentset
202+
- name: agent-variable-name1
203+
type: string
204+
- name: agent-variable-name2...
205+
type: repeatable string
206+
arguments:
207+
- name: r-variable-name
208+
type: string
209+
- type: agent or agentset
210+
- name: agent-variable-name
211+
type: string
212+
description: |
213+
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.
214+
215+
```
216+
clear-all
217+
sr:setup
218+
create-turtles 2
219+
ask turtle 0 [ set color red set xcor 5]
220+
ask turtle 1 [ set color blue set xcor -5]
221+
(sr:set-agent "t0" turtle 0 "who" "color" "xcor" "hidden?")
222+
sr:run "print(typeof(t0))"
223+
;; [1] "list"
224+
sr:run "print(t0)"
225+
;; $who
226+
;; [1] 0
227+
;;
228+
;; $color
229+
;; [1] 15
230+
;;
231+
;; $xcor
232+
;; [1] 5
233+
;;
234+
;; $`hidden?`
235+
;; [1] FALSE
236+
```
237+
name: set-agent
238+
type: command
239+
- alternateArguments:
240+
- name: r-variable-name
241+
type: string
242+
- name: agents
243+
type: agent or agentset
244+
- name: agent-variable-name1
245+
type: string
246+
- name: agent-variable-name2...
247+
type: repeatable string
248+
arguments:
249+
- name: r-variable-name
250+
type: string
251+
- name: agents
252+
type: agent or agentset
253+
- name: agent-variable-name
254+
type: string
255+
description: |
256+
Creates a new data frame in R with the given variable name.
257+
The columns will have the names of the NetLogo agent variables used and each row will
258+
be one agent's data. If you want multiple agent variables make sure to surround
259+
the command in parenthesis.
260+
261+
```
262+
clear-all
263+
sr:setup
264+
create-turtles 2
265+
ask turtle 0 [ set color red set xcor 5]
266+
ask turtle 1 [ set color blue set xcor -5]
267+
(sr:set-agent-data-frame "turtles_data_frame" turtles "who" "color" "xcor" "hidden?")
268+
sr:run "print(typeof(turtles_data_frame))"
269+
;; [1] "list"
270+
sr:run "print(is.data.frame(turtles_data_frame))"
271+
;; [1] TRUE
272+
sr:run "print(turtles_data_frame)"
273+
;; who color xcor hidden?
274+
;; 1 0 15 5 FALSE
275+
;; 2 1 105 -5 FALSE
276+
```
277+
name: set-agent-data-frame
278+
type: command
279+
- alternateArguments:
280+
- name: variable-name
281+
type: string
282+
- name: column-name1
283+
type: string
284+
- type: list or anything 1
285+
- name: column-name2
286+
type: string
287+
- type: list or anything 2...
288+
arguments:
289+
- name: r-variable-name
290+
type: string
291+
- name: column-name
292+
type: string
293+
- type: list or anything
294+
description: |
295+
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.
296+
297+
```
298+
clear-all
299+
sr:setup
300+
let l1 [10 20 30 40]
301+
let l2 [false true false false]
302+
let l3 ["orange" "green" "blue" "purple"]
303+
(sr:set-data-frame "df1" "score" l1 "enabled" l2 "color" l3)
304+
sr:run "print(typeof(df1))"
305+
;; [1] "list"
306+
sr:run "print(is.data.frame(df1))"
307+
;; [1] TRUE
308+
sr:run "print(df1)"
309+
;; score enabled color
310+
;; 1 10 FALSE orange
311+
;; 2 20 TRUE green
312+
;; 3 30 FALSE blue
313+
;; 4 40 FALSE purple
314+
```
315+
name: set-data-frame
316+
type: command
317+
- alternateArguments:
318+
- name: r-variable-name
319+
type: string
320+
- type: anything1
321+
- type: anything2...
322+
arguments:
323+
- name: r-variable-name
324+
type: string
325+
- type: anything
326+
description: Creates a new list in R with the given variable name. You can add additional values by surrounding the command in parenthesis.
327+
name: set-list
328+
type: command
329+
- alternateArguments:
330+
- name: r-variable-name
331+
type: string
332+
- name: column-name1
333+
type: string
334+
- type: list or anything 1
335+
- name: column-name2
336+
type: string
337+
- type: list or anything 2...
338+
arguments:
339+
- name: r-variable-name
340+
type: string
341+
- name: column-name
342+
type: string
343+
- type: list or anything
344+
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.
345+
name: set-named-list
346+
type: command
347+
- arguments: []
348+
description: Activates the visual plot device for R, popping open a window if one is not already open.
349+
name: set-plot-device
350+
type: command
351+
- description: |2
352+
353+
354+
Outputs the R home directory which is the top-level directory of the R installation
355+
being run.
356+
357+
```netlogo
358+
observer> sr:setup
359+
observer> show sr:r-home
360+
observer: "/Library/Frameworks/R.framework/Resources"
361+
```
362+
name: r-home
363+
returns: string
364+
type: reporter
365+
- description: |2
366+
367+
368+
Opens the R console. This console can be opened via the menu bar under the SimpleR heading.
369+
name: show-console
370+
type: command

0 commit comments

Comments
 (0)