all files updated for roxygen

.Rbuildignore

@@ -0,0 +1,2 @@
+^.*\.Rproj$
+^\.Rproj\.user$

.gitignore

@@ -11,3 +11,4 @@
 # produced vignettes
 vignettes/*.html
 vignettes/*.pdf
+.Rproj.user

EMMAgeo.Rproj

@@ -0,0 +1,18 @@
+Version: 1.0
+
+RestoreWorkspace: Default
+SaveWorkspace: Default
+AlwaysSaveHistory: Default
+
+EnableCodeIndexing: Yes
+UseSpacesForTab: Yes
+NumSpacesForTab: 2
+Encoding: UTF-8
+
+RnwWeave: Sweave
+LaTeX: pdfLaTeX
+
+BuildType: Package
+PackageUseDevtools: Yes
+PackageInstallArgs: --no-multiarch --with-keep.source
+PackageRoxygenize: rd,collate,namespace

R/GUI.R

@@ -0,0 +1,21 @@
+#' Start GUI for EMMA
+#' 
+#' This function starts a browser-based graphic user interface for EMMA.
+#' 
+#' @param ... further arguments to pass to \code{\link{runApp}}
+#' @author Michael Dietze
+#' @seealso \code{\link{runApp}}
+#' @examples 
+#' 
+#' \dontrun{
+#' # Start the GUI
+#' GUI()
+#' }
+#' 
+#' @export GUI
+GUI <- function(...) {
+  app <- shiny::runApp(system.file("shiny/EMMA", 
+                                   package = "EMMAgeo"), 
+                       launch.browser = TRUE, 
+                       ...)
+}

R/Mqs.uncertainty.R

@@ -105,50 +105,19 @@
 #' }
 #' 
 #' @export Mqs.uncertainty
-Mqs.uncertainty <-
-structure(function( # Function to estimate end-member scores uncertainty
-### The function uses either existing assemblages of end-member loadings or 
-### specified measures of centrality and dispersion as input for Monte 
-### Carlo runs to estimate the influence of different end-member loadings on
-### end-member scores. Likewise, the influence of the weight limit quantiles 
-### (lw) can be estimated.
-X,
-### Numeric matrix with m samples (rows) and n variables (columns).
-q,
-### Numeric scalar with the number of end-members to include. Only necessary
-### in combination with \code{Vqn} as matrix of user-defined end-member
-### loadings.
-lw,
-### Numeric vector with the weight tranformation limits (i.e. quantiles after
-### Klovan & Imbrie, 1971). If the parameter is of length 1, \code{lw} is assumed to
-### be a constant, if of length 2, \code{lw} defines either mean and
-### standard deviation or minimum and maximum, depending on the
-### value of \code{type.lw}.
-c,
-### Numeric scalar specifying the constant sum scaling parameter, e.g. 1, 
-### 100, 1000; default is 100.
-rotation = "Varimax",
-### Character scalar, rotation type, default is "Varimax" (cf. Dietze et 
-### al., 2012). One out of the rotations provided in GPArotation is 
-### possible (cf. \code{\link{rotations}}).
-Vqn,
-### Numeric matrix with existing unscaled end-member loadings. These may 
-### represent user-defined loadings (or mean loadings if \code{Vqn.sd} is  
-### specified). See example section for further information.
-Vqn.sd,
-### Numeric matrix with standard deviations of the mean unscaled end-member
-### loadings in \code{Vqn}.
-runs,
-### Logical scalar with the number of Monte Carlo runs to be performed,
-### default is 100.
-type.lw,
-### Character scalar with type of random lw value generation. Either
-### \code{"rnorm"} or \code{"runif"}, default is \code{"runif"}.
-autocorrelation
-### Numeric scalar optionally specifying the degree of autocorrelation among 
-### classes. Autocorrelation is realised as running mean of the specified 
-### length. Only odd values are allowed.
+Mqs.uncertainty <- function(
+  X,
+  q,
+  lw,
+  c,
+  rotation = "Varimax",
+  Vqn,
+  Vqn.sd,
+  runs,
+  type.lw,
+  autocorrelation
 ){
+
   ## test data consistency
   if(missing(Vqn) == FALSE &
     (missing(q) == TRUE |
@@ -224,81 +193,9 @@ autocorrelation
   ## rescale Mqs.mean to 100 %
   Mqs.mean <- Mqs.mean / apply(Mqs.mean, 1, sum)
 
-  ##value<< A list with numeric vector and matrix objects.
-  list(lw = lw.out, ##<< Randomised weight limit values.
-       Vqn = Vqn.out, ##<< Randomised unscaled end-member loadings.
-       Mqs = Mqs.out, ##<< Modelled end-member scores.
-       mean = Mqs.mean, ##<< Modelled end-member score means.
-       sd = Mqs.sd) ##<< Modelled end-member score standard deviations.
-  ##end<<
-
-  ##references<<
-  ## Dietze E, Hartmann K, Diekmann B, IJmker J, Lehmkuhl F, Opitz S, 
-  ## Stauch G, Wuennemann B, Borchers A. 2012. An end-member algorithm for 
-  ## deciphering modern detrital processes from lake sediments of Lake Donggi 
-  ## Cona, NE Tibetan Plateau, China. Sedimentary Geology 243-244: 169-180.\cr
-  ## Klovan JE, Imbrie J. 1971. An Algorithm and FORTRAN-IV Program for 
-  ## Large-Scale Q-Mode Factor Analysis and Calculation of Factor Scores. 
-  ## Mathematical Geology 3: 61-77.
-
-  ##seealso<<
-  ## \code{\link{test.robustness}}, \code{\link{test.parameters}}
-
-  ##keyword<<
-  ## EMMA
-}, ex = function(){
-  ## load example data set
-  data(X.artificial, envir = environment())
-
-  ## set model run parameters
-  q = 3 # set number of end-members, try 4 to see the difference!
-  Vqn <- EMMA(X.artificial, q)$Vqn # assign unscaled end-member loadings
-  Vqn.sd <- Vqn * 0.2 # assign a relative standard deviation of 20 %
-  lw.1 <- 0.2 # set lw to 0.2
-  lw.2 <- c(0.2, 0.08) # set lw to mean = 0.2 and sd = 0.08
-  runs <-  12 # senseless value to increase computation speed
-
-  ## EXAMPLE 1
-  ## Calculate Mqs uncertainty
-  M <- Mqs.uncertainty(X = X.artificial, 
-                       q = q, 
-                       lw = lw.1,
-                       runs = runs,
-                       Vqn = Vqn,
-                       Vqn.sd = Vqn.sd,
-                       type.lw = "rnorm",
-                       autocorrelation = 3)
-
-  ## Plot line-point graph with means and standard deviations
-  plot(NA,
-       xlim = c(1, nrow(X.artificial)),
-       ylim = c(0.5, q + 1),
-       main = "End-member scores with uncertainty")
-  for(i in 1:q) {
-    lines(1:nrow(X.artificial), M$mean[,i] - M$sd[,i] + i, col = i, lty = 2)
-    lines(1:nrow(X.artificial), M$mean[,i] + i, col = i, lwd = 2)
-    points(1:nrow(X.artificial), M$mean[,i] + i, col = i)
-    lines(1:nrow(X.artificial), M$mean[,i] + M$sd[,i] + i, col = i, lty = 2)
-  }
-
-  ## EXAMPLE 2
-  ## Calculate Mqs uncertainty
-  M <- Mqs.uncertainty(X = X.artificial, 
-                       q = q, 
-                       lw = lw.2,
-                       runs = runs,
-                       Vqn = Vqn,
-                       type.lw = "rnorm")
-
-  ## Plot point graph with error bars
-  plot(NA,
-       xlim = c(1, nrow(X.artificial)),
-       ylim = c(0.5, q + 1),
-       main = "End-member scores with uncertainty")
-  for(i in 1:q) {
-    points(1:nrow(X.artificial), M$mean[,i] + i, pch = 3, col = i)
-    arrows(1:nrow(X.artificial), M$mean[,i] - M$sd[,i] + i, 
-           1:nrow(X.artificial), M$mean[,i] + M$sd[,i] + i, 
-           code = 3, angle = 90, length = 0.05, col = i)
-  }
-})
+  return(list(lw = lw.out,
+              Vqn = Vqn.out,
+              Mqs = Mqs.out,
+              mean = Mqs.mean,
+              sd = Mqs.sd))
+}

R/check.data.R

@@ -32,28 +32,14 @@
 #' check.data(X = X.artificial, q = 6, lw = seq(0, 0.2, 0.01), c = 1)
 #' 
 #' @export check.data
-check.data <-
-structure(function # Function to check data consistency.
-### The input data matrix (X), number of end-members (q),
-### weight transformation limits (lw) and constant sum scaling
-### parameter (c) are checked for consistency. This includes checking
-### for absence of missing values, columns containing only zero-values and 
-### for numeric data type of variables. Furthermore, a check tests if 
-### lw is below the maximum possible value, preventing numerical instability 
-### prior to factor rotation.
-(X, 
-### Numeric matrix with m samples (rows) and n variables (columns).
-q, 
-### Numeric scalar with number of end-members to be modelled.
-lw,
-### Numeric scalar or vector specifying the weight transformation limit, i.e. 
-### quantile.
-c,
-### Numeric scalar specifying the constant sum scaling parameter, e.g. 1, 
-### 100, 1000.
-invisible = TRUE
-### Logical scalar setting visibility option.
+check.data <- function(
+  X, 
+  q, 
+  lw,
+  c,
+  invisible = TRUE
 ){
+
   ## create result vector
   result <- NA
 
@@ -171,23 +157,4 @@ invisible = TRUE
 
   ## return result
   return(result[2:length(result)])
-  ### Character vector with test results.
-
-  ##references<<
-  ## Dietze E, Hartmann K, Diekmann B, IJmker J, Lehmkuhl F, Opitz S, 
-  ## Stauch G, Wuennemann B, Borchers A. 2012. An end-member algorithm for 
-  ## deciphering modern detrital processes from lake sediments of Lake Donggi 
-  ## Cona, NE Tibetan Plateau, China. Sedimentary Geology 243-244: 169-180.
-
-  ##seealso<<
-  ## \code{\link{EMMA}}
-
-  ##keyword<<
-  ## EMMA
-}, ex = function(){
-  ## load example data set
-  data(X.artificial, envir = environment())
-
-  ## perform data set check
-  check.data(X = X.artificial, q = 6, lw = seq(0, 0.2, 0.01), c = 1)
-  })
+}

R/convert.units.R

@@ -25,15 +25,11 @@
 #' convert.units(mu = mu)
 #' 
 #' @export convert.units
-convert.units <-
-structure(function(# Function to convert between phi and micrometers.
-### The function converts values from the phi-scale to the 
-### micrometer-scale and vice versa.
-phi,
-### Numeric vector with grain-size class values in phi to be converted.
-mu
-### Numeric vector with grain-size class values in micrometres to be converted.
+convert.units <- function(
+  phi,
+  mu
 ){
+
   if(missing(mu) == TRUE){
     ## convert phi to mu
     result <- 1000 * 2^-phi
@@ -44,22 +40,4 @@ mu
 
   ## return result
   return(result)
-  ### Numeric vector with converted grain-size class values.
-
-  ##seealso<<
-  ## \code{\link{interpolate.classes}}
-
-  ##keyword<<
-  ## EMMA
-
-}, ex = function(){
-  ## generate phi-values
-  phi <- -2:5
-
-  ## convert and show phi to mu
-  mu  <- convert.units(phi = phi)
-  mu
-
-  ## convert and show phi to mu
-  convert.units(mu = mu)
-})
+}

R/create.EM.R

@@ -45,25 +45,14 @@
 #' lines(phi, EMa.2, col = "red")
 #' 
 #' @export create.EM
-create.EM <-
-structure(function # Function to create grain-size-distributions.
-### This function allows to create artificial grain-size-compositions. One
-### such "artificial end-member loading" may be composed of one or more
-### superimposed normal distributions.
-(p1,
-###  Numeric vector with means of normal distributions, i.e. mode positions.
-p2, 
-### Numeric vector with standard deviations of normal distributions, i.e.
-### mode width.
-s, 
-### Numeric vector with relative proportions of each mode, i.e. relative 
-### mode height.
-boundaries, 
-### Numeric vector of length 2 with class boundaries (i.e. \code{c(lower 
-### boundary, upper boundary)}).
-n
-### Numeric scalar with number of classes, i.e. resolution of the end-member.
+create.EM <- function(
+  p1,
+  p2, 
+  s, 
+  boundaries, 
+  n
 ){
+
   ## create result matrix
   EM <- matrix(nrow = length(p1), ncol = n)
 
@@ -79,37 +68,4 @@ n
   EM <- as.vector(EM / sum(EM))
 
   return(EM)
-  ### Numeric vector with normalised end-member loadings, consisting of 
-  ### the mixed normal distributions according to the input parameters.
-
-  ##details<<
-  ## When mixing individual artificial end member loadings, these should 
-  ## span over the same classes. Hence, \code{boundaries} and \code{n} 
-  ## should be the same for all end-member loadings. The function builds  
-  ## composites of individual normal distributions. Each distribution is
-  ## scaled according to \code{s}. Finally the distribution is scaled to
-  ## 100 %.
-
-  ##seealso<<
-  ## \code{\link{mix.EM}}
-
-  ##keyword<<
-  ## EMMA
-}, ex = function(){
-  ## set lower and upper class boundary, number of classes and class units
-  boundaries <- c(0, 11)
-  n <- 40
-  phi <- seq(from = boundaries[1], 
-             to = boundaries[2], 
-             length.out = n)
-
-  ## create two artificial end-member loadings
-  EMa.1 <- create.EM(p1 = c(2, 5), p2 = c(1, 0.8), s = c(0.7, 0.3), 
-                     boundaries = boundaries, n = n)
-  EMa.2 <- create.EM(p1 = c(4, 7), p2 = c(1.1, 1.4), s = c(0.5, 0.5),
-                     boundaries = boundaries, n = n)
-
-  ## plot the two artificial end-member loadings
-  plot(phi, EMa.1, type = "l")
-  lines(phi, EMa.2, col = "red")
-})
+}