R is a language and environment for statistical computing and graphics and is freely distributed under the terms of the GNU General Public License [?]. It is similar to the S language as originally developed at AT&T Bell Laboratories, although having important differences in the design.
R provides a wide variety of statistical and graphical techniques, is highly extensible having interface with procedures written in C/C++ or FORTRAN. A web site with further information can be found at http://www.r-project.org.
TerraLib is a Geographic Information System (GIS) library written in C++, developed at Brazil’s National Institute for Space Research (INPE), available from the Internet as an open source project, allowing for a collaborative environment for the development of multiple and flexible GIS tools [?]. TerraLib defines geographical and temporal data models and provides support for this model over a range of Data-Base Management Systems (DBMS). A web page with further information on TerraLib is available at http://www.terralib.org.
An example of application that use TerraLib library of classes is TerraView. This is a Geographical Application tool, with spatial analysis capabilities, and is also licensed as free software under the GNU General Public License. It can be downloaded together with TerraLib.
aRT (API R-TerraLib) is an R package that provides the integration between the softwares R and TerraLib. The idea is to have a package that uses the statistical analysis provided by R and the geographical data model and database support by TerraLib. A web site with further information can be found at http://leg.est.ufpr.br/aRT
The main motivation for the package development is to facilitate the exchanging of information between the spatial packages in R and the DBMS using TerraLib ability to manage and perform some spatial operations on the database. For instance, data can be easily moved between R and TerraLib, and routines in TerraLib can be used to proccess data, making functionalities in TerraLib available to the R packages. This way a data analyst could, for instance, import the data to R, perform some analysis using a spatial package such as spdep, splancs, gstat, geoR, among others, and return the results to the database. The results persisted in the database could them be accessed by a GIS software such as TerraView.
aRT is being developed under a GNU/Linux-Debian platform and although source code is distributed, there is no guarantee it will work in other one. There are tentatives to mantain a compiled Windows version in the aRT web age. The instructions about how to compile and install aRT are available at leg.est.ufpr.br/aRT.
After installing aRT and starting an R session, load the package with the command library(). If the package is loaded successfully a message TRUE will be displayed.
aRT has four main classes to manipulate TerraLib data/functions: aRTconn, aRTdb, aRTlayer and aRTtheme. The next subsections explain each class in details. As this is an introductory vignette, we will enable the aRT functions message dump, calling aRTsilent:
Once the package is loaded, we need a DBMS connection. It is encapsulated in an onbect of class aRTconn. The constructor of aRTconn gets as arguments user, password, host, dbms and port, and their default values are USER variable, empty string, empty string again, the first DBMS found by the configure, and the default port for that DBMS, respectivaly. For example:
After creating con, the variables it contains cannot be changed. If you need to set them, the only way is to create the object again. It happens because aRT uses external pointers to store the objects, but we will not explain how it works here.
One aRTconn object stores a virtual connection, i.e., all time that a database access is required, it connects, does something, and then disconnects. The objective of this class is to provide some database administration tasks, and open real connections. For example, if it is the first time you are using aRT, perhaps you will need to give permissions to some users. To do so, use addPermission():
Warning: this function gives ALL permissions in ALL databases to a user. If you want to do something different, see the documentation of addPermission.
With an aRTconn object, you can also see the databases available and remove them. The next example shows the databases and tries to remove a database called bodmin if it exists:
To create a new database, or to access one, there is the aRTdb class. One object from this class stores a real database connection, and we need an aRTconn object to create it:
This constructor fails if the database already exists. Once this object is created, it depends no more on the con object.
A aRTdb object contains all TerraLib objects in memory needed by aRT. This means that all objects opened from this one depends on it, even after they are created in R. If this object is removed from R, all his “childrens” become invalid objects when R’s garbage collector remove this object from memory.
To work with data in aRT, we need to manipulate layers. A layer can store any geometry of one kind (points, lines, polygons, raster and cells), and attributes. Layers are TerraLib abstrations that use tables of data and tables of control in one database. So they can be created from aRTdb objects.
To insert data in the layer, we will use the bodmin dataset, available within splancs package. We only need to remove the first point of bodmin polygon, because it is a repetition of the second point, and then TerraLib may interpret it as the end of a polygon with only one point.
Before insert into the database, we must convert the data to aRT format, following sp classes. The next commands converts it to a SpatialPointsDataFrame and inserts it into the database:
To insert the evolving polygon, we will create another layer:
Finally we will do a kernel analysis, and insert the raster data into the database, in another layer:
Finally, there are three layers in the database, and they can be seen in the next code:
To get the layer’s geometry call getGeometry, and then you can plot it. But if you don’t need the data the layer can be plotted directly:
The last class implemented in aRT is aRTtheme. Themes can be visualized in TerraView software, and they can select data and join tables. For now, we will only create themes of points and polygons, and put them in the view view:
There is an argument that can be used in raster themes: the colors configuration. It can be used as in the next example.