1 Getting started

For installation and configuration, see here.

library(rama)
#> Welcome to rama v0.0.1!
#> GAMA platform needs to be installed on your machine.
#> See http://www.gama-platform.org for more instructions about GAMA.
#> -- note that GAMA platform was found at /Applications/Gama.app
#> Gama configuration succeed!

1.1 Desiging experiments

We can make an experiment object either by reading an experiment from a GAML file with the load_experiment() funtion or by building it from scratch with the experiment() constructor.

1.1.1 Loading an experiment from a GAML file

Let’s use the following gaml file:

gaml_file <- system.file("models", "sir.gaml", package = "rama")

Loading the experiment sir from this file. Note that we also indicate the names of the folder where we wish to save the simulations outputs. If not specified, the name of the .gaml is used by default:

exp1 <- load_experiment("sir", gaml_file)
#> Loading experiment "sir" from file "sir.gaml"...
#> 
#> Periods of observation ("obsrates") are converted into integers.
#> 
#> Final time step ("tmax") is converted into integer.
#> 
#> Seed is converted into numeric.
#> 
#> Parameters' types are cast according to model definition
#> 

which gives:

exp1
#> Experiment with 1 simulation of 5 parameters and 3 observed variables
#> experiment name:  sir 
#> input gaml file:  /Library/Frameworks/R.framework/Versions/3.5/Resources/library/rama/models/sir.gaml 
#> model parameters:    p_S0, p_I0, p_R0, p_beta, p_gamma 
#> observed variables:  r_S, r_I, r_R 
#> Experiment overview:
#>   p_S0 p_I0 p_R0 p_beta p_gamma r_S r_I r_R tmax seed output
#> 1  999    1    0    1.5    0.15   1   1   1 1000    1     NA

An experiment is a simple data frame:

class(exp1)
#> [1] "experiment" "tbl_df"     "tbl"        "data.frame"

This implies that we will be able to use all the data frame methods to manipulate experiments.

1.1.2 Building an experiment from scratch

Alternatively, an experiment can be built from scratch with the experiment constructor:

df <- data.frame("S0" = 999, "I0" = 1, "R0" = 0, "beta" = 1.5,
                 "gamma" = 0.15, "S" = 1, "I" = 1, "R" = 1,
                 "a" = 2, "b" = 1)

exp2 <- as_experiment(df = df,
           parameters = c("S0", "I0", "R0", "beta", "gamma"),
           obsrates = c("S", "I", "R"), tmax = "a", seed = "b",
           experiment = "sir", model = gaml_file)
#> Periods of observation ("obsrates") are converted into integers.
#> 
#> Final time step ("tmax") is converted into integer.
#> 
#> Parameters' types are cast according to model definition
#> 

Which gives the same thing:

exp2
#> Experiment with 1 simulation of 5 parameters and 3 observed variables
#> experiment name:  sir 
#> input gaml file:  /Library/Frameworks/R.framework/Versions/3.5/Resources/library/rama/models/sir.gaml 
#> model parameters:    p_S0, p_I0, p_R0, p_beta, p_gamma 
#> observed variables:  r_S, r_I, r_R 
#> Experiment overview:
#>   p_S0 p_I0 p_R0 p_beta p_gamma r_S r_I r_R tmax seed output
#> 1  999    1    0    1.5    0.15   1   1   1    2    1     NA

Note that if you enter values of inequal lengths, it will automatically complete:

df <- data.frame("S0" = c(999, 990), "I0" = c(1, 2), "R0" = 0, "beta" = 1.5,
                 "gamma" = 5, "S" = 1, "I" = 1, "R" = 1,
                 "a" = 2, "b" = 1)
exp3 <- as_experiment(df = df, parameters = c(1:5),
           obsrates = c(6:8), tmax = "a", seed = "b",
           experiment = "sir", model = gaml_file)
#> Periods of observation ("obsrates") are converted into integers.
#> 
#> Final time step ("tmax") is converted into integer.
#> 
#> Parameters' types are cast according to model definition
#> 

Which gives:

exp3
#> Experiment with 2 simulations of 5 parameters and 3 observed variables
#> experiment name:  sir 
#> input gaml file:  /Library/Frameworks/R.framework/Versions/3.5/Resources/library/rama/models/sir.gaml 
#> model parameters:    p_S0, p_I0, p_R0, p_beta, p_gamma 
#> observed variables:  r_S, r_I, r_R 
#> Experiment overview:
#>   p_S0 p_I0 p_R0 p_beta p_gamma r_S r_I r_R tmax seed output
#> 1  999    1    0    1.5       5   1   1   1    2    1     NA
#> 2  990    2    0    1.5       5   1   1   1    2    1     NA

Note finally, that we can make smart use of the expand.grid() function of the base package to efficiently generate a complete experimental design:

