CapsisBridgeRClient

R Client for CAPSISBridge

• R Client for CAPSISBridge
  • Building the package
  • Getting connected to the server
  • Loading previously saved meta-models
  • Getting the available stratum groups
  • Getting the possible output types
  • Getting predictions from a meta-model

Building the package

This package relies on Rcpp and the CapsisBridgeClientLib C++ library to allow access to Capsis through gRPC calls.

1. Follow these instructions first to build the C++ library under MinGW64 : https://sourceforge.net/p/capsisbridge/wiki/Building%20on%20Microsoft%20Windows%20and%20MinGW64/
2. Start RStudio and open the CapsisBridge R client project
3. Modify the Makevars.win file into the src subfolder and set the variable CAPSISBRIDGE_INSTALLDIR to the location where the C++ library has been installed (typically the install folder under the build_mingw64 folder of the c++ lib folder). i.e. : /w/projects/cpp/CapsisBridge/cppclient/build_mingw64/install
4. (Linux only) On Linux systems, when gRPC is installed locally, we must specify the location of the grpc installation so that the Makevars file pkg-config statement can find grpc at its dependencies, i.e. ~/.local/lib/pkgconfig using command :
   export PKG_CONFIG_PATH=~/.local/lib/pkgconfig
5. Build the package using CTRL-SHIFT-B

Getting connected to the server

The connection to the server is made through the MMInitialize function:

> MMInitialize("localhost:50002")
[1] 0
>

The argument string must contain the IP address and the port number separated by a colon.

Loading previously saved meta-models

The meta-models are embedded in a meta-model manager which can be loaded and saved. When loading a meta-model, the file must be located in a known directory on the server.

> MMLoad("D:\\projects\\java\\CapsisBridge\\javaserver\\data\\QC_FMU02664_MS2_NoChange_AliveVolume_ConiferousSpecies.zml")
-------------- load --------------
-------------- load OK -----------
[1] 0
>

Getting the available stratum groups

Calling the CBGetStratumGroups method returns the available stratum groups in the meta-model manager instance. For example,

> MMGetStratumGroups()
-------------- getStratumGroups --------------
-------------- getStratumGroups OK -----------
-------------- getStratumGroups --------------
-------------- getStratumGroups OK -----------
 [1] "RE1_NoChange"     "RE1_Plus2Degrees" "RE1_Plus4Degrees" "RE1_Plus6Degrees" "RE2_NoChange"    
 [6] "RE2_Plus2Degrees" "RE2_Plus4Degrees" "RE2_Plus6Degrees" "RE3_NoChange"     "RE3_Plus2Degrees"
[11] "RE3_Plus4Degrees" "RE3_Plus6Degrees" "RS2_NoChange"     "RS2_Plus2Degrees" "RS2_Plus4Degrees"
[16] "RS2_Plus6Degrees"
>

Here the function returned 16 meta-models corresponding to different combinations of stratum groups (RE1, RE2, RE3, RS2) and climate scenarios (NoChange, Plus2Degrees, Plus4Degrees, Plus6Degrees).

Getting the possible output types

The simulation can return different output types such as species specific volumes or basal areas. To get the available output types for a particular meta-model, use the MMGetPossibleOutputTypes with the name of the stratum group as argument:

> MMGetPossibleOutputTypes("RS2_Plus2Degrees")
-------------- getPossibleOutputTypes --------------
-------------- getPossibleOutputTypes OK -----------
-------------- getPossibleOutputTypes --------------
-------------- getPossibleOutputTypes OK -----------
[1] "Broadleaved" "Coniferous" 
>

In this example, the meta-model of stratum group "RS2_Plus2Degrees" has two output types: the volume of broadleaved species and the volume or coniferous species.

Getting predictions from a meta-model

The MMGetPrediction function makes it possible to obtain the prediction from a particular meta-model. For example, this call

> MMGetPrediction("RS2_Plus2Degrees", 50, 0, "Coniferous")
-------------- getPrediction --------------
-------------- getPrediction OK -----------
[1] 82.10176
> 

returns the volume prediction at 50 years of age at the beginning of the simulation for coniferous species in the stratum group "RS2_Plus2Degrees".