Using MCSim on Windows with RStudio

3.1. Make program

When loading the function.R, it will create the mod.exe program in MCSim folder through makemod(). Since MCSim is free and open source software, each file is provided through human-readable code (most are written by C language). To let the computer run these code, we need to compile the source code to the machine-readable program. The makemod() will automatically execute when loading the function.R, which means we don’t need to run this function unless we accidentally remove the mod.exe. Also, the pkgbuild package will be installed to check the Rtools.

3.2. Build model

Next, we need to build and compile the model code to the executable model program. We can use makemcsim() function to create the program with the name mcsim. ... .exe. The example code of linear model looks like this,

# ---------------------------------------------------------
# Model definition file for a linear model (linear.model.R)
# ---------------------------------------------------------
Outputs = {y}

# Model Parameters
A = 0; # Default value of intercept
B = 1; # Default value of slope

# Statistical parameter
SD_true = 0;

CalcOutputs { y = A + B * t + NormalRandom(0,SD_true); }

End. 

When building the model, be sure to put the semi-colon (;) at the end of statements. Also, the keyword “End.” should put at the end of every model. Then run the following code to create the model program mcsim.linear.model.R.exe.

makemcsim(model = "linear.model.R")

## * Created executable program 'mcsim.linear.model.R.exe'.

The above function has the same action as makemcsim linear.model.R mcsim.linear.model.R.exe in command prompt.

3.3. Input & simulation

Finally, to conduct the model simulation, we need an input-file that includes the given model parameter value and/or input data based on the study purpose.

# ---------------------------------------------------------
# Input definition file for a linear model (linear.in.R)
# ---------------------------------------------------------
Simulation { # 1 simple simulation
  
  A  = 1; # given value of intercept 
  B  = 2; # given value of slope 
  SD_true = 2; # given SD of noise 
  
  PrintStep (y, 0, 10, 1); 
}

END.

The mcsim() function in function.R provides an alternative way to run simulation in R environment instead of using the command prompt to run the simulation.

out <- mcsim(model = "linear.model.R", input = "linear.in.R")

## Execute: ./mcsim.linear.model.R.exe modeling/linear.in.R

The simulation will generate an output file sim.out. The above function has the same action as ./mcsim.linear.model.R.exe linear.in.R in command prompt.

The mcsim() can automatically read the output after generating the sim.out. Here is the output result,

out

##    Time         y
## 1     0 -0.415609
## 2     1 -1.430340
## 3     2  4.144040
## 4     3  7.535080
## 5     4  9.517630
## 6     5 10.871900
## 7     6 13.735700
## 8     7 13.075000
## 9     8 16.095100
## 10    9 16.816300
## 11   10 21.300200

We can use the R base plot function to visualize the output as well.

plot(x = out$Time, y = out$y)
abline(a = 1, b = 2)

3.4. Summary of R function (function.R)

Here are the R functions that can help you run GNU MCSim in R environment more easily. All R functions are put in functions.R in MCSim folder.

set_PATH(PATH)

• Detecting, checking, and setting the C compiler in your computer. This process will automatically execute. The default PATH setting is "c:/Rtools/mingw_32/bin". If your have “mingw_64” you can use set_PATH(PATH = "c:/Rtools/mingw_64/bin") to have faster compiling speed.

makemod()

• Creating MCSim program mod.exe. This process will automatically execute.

makemcsim(model, dir = "modeling", deSolve = F)

• Preprocessing and compiling the model-file to the executable file as makemcsim in GNU MCSim. The model assignment is a string giving the name of the model-file (e.g., "linear.model.R"). The deSolve assignment is a logical factor to use deSolve package as an ODE solver.

• The default location of modeling files are setting at modeling folder. The loaction can change by re-assign dir.

mcsim(model, input, dir = "modeling", parallel = F)

• Using the compiled program with the input-file to run the simulation. The input assignment is a string giving the name of the input-file (e.g., "linear.in.R"). This function can also automatically compile the model, if you forgot to use makemcsim() to create model program. Besides, this function can also automatically compile the model.

• Can use parallel = T if using parallel computing in MCMC model calibration.

clear()

• Removing all executable and output files with extension .exe, .out, and .perks in the working directory. This function is used to ensure that all simulation process can be reproduced without misusing the old version of the file with the same file name. This function will not remove mod.exe.

mcsim_report()

• Reporting the system setting. If you meet any problem use this function and copy the report to https://github.com/nanhung/MCSim_under_R/issues