SVN and R
From Intamap
This page gives a general description on how you can make changes to the R INTAMAP package, and how to make these changes available to the other developers using the SVN-server.
Contents |
SVN-repository
The use of a subversion repository is a way of jointly deveoping documents and computer source code. The repository (http://intamap.svn.sourceforge.net/svnroot/intamap/) stores all versions of documents being uploaded to it, and is able to compare the different versions.
Windows
The easiest is to download Tortoise SVN. This program gives you a simple access to the SVN-repository through your file browser window (explorer or alternatives, as xplorer2). After installing Tortoise SVN, you should first download a copy of the documents in the SVN repository to your own computer. This can be done by:
1) Create a directory which you want to use (SVN might be a convenient name, but not mandatory)
2) Right-click on the directory and go to SVN checkout on the context menu
3) Give the web-address to SVN-repository: https://intamap.svn.sourceforge.net/svnroot/intamap
4) Choose whether you want to download everything in the repository (including automap and raisin) or only the intamap R package.
5) Download
When you later want to download the latest version of a file or directory, you click on update on the context menu. If there are differences between the files in the SVN repository and on your computer, these will be marked with a red symbol in your file browser.
After having modified existing documents or added new files, you can upload your changes back to the repository by choosing "Commit" from the context menu. Username and password for sourceforge are needed for uploading files. You can get usernames directly from http://www.sourceforge.net, and after sending your username to Edzer, Kor or Jorge, they will include you as developer in the project.
Conflicts
It is possible that two or more partners work on the same file at the same time. If another partner first commits his/her changes, the file will be marked as a file with a conflict in your file browser as the SVN-version might have changes inconsistent with the version you are working on. These conflicts can be solved using Diff and Merge, which are found under Tortoise SVN in the context menu after right-clicking on the file.
Linux
Access to the files in the SVN repository are generally given by the command
> svn
followed by a more detailed description of what should be done. The first time you download from the SVN repository into your SVN-directory, this can be done by:
> svn checkout https://intamap.svn.sourceforge.net/svnroot/intamap
After having modified files, you can again upload these by:
> svn commit –m ’a message describing the changes you have made’
If you haven’t worked with the source tree for a while, it makes sense to synchronize your tree with that on the svn server before further editing, by
> svn update
The R intamap package
After downloading the package, you can first install it as it is.
Windows:
1) Open the Rgui
2) From the menus, choose Packages -> install package(s) from local zip-files
3) A compiled version of the R intamap package is usually found under
Intamap/pkg/intamap_x.x-x.zip
Where x.x-x refers to version number
4) To be able to build the package, you need a range of extra programs. These are collected in a toolbox called Rtools, which you can find on :
http://www.murdoch-sutherland.com/Rtools/installer.html
This toolbox is usually able to change the path properly, if not, there is a description on how to manually change the path.
5) The commands for creating a package is run from a command prompt (DOS window)
Linux
For Linux, the source tar-ball is used for installation:
> R CMD INSTALL intamap_x.x-x.tar.gz
If you have limited write access on the computer, you might have to set the R library to be somewhere you have a write access. Create the file .Rprofile with
.libPaths("/home/jon/RLIBS/")
Or .Renviron with:
.libPaths("/home/jon/RLIBS/")
Alternatively, set the R_LIBS environment variable to the lib directory, or equivalently start R by
> R_LIBS=/home/jon/RLIBS R
General:
1) The R package on sourceforge does not include any data files. These can be downloaded as the file data.zip from the restricted part of the intamap home page: http://www.intamap.org/
Create a directory data in the directory where the intamap package was installed in the R-library
(Usually: c:/program files/R/RX.X-X/library/intamap/data) and unpack the data-file in this directory. If you are developing the R intamap package, you should also copy the data to a data directory here.
2) The intamap package can now be built by the command:
R CMD build intamap (for a tar-ball of the package)
R CMD build –binary intamap (for a zip file that can be installed as in point 2) above)
Recommendations when programming
1) The interpolation framework in the Intamap package is done through the use of a krigingObject, which is a list of necessary variables. A minimum requirement at the current stage is that this object at least contains:
pointData (observations)
params (usually included from getIntamapParams – with a series of defaults)
predictionLocations – points or polygons for predictions
Each step in the framework receives this object, adds its output to it, and returns the full (augmented) object.
2) Choose names that are self explanatory. If a function or variable name has several words, capitalize each of them except from the first one. A function then typically has the name:
doSomething
whereas a variable can have names as
variable, data
variableName, pointData
3) Functions like estimateParameters and spatialPredict should only take the krigingObject as input, and also return a modified version of this object as output.
4) Instances of functions (e.g. linear kriging, automap, Bayesian) are defined by the use of classes. A call to spatialPredict with a krigingObject of class automap will for example use the function spatialPredict.automap.
5) See also 00Introduction in the help files
Help files
It is important to write functions, but these are rather useless if other users are not able to use them. Therefore, you have to write help files for each new function, to be saved in the directory man. The easiest way to get started is to copy one of the other files, and modify it. Errors in the help-files cause the build process to crash, usually after having built for a long time. The best way to prevent this is to check them with:
R CMD Rd2txt myFunction.Rd
For functions that have several instances with rather different behavior (as spatialPredict), information about a new instance can be included in the file spatialPredict.Rd. However, this file might get too complicated if the different instances have very different behavior, and e.g spatialPredict.astonKriging could also be defined as:
spatialPredict.astonKriging = function(krigingObject) {
observations = krigingObject$pointData
params = krigingObject$params$paramsAston (this does not yet exist in the parameters)
predictionLocations = krigingObject$predictionLocations
krigingObject = astonKriging(observations,predictionLocations,params)
}
There will then only be a reference to astonKriging in spatialPredict, and the rest of the description of this function will be in astonKriging.Rd
Test files
Test files have two purposes.
1) To check your own code and help pages
2) To automatically be able to check that the functions does the same as last when there has been an upgrade of R itself or some of the packages (including the intamap package)
The test functions are invoked by calling
R CMD check intamap
R will then check the code, and run all tests stored under the tests directory. These tests are R-scripts that test different parts of the complete intamap package. Results are stored in the directory
C:\SVN\intamap.Rcheck\tests
If the test gives the result you think it should give, you can copy the result of the test from this directory to the test directory under intamap.
Further reading
There are many sources to further information (R home page, task views, wiki pages, books). A highly relevant book for R and spatial data is of course the book:
Bivand, R. S., E. J. Pebesma, and V. Gomez-Rubio (2008) Applied spatial data analysis with R, 378 pp., Springer.
Below is a link to a simple source to more information about building R packages. The document is particularly targeted at windows-users, but much of the information is also relevant for Linux-users.