df <- expand.grid(S0 = c(900, 950, 999),
               I0 = c(100, 50, 1),
               R0 = 0,
               beta = 1.5,
               gamma = .15,
               S = 1,
               I = 1,
               R = 1,
               tmax = 2,
               seed = 1)

exp4 <- as_experiment(df, parameters = c(1:5),
           obsrates = c(6:8), tmax = "tmax", seed = "seed",
           experiment = "sir", model = gaml_file)
#> Periods of observation ("obsrates") are converted into integers.
#> 
#> Final time step ("tmax") is converted into integer.
#> 
#> Parameters' types are cast according to model definition
#> 

Which gives:

exp4
#> Experiment with 9 simulations of 5 parameters and 3 observed variables
#> experiment name:  sir 
#> input gaml file:  /Library/Frameworks/R.framework/Versions/3.5/Resources/library/rama/models/sir.gaml 
#> model parameters:    p_S0, p_I0, p_R0, p_beta, p_gamma 
#> observed variables:  r_S, r_I, r_R 
#> Experiment overview:
#>   p_S0 p_I0 p_R0 p_beta p_gamma r_S r_I r_R tmax seed output
#> 1  900  100    0    1.5    0.15   1   1   1    2    1     NA
#> 2  950  100    0    1.5    0.15   1   1   1    2    1     NA
#> 3  999  100    0    1.5    0.15   1   1   1    2    1     NA
#> 4  900   50    0    1.5    0.15   1   1   1    2    1     NA
#> 5  950   50    0    1.5    0.15   1   1   1    2    1     NA
#> 6  999   50    0    1.5    0.15   1   1   1    2    1     NA
#> 7  900    1    0    1.5    0.15   1   1   1    2    1     NA
#> 8  950    1    0    1.5    0.15   1   1   1    2    1     NA
#> 9  999    1    0    1.5    0.15   1   1   1    2    1     NA

We’ll see more about that in the next sections.

1.1.3 Building an experiment from a data frame

df <- data.frame(
  S0 = c(700, 800, 900, 950, 999),
  R0 = 0,
  beta = 1.5,
  gamma = .15,
  S = 1,
  I = 1,
  tmax = 2,
  seed = sample(5)
)

Constant population size of 1000:

df$I0 <- 1000 - df$S0

df
#>    S0 R0 beta gamma S I tmax seed  I0
#> 1 700  0  1.5  0.15 1 1    2    5 300
#> 2 800  0  1.5  0.15 1 1    2    4 200
#> 3 900  0  1.5  0.15 1 1    2    1 100
#> 4 950  0  1.5  0.15 1 1    2    3  50
#> 5 999  0  1.5  0.15 1 1    2    2   1

Let’s now transform this data frame into an experiment:

exp5 <- as_experiment(df = df,
           parameters = c("S0", "R0", "I0", "beta", "gamma"),
           obsrates = c("S", "I"), tmax = "tmax", seed = "seed",
           experiment = "sir", model = gaml_file)
#> Periods of observation ("obsrates") are converted into integers.
#> 
#> Final time step ("tmax") is converted into integer.
#> 
#> Parameters' types are cast according to model definition
#> 

Which gives:

exp5
#> Experiment with 5 simulations of 5 parameters and 2 observed variables
#> experiment name:  sir 
#> input gaml file:  /Library/Frameworks/R.framework/Versions/3.5/Resources/library/rama/models/sir.gaml 
#> model parameters:    p_S0, p_R0, p_I0, p_beta, p_gamma 
#> observed variables:  r_S, r_I 
#> Experiment overview:
#>   p_S0 p_R0 p_I0 p_beta p_gamma r_S r_I tmax seed output
#> 1  700    0  300    1.5    0.15   1   1    2    5     NA
#> 2  800    0  200    1.5    0.15   1   1    2    4     NA
#> 3  900    0  100    1.5    0.15   1   1    2    1     NA
#> 4  950    0   50    1.5    0.15   1   1    2    3     NA
#> 5  999    0    1    1.5    0.15   1   1    2    2     NA

1.2 Manipulating experiments

As mentioned above, since experiment objects are data frames, all the data frame methods can be used to manipulate them, such as nrow() to know the number of simulations in an experiment:

nrow(exp4)
#> [1] 9

1.2.1 Replicating experiments

From the following experiment

exp1
#> Experiment with 1 simulation of 5 parameters and 3 observed variables
#> experiment name:  sir 
#> input gaml file:  /Library/Frameworks/R.framework/Versions/3.5/Resources/library/rama/models/sir.gaml 
#> model parameters:    p_S0, p_I0, p_R0, p_beta, p_gamma 
#> observed variables:  r_S, r_I, r_R 
#> Experiment overview:
#>   p_S0 p_I0 p_R0 p_beta p_gamma r_S r_I r_R tmax seed output
#> 1  999    1    0    1.5    0.15   1   1   1 1000    1     NA

