RGeoS Manual Didier RENARD

th ,

February 5

2013

Abstract This document gives the basic information for using the package RGeoS. It essentially describes the way to install RGeoS and gives an overall presentation of the package, developed using R language.

1 History The Centre de Géostatistique of the Ecole des Mines de Paris spent several years developing dierent commercial libraries or softwares in the past. Let us mention: : the rst geostatistical library in FORTRAN

•

GEOSLIB

•

BLUEPACK

•

SIMPACK

•

HERESIM

•

ISATIS

: a geostatistical package that lasted over 10 years and was famous in most mining and oil companies over the world : a package dedicated to geostatistical stochastic simulations

: a package, developed jointly with Institut Français du Pétrole, based on the Plurigaussian simulation technique : the geostatistical toolbox, developed jointly and commercialized by Géovariances

It is therefore a tradition for the Centre de Géostatistique to imagine, produce and commercialize the algorithms developed by scientists so that practitioner can apply these fancy techniques to the dierent elds in their own domain of activity, without having to bother writing lines of code. However, these packages do not allow the user to modify the code in order to test new ideas or algorithms. This is the reason why, starting in late 1990's, some researchers started introducing some algorithms in the framework of the R package. This was initiated with the GEFA package developed for the sheries community, which uses geostatistical techniques to forecast the sh density by 1

species and age. The user could benet from all the advantages due to the large number of contributors of R developers, combined to the procedures established by the researchers of the Centre de Géostatistique. As usual with writing packages using the R interpreted language, the GEFA package needed to be strongly improved for improving the calculation speed. This usually involves writing pieces of the package in using a compiled language (such as C or C++). This is precisely where RGeoS came. All the geostatistical code is written in C (and C++) and constitutes the specic library called Geoslib. The dierent procedures are then mapped into R functions. Finally a set of R objects are designed for storing data, parameters and results. This setup is now called RGeoS. The main characteristics of the RGeoS package is to perform geostatistical operations simultaneously on several (p) variables in a space of any dimension (n): we will designate this package as Rn -Rp package. However, some techniques are not dened for any space dimension, nor any number of variables treated simultaneously: a special test restricts their usage.

2 What is RGeoS ? RGeoS is similar to any standard R package (as could be obtained from the CRAN site). It provides: • all the R procedures with the corresponding on-line help (use the command ?func_name

to access the on-line help of the function func_name )

• the object library of the geostatistical code Geoslib • some demonstration case studies: the user can run them using the com-

mand demo() with the available data sets.

Note that the source code corresponding to the Geoslib library is not available.

3 Who can use RGeoS ? RGeoS can be downloaded by anyone. RgeoS can be used free of charge in a non-commercial use.

2

4 The reference to RGeoS When you use this software for publication, please use the following reference: Renard D., Bez N., Desassis N., Beucher H., Ors F., Laporte F. RGeoS: The Geostatistical package [version number]. Mines ParisTech. Free download from: www.cg.ensmp.fr/rgeos

5 Where can I nd RGeoS ? The package RGeoS must downloaded in turn from the web site of the Centre de Géostatistique of the Ecole des Mines de Paris: http : / / r g e o s . f r e e . f r This site contains several directories, such as: • the distributions where you can download RGeoS, according to the Oper-

ating System where you want to use the package. This download comes as a zip le for Windows, a tgz for Mac or a tar.gz for a Linux le. These distributions correspond to binaries which depend upon the version of the Operating System: for example, the LINUX distribution has been compiled on a Fedora Core 13 system.

• the demonstration directory where you can nd several case studies: each

case study contains:

 a PDF le where the case study is fully described  the ASCII le(s) that are used in the case study: however, these data sets are already contained in the distribution and can be downloaded using the data() procedure.

The package is provided for download on few platforms. For each platform, RGeoS is provided as a single le in an archive format. The extension of the archive le depends upon the platform: 32 or 64 bits: le with extension zip

•

Windows

•

LINUX 32 bits

•

LINUX 64-bits

•

Mac

-

: le with extension linux32.tar.gz

: le with extension linux64.tar.gz

: le with extension tgz 3

6 Installing the RGeoS package 6.1

Installing R

The package R must be installed rst. R is a free software environment for statistical computing and graphics. It compiles and runs on a wide variety of UNIX platforms, Windows and MacOS. This package can be downloaded from the site: http : / / cran . r − p r o j e c t . org If available for your Operating System, it is easier to install directly the dedicated binary version. Otherwise, one can always download the source code, congure it and compile it. Then please follow ocial information provided on the site. The installation requires the Administrator rights. 6.2

Additional contributions

Moreover, some additional contributions can be downloaded (from the same site): such as maps and mapproj which are only necessary in some parts of the package RGeoS and will be only needed upon request. Each extension comes as an archive le. 6.3

Installing an additional contribution

When installaing a package, one may choose between: • installing it as a permanent extension of R: this operation requires the

Administrator rights as the RGeoS add-on package is written on the directory where R distribution is installed. The installation is performed by typing:

R CMD INSTALL mypack • installing it as a personal extension: this is the case when an extension

often varies. This installation does not require the Administrator rights. The package is installed on a user's dedicated directory (say my_dir ) by typing:

R CMD INSTALL mypack −− l i b r a r y=my_dir

4

7 Starting with RGeoS You must rst start R in a working directory. You may have one working directory by project. You launch R by typing the corresponding command (or clicking the corresponding icon on Windows for example) Within the R session, you must load the RGeoS. If RGeoS has been installed in the R distribution directory, simply type: l i b r a r y (RGeoS) Otherwise type: l i b r a r y (RGeoS , l i b . l o c =/my_dir ) This information can be stored in a specic (hidden) le, called .First, which is automatically started each time R is loaded in the working directory. In order to create it, the best solution is to enter the R session and to dene it interactively by typing: fix (. First ) The previous command launches a text editor. The name of the text editor can also be parametrized in the .First le for future use. The contents of the .First le could be something as : . First function () { l i b r a r y (RGeoS , l i b . l o c ="/my_dir ") } 7.1

Additional information on RGeoS

When RGeoS is loaded successfully, the user can check the version of the RGeoS package. This information may become usefull for further discussion concerning the ability of the package to perform a given task or to describe a mysfunctioning: acknowledge ("RGeoS") The following message is displayed (which may evolve with time): Package RGeoS ( Version : 9 . 0 . 9 − Date : 0 4 Feb 2013) ================================================ u s i n g G e o s l i b Li bra ry ( Version : 9 . 1 . 2 − Date : 3 0 July 2012) Authors : 5

D i d i e r RENARD N i c o l a s BEZ N i c o l a s DESASSIS Helene BEUCHER Fabien ORS F l o r e n c e LAPORTE

( d i d i e r . renard@mines − p a r i s t e c h . f r ) ( n i c o l a s . bez@ird . f r ) ( n i c o l a s . desassis@mines − p a r i s t e c h . f r ) ( h e l e n e . beucher@mines − p a r i s t e c h . f r ) ( f a b i e n . ors@mines − p a r i s t e c h . f r )

Another interesting function (R standard) gives the position where the package has been loaded by typing: search () The following information is obtained in the R session (the contents depends upon the R version, the user's environment and the list of packages already loaded): search () [ 1 ] " . GlobalEnv " [ 4 ] " package : g r D e v i c e s " [ 7 ] " package : RGeoS" [ 1 0 ] " package : methods"

" package : s t a t s " " package : u t i l s " " package : mapproj " " Autoloads "

" package : g r a p h i c s " " package : d a t a s e t s " " package : maps" " package : base "

The order of the loaded packages may vary depending on the user's preferences. It is easy to see that here RGeoS is loaded in position 7. The user can then type the following command in order to get the list of all the procedures included in RGeoS: l s ( pos =7) Another way to learn about each command (say my_command) is to ask for its calling arguments by typing: a r g s (my_command) But obviously the best solution is to get the information on the command by typing: ?my_command The information can even be displayed in a more sophisticated manner is the user has launched a HTML browser beforehand by typing the following command at least once in the R session: help . s t a r t ( )

6

7.2

The License File

When starting RGe oS for the rst time, the following message is issued: Problem w i t h

t h e RGeoS L i c e n s e

File

− I f you have a L i c e n s e F i l e , p l e a s e i d e n t i f y i t ( f u l l p a t h ) . − O t h e r w i s e you can g e n e r a t e i t from t h e s i t e : h t t p : / / r g e o s . f r e e . f r / form . php You must i d e n t i f y y o u r s e l f and p r o v i d e t h e a c t i v a t i o n c o d e : XXXXXX You w i l l r e c e i v e t h e l i c e n s e f i l e by e m a i l . − I f you do n o t i d e n t i f y t h e l i c e n s e f i l e , y o u r R s e s s i o n r e m a i n s v a l i d but RGeoS f u n c t i o n s w i l l n o t be a c c e s s i b l e . I n c a s e o f problem , p l e a s e c o n t a c t : r g e o s @ g e o s c i e n c e s . mines − p a r i s t e c h . f r E n t e r L i c e n s e F i l e Complete Path o r ( Def =) :

As mentionned in the previous message, you must have a License File to run RGeoS. This License File needs to be installed only once, at your rst use of RGeoS. In all subsequent R sessions involving RGeoS, the License File will not be asked again (unless you modied its contents or its location on your disk). The license le can be generated automatically from the site where you already downloaded the RGeoS package from. You must simply ll a questionnaire where you identify yourself and the institution to which you belong, you enter your email address and you provide the activation code (XXXXXX in the previous message). You will immediatly receive your license le by email. Specifying its complete path to the initial question will give you the authorization to use RGeoS : no specic message is displayed.

7

Contents 1 History

1

2 What is RGeoS ?

2

3 Who can use RGeoS ?

2

4 The reference to RGeoS

3

5 Where can I nd RGeoS ?

3

6 Installing the RGeoS package

4

6.1 Installing R . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4

6.2 Additional contributions . . . . . . . . . . . . . . . . . . . . . . .

4

6.3 Installing an additional contribution . . . . . . . . . . . . . . . .

4

7 Starting with RGeoS

5

7.1 Additional information on RGeoS . . . . . . . . . . . . . . . . . .

5

7.2 The License File . . . . . . . . . . . . . . . . . . . . . . . . . . .

7

8