You are here: 52°North>Wiki>Geostatistics Web>Sos4R (29 Jan 2015, DanielNuest)Edit Attach


User Documentation

This page contains information for developers of the R package sos4R. Documentation for users can be found in the package vignette. You can install the package simply by calling install.packages("sos4R").


Contributor Documentation

We use the "fork & pull" development model for all developments. If you want to develop further functions for the package always use the up-to-date version and start a new branch.

Code Repository

sos4R is on GitHub and you can get the code with git clone

Development Version

ALERT! This section is outdated - it is now recommended to fork and clone the repository and then create a new RStudio project. If you're not an RStudio user, consider using the devtools package. ALERT!

Please make sure that you have the packages XML and RCurl installed (i.e. install.packages("RCurl"); install.packages("XML")).

Once you checked out the code you can easily load all files into an R session by sourcing the file .../sandbox/loadSources.R, i.e. source("/sos4R/sandbox/loadSources.R"). If you use StatET, you can even automate that by configuring your run configuration: Open the run configuration management page, go to the tab /R Console/ and add the following lines to /R snipped run after startup/:

.path = "<your path to the workspace>/sos4R"

source("<your path to the workspace>/sos4R/sandbox/loadSources.R")

Be aware that if you edit functions that are exchangeable (and therefore called from the lists inside a SOS instance in R), it does /not/ suffice to run the function definition in the current session, but you also have to set the defaults again and then recreate the SOS object.

Branches and Versions

A new branch should be created for new versions that significantly change the code, the master branch should be in line with the version available on CRAN and used only for bugfixes.

Package Structure

Folder Structure

The package follows the common folder structure for R packages, documented in the manual Writing R Extensions. Please follow the rules described there at all times.

Additional Folders

  • sos4R/sandbox contains code that is not exported from the package but is used during development to test during the implementation of (new) functionality. Please consider using this extensively as a history to be able to resolve problems that occurred before and to document what is working and what not. It is also recommended to run related tests again after (even minor) changes in the code.
  • sos4R/inst/doc contains the Sweave file for the package vingette, sos4R.Rnw.

R Source File Structure

File Naming System

The files named in the source code folder sos4R/R follow the following naming scheme.
  • Class-[OperationName].R contains the R representation of the requests for a certain SOS operation, like Class-DescribeSensor.R.
  • Class-[Namespace prefix].R contains the class declarations for objects from the given namespace, like classes for XML types in Class-GML.R, but also generic classes as in Class-SOS.R.
  • Constants.R contains constants, which shall not be changed by the user. Please reconsider every time you write a character string in the code if it should not be a constant. Names of XML types and elements shall always be constants, attribute names can be constants. This file also contains the lists of supported features, like result models and connection methods. Use accessor functions where needed.
  • Defaults.R contains useful default settings and lists and accessor functions for the parsing, encoding and conversion functions. Useful stuff, like example URLs, may also be saved here.
  • [OperationName]-methods.R contains methods for objects related to the given operation, like constructor functions and encoding functions.
  • Generic-methods.R contains declarations for generic methods (except the accessor functions from SOS-methods-util.R).
  • [Namespace prefix]-methods.R contains constructor functions and encoding functions for classes of the given namespace.
  • [Namespace prefix]-methods-parsing.R contains the parsing/decoding methods for the elements of the given namespace. If there is a very limited number of parsing functions and the file is not very long, the parsing functions may also be in the file [Namespace prefix]-methods.R.
The Core Source Files

Some imporant files in the package sos4R are the following.
  • SOS-methods.R contains the functions for the operations, like getCapabilities(sos:SOS), and the function that actually does the sending of the request, sosRequest(...).
  • SOS-methods-accessor.R contains accessor functions.
  • SOS-methods-util.R contains a lot of convenience and accessor functions, and should be used to keep the file SOS-methods.R lucid.
  • SOS-methods-plotting.R contains plotting functions.
  • testing.R contains tests done during the development of certain functions and is a very good opportunity to (re-)check functionality and keep a history of functionality that is working (at some point in time at least...).
  • testing-SOSs.R contains tests of connections to different types of SOS and different SOS instances.
  • packaging.R contains the functions for creating package documentation and should be used as the spot to collect useful functions and workflows around future documentation and the packaging process.
Naming of Functions, Defaults, and Constants

The following guidelines are a non extensive list of naming rules that were used within the package. Please also browse through the code files before starting to develop new functions to get to know the structures that are already in place so that a good user experience can be ensured.
  • Defaults: sosDefaultXYZ, e.g. sosDefaultCharacterEncoding
  • Defaults with accessor function: Follows the same rules, but add a point to the actual variable so that it is not exported and start the function with a capital letter, e.g. .sosDisabledParsers and SosDisabledParsers()
  • Constants: Constants for names of XML elements start with a lowercase character string of the namespace prefix, a unique name of the element (where parts like "type" and special characters may be left out, and other descripte elements may be added for clarity), and end with Name, e.g. gmlEnvelopeName <- "Envelope", ogcGeometryOperandLineStringName <- "gml:LineString", or ogcTempOpTMEqualsName <- "TM_Equals".
  • Supported features: The supported features, like connection methods and supported response modes, shall be accessible by functions starting with SosSupported, e.g. SosSupportedConnectionMethods().
  • Accessor functions: Shall start with sos, e.g. sosOfferings(sos:SOS).
  • Functions to access default values, especially lists and functions with merging feature: Shall start with Sos, e.g. SosEncodingFunctions().

Building and Release

Version Numbers and Changelog

The version numbering scheme follows the one of R itself (which is semantic versioning: [major version].[minor version]{-[bugfix]}, where [bugfix] is optional.
  • Bugfix releases can be used extensively (for several, or even just on major bug) to show users that errors are resolved.
  • Minor versions shall include several major bug fixes or a considerable addition of tested and working functionality.
  • Code changes that possibly break existing code shall only be released with a major version change and should be discussed in the developer community beforehand.
Major bugs and all changes must be listed in the change log file sos4R/NEWS. Please read the GNU Coding Standard for change log files for some guidelines.

The version number and current date must be changed in the following files:
  • sos4R-package.Rd


The vignette is stored in the directory /vignettes. You can compile it with Sweave and StatET by creating a new Run Configuration for R and setting the following options.

R options: Working Directory: ${workspace_loc}/sos4R/vignettes

Then create a new External Tool Configuration for Sweave Document Processing and set the following options:

Run commands in active console: Sweave(file = "${resource_name}")

Then start the R console and run the external tool configuration while having the Sweave file open. Google if you have problems with Sweave.sty.


A new release shall be uploaded to CRAN after testing and under the following procedure:
  • Create tag with version number
  • Update NEWS file based on latest commits
  • When available on CRAN

Submission to CRAN

Read again and again.

Most important points:
  • R CMD check --as-cran has been run on the tarball to be uploaded before submission.
  • A submission should be accompanied by an email to sent from the maintainer address listed in the package, and using the subject line `CRAN submission ', where and are the package name and version, respectively.
    • CRAN submission sos4R 0.2-8
  • non-ASCII characters > find them with tools::showNonASCIIfile()

Roadmap and To-Do List

Feature ideas (as issues tagged "enhancement"), roadmap (as milestones) and tasks (issues in the current milestone) as as well as bugs (tagges as "bugs") are managed on GitHub:
Topic revision: r62 - 29 Jan 2015 09:16:27, DanielNuest
This site is powered by FoswikiCopyright &© by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding Wiki? Send feedback