Update docs, change version to 1.0.0

Author: rplzzz

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: fldgen
 Type: Package
 Title: Generate Temperature Fields with Spatial and Temporal Correlation
-Version: 0.5.0
+Version: 1.0.0
 Authors@R: person("Robert", "Link", email = "[email protected]", role = c("aut", "cre"))
 Description: Provides functions to learn the spatial and temporal correlation of the
     variability in an ESM and generate random temperature fields with equivalent

R/fldgen.R

@@ -6,31 +6,22 @@
 #'
 #' @section Example:
 #'
-#' The data used in this example can be found in \code{tests/testthat/data}
+#' The data used in this example can be found in \code{system.file('extdata', package='fldgen')}
 #'
 #' \verb{
 #' library(fldgen)
 #'
-#' griddata <- read.temperatures('data/tann1.nc')
-#' tgav <- readtgav('data/wgttann1.nc')
-#' pscl <- pscl_analyze(griddata$tas, tgav)
-#' reof <- eof_analyze(pscl$r, griddata$tgop)
-#' Fx <- mvfft(reof$x)                     # Fourier transforms of the coordinates
-#'                                         # in the orthogonal basis.
-#' Fxmag <- abs(Fx)
-#' Fxphase <- atan2(Im(Fx), Re(Fx))
+#' emulator <- train('extdata/tann1.nc')
+#'
 #' tempgrids <- list()                     # Empty list to hold the temperature
-#'                                         # realizations we are about to create.
+#'                                        # realizations we are about to create.
 #' length(tempgrids) <- 4
 #'
 #' ##  Run with the phases of the actual time series
-#' meanfield <- pscl_apply(pscl, tgav)
-#' tempgrids[[1]] <- reconst_fields(reof$rotation, mkcorrts(Fxmag, Fxphase) , meanfield)
+#' meanfield <- pscl_apply(emulator$pscl, emulator$tgav)
+#' tempgrids[[1]] <- reconst_fields(emulator$reof$rotation, mkcorrts(emulator) , meanfield)
 #' ## Run the rest with random phases
 #' for(i in 2:4)
-#'     ## If you wanted to use a smaller number of PCs, say 50, you could
-#'     ## use reof$rotation[,1:50] and Fxmag[,1:50] in the next call.
-#'     tempgrids[[i]] <- reconst_fields(reof$rotation, mkcorrts(Fxmag), meanfield)
-#' }
-#'
+#'     tempgrids[[i]] <- reconst_fields(emulator$reof$rotation, mkcorrts(emulator), meanfield)
+#'}
 "_PACKAGE"

R/train.R

@@ -21,7 +21,8 @@
 #' returned object.  This is for the your information only; none of the code
 #' here does anything with the recorded filenames.  You have the choice of
 #' recording either absolute filenames (useful for determining exactly which
-#' dataset was used) or relative filenames (useful if you might distribute a
+#' dataset was used, if you have a lot of similarly named files) or relative
+#' filenames (useful if you might distribute a
 #' saved model to other users who might not have the same directory structure as
 #' you).
 #'

README.md

@@ -5,36 +5,43 @@
 
 
 
-This package rovides functions to learn the spatial and temporal
+The `fldgen` package rovides functions to learn the spatial and temporal
 correlation of the variability in an ESM and generate random
 temperature fields with equivalent properties.
 
+## Installation
+
+The easiest way to install `fldgen` is using `install_github` from the
+`devtools` package.
+```R
+install_github('JGCRI/fldgen', ref='v1.0.0', build_vignettes=TRUE)
+```
+
 ## Example
 
