Merge pull request #47 from biometry/develop

Develop

rLPJGUESS/DESCRIPTION

@@ -1,11 +1,13 @@
 Package: rLPJGUESS
 Title: A R package that wraps the LPJ-GUESS 3.1 model
-Version: 1.1.0
+Version: 1.1.1
+Date: 2018-07-03
 Authors@R: c(person("Florian", "Hartig", , "florian.hartig@biom.uni-freiburg.de", role = c("aut")),
             person("Maurizio", "Bagnara", , "maurizio.bagnara@biom.uni-freiburg.de", role = c("aut", "cre")),
             person("Ramiro", "Silveyra Gonzalez", , "rasilgon@gmail.com", role = c("aut")))
-Description: The rLPJGUESS package provides functions to run LPJ-GUESS within R. It
-    also allows to parallelize the model execution on personal laptops and on HPC.
+Description: The rLPJGUESS package provides functions to run LPJ-GUESS within
+    R. It also allows to parallelize the model execution on personal laptops and on
+    HPC clusters.
 Depends:
     R (>= 3.1.0)
 Imports:
@@ -17,7 +19,7 @@ Suggests:
     rmarkdown (>= 1.3),
     testthat (>= 1.0.2),
     Rmpi (>= 0.6-5)
-License: file LICENSE
+License: GPL-3
 LazyData: true
 VignetteBuilder: knitr
-RoxygenNote: 6.0.1
+RoxygenNote: 5.0.1

rLPJGUESS/NEWS

@@ -0,0 +1,5 @@
+
+rLPJGUESS 1.1.1
+
+- various smaller fixes
+- improved unit tests

rLPJGUESS/R/LPJDataClass.R

@@ -9,6 +9,7 @@
 #' }
 #' @keywords rLPJGUESS
 #' @export
