Lesson 10 is not so much a lesson as a set of instructions capturing many of the details involved in updating the seismic packages.
By far the best available documentation on creating R packages is Hadley Wickham’s R Packages. In the introduction, Wickham provides links to other useful blog posts as well as the official, exhaustive and somewhat obtuse writing R extensions manual.
Karl Broman offers another package primer that might be a good place to start learning about R packages.
This lesson assumes that users have familiarized themselves with package basics by reading background documentation before attempting to modify seismic~ packages with the instructions below.
Each package has the requisite minimal structure:
NOTE: As currently written, the seismic~ packages do not take advantage of the devtools package that features prominently in the R Packages book.
All code for seismic~ packages exists in a subversion repository hosted at IRIS DMC:
http://seiscode.iris.washington.edu/svn/mustang-dev/metrics/trunk
If you are going to be working on code to be contributed to the packages, you should see IRIS DMC staff about getting a user account to be able to check out the source code. The following instructions assume that you have a working version of the code and that you will be working with RStudio.
Code for the seismicRoll package is found in the metrics/seismicRoll/ directory.
The seismicRoll package is the easiest to update but probably the least likely to need an update. This package has been restructured to take advantage of automatic documentation features available through the RStudio IDE. It relies on the following three packages being installed before RStudio is opened: Rcpp, roxygen2 and knitr. With a recent version of RStudio, these may already be installed. You can check for this with:
installed.packages()[c('Rcpp','roxygen2','knitr'),1:3]## Package
## Rcpp "Rcpp"
## roxygen2 "roxygen2"
## knitr "knitr"
## LibPath
## Rcpp "/Library/Frameworks/R.framework/Versions/3.1/Resources/library"
## roxygen2 "/Library/Frameworks/R.framework/Versions/3.1/Resources/library"
## knitr "/Library/Frameworks/R.framework/Versions/3.1/Resources/library"
## Version
## Rcpp "0.11.6"
## roxygen2 "4.1.0"
## knitr "1.9"If you have previously checked out mustang-dev/metrics/trunk you should have a seismicRoll/ directory.
In RStudio you should “File > New Project… > Existing Directory” and enter the location of the seismicRoll/ directory.
Your RStudio pane that has the “Environment” and “History” tabs (by default in the upper right) should now have additional tabs labeled “SVN” and “Build”. The “SVN” tab allows you to work with version control while the “Build” tab helps to create the package.
We have to let RStudio know what build tools we want to use. For the seismicRoll package we will be using roxygen-style comments for automatic creation of documentation and the NAMESPACE file. To specify this you should open “Build > More… > Configure BuildTools…” and then:
Now we are ready to make changes.
Before making any changes to the package you should first edit the DESCRIPTION file and bump the version number.
The scripts in the R/ directory all contain roxygen-style comments which a processed by roxygen to automatically generate both the NAMESPACE file and all of the documentation in the man/ directory. Guidance on the use of roxygen comments us available in Documentation, in Karl Broman’s primer or in an RStudio document.
After making any changes to the roxygen-style comments you can click on “Build > Document” to regenerate files in the man/ directory. If you open up the .Rd documentation file in RStudio, the code editing page (upper left) will now have a “Preview” button that you can click to see how the documentation will look in RStudio. (Note that LateX style equations will not render properly.)
Note: Do not edit the RcppExports.R file which is generated automatically by Rcpp.
The seismicRoll package has source code written in C/C++ to dramatically speed up low level rolling- functions. This code relies on the Rcpp package to provide an interface between R and C/C++. An explanation of how to use Rcpp is beyond the scope of these notes but a good starting point would be Using R – Calling C code with Rcpp.
The source code for the rolling- functions is found in the src/source_files.cpp file. Wrapper files src/RcppExports.cpp R/RcppExports.R are generated automatically by running Rcpp::compileAttributes(verbose=TRUE) at the R command line. (Your working directory must be seismicRoll/.)
The quickest way to test your changes is to click on the “Build & Reload” button in the “Build” tab. This will build and reload the package in your existing R session. Once this is done you should be able to check the package documentation and run any examples or other R code to test the proper functioning of the package.
Although the RStudio “Build” tab as a “Test Package” option, we recommend that you get in the habit of creating a source package and then testing from the command line. First, create a source package with “Build > Build Source Package”. This will create seismicRoll_#.#.#.tar.gz at the same level as the seismicRoll/ directory. You should finish by running the package through a set of grueling, persnickety checks provided with R. At the command line just type:
R CMD check --as-cran seismicRoll_#.#.#.tar.gz
It is OK to have messages that say NOTE but you should deal with anything that says WARNING and of course all ERRORs.
The only tests available for the seismicRoll package are those in the Examples section of each documentation page. Most of these generate graphical output that should make it obvious whether the code is functioning properly or not.
Code for the IRISSeismic package is found in the metrics/seismic/ directory.
The IRISSeismic package is the workhorse package that defines new S4 objects IrisClient, Stream, Trace and TraceHeader. Because this package is not using roxygen-style comments, you should uncheck both “Use devtools…” and “Generate documentation…” in “Build > More… > Configure Build Tools…” as soon as you create the new project in RStudio.
Before making any changes to the package you should first edit the DESCRIPTION file and bump the version number.
This package has not been reconfigured to use roxygen-style comments in part because support for this style of commenting with S4 objects highly complex. Instead, this package uses hand-edited documentation pages in R documentation format. While hand-editing man pages, you can use the “Preview” button in RStudio to see how your page will be rendered. This will also display any error messages generated when formatting your .Rd file.
The src/ directory in the IRISSeismic package does not use the Rcpp package. Instead, it utilizes the older .Call function in R. The approach is fully described in the following blog posts:
At the moment, the src/ directory only contains the libmseed source code as well as the parseMiniSEED.c function. This, function, combined with functions defined in R/mseedWrappers.R provide access to libmseed methods. The only anticipated changes in the src/ directory would be updates to the libmseed source code.
Again, the quickest way to test your changes is to click on the “Build & Reload” button in the “Build” tab. Once built, you should run examples from the package documentation, many of which are configured to be skipped during automatic testing with R CMD check. (See dontrun{...} in some of the documentation files.)
You should again create a source package with “Build > Build Source Package”. This will create IRISSeismic_#.#.#.tar.gz at the same level as the seismic/ directory. You should finish by running the package through a set of grueling, persnickety checks provided with R. At the command line just type:
R CMD check --as-cran IRISSeismic_#.#.#.tar.gz
It is OK to have messages that say NOTE but you should deal with anything that says WARNING and of course all ERRORs.
The only tests available for the IRISSeismic package are those in the Examples section of each documentation page. Most of these generate graphical output that should make it obvious whether the code is functioning properly or not.
Code for the IRISMustangMetrics package is found in the metrics/seismicMetrics/ directory.
Because this package is not currently using roxygen-style comments, you should uncheck both “Use devtools…” and “Generate documentation…” in “Build > More… > Configure Build Tools…” as soon as you create the new project in RStudio.
Before making any changes to the package you should first edit the DESCRIPTION file and bump the version number.
This package has not been reconfigured to use roxygen-style comments in part because support for this style of commenting with S4 objects highly complex. Instead, this package uses hand-edited documentation pages in R documentation format.
This package currently has no compiled code.
The quickest way to test your changes is to click on the “Build & Reload” button in the “Build” tab. Once built, you should run examples from the package documentation, many of which are configured to be skipped during automatic testing with R CMD check.
You should create a source package with “Build > Build Source Package”. This will create IRISMustangMetrics_#.#.#.tar.gz at the same level as the seismicMetrics/ directory. You should finish by running the package through a set of grueling, persnickety checks provided with R. At the command line just type:
R CMD check --as-cran IRISMustangMetrics_#.#.#.tar.gz
It is OK to have messages that say NOTE but you should deal with anything that says WARNING and of course all ERRORs.
The only tests available for the IRISMustangMetrics package are those in the Examples section of each documentation page. Most of these generate graphical output that should make it obvious whether the code is functioning properly or not.
End-to-end functionality of the MUSTANG system and proper functioning of the seismic packages can be tested with code in the test/ directory.
The test/ directory contains a number of R scripts that were written in the process of developing the packages. They were designed to assess the proper functioning of specific algorithms. These scripts can be loaded into RStudio and run and should produce self-explanatory output graphics. They fall into three categories:
The MUSTANG system relies on stand-alone executable files that can be fired off by a controller. These .Rscript files contain a lot of top level code that decides which SNCLs should be retrieved before various metrics are applied. These files live at the metrics/trunk/ level.
If the seismic packages are installed, these .Rscript executables can be run at the command line. The test/EXAMPLES text file contains a large number of command line examples to use as tests along with comments describing what to expect from the test results. These examples will generate either XML or .RData output which can be inspected for proper functioning of the individual .Rscript which of course implies proper functioning of all the seismic~ packages.
Creating new Metrics < prev | next > Resources