StellaR
Home

Download

StellaR is a free and open source python application which translates a Stella model into an R script. This application has been developed by  Babak Naimi  and Alexey Voinov.

R is a language and a free (under the GNU general public license) and open source environment for statistical computing, data analysis and graphics. R provides a wide variety of statistical and graphical techniques, and is highly extensible. Although R has been widely known as an environment for statistical analysis and graphical representation, it is rapidly becoming more suitable for mathematical computing. The capabilities of R are can be extended through these user-created packages, which allow to develop new and specialize analytical techniques, graphical devices, import/export capabilities, reporting tools, etc. All of these capabilities make R so powerful and consequently, the number of users and its functionality is growing in exponential terms.

R uses a command line interface; however, several graphical user interfaces are available for use with R  (e.g. RStudio, Tinn-R).

 StellaR

There are several well-established dynamic simulation systems including STELLA and iThink, PowerSim, Berkeley Madonna, VENSIM, Simile, etc. One of the reasons that these systems dynamics software became so popular in modeling is that they provide handy tools to put together conceptual diagrams, and, provide tools to convert them into numeric computer models (Voinov 2008). Although they can be very useful for specific applications, they often lack the full power and flexibility of programming language (Petzoldt and Rinke 2007).

StellaR provides a bridge to simultaneously use conceptual modeling tools together with great functionalities and programming flexibilities provided by R.

How to use StellaR

First you build your model in Stella. Make sure it runs and produces some output.

Next, there are three simple steps to translate a STELLA model to R scripts:

  • Export STELLA equations to a text file
  • Use StellaR program to translate the exported file into R scripts and data files (if there is any)
  • Open up the script in R, and run the model by loading deSolve package (Soetaert et al. 2010b)

a) Export STELLA model into a text format:

Open the STELLA model -> Go to Equation layer -> From File menu, select ‘Save as text’ to export the STELLA model as a text file in the working directory on your machine.

STELLA to Text

b) Using StellaR program to translate STELLA model to R script:

First download the program file, from http://sourceforge.net/projects/stella-r/files/

A distribution for windows as well as python source code, which can be execuded on any operating system, are available.

StellaR is a command based program. It only needs the name of text file which is exported from STELLA, and the name of R project as arguments.

Following you will see the usage of StellaR in windows OS:

Suppose the name of exported STELLA model to text format is ‘st.txt’, and you have this file together with the executable StellaR program on d:\test. Open command prompt (cmd.exe), change the path into the working directory (d:\test), and use StellaR as:

D:\test> StellaR  st.txt  st_r

The first argument (after StellaR) is the name of stella model, exported as a text format (st.txt); and the second argument is the new name that you can consider for your project in R.

To execute the command using python source code, having python on your machine, you can use the following line:

$ python StellaR.py st.txt st_r

The program creates a new folder with specified name for R project (here, st_r). Inside the folder, at least two files (R script) will be created. If there is any data inside the STELLA model, for each data item a separate file with CSV format also will be created.

c) Open the translated model in R:

You only need to open the R script with the name you specified as the second argument in the command line in R software.

In R you can perform most actions by typing commands in R console. By puting commands in a file, called R script, you can easily re-run, edit, and manage them. There are some software can be installed together with R to assist you in scripting and managing your projects in R. Here we used RStudio (www.rstudio.org) which can be considered an IDE for R scripting. It has been realised for major operating systems. There is, however, some other IDEs like Tinn-R.

As it is already mentioned, the STELLA model is translated into some R scripts and data files. To open the script in R, first set up the working directory to the location that the StellaR has created as R project. setwd() function set up working directory:

By selecting the ‘open file’ from File menu, you can open the main R script that can be executed in R environment. You do not need to open the other generated scripts and data files since they will automatically be read by main script. The main script has the name you specified as the name of project with extension ‘.R’.

You can simply select all lines in the script and press the Run button to execute the model.

The STELLA model including the differential equations and the defined processes (flows), is specified as a function in R. The function (model) has several arguments including time, the initial values of the state variables, and a vector of the parameters. This function will be called by the ode function in deSolve package (for more information on the usage of deSolve package, see Soetaert et al. 2010b).  Following figure represents the structure of the function in R.

R model

References

Naimi, B. amd Voinov, A. 2012. StellaR: A software to translate Stella models into R open-source environment. — Environmental modelling & Software. 38: 117-118

Petzoldt, T. and Rinke, K. 2007. Simecol : An Object-Oriented Framework for Ecological Modeling in R. — Journal of Statistical Software 22: 1-31.

Soetaert, K. et al. 2010a. Solving Differential Equations in R. — In: Psihoyios, G. and Tsitouras, C. (eds), Numerical Analysis and Applied Mathematics, Vols I-Iii. Amer Inst Physics, pp. 31-34.

Soetaert, K. et al. 2010b. Solving Differential Equations in R: Package Desolve. — Journal of Statistical Software 33: 1-25.

Voinov, A. 2008. Systems Science and Modeling for Ecological Economics. — Academic Press.

 

Home | Download | About | Contact
For comments, questions, and problems contact me at: naimi@r-gis.net