We can replicate:

exp5 <- repl(exp1, 10)

Which gives:

exp5
#> Experiment with 10 simulations of 5 parameters and 3 observed variables
#> experiment name:  sir 
#> input gaml file:  /Library/Frameworks/R.framework/Versions/3.5/Resources/library/rama/models/sir.gaml 
#> model parameters:    p_S0, p_I0, p_R0, p_beta, p_gamma 
#> observed variables:  r_S, r_I, r_R 
#> Experiment overview:
#>    p_S0 p_I0 p_R0 p_beta p_gamma r_S r_I r_R tmax seed output
#> 1   999    1    0    1.5    0.15   1   1   1 1000    1     NA
#> 2   999    1    0    1.5    0.15   1   1   1 1000    1     NA
#> 3   999    1    0    1.5    0.15   1   1   1 1000    1     NA
#> 4   999    1    0    1.5    0.15   1   1   1 1000    1     NA
#> 5   999    1    0    1.5    0.15   1   1   1 1000    1     NA
#> 6   999    1    0    1.5    0.15   1   1   1 1000    1     NA
#> 7   999    1    0    1.5    0.15   1   1   1 1000    1     NA
#> 8   999    1    0    1.5    0.15   1   1   1 1000    1     NA
#> 9   999    1    0    1.5    0.15   1   1   1 1000    1     NA
#> 10  999    1    0    1.5    0.15   1   1   1 1000    1     NA

On which we could use different seeds for each simulation:

exp5$seed <- sample(10)

Which gives:

exp5
#> Experiment with 10 simulations of 5 parameters and 3 observed variables
#> experiment name:  sir 
#> input gaml file:  /Library/Frameworks/R.framework/Versions/3.5/Resources/library/rama/models/sir.gaml 
#> model parameters:    p_S0, p_I0, p_R0, p_beta, p_gamma 
#> observed variables:  r_S, r_I, r_R 
#> Experiment overview:
#>    p_S0 p_I0 p_R0 p_beta p_gamma r_S r_I r_R tmax seed output
#> 1   999    1    0    1.5    0.15   1   1   1 1000    9     NA
#> 2   999    1    0    1.5    0.15   1   1   1 1000    8     NA
#> 3   999    1    0    1.5    0.15   1   1   1 1000    6     NA
#> 4   999    1    0    1.5    0.15   1   1   1 1000    5     NA
#> 5   999    1    0    1.5    0.15   1   1   1 1000    3     NA
#> 6   999    1    0    1.5    0.15   1   1   1 1000    4     NA
#> 7   999    1    0    1.5    0.15   1   1   1 1000    2     NA
#> 8   999    1    0    1.5    0.15   1   1   1 1000    1     NA
#> 9   999    1    0    1.5    0.15   1   1   1 1000    7     NA
#> 10  999    1    0    1.5    0.15   1   1   1 1000   10     NA

1.2.2 Extracting parameters values

parameters(exp5)
#>    p_S0 p_I0 p_R0 p_beta p_gamma
#> 1   999    1    0    1.5    0.15
#> 2   999    1    0    1.5    0.15
#> 3   999    1    0    1.5    0.15
#> 4   999    1    0    1.5    0.15
#> 5   999    1    0    1.5    0.15
#> 6   999    1    0    1.5    0.15
#> 7   999    1    0    1.5    0.15
#> 8   999    1    0    1.5    0.15
#> 9   999    1    0    1.5    0.15
#> 10  999    1    0    1.5    0.15

1.2.3 Extracting observation rates

obs_rates(exp5)
#>    r_S r_I r_R
#> 1    1   1   1
#> 2    1   1   1
#> 3    1   1   1
#> 4    1   1   1
#> 5    1   1   1
#> 6    1   1   1
#> 7    1   1   1
#> 8    1   1   1
#> 9    1   1   1
#> 10   1   1   1

1.2.4 tmax and seed

As seen above, seed can be extracted and changed with regular data frame methods:

