|
UsingRFortran
Provides a references for the RFortran functionality
Featured
Core FunctionalityRinitDescription Initialises R ready to transfer commands to and data to/from R and Fortran Syntax Rinit([Rfortran_ScriptPathIn],[wait4RIn],[RGuiPathIn],[workingDirIn],[log_file],[log_append],[log_echo],[RgraphicsDevTypeIn],[GraphicsDev_name],[GraphicsDev_cmd]) Arguments
Value Returns scalar integer(mik): 0 = success other values = failure, see also Error Handling Details Rinit performs the following tasks:
Examples Initialise R and auto-load R scripts in path D:\RFortran\Rscripts ok=Rinit(Rfortran_ScriptPathIn='D:\RFortran\Rscripts') Initialise R and wait 5 secs after auto-opening R before initialising COM interface ok=Rinit(wait4RIn=5000) Initialise R and auto-load Rgui.exe in path C:\Program Files\R\R-2.8.1\bin\ wait 5 secs after auto-opening R before initialising COM interface ok=Rinit(RGuiPathIn='C:\Program Files\R\R-2.8.1\bin\') RevalDescription This evaluates commands to be executed in R. Syntax Reval(commandstring) Arguments
Value Returns scalar integer(mik): 0 = success other values = failure, see also Error Handling Details commandstring is the R command that you would type at the R prompt, see examples below Examples Set value of R variable x to 1 ok=Reval("x=1")Generate 100 normal random numbers and store in a and b, then plot them (illustrates use of double and single quotes) ok=Reval("a=rnorm(100)")
ok=Reval("b=rnorm(100)")
ok=Reval("plot(a,b,xlab='x')")RputDescription There two forms for using Rput - this one transfers variables from Fortran to R. The other is for commands to be executed in R - see [Rput(command)] Syntax Rput(R_var,Fortran_var,[mv],[status]) Arguments
Value Returns scalar integer(mik): 0 = success other values = failure, see also Error Handling Details Current types of Fortran_var that are supported are: Scalars, 1-D, 2-D, 3-D arrays integer(2), integer(4), real(4), real(8), logical(4), character(*) [mv] is useful for transferring missing values from Fortran to R - see Examples below [status] determines how the overwriting of R variables by Rput is handled. Possible values and actions are:
These options are similar to the STATUS argument for the Fortran function OPEN used for connecting to files. Examples Transfer a real(4) scalar real(4) :: pi_short = 3.1415
ok = Rput("pi_short",pi_short)At R prompt: > pi_short [1] 3.1415 Transfer an integer(4) 1D array integer(4) :: cc(1:5) = (/112, 222, 333, 444, 555/)
ok = Rput("cc",cc)At R prompt: > cc [1] 112 222 333 444 555 Transfer an integer(4) 1D array with missing values integer(4) :: cc(1:5) = (/112, 222, 333, 444, 555/)
ok = Rput("cc",cc,mv=(cc==222)) At R prompt: > cc [1] 112 NA 333 444 555 Many more examples of using Rput and Rget are provided in TEST_RputRget.f90 RgetDescription Transfers data from a variable in R to a Fortran variable. Syntax Rget(R_var,Fortran_var,[alloc],[typeOption],[InvalidOption]) Arguments
Value Returns scalar integer(mik): 0 = success other values = failure, see also Error Handling Details The types and shapes of data being transferred from R to Fortran currently supported are are the same as with the Rput function. Fortran_var must match the type and the dimension of R_var- see Error Handling for how type and dimension mismatches are handled. For arrays, if alloc=.true. and Fortran_var is allocatable then Fortran_var is reallocated/allocated to match size of R_var In all other cases R_var and Fortran_var must have the same size, otherwise an error will result. The Rget routine can handle R expressions providing they result in a data variable that matches the Fortran variable, see examples below. Examples Get a real(4) scalar real(4) :: pi_short = 3.1415
ok = Rput("pi_short",pi_short)
ok = Rget("pi_short",pi_short)Get an integer(4) 1D array integer(4) :: cc(1:5) = (/112, 222, 333, 444, 555/)
ok = Rput("cc",cc)
ok = Rget("cc",cc)Examples of R expressions that can be Rget: components of objects '$' symbol Rget('a$statistic',scalar)portions of arrays '[]' symbols Rget('x[3:10]',array)results of functions '()' symbols Rget('length(x)', scalar)arithmetic expressions +/-*, etc Rget('1+2', scalar)all of the above Rget('arima(rnorm(50),c(1,0,0))$coef[1]', scalar)Many more examples of using Rput and Rget are provided in TEST_RputRget.f90 RcallDescription Handles passing of multiple variables and commands to R. Syntax Rcall(vars,cmds) Arguments
Value Returns scalar integer(mik): 0 = success other values = failure, see also Error Handling Details This is a really useful function! vars can be used to pass multiple variables to R via a series of Rput commands cmds is a character vector of commands to be executed in R (usually using the variables passed to R in vars) Examples Send xdata and ydata to R, plot them and then remove them Rcall(vars=(/Rput("x",xdata),Rput("y",ydata)/), &
cmds=(/cl("plot(x,y,xlab='x',ylab='y-axis',xlim=c(0,1.2),ylim=c(0,1.2))"),&
cl("rm(x,y)")/))Note: cl is simply a string function 'common length) used to ensure all the components of the cmds character vectors have the same length to avoid a Fortran compiler warning! Error HandlingAll RFortran functions return integer error flags, using non-zero values to indicate error conditions. Descriptive error messages are written to a log file, message.log. In addition, a look-up table of the error codes is provided below. Error Codes[rcom] in description denotes an error produced by the rcom interface and passed to RFortran. All other errors are produced within the RFortran code itself.
When transferring variables using Rput from Fortran to R, as long as the syntax is correct there are minimal errors since the flexible R language changes the R variable to the type,dimension and size of the Fortran variable When transferring from R to Fortran using Rget many potential errors can occur. How each type of error is handled is as follows: Type MismatchesIf types of R_var and Fortran_var are different then this handled depending on the value of optional argument typeOption to Rget or if it isn't present, then typeOptionDef set in RFortran.set Possible values for typeOption and their actions are:
Dimension MismatchesDimension mismatches between R_var and Fortran_var report an error and no transfer occurs Size MismatchesSize mismatches between R_var and Fortran_var report a warning but a transfer from R to Fortran occurs - with any potential side effects Invalid ValuesR variables can take certain values, such as NA, NaN and Inf which cannot be transferred to Fortran. RFortran checks for the existence of these invalid values and takes action depending on value of optional argument InvalidOption to Rget or if it isn't present then InvalidOptionDef set in RFortran.set Possible values for InvalidOption and their actions are:
If InvalidOption=CONVERT, different variable types are converted to following values:
A side effect of this conversion is that the invalid values in r_var are converted to the convert values specified in the table above. Example Put an integer(4) 1D array with missing values integer(4) :: cc(1:5) = (/112, 222, 333, 444, 555/)
ok = Rput("cc",cc,mv=(cc==222)) At R prompt: > cc [1] 112 NA 333 444 555 Get an integer(4) 1D array with missing values Case 1: InvalidOption=ERROR_DONTPASS ok = Rget("cc",cc,InvalidOption=ERROR_DONTPASS) Result in Fortran: ok!=0 and cc is not transferred Case 2: InvalidOption=ERROR_DOPASS ok = Rget("cc",cc,InvalidOption=ERROR_DOPASS) Result in Fortran: ok=0 and cc is transferred - unpredictable results Case 3: InvalidOption=ERROR_DOPASS and Convert_Invalid_I4_val=-999 ok = Rget("cc",cc,InvalidOption=CONVERT) Result in Fortran: ok=0 and cc=(/112,-999,333,444,555/) At R prompt (shows side-effect): >cc [1] 112 -999 333 444 555 If InvalidOption were not present in any of the above then InvalidOptionDef in would determine action. RFortran SettingsRFortran has several global variables that can be modified by the user to suit their own configuration/project. These variables are all contained in the RFortran.set file and are listed in the table below.
A default version of RFortran.set is installed to the folder RFortran\Settings. This file contains instructions on how to modify it to change these global variables. When Rinit is called it looks for RFortran.set in the following locations in order of priority:
This enables different projects which use RFortran to have different 'RFortran.set' files Setting up your own projects to use RFortran FunctionalityXXX=CVF or IVF. CVF users substitute 'solution' for 'workspace' below There are two ways to use the RFortran software library in your own projects (1) Insert the source code directly into your project The easiest way to do this is to add the project RFortran\RFORTRAN_XXX\RFORTRAN_XXX_LIB to your solution, and copy the folders RFortran and MUtilslib-readonly into your project This has the disadvantage that RFortran can be re-compiled everytime you rebuild your project (2) Add the static library RFortran_XXX.lib to your project This has the advantage that only one version of RFortran is compiled on your computer. Choose one of the following methods:
This does not auto-link to the debug and release configurations of RFortran This is the optimal solution - auto-links to debug and release configurations of a single RFortran static library. The following are suggested project properties\settings: IVF
If you apply the above project properties to "All Configurations" you do not need to change the debug and release configurations seperately. CVF
where RFortran install path = install path of RFortran ZZZ = debug or release configuration The projects in the tutorial examples folder provide an example of how to configure the project properties/settings to use the static library.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
► Sign in to add a comment