In choisy/gamar3: Interface to the Agent-Based Modeling Platform GAMA

# general options:
knitr::knit_hooks$set(margin = function(before, options, envir) {
  if (before) par(mgp = c(1.5, .5, 0), bty = "n", plt = c(.105, .97, .13, .97))
  else NULL
})

knitr::opts_chunk$set(margin = TRUE, prompt = TRUE, comment = "",
                      collapse = TRUE, cache = FALSE, autodep = TRUE,
                      dev.args = list(pointsize = 11), fig.height = 3.5,
                      fig.width = 4.24725, fig.retina = 2, fig.align = "center")

# overwritting some functions:
library <- function(...) base::library(..., warn.conflicts = FALSE, quiet = TRUE)
require <- function(...) base::require(..., warn.conflicts = FALSE, quiet = TRUE)

# redefining the locales:
l <- "en_US.UTF-8"
Sys.setenv(LANGAGE = l)
Sys.setlocale(locale = l)
Sys.setlocale("LC_MESSAGES", l)

# cleaning the packages space:
search_path <- search()
pkgs <- c("stats", "graphics", "grDevices", "utils", "datasets", "methods", "base")
tdet <- grep("package", search_path[!(search_path %in% paste0("package:", pkgs))],
             value = TRUE)
for(i in tdet) detach(i, unload = TRUE, character.only = TRUE)

workspace <- "/Users/choisy/using_gamar"
if (dir.exists(workspace)) unlink(workspace, recursive = TRUE)
dir.create(workspace)
knitr::opts_knit$set(root.dir = workspace)
rm(list = ls())

Information about the current R session is at the bottom of the document

Installing and loading gamar

Installing devtools if needed:

install.packages("devtools")

Installing gamar:

devtools::install_github("choisy/gamar")

Loading gamar:

library(gamar)

Defining the path to GAMA executable, if needed (if you are using Mac OS, gamar will by default use the /Applications/Gama.app if it exists):

defpath("path_to_your_GAMA_folder")

Handling experiments

There are a number of built-in examples in the gamar package, of which you can see the list:

examples()

To use one of these examples, we recommand that you first move it to your local directory (by default):

dir()
examples("sir")
dir()

or to any other directory of your choice:

examples("sir", "one_directory")
dir()
dir("one_directory")

If a file with the same name already exists in the destination directory, the name of the copied file is appended a digit making it unique:

examples("sir", "one_directory")
dir("one_directory")

The minimum that these examples include is a .gaml file that specifies the model and some experiment(s). Sometimes additional files are also included, for examples, shape files defining the space. That's the case for the predator-prey model. All the files of the model are then contained in a directory:

dir()
examples("predator-prey")
dir("predator_prey", recursive = TRUE)

Again, if the name of the directory already exists in the destination directory, the name of the directory is appended a digit making it unique:

examples("predator-prey")
dir()

Last thing about this examples function is that you can copied several models at the same time:

examples(c("sir", "predator-prey"))

specifying a common destination directory:

examples(c("sir", "predator-prey"), "common_directory")
dir()
dir("common_directory")

or a different directory for each model:

examples(c("sir", "predator-prey"), c("directory1", "directory2"))
dir()
dir("directory1")
dir("directory2")

Once the file(s) of a model are copied to any of your local working directory (on which you have writting rights), you can load an experiment from a .gaml file. For example, loading experiment sir from the sir.gaml GAML file:

dir()
ls()
sir <- experiment("sir", "sir.gaml") # creates workgamar with sir_1.xml in it
dir()
ls()

Note that it creates object sir (which is the name of the experiment) in the workspace. This object is linked to the original .gaml file that contains the experiment description (in terms of parameters values and outputs) as well as the description of the model (in terms of world and species). Note finally that it also creates a directory workgamar that contains an XML version of the experiment. The loaded object is of class experiment:

class(sir)

or

is.experiment(sir)

You can see that this object contains the experiment description in terms of parameters values and outputs as well as the link to the original .gaml file that contains in addition the description of the model in terms of world and species:

sir

There are a number of accessor and assignator methods associated to this experiment class. You can retrive the names of the experiment parameters (input and output):

names(sir)

And the name of the .gaml file to which your experiment object is linked:

fname(sir)

And you can also change the .gaml file to which the experiment object is linked, either specifying a relative path:

fname(sir) <- "sir_1.gaml"
fname(sir)

or an absolute path:

fname(sir) <- paste0(getwd(), "/sir.gaml")
fname(sir)

The most general accessor/assignator is through the [ operator that can take a single argument:

sir["S0"]
sir["I"]
sir["sourcePath"]

or multiple arguments at the same time:

sir[c("I0", "R", "finalStep")]

To change the value of one parameter, it's as simple as

sir["R0"]
sir["R0"] <- 10
sir["R0"]

Same thing with several parameters at the same time:

sir[c("beta", "gamma")]
sir[c("beta", "gamma")] <- 3 * sir[c("beta", "gamma")]
sir[c("beta", "gamma")]

Note the equivalences between the [ accessor/assignator operator and the name and fname shortcut functions:

fname(sir)

is equivalent to

sir["sourcePath"]

The only difference being that the shortcut functions return unnamed vectors.

Model

To finish with experiments handling, with can also edit the .gaml model file:

model(sir)

This allows to edit the .gaml file to which the experiment is linked.

Plans of experiments

Let's see now how we can gather together several experiments of a same model into an experiment plan and let's introduce the plan class:

plan1 <- c(sir, sir)
class(plan1)
is.plan(plan1)

You can see a summary of the content of the experimental plan:

plan1

Note that it renames experiments so that they have non-conflicting names. Note also that all the characteristic of the experiments of a plan is that they are all linked to the same .gaml file (i.e. the same underlying model structure). An alternative way to define the structure of a plan is with the rep function:

plan2 <- rep(sir, 3)
plan2

A third way to define a plan of experiments is from an experiment and a data frame of values. As an example, let's consider the following fake data frame:

n <- 7
thenames <- names(sir)
thenames <- thenames[!(thenames %in% c("experiment", "sourcePath"))]
fakedf <- setNames(
  10 * as.data.frame(matrix(round(runif(n*length(thenames)), 4), n)),
  thenames)
fakedf$id <- 1:7

fakedf

A plan of experiments can be generated from this data frame, simply by associating it to the sir experiment:

(sir_plan <- plan(fakedf, sir))

Note that the names of the experiments come from the row names of the data frames:

names(sir_plan)
names(sir_plan["1"])
# which is equivalent to:
names(sir_plan[1])

If we had more explicit row names in the data frame we'd get this:

rownames(fakedf) <- paste0("sir", seq_len(nrow(fakedf)))
(sir_plan <- plan(fakedf, sir))

Note also that you can combine objects of class experiment and plan in the concatenator function c:

plan3 <- c(sir, plan1, plan2)
plan3

There are a number of useful methods defined with this plan class to retrieve the number of experiments in the experimental plan:

length(plan3)

or to see or change the names of the experiments in the plan:

names(plan3)
names(plan3) <- paste0("sir", seq_along(plan3))
plan3

Simulating experiments

out1 <- run(sir, 1, "output1")
str(out1)

out2 <- run(plan1, 1, "output2")
str(out2)

Session information

sessionInfo()

choisy/gamar3 documentation built on May 28, 2019, 7:17 p.m.