exp5$seed
#>  [1]  9  8  6  5  3  4  2  1  7 10
exp5$seed <- sample(10)
exp5
#> Experiment with 10 simulations of 5 parameters and 3 observed variables
#> experiment name:  sir 
#> input gaml file:  /Library/Frameworks/R.framework/Versions/3.5/Resources/library/rama/models/sir.gaml 
#> model parameters:    p_S0, p_I0, p_R0, p_beta, p_gamma 
#> observed variables:  r_S, r_I, r_R 
#> Experiment overview:
#>    p_S0 p_I0 p_R0 p_beta p_gamma r_S r_I r_R tmax seed output
#> 1   999    1    0    1.5    0.15   1   1   1 1000    7     NA
#> 2   999    1    0    1.5    0.15   1   1   1 1000    1     NA
#> 3   999    1    0    1.5    0.15   1   1   1 1000    8     NA
#> 4   999    1    0    1.5    0.15   1   1   1 1000    6     NA
#> 5   999    1    0    1.5    0.15   1   1   1 1000   10     NA
#> 6   999    1    0    1.5    0.15   1   1   1 1000    2     NA
#> 7   999    1    0    1.5    0.15   1   1   1 1000    9     NA
#> 8   999    1    0    1.5    0.15   1   1   1 1000    4     NA
#> 9   999    1    0    1.5    0.15   1   1   1 1000    3     NA
#> 10  999    1    0    1.5    0.15   1   1   1 1000    5     NA

Same for tmax:

exp5$tmax
#>  [1] 1000 1000 1000 1000 1000 1000 1000 1000 1000 1000
exp5$tmax <- 3L
exp5
#> Experiment with 10 simulations of 5 parameters and 3 observed variables
#> experiment name:  sir 
#> input gaml file:  /Library/Frameworks/R.framework/Versions/3.5/Resources/library/rama/models/sir.gaml 
#> model parameters:    p_S0, p_I0, p_R0, p_beta, p_gamma 
#> observed variables:  r_S, r_I, r_R 
#> Experiment overview:
#>    p_S0 p_I0 p_R0 p_beta p_gamma r_S r_I r_R tmax seed output
#> 1   999    1    0    1.5    0.15   1   1   1    3    7     NA
#> 2   999    1    0    1.5    0.15   1   1   1    3    1     NA
#> 3   999    1    0    1.5    0.15   1   1   1    3    8     NA
#> 4   999    1    0    1.5    0.15   1   1   1    3    6     NA
#> 5   999    1    0    1.5    0.15   1   1   1    3   10     NA
#> 6   999    1    0    1.5    0.15   1   1   1    3    2     NA
#> 7   999    1    0    1.5    0.15   1   1   1    3    9     NA
#> 8   999    1    0    1.5    0.15   1   1   1    3    4     NA
#> 9   999    1    0    1.5    0.15   1   1   1    3    3     NA
#> 10  999    1    0    1.5    0.15   1   1   1    3    5     NA

If you want to stop observing the variable R and observe the variable I every 2 steps, you’d do:

exp5$r_R <- NULL
exp5$r_I <- 2

Which gives:

exp5
#> Experiment with 10 simulations of 5 parameters and 2 observed variables
#> experiment name:  sir 
#> input gaml file:  /Library/Frameworks/R.framework/Versions/3.5/Resources/library/rama/models/sir.gaml 
#> model parameters:    p_S0, p_I0, p_R0, p_beta, p_gamma 
#> observed variables:  r_S, r_I 
#> Experiment overview:
#>    p_S0 p_I0 p_R0 p_beta p_gamma r_S r_I tmax seed output
#> 1   999    1    0    1.5    0.15   1   2    3    7     NA
#> 2   999    1    0    1.5    0.15   1   2    3    1     NA
#> 3   999    1    0    1.5    0.15   1   2    3    8     NA
#> 4   999    1    0    1.5    0.15   1   2    3    6     NA
#> 5   999    1    0    1.5    0.15   1   2    3   10     NA
#> 6   999    1    0    1.5    0.15   1   2    3    2     NA
#> 7   999    1    0    1.5    0.15   1   2    3    9     NA
#> 8   999    1    0    1.5    0.15   1   2    3    4     NA
#> 9   999    1    0    1.5    0.15   1   2    3    3     NA
#> 10  999    1    0    1.5    0.15   1   2    3    5     NA

1.3 Running experiments

Then, we run the experiment by one command run_experiment, in which we specify the experiment and optionally number of cores, output folder for the results of this experiment, parameters file in xml format.

model(exp1)$md5sum
#> /Library/Frameworks/R.framework/Versions/3.5/Resources/library/rama/models/sir.gaml 
#>                                                  "a1316e76832682f5ce9e89ee8e65e2a8"

output <- run_experiment(exp1, hpc = 2)
#> Running experiment plan...

Which gives:

output
#> Experiment with 1 simulation of 5 parameters and 3 observed variables
#> experiment name:  sir 
#> input gaml file:  /Library/Frameworks/R.framework/Versions/3.5/Resources/library/rama/models/sir.gaml 
#> model parameters:    p_S0, p_I0, p_R0, p_beta, p_gamma 
#> observed variables:  r_S, r_I, r_R 
#> Experiment overview:
#>   p_S0 p_I0 p_R0 p_beta p_gamma r_S r_I r_R tmax seed               output
#> 1  999    1    0    1.5    0.15   1   1   1 1000    1 <data.frame[1000,4]>