+#' @example /inst/examples/LPJDataClassHelp.R
 #' @author Ramiro Silveyra Gonzalez
 setClass("LPJData",
          representation(

rLPJGUESS/R/LPJSetupClass.R

@@ -16,6 +16,7 @@
 #' }
 #' @keywords rLPJGUESS
 #' @export
+#' @example /inst/examples/LPJSetupClassHelp.R
 #' @author Ramiro Silveyra Gonzalez
 setClass("LPJSetup",
          representation(

rLPJGUESS/R/callLPJ.R

@@ -8,13 +8,12 @@
 #'  If not provided, package templates will be used
 #' @param mode a character string indicating whether using cru or cf data
 #' @return none
+#' @details Please note that this function is integrated in \code{\link{runLPJ}}.
 #' @keywords rLPJGUESS
 #' @export
 #' @author  Ramiro Silveyra Gonzalez, Maurizio Bagnara, Florian Hartig
 #' @note Based an older code of Istem Fer, Uni Potsdam
-#' @examples \dontrun{
-#' callLPJ("/home/LPJrun", "/home/LPJrun/runDirectory1", "global_cru.ins")
-#' }
+#' @example /inst/examples/callLPJHelp.R
 callLPJ <- function(mainDir, runDir , template2, mode){
   #----------------------------------------------------------------------------#
   # CHECK INPUTS AND EXIT IF ANY ERROR

rLPJGUESS/R/exitMPI.R

@@ -10,9 +10,7 @@
 #' The function is a wrapper of mpi.finalize from the Rmpi package. Check the
 #' package manual for futher advise on using mpi.finalize and mpi.quit.
 #'
-#' @examples \dontrun{
-#' exitMPI()
-#'  }
+#' @example /inst/examples/exitMPIHelp.R
 exitMPI <- function(){
   if (is.loaded("mpi_initialize")){
     if (Rmpi::mpi.comm.size(comm =1) > 1){

rLPJGUESS/R/getData.R

@@ -1,7 +1,7 @@
 #' @title A function to process LPJ-GUESS outputs
 #' @description This function reads the ASCII outputs produced by LPJ-GUESS.
 #' It takes a list of output types (typeList) and finds them in the specified path.
-#' The data is stored in a data class object: LPJData. If processing is TRUE,
+#' The data is stored in a data class object: \linkS4class{LPJData}. If processing is TRUE,
 #' the data will be stored as zoo time series. Ohterwise, as data frames.
 #' @param x a character string indicating path to the output files
 #' @param typeList  a character vector with the outputs to be analyzed.
@@ -11,18 +11,17 @@
 #' the processed outputs of the model (optional)
 #' @param processing a boolean indicating whether output files will be turned
 #'  into time series (default is FALSE)
-#' @return the processed data returned in a S4 Class: LPJData Class
+#' @return the processed data returned in a S4 Class: \linkS4class{LPJData} class
+#' @details Please note that this function is integrated in \code{\link{runLPJ}},
+#' which alread returns the data as a \linkS4class{LPJData} object.
 #' @seealso \linkS4class{LPJData}, \url{https://cran.r-project.org/web/packages/zoo/zoo.pdf}
 #' @author Ramiro Silveyra Gonzalez, Maurizio Bagnara, Florian Hartig
 #' @note Based on an older code of Joerg Steinkamp
 #' @details To convert the outputs into zoo time series is only supported when running the
-#' model for one grid cell. For running  LPJ-GUESS for several grid cells, please set
+#' model for one grid cell. When running  LPJ-GUESS for several grid cells, please set
 #' processing to FALSE.
 #' @export
-#' @examples \dontrun{
-#' LPJout <- getLPJData( typeList = c("aaet",  "cflux","lai", "nflux"),
-#'           "~/path/to/output/files", runInfo = list(parameter1 = 0.5, grid = 1))
-#' }
+#' @example /inst/examples/getDataHelp.R
 getLPJData <- function(x, typeList = NULL,  runInfo=NULL, processing = FALSE){
                     #, fun = NULL){
   # other options which could be included:

rLPJGUESS/R/getDesign.R

@@ -6,9 +6,7 @@
 #' @return a list or a matrix with design parameter names and their values
 #' @export
 #' @author Ramiro Silveyra Gonzalez, Maurizio Bagnara
-#' @examples \dontrun{
-#' parameterList <- getParameterList("global")
-#' }
+#' @example /inst/examples/getDesignHelp.R
 getDesign <- function(scale, list =  F){
   if ( is.null(scale) || scale != "global" & scale != "europe"){
     stop("Please provide a valid scale: global or europe")

rLPJGUESS/R/getParameterList.R

@@ -6,10 +6,10 @@
 #' as a list, otherwise as a matrix.
 #' @return a list or a matrix with parameter names and their values
 #' @export
+#' @details To obtain the parameters used in previous runs, see \code{\link{getRunInfo}}.
+#' @seealso \code{\link{runLPJ}}, \code{\link{getRunInfo}}
 #' @author Ramiro Silveyra Gonzalez, Maurizio Bagnara
-#' @examples \dontrun{
-#' parameterList <- getParameterList("global")
-#' }
+#' @example /inst/examples/getParameterListHelp.R
 getParameterList <- function(scale, list =  TRUE){
   if ( is.null(scale) || scale != "global" & scale != "europe"){
     stop("Please provide a valid scale: global or europe")

rLPJGUESS/R/getRunInfo.R

@@ -1,24 +1,14 @@
 #' @title A get runInfo data
-#' @description  This function reads the runLPj outputs stored in the runInfoDir
-#' and returns as a list, with the same structure as the runLPJ outputs. Additionally,
-#' allows to retrieve the parameters from the runInfoDir files or the runLPJ outputs.
+#' @description  This function reads the \code{\link{runLPJ}} outputs stored in the runInfo file. Additionally,
+#' allows to retrieve the parameters from the runInfoDir files.
 #' @param x a character string indicating the absolute path to the runInfoDir folder or
-#' a R object produced by runLPJ
+#' a R object produced by \code{\link{runLPJ}}
 #' @param parameters a character boolean to specify whether to return the parameters
-#' instead of the LPJData objects
+#' instead of the \linkS4class{LPJData} objects
+#' @seealso \code{\link{runLPJ}}, \linkS4class{LPJData}
 #' @export
 #' @author Ramiro Silveyra Gonzalez
-#' @examples \dontrun{
-#' # recover the data from the runInfo folder
-#' result <- getRunInfo("/some/absolute/path/runInfo_2016_08_11_121507")
-#'
-#' # recover only the paramaters from the runInfo folder
-#' parameters <- getRunInfo("/some/absolute/path/runInfo_2016_08_11_121507", parameters =T)
-#'
-#' # recover only the parameters from the result
-#' parameters <- getRunInfo(result, parameters =T)
-#'
-#' }
+#' @example /inst/examples/getRunInfoHelp.R
 getRunInfo <- function(x, parameters = F){
 
   if(parameters){
@@ -64,7 +54,7 @@ readRunInfo <- function(x){
   if (length(outputs)==0 || !grepl("RData", outputs) & !grepl("Rdata", outputs) ){stop("runDirInfo folder is empty")}
 
   result <- try(lapply(outputs, function(x){
-                LPJout <- loadRData
+                LPJout <- loadRData(x)
               }), F)
   if ('try-error' %in% class(result)){ stop("Invalid runDirInfo folder")  }
 

rLPJGUESS/R/getTemplate.R

@@ -7,10 +7,7 @@
 #' @export
 #' @keywords rLPJGUESS
 #' @author Ramiro Silveyra Gonzalez, Maurizio Bagnara, Florian Hartig
-#' @examples \dontrun{
-#' template <- getTemplate("global.ins")
-#' getTemplate("global.ins", "/home/LPJTemplates/")
-#' }
+#' @example /inst/examples/getTemplateHelp.R
 getTemplate <- function(type, outputDir = NULL){
   if (is.null(type) || type != "global" & type != "global_cf" & type != "global_cru"
       &  type != "europe" &  type != "europe_cf" &  type != "europe_cru"){

rLPJGUESS/R/getTypeList.R

@@ -3,9 +3,7 @@
 #' @return a character vector with the default output types
 #' @export
 #' @author Ramiro Silveyra Gonzalez, Maurizio Bagnara
-#' @examples \dontrun{
-#' typelist <- getTypeList()
-#' }
+#' @example /inst/examples/getTypeListHelp.R
 getTypeList <- function(){
   tmp <- typelist.default
   return(tmp)

rLPJGUESS/R/plotLPJData.R

@@ -1,23 +1,24 @@
 #' @title A plot function for LPJData objects
-#' @description  This function reads data from a LPJData object and plots the
+#' @description  This function reads data from a \linkS4class{LPJData} object and plots the
 #'  variables against time. If the save.plots is set to TRUE, plots are saved in the output folder.
-#' @param x a LPJData object.
+#' @param x a \linkS4class{LPJData} object
 #' @param outDir a character string indicating the folder where the plots will be
 #' saved, if save.plot set to TRUE
 #' @param save.plots a boolean indicating whether the plots are saved in the outDir.
-#'  Plots will be saved as pdf
+#'  Plots will be saved as pdf.
 #' @param typeList a character vector with the outputs to be plotted
 #' @param prefix a character string specifying the prefix to be added to the plots files.
 #' Only relevant if saving plots is TRUE
-#' @return plots for data types included in typeList. The grid cells will be plotted independently
-#' @seealso \url{https://cran.r-project.org/web/packages/zoo/zoo.pdf}
+#' @return time series plots for the data types included in typeList.
+#' The grid cells will be plotted independently.
+#' @details Please note that this function is integrated in \code{\link{runLPJ}}.
+#' The call to \code{\link{runLPJ}} can plot straigthaway the outputs (see examples below).
+#' @seealso \code{\link{runLPJ}}, \linkS4class{LPJData},
+#'  \url{https://cran.r-project.org/web/packages/zoo/zoo.pdf}
 #' @export
 #' @keywords rLPJGUESS
 #' @author Ramiro Silveyra Gonzalez, Maurizio Bagnara, Florian Hartig
-#' @examples \dontrun{
-#' plotLPJData(data, typeList = c("aaet", "lai"),
-#'  outDir = "/runDir/outDir", save.plots = FALSE)
-#' }
+#' @example /inst/examples/plotLPJDataHelp.R
 plotLPJData <- function(x, typeList = NULL, outDir= NULL, save.plots = FALSE, prefix = ""){
 
   # checking input parameters

rLPJGUESS/R/rLPJGUESS-package.R

@@ -26,7 +26,7 @@
 #'  \item \code{\link{getParameterList}} To obtain the parameter default values
 #'  \item \code{\link{getDesign}} To obtain the default desgin
 #'  \item \code{\link{getTypeList}} To obtain the default output model types
-#'  \item \code{\link{getRunInfo}} To recover data or parameters from the runInfoDir
+#'  \item \code{\link{getRunInfo}} To recover data or parameters from the runInfo file
 #' }
 #'
 #' @section IV. Other functions: \itemize{
@@ -35,6 +35,13 @@
 #'  \item \code{\link{writeTemplate}} To write LPJ-GUESS templates
 #'
 #' }
+#' @section V. S4 classes: \itemize{
+#'  \item \linkS4class{LPJData} To store both LPJ-GUESS outputs
+#' and run information
+#'  \item  \linkS4class{LPJSetup} To store the configuration for parallel
+#' runs
+#' }
+#'
 #'
 #' @author Except where indicated otherwise, the functions in this package were
 #'  written by Ramiro Silveyra Gonzalez, Maurizio Bagnara and Florian Hartig