R/gridboxrange.R

In cmsafops: Tools for CM SAF NetCDF Data

#'Determine ranges of selected grid boxes
#'
#'The function determines ranges of selected grid boxes from data of a single 
#'CM SAF NetCDF input file.
#'
#'@param var Name of NetCDF variable (character).
#'@param lonGrid INTEGER Number of grid boxes in x direction
#'@param latGrid INTEGER Number of grid boxes in y direction
#'@param infile Filename of input NetCDF file. This may include the directory
#'  (character).
#'@param outfile Filename of output NetCDF file. This may include the directory
#'  (character).
#'@param nc34 NetCDF version of output file. If \code{nc34 = 3} the output file will be
#'  in NetCDFv3 format (numeric). Default output is NetCDFv4.
#'@param overwrite logical; should existing output file be overwritten?
#'@param verbose logical; if TRUE, progress messages are shown
#'@param nc Alternatively to \code{infile} you can specify the input as an
#'  object of class `ncdf4` (as returned from \code{ncdf4::nc_open}).
#'
#'@return A NetCDF file including a time series of ranges of selected grid boxes is written.
#'@export
#'
#'@family grid boxes statistics
#'
#' @examples
#'## Create an example NetCDF file with a similar structure as used by CM
#'## SAF. The file is created with the ncdf4 package.  Alternatively
#'## example data can be freely downloaded here: <https://wui.cmsaf.eu/>
#'
#'library(ncdf4)
#'
#'## create some (non-realistic) example data
#'lon <- seq(5, 15, 0.5)
#'lat <- seq(45, 55, 0.5)
#'time <- seq(as.Date("2000-03-01"), as.Date("2000-05-31"), "month")
#'origin <- as.Date("1983-01-01 00:00:00")
#'time <- as.numeric(difftime(time, origin, units = "hour"))
#'data <- array(250:350, dim = c(21, 21, 3))
#'
#'## create example NetCDF
#'x <- ncdim_def(name = "lon", units = "degrees_east", vals = lon)
#'y <- ncdim_def(name = "lat", units = "degrees_north", vals = lat)
#'t <- ncdim_def(name = "time", units = "hours since 1983-01-01 00:00:00",
#'              vals = time, unlim = TRUE)
#'var1 <- ncvar_def("SIS", "W m-2", list(x, y, t), -1, prec = "short")
#'vars <- list(var1)
#'ncnew_1 <- nc_create(file.path(tempdir(), "CMSAF_example_file.nc"), vars)
#'
#'ncvar_put(ncnew_1, var1, data)
#'
#'ncatt_put(ncnew_1, "lon", "standard_name", "longitude", prec = "text")
#'ncatt_put(ncnew_1, "lat", "standard_name", "latitude", prec = "text")
#'nc_close(ncnew_1)
#'
#'## Determine the ranges of selected grid boxes of the example CM SAF NetCDF file and write
#'## the output to a new file.
#'gridboxrange(var = "SIS", lonGrid = 4, latGrid = 4, infile = file.path(tempdir(), 
#'  "CMSAF_example_file.nc"), outfile = file.path(tempdir(), 
#'  "CMSAF_example_file_gridboxrange.nc"))
#'
#'unlink(c(file.path(tempdir(), "CMSAF_example_file.nc"), file.path(tempdir(), 
#'  "CMSAF_example_file_gridboxrange.nc")))
gridboxrange <- function(var, lonGrid, latGrid, infile, outfile, nc34 = 4, overwrite = FALSE, verbose = FALSE, nc = NULL) {
  gridboxx_wrapper(3, var, lonGrid, latGrid, infile, outfile, nc34, overwrite, verbose, nc = nc)
}