-The data used in this example can be found in `tests/testthat/data`.
+The data used in this example are installed with the package.  They
+can be found in `system.file('extdata', package='fldgen')`.
 
 ```R
 library(fldgen)
 
-griddata <- read.ncdf('data/tann1.nc')
-tgav <- readtgav('data/wgttann1.nc')
-pscl <- pscl_analyze(griddata$tas, tgav)
-reof <- eof_analyze(pscl$r, griddata$tgop)
-Fx <- mvfft(reof$x)                     # Fourier transforms of the coordinates
-                                        # in the orthogonal basis.
-Fxmag <- abs(Fx)
-Fxphase <- atan2(Im(Fx), Re(Fx))
+emulator <- train('extdata/tann1.nc')
+
 tempgrids <- list()                     # Empty list to hold the temperature
                                         # realizations we are about to create.
 length(tempgrids) <- 4
 
 ##  Run with the phases of the actual time series
-meanfield <- pscl_apply(pscl, tgav)
-tempgrids[[1]] <- reconst_fields(reof$rotation, mkcorrts(Fxmag, Fxphase) , meanfield)
+meanfield <- pscl_apply(emulator$pscl, emulator$tgav)
+tempgrids[[1]] <- reconst_fields(emulator$reof$rotation, mkcorrts(emulator) , meanfield)
 ## Run the rest with random phases
 for(i in 2:4)
-    ## If you wanted to use a smaller number of PCs, say 50, you could
-    ## use reof$rotation[,1:50] and Fxmag[,1:50] in the next call.
-    tempgrids[[i]] <- reconst_fields(reof$rotation, mkcorrts(Fxmag), meanfield)
+    tempgrids[[i]] <- reconst_fields(emulator$reof$rotation, mkcorrts(emulator), meanfield)
+
+```
 
+A more detailed example can be found in the tutorial vignette included
+with the package.
+```R
+vignette('tutorial','fldgen')
 ```

fldgen.Rproj

@@ -18,4 +18,4 @@ StripTrailingWhitespace: Yes
 BuildType: Package
 PackageUseDevtools: Yes
 PackageInstallArgs: --no-multiarch --with-keep.source
-PackageRoxygenize: rd,collate,namespace
+PackageRoxygenize: rd,collate,namespace,vignette

man/fldgen-package.Rd

@@ -4,7 +4,7 @@ author: "Robert Link"
 date: "`r Sys.Date()`"
 output: rmarkdown::html_vignette
 vignette: >
-  %\VignetteIndexEntry{Vignette Title}
+  %\VignetteIndexEntry{Fldgen Tutorial}
   %\VignetteEngine{knitr::rmarkdown}
   %\VignetteEncoding{UTF-8}
 ---
@@ -55,10 +55,15 @@ datadir <- system.file('extdata', package='fldgen')
 
 ### One-step emulator training
 
-You can do the read and analyze steps below in a single command by running
+You can do the read and analyze steps below in a single command by running:
 ```
-emulator <- train(file.path(datadir, 'tann1.nc'))
+infile <- file.path(datadir, 'tann1.nc')
+emulator <- train(infile)
 ```
+If you want to use multiple ESM runs for the training, you can either pass
+`train` a list of filenames, or you can give it the name of a directory, in
+which case it will use all of the netCDF files it finds there.
+
 If you use this (recommended) method, then you can skip directly to [Generating 
 fields].  For users that wish to customize the training process, the next two 
 sections describe what is happening inside the `train` function and show how to
@@ -130,7 +135,7 @@ emulator <- fldgen_object(griddata, tgav, pscl, reof, Fx, phasecoef, filename)
 
 Now we're ready to generate fields.  We'll do `r ngen` fields in this example. 
 The first one will be a reconstruction of the original input.  The other three
-will new fields.
+will be new fields.
 
 ```{r genfields}
 tempgrids <- list()
@@ -140,13 +145,11 @@ length(tempgrids) <- ngen
 meanfield <- pscl_apply(pscl, tgav)
 
 ## First field will have the same phases as the input ESM data
-tempgrids[[1]] <- suppressMessages(         # mkcorrts emits a bunch of status messages that we don't want here.
-    reconst_fields(reof$rotation, mkcorrts(emulator, Fxphase), meanfield))
+tempgrids[[1]] <- reconst_fields(reof$rotation, mkcorrts(emulator, Fxphase), meanfield)
 
 ## Other fields will have random phases
 for(i in 2:ngen) {
-  tempgrids[[i]] <- suppressMessages(       # don't want the status messages
-      reconst_fields(reof$rotation, mkcorrts(emulator), meanfield))
+  tempgrids[[i]] <- reconst_fields(reof$rotation, mkcorrts(emulator), meanfield)
 }
 
 ## Subtract off the mean field.  Save these because we will want to use them later