| Title: | Invoke 'Repast Simphony' Simulation Models |
|---|---|
| Description: | An R and Repast integration tool for running individual-based (IbM) simulation models developed using 'Repast Simphony' Agent-Based framework directly from R code supporting multicore execution. This package integrates 'Repast Simphony' models within R environment, making easier the tasks of running and analyzing model output data for automated parameter calibration and for carrying out uncertainty and sensitivity analysis using the power of R environment. |
| Authors: | Antonio Prestes Garcia [aut, cre], Alfonso Rodriguez-Paton [aut, ths] |
| Maintainer: | Antonio Prestes Garcia <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.8.0 |
| Built: | 2024-10-17 07:04:27 UTC |
| Source: | CRAN |
Builds up the factor collection.
AddFactor(factors = c(), lambda = "qunif", name, min, max, int = FALSE)AddFactor(factors = c(), lambda = "qunif", name, min, max, int = FALSE)
factors |
The current factor collection |
lambda |
The function to apply FUN(p,min,max) |
name |
The name of factor |
min |
The minimun of parameter p |
max |
The maximun of parameter p |
int |
Boolean for truncating the factor value |
The collection of created factors
## Not run: f<- AddFactor(name="Age",min=20,max=60) f<- AddFactor(factors=f, name="Weight",min=50,max=120) ## End(Not run)## Not run: f<- AddFactor(name="Age",min=20,max=60) f<- AddFactor(factors=f, name="Weight",min=50,max=120) ## End(Not run)
Creates or appends the factor collection
AddFactor0(factors = c(), ...)AddFactor0(factors = c(), ...)
factors |
The current factor collection |
... |
The variadic parameter list |
The factor collection
## Not run: f<- AddFactor0(name="Age",min=20,max=60) f<- AddFactor0(factors=f, name="Weight",min=50,max=120) ## End(Not run)## Not run: f<- AddFactor0(name="Age",min=20,max=60) f<- AddFactor0(factors=f, name="Weight",min=50,max=120) ## End(Not run)
This function stores the output of the last model execution and it is intended to be used internally.
AddResults(d)AddResults(d)
d |
A data frame containing one replication data |
The Design Of Experiments Base function
AoE.Base(m, factors = c(), fun = NULL)AoE.Base(m, factors = c(), fun = NULL)
m |
The base design matrix |
factors |
A subset of model parameters |
fun |
The function which will be applied to m |
The design matrix
This function Calculates the relative squared
deviation (RSD or CoV) for an used provided column name key
in the parameter dataset.
AoE.ColumnCoV(dataset, key)AoE.ColumnCoV(dataset, key)
dataset |
A model output dataset |
key |
Column name from output dataset |
A data frame with Coefficient of variations
A simple funcion for calculate the Coefficient of Variation
AoE.CoV(d)AoE.CoV(d)
d |
The data collection |
The coefficient of variation for data
Generate a Full Factorial sampling for evaluating the parameters of a model.
AoE.FullFactorial(n = 10, factors = c())AoE.FullFactorial(n = 10, factors = c())
n |
The number of samples |
factors |
The model's parameters which will be evaluated |
The Full Factorial design matrix for provided parameters
## Not run: f<- AddFactor(name="cyclePoint",min=40,max=90) f<- AddFactor(factors=f, name="conjugationCost",min=1,max=80) d<- AoE.FullFactorial(2,f) ## End(Not run)## Not run: f<- AddFactor(name="cyclePoint",min=40,max=90) f<- AddFactor(factors=f, name="conjugationCost",min=1,max=80) d<- AoE.FullFactorial(2,f) ## End(Not run)
Returns a dataframe holding the Morris result set
AoE.GetMorrisOutput(obj)AoE.GetMorrisOutput(obj)
obj |
A reference to a morris object instance |
The results of Morris method
Generate a LHS sample for model parameters
AoE.LatinHypercube(n = 10, factors = c(), convert = TRUE)AoE.LatinHypercube(n = 10, factors = c(), convert = TRUE)
n |
The number of samples |
factors |
The model's parameters which will be evaluated |
convert |
Adjust experiment matrix to parameter scale |
Generate the LHS sampling for evaluating the parameters of a model.
The LHS design matrix for provided parameters
## Not run: f<- AddFactor(name="cyclePoint",min=40,max=90) f<- AddFactor(factors=f, name="conjugationCost",min=1,max=80) d<- AoE.LatinHypercube(2,f) ## End(Not run)## Not run: f<- AddFactor(name="cyclePoint",min=40,max=90) f<- AddFactor(factors=f, name="conjugationCost",min=1,max=80) d<- AoE.LatinHypercube(2,f) ## End(Not run)
Calculates the average-error magnitude (MAE)
AoE.MAE(xs, xe)AoE.MAE(xs, xe)
xs |
The simulated data set |
xe |
The experimental data set |
The MAE value for provided datasets
This is a wrapper for performing Morris's screening method on repast models. We rely on morris method from sensitivity package.
AoE.Morris(k = c(), p = 5, r = 4)AoE.Morris(k = c(), p = 5, r = 4)
k |
The factors for morris screening. |
p |
The number of levels for the model's factors. |
r |
Repetitions. The number of random sampling points of Morris Method. |
Gilles Pujol, Bertrand Iooss, Alexandre Janon with contributions from Sebastien Da Veiga, Jana Fruth, Laurent Gilquin, Joseph Guillaume, Loic Le Gratiet, Paul Lemaitre, Bernardo Ramos and Taieb Touati (2015). sensitivity: Sensitivity Analysis. R package version 1.11.1. https://CRAN.R-project.org/package=sensitivity
A simple Normalized Root-Mean-Square Deviation calculation using max and min values. NRMSD = RMSD(x) / (max(x) - min(x))
AoE.NRMSD(xs, xe)AoE.NRMSD(xs, xe)
xs |
The simulated data set |
xe |
The experimental data set |
The NRRMSD value for provided datasets
Generate a Simple Random Sampling experiment design matrix.
AoE.RandomSampling(n = 10, factors = c())AoE.RandomSampling(n = 10, factors = c())
n |
The number of samples |
factors |
The model's parameters which will be evaluated |
The random sampling design matrix
## Not run: f<- AddFactor(name="cyclePoint",min=40,max=90) f<- AddFactor(factors=f, name="conjugationCost",min=1,max=80) d<- AoE.RandomSampling(2,f) ## End(Not run)## Not run: f<- AddFactor(name="cyclePoint",min=40,max=90) f<- AddFactor(factors=f, name="conjugationCost",min=1,max=80) d<- AoE.RandomSampling(2,f) ## End(Not run)
A simple Root-Mean-Square Deviation calculation.
AoE.RMSD(xs, xe)AoE.RMSD(xs, xe)
xs |
The simulated data set |
xe |
The experimental data set |
The RMSD value for provided datasets
This is a wrapper for performing Global Sensitivity Analysis using the Sobol Method provided by sensitivity package.
AoE.Sobol(n = 100, factors = c(), o = 2, nb = 100, fun.doe = AoE.LatinHypercube, fun.sobol = sobolmartinez)AoE.Sobol(n = 100, factors = c(), o = 2, nb = 100, fun.doe = AoE.LatinHypercube, fun.sobol = sobolmartinez)
n |
The number of samples |
factors |
The model's parameters which will be evaluated |
o |
Maximum order in the ANOVA decomposition |
nb |
Number of bootstrap replicates |
fun.doe |
The sampling function to be used for sobol method |
fun.sobol |
The sobol implementation |
This function is not intended to be used directly from user programs.
Gilles Pujol, Bertrand Iooss, Alexandre Janon with contributions from Sebastien Da Veiga, Jana Fruth, Laurent Gilquin, Joseph Guillaume, Loic Le Gratiet, Paul Lemaitre, Bernardo Ramos and Taieb Touati (2015). sensitivity: Sensitivity Analysis. R package version 1.11.1. https://CRAN.R-project.org/package=sensitivity
This function verifies the stability
of CoV for all columns given by parameter keys
or all dataset columns if keys is empty.
AoE.Stability(dataset, keys = c())AoE.Stability(dataset, keys = c())
dataset |
A model output dataset |
keys |
A list of column names |
A data frame with Coefficient of variations
Correct the LHS sampling matrix for a specific range applying the lambda function. The default value of 'lambda' is 'qunif'.
ApplyFactorRange(design, factors)ApplyFactorRange(design, factors)
design |
The LHS design matrix |
factors |
THe collection of factors |
The corrected design matrix
Merges the design matrix with parameters which will be keep fixed along simulation runs.
BuildParameterSet(design, parameters)BuildParameterSet(design, parameters)
design |
The experimental desing matrix for at least one factor |
parameters |
All parameters of the repast model. |
A data frame holding all parameters required for running the model
## Not run: modeldir<- "c:/usr/models/BactoSim(HaldaneEngine-1.0)" e<- Model(modeldir=modeldir,dataset="ds::Output") Load(e) f<- AddFactor(name="cyclePoint",min=40,max=90) p<- GetSimulationParameters(e) d<- AoE.LatinHypercube(factors=f) p1<- BuildParameterSet(d,p) ## End(Not run)## Not run: modeldir<- "c:/usr/models/BactoSim(HaldaneEngine-1.0)" e<- Model(modeldir=modeldir,dataset="ds::Output") Load(e) f<- AddFactor(name="cyclePoint",min=40,max=90) p<- GetSimulationParameters(e) d<- AoE.LatinHypercube(factors=f) p1<- BuildParameterSet(d,p) ## End(Not run)
Gets the list of keys (the factor names)
Calibration.GetMemberKeys(obj)Calibration.GetMemberKeys(obj)
obj |
An instance of the object returned by |
The collection of keys
Gets the member list value
Calibration.GetMemberList(obj, key, name)Calibration.GetMemberList(obj, key, name)
obj |
An instance of the object returned by |
key |
The key value |
name |
The column name |
The member list
Check if the integration jar library is correctelly installed in the model lib directory
check.integration(modelpath)check.integration(modelpath)
modelpath |
The path where model is installed |
TRUE if the integration code is correctelly deployed
Check if the scenario.xml is configured with the rrepast itegration code
check.scenario(modelpath)check.scenario(modelpath)
modelpath |
The path where model is installed |
TRUE if scenario is properly configured
This function is called automatically every time Run method is called.
ClearResults()ClearResults()
Sum all columns but one (pset) of a data frame
col.sum(d, skip = c())col.sum(d, skip = c())
d |
The data frame |
skip |
The columns which should not be included in the sum |
The original data frame with a new column (sum) holding the sum
Verify if the installed model is correctelly configurated.
config.check(modelpath)config.check(modelpath)
modelpath |
The path where model is installed |
TRUE when all requisites are met
Install or uninstall the integration jar file. This function manages the installation process of required jars to the model lib dir.
config.copylib(modelpath, uninstall = FALSE)config.copylib(modelpath, uninstall = FALSE)
modelpath |
The path where model is installed |
uninstall |
If TRUE uninstall integration jar |
TRUE if install operation succed
Add the integration library to the model's configuration
config.scenario(modelpath, uninstall = FALSE)config.scenario(modelpath, uninstall = FALSE)
modelpath |
The path where model is installed |
uninstall |
If TRUE restore original scenario.xml file |
A logical TRUE if the model's scenario file has been modified
A simple function to make a directory to save the model's data.
createOutputDir()createOutputDir()
Create the, if required, the directory to save the output data generate by the model. It is intended for internal use.
This function converts data frames to matrix data type.
df2matrix(d, n = c())df2matrix(d, n = c())
d |
The data frame |
n |
The column names to be converted. Null for all data frame columns |
The data frame converted to a matrix
Selects a subset of a data frame, filtering by column values.
dffilterby(d, key, values = c())dffilterby(d, key, values = c())
d |
The data frame holding data to be filtered |
key |
The column name for selection valuas |
values |
The collection of values used to filter the data set |
The filtered data set
Round all numeric columns of a data frame
dfround(d, p)dfround(d, p)
d |
The data frame |
p |
The number of decimal digits to be keept |
A data frame with rounded columns
Sum data frame columns but tho
dfsumcol(d, lst = c(), invert = FALSE)dfsumcol(d, lst = c(), invert = FALSE)
d |
The data frame |
lst |
Skip columns included. Sum columns NOT included |
invert |
Sum only the columns included in |
The original data frame with a new column (sum) holding the sum
Search for the best set of parameters trying to minimize the calibration function provided by the user. The function has to operational models, the first based on the experimental setup where all parameters are defined a priori and the second using optimization techniques. Currently the only supported optimization technique is the particle swarm optimization.
Easy.Calibration(m.dir, m.ds, m.time = 300, parameters, exp.n = 100, exp.r = 1, smax = 4, design = "lhs", FUN, default = NULL)Easy.Calibration(m.dir, m.ds, m.time = 300, parameters, exp.n = 100, exp.r = 1, smax = 4, design = "lhs", FUN, default = NULL)
m.dir |
The installation directory of some repast model |
m.ds |
The name of any model aggregate dataset |
m.time |
The total simulated time |
parameters |
The input factors |
exp.n |
The experiment sample size |
exp.r |
The number of experiment replications |
smax |
The number of solutions to be generated |
design |
The sampling scheme ["lhs"|"mcs"|"ffs"] |
FUN |
The objective or cost function. A function defined over the model output. |
default |
The alternative values for parameters which should be kept fixed |
A list with holding experiment, object and charts
## Not run: my.cost<- function(params, results) { criteria<- c() Rate<- AoE.RMSD(results$X.Simulated,results$X.Experimental) G<- AoE.RMSD(results$G.T.,52) total<- Rate + G criteria<- cbind(total,Rate,G) return(criteria) } Easy.Setup("/models/BactoSim") v<- Easy.Calibration("/models/BactoSim","ds::Output",360, f,exp.n = 1000, exp.r=1, smax=4, design="mcs", my.cost) ## End(Not run)## Not run: my.cost<- function(params, results) { criteria<- c() Rate<- AoE.RMSD(results$X.Simulated,results$X.Experimental) G<- AoE.RMSD(results$G.T.,52) total<- Rate + G criteria<- cbind(total,Rate,G) return(criteria) } Easy.Setup("/models/BactoSim") v<- Easy.Calibration("/models/BactoSim","ds::Output",360, f,exp.n = 1000, exp.r=1, smax=4, design="mcs", my.cost) ## End(Not run)
Returns the chart instance
Easy.getChart(obj, key)Easy.getChart(obj, key)
obj |
A reference to the output of Easy.Stability |
key |
The param name |
The plot instance
Returns the chart instance
Easy.getPlot(obj, c, key)Easy.getPlot(obj, c, key)
obj |
A reference to the output of an "Easy" API method |
c |
The output name |
key |
The param name |
The plot instance
This function wraps all calls to perform Morris method.
Easy.Morris(m.dir, m.ds, m.time = 300, parameters, mo.p, mo.r, exp.r, FUN, default = NULL)Easy.Morris(m.dir, m.ds, m.time = 300, parameters, mo.p, mo.r, exp.r, FUN, default = NULL)
m.dir |
The installation directory of some repast model |
m.ds |
The name of any model aggregate dataset |
m.time |
The total simulated time |
parameters |
The factors for morris screening. |
mo.p |
The number of levels for the model's factors. |
mo.r |
Repetitions. The number of random sampling points of Morris Method. |
exp.r |
The number of experiment replications |
FUN |
The objective or cost function. A function defined over the model output. |
default |
The alternative values for parameters which should be kept fixed |
A list with holding experimnt, object and charts
This function provides a simple wrapper for performing a single or replicated model execution with a single set of parameters.
Easy.Run(m.dir, m.ds, m.time = 300, r = 1, default = NULL)Easy.Run(m.dir, m.ds, m.time = 300, r = 1, default = NULL)
m.dir |
The installation directory of some repast model |
m.ds |
The name of any model aggregate dataset |
m.time |
The total simulated time |
r |
The number of replications |
default |
The alternative values for the default model parameters |
This function provides a simple wrapper for performing experimental setups using a design matrix
Easy.RunExperiment(m.dir, m.ds, m.time = 300, r = 1, design, FUN, default = NULL)Easy.RunExperiment(m.dir, m.ds, m.time = 300, r = 1, design, FUN, default = NULL)
m.dir |
The installation directory of some repast model |
m.ds |
The name of any model aggregate dataset |
m.time |
The total simulated time |
r |
The number of replications |
design |
The design matrix holding parameter sampling |
FUN |
The objective or cost function. A function defined over the model output. |
default |
The alternative values for parameters which should be kept fixed |
The experiment results
This function configures the deployment directory where logs and output dataset will be generated. By default the deployment directory will be created under the model installation directory. The output generated by the Repast model will be redirected to the SystemOut.log file.
Easy.Setup(model, multicore = FALSE, deployment = c())Easy.Setup(model, multicore = FALSE, deployment = c())
model |
The base directory where Repast model is installed. |
multicore |
Bolean flag indicating to use multiplecore. |
deployment |
The directory to save the output and logs. |
If the deployment directory is empty the installation
directory given by the parameter model is used instead as
the base directory. The deployment directory is /rrepast-deployment/.
Returns the list current model parameters
Easy.ShowModelParameters(v)Easy.ShowModelParameters(v)
v |
The installation directory of some repast model |
The model parameters
This functions wraps all required calls to perform Sobol method for global sensitivity analysis.
Easy.Sobol(m.dir, m.ds, m.time = 300, parameters, exp.n = 500, bs.size = 200, exp.r = 1, FUN, default = NULL, fsobol = sobol2002, fsampl = AoE.LatinHypercube)Easy.Sobol(m.dir, m.ds, m.time = 300, parameters, exp.n = 500, bs.size = 200, exp.r = 1, FUN, default = NULL, fsobol = sobol2002, fsampl = AoE.LatinHypercube)
m.dir |
The installation directory of some repast model |
m.ds |
The name of any model aggregate dataset |
m.time |
The total simulated time |
parameters |
The input factors |
exp.n |
The experiment sample size |
bs.size |
The bootstrap sample size for sobol method |
exp.r |
The number of experiment replications |
FUN |
The objective or cost function. A function defined over the model output. |
default |
The alternative values for parameters which should be kept fixed |
fsobol |
The alternative function for calculating sobol indices |
fsampl |
The function for sampling data |
A list with holding experimnt, object and charts
This functions run model several times in order to determine how many experiment replications are required for model's output being stable (i.e. the convergence of standard deviation)
Easy.Stability(m.dir, m.ds, m.time = 300, parameters, samples = 1, tries = 100, vars = c(), FUN, default = NULL)Easy.Stability(m.dir, m.ds, m.time = 300, parameters, samples = 1, tries = 100, vars = c(), FUN, default = NULL)
m.dir |
The installation directory of some repast model |
m.ds |
The name of any model aggregate dataset |
m.time |
The total simulated time |
parameters |
The factors or model's parameter list |
samples |
The number of factor samples. |
tries |
The number of experiment replications |
vars |
The model's output variables for compute CoV |
FUN |
The objective or cost function. A function defined over the model output. |
default |
The alternative values for parameters which should be kept fixed |
A list with holding experiment, object and charts
Creates an instance of Engine
Engine()Engine()
This function creates an instance of Repast model wrapper class. Before invoking the function Engine, make sure that environment was correctly initialized.
An onject instance of Engine class
Configure the maximun simulated time for the current model run
Engine.endAt(e, v)Engine.endAt(e, v)
e |
An engine object instance |
v |
The number of Repast time ticks |
Performs a cleanup on a engine instance.Finalize and destroy repast controller data.
Engine.Finish(e)Engine.Finish(e)
e |
An engine object instance |
This function provides a wrapper to the method getId() from repast context. The id is basically a String with the currently instantiated model name.
Engine.getId(e)Engine.getId(e)
e |
An engine object instance |
Gets the model output data as a CSV String array. Calls the engine method GetModelOutput to drain model output data.
Engine.GetModelOutput(e)Engine.GetModelOutput(e)
e |
An engine object instance |
An array of strings containing the model's output
## Not run: d<- "c:/usr/models/your-model-directory" m<- Model(d) csv<- Engine.GetModelOutput(m) ## End(Not run)## Not run: d<- "c:/usr/models/your-model-directory" m<- Model(d) csv<- Engine.GetModelOutput(m) ## End(Not run)
The function gets the value of model
parameter k as java.lang.Object
Engine.getParameter(e, k)Engine.getParameter(e, k)
e |
An engine object instance |
k |
The parameter name |
The parameter value
Get the value of model parameter k as java.lang.Double
Engine.getParameterAsDouble(e, k)Engine.getParameterAsDouble(e, k)
e |
An engine object instance |
k |
The parameter name |
The parmeter value as double
Get the value of model parameter
k as java.lang.Number
Engine.getParameterAsNumber(e, k)Engine.getParameterAsNumber(e, k)
e |
An engine object instance |
k |
The parameter name |
The parmeter value as number
Get the value of model parameter k
as java.lang.String
Engine.getParameterAsString(e, k)Engine.getParameterAsString(e, k)
e |
An engine object instance |
k |
The parameter name |
The parameter value as string
Get the parameter names
Engine.getParameterNames(e)Engine.getParameterNames(e)
e |
An engine object instance |
Returns the names of all declared model's parameters in the parameter.xml file in the scenario directory.
A collection of parameter names
Returns the declared type of a Repast model parameter
Engine.getParameterType(e, k)Engine.getParameterType(e, k)
e |
An engine object instance |
k |
The parameter name |
The parameter type string
Loads the model's scenario files
Engine.LoadModel(e, f)Engine.LoadModel(e, f)
e |
An engine object instance |
f |
The full path of scenario directory |
This function loads the scenario of a Repast Model and initialize de model.
Resets the the model output holder
Engine.resetModelOutput(e)Engine.resetModelOutput(e)
e |
An engine object instance |
Performs the execution of Repast model
Engine.RunModel(e)Engine.RunModel(e)
e |
An engine object instance |
Sets the model's dataset
Engine.SetAggregateDataSet(e, k)Engine.SetAggregateDataSet(e, k)
e |
An engine object instance |
k |
The repast model's data set name |
Configure a dataset with the desired output values to be "drained" by the function Engine.GetModelOutput.
## Not run: d<- "C:/usr/models/your-model-directory" m<- Model(d) setAggregateDataSet(m,"dataset-name") ## End(Not run)## Not run: d<- "C:/usr/models/your-model-directory" m<- Model(d) setAggregateDataSet(m,"dataset-name") ## End(Not run)
Set the value of model parameter
Engine.setParameter(e, k, v)Engine.setParameter(e, k, v)
e |
An engine object instance |
k |
The parameter name |
v |
The parameter value |
Return the current calls to the 'Engine.RunModel' function
enginestats.calls(increment = FALSE)enginestats.calls(increment = FALSE)
increment |
A flag telling to increment and update the counter |
The number of calls to 'Engine.RunModel'
Reset internal statistics
enginestats.reset()enginestats.reset()
dataset
The RunExperiment function returns a list holding
the paramset, output and dataset collection.
The paramset collection contains the parameters used for
running the experimental setup. The output has the results
from user provided calibration function. The dataset
collection has the raw output of 'Repast' aggregated dataset.
getExperimentDataset(e)getExperimentDataset(e)
e |
The experiement object returned by |
The reference to dataset container.
output
The RunExperiment function returns a list holding
the paramset, output and dataset collection.
The paramset collection contains the parameters used for
running the experimental setup. The output has the results
from user provided calibration function. The dataset
collection has the raw output of 'Repast' aggregated dataset.
getExperimentOutput(e)getExperimentOutput(e)
e |
The experiement object returned by |
The reference to output container.
paramset
The RunExperiment function returns a list holding
the paramset, output and dataset collection.
The paramset collection contains the parameters used for
running the experimental setup. The output has the results
from user provided calibration function. The dataset
collection has the raw output of 'Repast' aggregated dataset.
getExperimentParamSet(e)getExperimentParamSet(e)
e |
The experiement object returned by |
The reference to output container.
## Not run: d<- "C:/usr/models/your-model-directory" m<- Model(d) ... e<- RunExperiment(e,r=1,exp.design,my.cost) p<- getExperimentParamSet(e) ## End(Not run)## Not run: d<- "C:/usr/models/your-model-directory" m<- Model(d) ... e<- RunExperiment(e,r=1,exp.design,my.cost) p<- getExperimentParamSet(e) ## End(Not run)
Returns the fator's levels
GetFactorLevels(factors, name)GetFactorLevels(factors, name)
factors |
The current factor collection |
name |
The factor name |
Levels
## Not run: f<- AddFactor0(name="Age",levels=c(25,30,40,65)) f<- AddFactor0(factors=f, name="Weight",levels=c(60,70,80,90)) GetFactorLevels(factors=f, "Age") ## End(Not run)## Not run: f<- AddFactor0(name="Age",levels=c(25,30,40,65)) f<- AddFactor0(factors=f, name="Weight",levels=c(60,70,80,90)) GetFactorLevels(factors=f, "Age") ## End(Not run)
Returns the total number of factors
GetFactorsSize(factors)GetFactorsSize(factors)
factors |
A collection of factors created with AddFactor |
The number of parameters in factors collection
Provides the name of the model currently instantiated.
getId()getId()
Returns the Repast randomSeed parameter name.
getKeyRandom()getKeyRandom()
A string value holding the randomSeed name.
Returns the results of a model a data.frame from the last RUN. Should be used only if model replication is equal to 1, otherwise GetResults must be used.
GetOutput(e)GetOutput(e)
e |
An engine object instance |
Returns a data.frame with output data
## Not run: d<- "C:/usr/models/your-model-directory" m<- Model(d) ... data<- GetOutput(m) ## End(Not run)## Not run: d<- "C:/usr/models/your-model-directory" m<- Model(d) ... data<- GetOutput(m) ## End(Not run)
Returns the value of module variable for storing the current output directory.
getOutputDir()getOutputDir()
Returns the maximum number of cores to be used in parallel computations
getpkgcores()getpkgcores()
The number of cores
Provides the package default parallelism level which is 80% of total cores available
getpkgdefaultcores()getpkgdefaultcores()
Cores used by R/Repast
Returns the current set of paramters used for the last model run.
GetResultsParameters()GetResultsParameters()
A data.frame with parameters of the model.
Returns a dataframe with the current set of input parameters for the last model run.
GetSimulationParameters(e)GetSimulationParameters(e)
e |
An engine object instance |
A data frame with simulation parameters
Returns the declared parameter type.
GetSimulationParameterType(e, k)GetSimulationParameterType(e, k)
e |
An instance of 'Engine' object |
k |
The parameter name |
The parameter type as string
Returns to the saved work directory
GoToPreviousDir()GoToPreviousDir()
Changes the current work directory saving the previous one
which is used in GoToPreviousDir. This function is called
by Easy.Setup
GoToWorkDir()GoToWorkDir()
Calculates the distance between some value a reference target value. It is an hybrid distance because when the value falls whithin a reference range the distance is 0, otherwise the distance between the value and the reference value is calculated using the user provided distance function.
hybrid.distance(value, reference, FUN = AoE.NRMSD)hybrid.distance(value, reference, FUN = AoE.NRMSD)
value |
The value which will be compared against the reference |
reference |
The reference value. It should be a list holding the value, the range of values. |
FUN |
The distance function. The default is the NRMSD |
The distance metric
A simple helper function for generating the input list for the function 'hybrid.distance'. This list must hold the value and a range centered over the value.
hybrid.value(value, distance)hybrid.value(value, distance)
value |
The reference value |
distance |
The distance interval. |
The list holding the value and the interval 'min — value — max'
The jarfile returns the full path to some jar file available inside rrpast package
jarfile(fjar)jarfile(fjar)
fjar |
The name of jar file |
The full path to jar file
Enable jmx for the current R/rJava session
jvm.enablejmx()jvm.enablejmx()
Configures the JMX subsystem for the current session of R/rJava.
This function must be called before any other function which initializes
r/Java such as Easy.Setup or Model otherwise it will have no effect.
## Not run: jvm.enablejmx() ## End(Not run)## Not run: jvm.enablejmx() ## End(Not run)
Returns the current java virtual machine parameters
jvm.get_parameters()jvm.get_parameters()
A string with JVM parameters.
A wrapper for System.getRuntime()
jvm.getruntime()jvm.getruntime()
A simple wrapper for System.getRuntime() java method
Initialize rJava and repast environment with classpath. This function is called internally and it is not meant to be used directlly.
jvm.init()jvm.init()
The default parameters can be changed as needed calling the
primitive jvm.set_parameters befor instantiating the model
engine.
[1] rJava: Low-Level R to Java Interface. Low-level interface to Java VM very much like .C/.Call and friends. Allows creation of objects, calling methods and accessing fields.
## Not run: jvm.init() ## End(Not run)## Not run: jvm.init() ## End(Not run)
JVM memory state
jvm.memory()jvm.memory()
Provides information about the memory used by the JVM subsystem
Reset the System.out filed value to console output
jvm.resetOut()jvm.resetOut()
## Not run: jvm.resetOut() ## End(Not run)## Not run: jvm.resetOut() ## End(Not run)
A wrapper for Runntime.gc()
jvm.runtimegc()jvm.runtimegc()
Forces the execution of the JVM garbage collector
Configures the jvm parameters
jvm.set_parameters(s)jvm.set_parameters(s)
s |
The paramter string to be passed to the underlying JVM |
Set the underlying parameters for java virtual machine. The default values are "-server -Xms1024m -Xmx1024m". These defaults can be changed to fit the model requirements.
## Not run: jvm.set_parameters("-server -Xms512m -Xmx2048m") ## End(Not run)## Not run: jvm.set_parameters("-server -Xms512m -Xmx2048m") ## End(Not run)
Set the System.out filed to a file
jvm.setOut(f)jvm.setOut(f)
f |
The output file name |
## Not run: jvm.setOut("/tmp/SysteOut.log") ## End(Not run)## Not run: jvm.setOut("/tmp/SysteOut.log") ## End(Not run)
Cheks if a list contains a name
lcontains(l, n)lcontains(l, n)
l |
The list object |
n |
The item name |
Boolean TRUE if name is found on list
Retrieve the value for a list item
lget(l, n)lget(l, n)
l |
The list object |
n |
The item name |
The item value
Loads the model's scenario. This function must be called before running the model.
Load(e)Load(e)
e |
An engine object instance |
## Not run: d<- "C:/usr/models/your-model-directory" m<- Model(d) Load(m) ## End(Not run)## Not run: d<- "C:/usr/models/your-model-directory" m<- Model(d) Load(m) ## End(Not run)
Configures the underlying logging system
Logger.setLevelInfo()Logger.setLevelInfo()
Configures the underlying logging system
Logger.setLevelWarning()Logger.setLevelWarning()
Instantiate a repast model from the model dir without loading the scenario file.
Model(modeldir = "", maxtime = 300, dataset = "none", load = FALSE)Model(modeldir = "", maxtime = 300, dataset = "none", load = FALSE)
modeldir |
The installation directory of some repast model |
maxtime |
The total simulated time |
dataset |
The name of any model aggregate dataset |
load |
If true instantiate model and load scenario |
This is the entry point for model execution. Typically
any model execution will start with this function which encapsulates
all low level calls for model initialization. In order to perform
simulations with repast from R code only Model and a
few more function calls are required: Load,
Run. Finally the output of model is managed with
functions GetResults and SaveSimulationData.
Returns the instance of repast model
[1] North, M.J., N.T. Collier, and J.R. Vos, "Experiences Creating Three Implementations of the Repast Agent Modeling Toolkit," ACM Transactions on Modeling and Computer Simulation, Vol. 16, Issue 1, pp. 1-25, ACM, New York, New York, USA (January 2006).
## Not run: d<- "C:/usr/models/your-model-directory" m<- Model(d) ## End(Not run)## Not run: d<- "C:/usr/models/your-model-directory" m<- Model(d) ## End(Not run)
Finalize the parallel execution environment for R/Repast
ParallelClose()ParallelClose()
Initialize the parallel execution environment for R/Repast
ParallelInit()ParallelInit()
Tells R/Repast to use multicore. Default is using just one core.
parallelize(v = NULL)parallelize(v = NULL)
v |
A Bollean value telling if use multiple cores. When null just returns the current setting |
Boolean with current state
Run the model multiple times for different parameters given by design matrix function parameter.
ParallellRunExperiment(modeldir, datasource, maxtime, r = 1, design, FUN, default = NULL)ParallellRunExperiment(modeldir, datasource, maxtime, r = 1, design, FUN, default = NULL)
modeldir |
The installation directory of some repast model |
datasource |
The name of any model aggregate dataset |
maxtime |
The total simulated time |
r |
The number of experiment replications |
design |
The desing matrix holding parameter sampling |
FUN |
THe calibration function. |
default |
The alternative values for parameters which should be kept fixed |
The FUN function must return zero for perfect fit and values greater than zero otherwise.
A list with output and dataset
## Not run: my.cost<- function(params, results) { # your best fit calculation, being 0 the best metric. } d<- "/usr/models/your-model-directory" f<- AddFactor(name="cyclePoint",min=40,max=90) f<- AddFactor(factors=f, name="conjugationCost",min=1,max=80) d<- AoE.LatinHypercube(factors=f) v<- ParallellRunExperiment() ## End(Not run)## Not run: my.cost<- function(params, results) { # your best fit calculation, being 0 the best metric. } d<- "/usr/models/your-model-directory" f<- AddFactor(name="cyclePoint",min=40,max=90) f<- AddFactor(factors=f, name="conjugationCost",min=1,max=80) d<- AoE.LatinHypercube(factors=f) v<- ParallellRunExperiment() ## End(Not run)
Run simulations in parallel. This function
executes the time steps of an instantiated model. The number
of replications of model runs can be specified by the
function parameter. The seed parameter may be
omitted and will be generated internally. If provided,
the seed collection, must contain the same
number of r parameter.
ParallelRun(modeldir, datasource, maxtime, r = 1, seed = c(), design = NULL, default = NULL)ParallelRun(modeldir, datasource, maxtime, r = 1, seed = c(), design = NULL, default = NULL)
modeldir |
The installation directory of some repast model |
datasource |
The name of any model aggregate dataset |
maxtime |
The total simulated time |
r |
The number of experiment replications |
seed |
The random seed collection |
design |
The desing matrix holding parameter sampling |
default |
The alternative values for parameters which should be kept fixed |
The model output dataset
## Not run: md<- "/usr/models/your-model-directory" output<- ParallelRun(modeldir= md, maxtime = 360, dataset= ds, r=4) ## End(Not run)## Not run: md<- "/usr/models/your-model-directory" output<- ParallelRun(modeldir= md, maxtime = 360, dataset= ds, r=4) ## End(Not run)
Initialize progress bar for model execution.
PB.init(psets, replications)PB.init(psets, replications)
psets |
– The total number of paramter sets being simulated |
replications |
– The number of replications per simulation round |
Returns the global value indicating if progress bar is enabled.
PB.isEnabled()PB.isEnabled()
Boolean TRUE if progress bar must be shown
Update pset value
PB.pset(v)PB.pset(v)
v |
The current parameter set being simulated |
Update run number value
PB.rnum(v)PB.rnum(v)
v |
The current run number |
Ses the progress bar descriptor
PB.set(obj)PB.set(obj)
obj |
– The progress bar descriptor |
Update progress bar
PB.update(r = NULL)PB.update(r = NULL)
r |
The current replication number |
Choose the best solutions minimizing the objective function
pick.fittest(out, goals = c(), n = 4)pick.fittest(out, goals = c(), n = 4)
out |
The output data set holding the values of goals |
goals |
The column names which must be used as goal |
n |
The number of solutions |
The n rows holding the best results
Generate plot for parameter sets providing best fit
Plot.Calibration(obj, key, title = NULL)Plot.Calibration(obj, key, title = NULL)
obj |
An instance of calibration Object |
key |
The column name |
title |
Chart title, may be null |
The resulting ggplot2 plot object
Generate plot for Morris's screening method
Plot.Morris(obj, type, title = NULL)Plot.Morris(obj, type, title = NULL)
obj |
An instance of Morris Object |
type |
The chart type (mu*sigma|musigma|mu*mu) |
title |
Chart title, may be null |
The resulting ggplot2 plot object
Generate plot for Sobol's GSA
Plot.Sobol(obj, type, title = NULL)Plot.Sobol(obj, type, title = NULL)
obj |
An instance of Sobol Object |
type |
The chart type |
title |
Chart title, may be null |
The resulting ggplot2 plot object
Generate plot for visually access the stability of coefficient of variation as function of simulation sample size.
Plot.Stability(obj, title = NULL)Plot.Stability(obj, title = NULL)
obj |
An instance of Morris Object |
title |
Chart title, may be null |
The resulting ggplot2 plot object
Simplify the access to the charts member
Results.GetCharts(obj)Results.GetCharts(obj)
obj |
An instance of the object returned by |
The charts element inside results
Simplify the access to the experiment member
Results.GetExperiment(obj)Results.GetExperiment(obj)
obj |
An instance of the object returned by |
The experiment element inside results
Simplify the access to the object member
Results.GetObject(obj)Results.GetObject(obj)
obj |
An instance of the object returned by |
The object element inside results
This function executes the time steps of an
instantiated model. The number of replications of model
runs can be specified by the function parameter. The seed
parameter may be omitted and will be generated internally.
If provided, the seed collection, must contain the same
number of r parameter.
Run(e, r = 1, seed = c())Run(e, r = 1, seed = c())
e |
An engine object instance |
r |
The number of experiment replications |
seed |
The random seed collection |
The model output dataset
## Not run: d<- "C:/usr/models/your-model-directory" m<- Model(d) Load(m) Run(m,r=2) # or Run(m,r=2,seed=c(1,2)) ## End(Not run)## Not run: d<- "C:/usr/models/your-model-directory" m<- Model(d) Load(m) Run(m,r=2) # or Run(m,r=2,seed=c(1,2)) ## End(Not run)
Run the model multiple times for different parameters given by design matrix function parameter.
RunExperiment(e, r = 1, design, FUN)RunExperiment(e, r = 1, design, FUN)
e |
An engine object instance |
r |
The number of experiment replications |
design |
The desing matrix holding parameter sampling |
FUN |
THe calibration function. |
The FUN function must return zero for perfect fit and values greater than zero otherwise.
A list with output and dataset
## Not run: my.cost<- function(params, results) { # your best fit calculation, being 0 the best metric. } d<- "c:/usr/models/your-model-directory" m<- Model(d,dataset="ds::Output") Load(m) f<- AddFactor(name="cyclePoint",min=40,max=90) f<- AddFactor(factors=f, name="conjugationCost",min=1,max=80) d<- LatinHypercube(factors=f) p<- GetSimulationParameters(e) exp.design<- BuildParameterSet(d,p) v<- RunExperiment(e,r=1,exp.design,my.cost) ## End(Not run)## Not run: my.cost<- function(params, results) { # your best fit calculation, being 0 the best metric. } d<- "c:/usr/models/your-model-directory" m<- Model(d,dataset="ds::Output") Load(m) f<- AddFactor(name="cyclePoint",min=40,max=90) f<- AddFactor(factors=f, name="conjugationCost",min=1,max=80) d<- LatinHypercube(factors=f) p<- GetSimulationParameters(e) exp.design<- BuildParameterSet(d,p) v<- RunExperiment(e,r=1,exp.design,my.cost) ## End(Not run)
Saves the simulation results of last call to Run(e) function.
SaveSimulationData(as = "csv", experiment = NULL)SaveSimulationData(as = "csv", experiment = NULL)
as |
The desired output type, must be csv or xls |
experiment |
The experiment output |
The model must have been initialized or user must call
setId explicitelly.
The id of saved data
Generate a sequence from min to max using an increment based on the number of of elements in v
SequenceItem(v, min, max)SequenceItem(v, min, max)
v |
A column of n x k design matrix |
min |
The lower boundary of range |
max |
The uper boundary of range |
A sequence between min and max value
Set the name of the model currently instantiated.
setId(s)setId(s)
s |
The model name |
Configures a non-default value for Repast randomSeed parameter name.
setKeyRandom(k)setKeyRandom(k)
k |
The string with an alternative name for randomSeed |
Configure the desired directoy to save model output data.
setOutputDir(s)setOutputDir(s)
s |
The full path for output directory |
Configures the maximum number of cores to be used in parallel computations
setpkgcores(v)setpkgcores(v)
v |
The number of cores |
Stores a data.frame
SetResults(d)SetResults(d)
d |
A data frame containing one replication data |
Save the current set of paramters used for the last model run.
SetResultsParameters(d)SetResultsParameters(d)
d |
A data.frame with parameter values |
Modify model's default parameter collection
SetSimulationParameter(e, key, value)SetSimulationParameter(e, key, value)
e |
An engine object instance |
key |
The paramter name |
value |
The parameter value |
Modify the repast model parameters with values provided in parameter 'p' which is a data frame with just one row.
SetSimulationParameters(e, p)SetSimulationParameters(e, p)
e |
An engine object instance |
p |
A data frame with simulation parameters |
Shows the current classpath
ShowClassPath()ShowClassPath()
the current setting of JVM classpath
## Not run: ShowClassPath() ## End(Not run)## Not run: ShowClassPath() ## End(Not run)
Prints the paths. Shows the directories currently used to load model scenario and lib. The output of this function is informational only and can be used to check whether model data is being loaded properly from correct locations.
ShowModelPaths()ShowModelPaths()
## Not run: ShowModelPaths() ## End(Not run)## Not run: ShowModelPaths() ## End(Not run)
Modify the value of the default parameters which should be kept fixed
UpdateDefaultParameters(e, p)UpdateDefaultParameters(e, p)
e |
An engine object instance |
p |
The collection of model fixed paramters to change |
## Not run: d<- "C:/usr/models/your-model-directory" m<- Model(d) Load(m) p<- c(name1=value1, name2=2) UpdateDefaultParameters(m,p) ## End(Not run)## Not run: d<- "C:/usr/models/your-model-directory" m<- Model(d) Load(m) p<- c(name1=value1, name2=2) UpdateDefaultParameters(m,p) ## End(Not run)
Wrapper for the Run and ParallelRun functions
WrapperRun(modeldir, datasource, maxtime, r = 1, seed = c(), design = NULL, default = NULL, multi = TRUE)WrapperRun(modeldir, datasource, maxtime, r = 1, seed = c(), design = NULL, default = NULL, multi = TRUE)
modeldir |
The installation directory of some repast model |
datasource |
The name of any model aggregate dataset |
maxtime |
The total simulated time |
r |
The number of experiment replications |
seed |
The random seed collection |
design |
The desing matrix holding parameter sampling |
default |
The alternative values for parameters which should be kept fixed |
multi |
allows forcing single core execution, default is using multi-core |
The model output dataset
Wrapper for the RunExperiment and ParallelRunExperiment functions
WrapperRunExperiment(modeldir, datasource, maxtime, r = 1, design, FUN, default = NULL)WrapperRunExperiment(modeldir, datasource, maxtime, r = 1, design, FUN, default = NULL)
modeldir |
The installation directory of some repast model |
datasource |
The name of any model aggregate dataset |
maxtime |
The total simulated time |
r |
The number of experiment replications |
design |
The desing matrix holding parameter sampling |
FUN |
The objective function. |
default |
The alternative values for parameters which should be kept fixed |
The model output dataset