krigR: (multi-core) Kriging

In ErikKusch/KrigR: Downloading, Aggregating, and Kriging of ECMWF CDS-Data

(multi-core) Kriging

Description

This function statistically downscales input data using covariate data and the kriging methodology. The function can be run in two ways:

1. By Itself: Use the arguments Data, Covariates_coarse, Covariates_fine when you already have raster files for your data which is to be downscaled as well as covariate raster data.

2. From Scratch: Use the arguments Variable, Type, DataSet, DateStart, DateStop, TResolution, TStep, Extent, Dir, FileName, API_Key, API_User, and arget_res. By doing so, krigR will call the functions download_ERA() and download_DEM() for one coherent kriging workflow. Note that this process does not work when targetting UERRA data.

Use optional arguments such as Dir, FileName, Keep_Temporary, SingularTry, KrigingEquation and Cores for ease of use, substitution of non-GMTED2010 covariates, and parallel processing.

Usage

krigR(
  Data = NULL,
  Covariates_coarse = NULL,
  Covariates_fine = NULL,
  KrigingEquation = "ERA ~ DEM",
  Cores = detectCores(),
  Dir = getwd(),
  FileName,
  Keep_Temporary = TRUE,
  SingularTry = 10,
  Variable,
  PrecipFix = FALSE,
  Type = "reanalysis",
  DataSet = "era5-land",
  DateStart,
  DateStop,
  TResolution = "month",
  TStep = 1,
  FUN = "mean",
  Extent,
  Buffer = 0.5,
  ID = "ID",
  API_Key,
  API_User,
  Target_res,
  Source = "USGS",
  nmax = Inf,
  TryDown = 10,
  verbose = TRUE,
  TimeOut = 36000,
  SingularDL = FALSE,
  ...
)

Arguments

Data	Raster file which is to be downscaled.
Covariates_coarse	Raster file containing covariates at training resolution.
Covariates_fine	Raster file containing covariates at target resolution.
KrigingEquation	Formula or character string specifying which covariates to use and how. Layer names in Covariates_coarse and Covariates_fine need to match Parameters in this formula. Needs to start with "X ~ ". X can read anything you like.
Cores	Numeric. How many cores to use. If you want output to your console during the process, use Cores == 1. Parallel processing is carried out when Cores is bigger than 1. Default is detecting all cores of your machine.
Dir	Optional. Directory specifying where to place final kriged product. Default is current working directory.
FileName	Optional. A file name for the netcdf produced. Default is a combination parameters in the function call.
Keep_Temporary	Logical, whether to delete individual kriging products of layers in Data after processing. Default is TRUE.
SingularTry	Numeric. How often to try kriging of each layer of the input. This usually gets around issues of singular covariance matrices in the kriging process, but takes some time. Default is 10
Variable	Optional, calls download_ERA(). ERA5(Land)-contained climate variable.
PrecipFix	Optional. Era5(-land) total precipitation is recorded in cumulative steps per hour from the 00:00 time mark per day. Setting PrecipFix to TRUE converts these into records which represent the total precipitation per hour. Monthly records in Era5(-land) express the average daily total precipitation. Setting this argument to TRUE multiplies monthly records by the number of days per the respective month(s) to get to total precipitation records instead of average. Default is FALSE.
Type	Optional. Whether to download reanalysis ('reanalysis') or ensemble ('ensemble_members', 'ensemble_mean', or 'ensemble_spread') data. Passed on to download_ERA.
DataSet	Optional. Which ERA5 data set to download data from. 'era5' or 'era5-land'. Passed on to download_ERA.
DateStart	Optional. Date ('YYYY-MM-DD') at which to start time series of downloaded data. Passed on to download_ERA.
DateStop	Optional. Date ('YYYY-MM-DD') at which to stop time series of downloaded data. Passed on to download_ERA.
TResolution	Optional. Temporal resolution of final product. hour', 'day', 'month'. Passed on to download_ERA.
TStep	Optional. Which time steps (numeric) to consider for temporal resolution. Passed on to download_ERA.
FUN	Optional. A raster calculation argument as passed to ‘raster::stackApply()'. This controls what kind of data to obtain for temporal aggregates of reanalysis data. Specify ’mean' (default) for mean values, 'min' for minimum values, and 'max' for maximum values, among others.
Extent	Optional, download data according to rectangular bounding box. specify as extent() object or as a raster, a SpatialPolygonsDataFrame object, or a data.frame object. If Extent is a SpatialPolygonsDataFrame, this will be treated as a shapefile and the output will be cropped and masked to this shapefile. If Extent is a data.frame of geo-referenced point records, it needs to contain Lat and Lon columns as well as a non-repeating ID-column. Passed on to download_ERA and download_DEM.
Buffer	Optional. Identifies how big a rectangular buffer to draw around points if Extent is a data frame of points. Buffer is expressed as centessimal degrees. Passed on to download_ERA and download_DEM.
ID	Optional. Identifies which column in Extent to use for creation of individual buffers if Extent is a data.frame. Passed on to download_ERA and download_DEM.
API_Key	Optional. ECMWF cds API key. Passed on to download_ERA.
API_User	Optional. ECMWF cds user number. Passed on to download_ERA.
Target_res	Optional. The target resolution for the kriging step (i.e. which resolution to downscale to). An object as specified/produced by raster::res(). Passed on to download_DEM.
Source	Optional, character. Whether to attempt download from the official USGS data viewer (Source = "USGS") or a static copy of the data set on a private drive (Source = "Drive"). Default is "USGS". Use this if the USGS viewer is unavailable. Passed on to download_DEM.
nmax	Optional. Controls local kriging. Number of nearest observations to be used kriging of each observation. Default is to use all available (Inf). You can specify as a number (numeric).
TryDown	Optional, numeric. How often to attempt the download of each individual file (if querying data download) that the function queries from the server. This is to circumvent having to restart the entire function when encountering connectivity issues.
verbose	Optional, logical. Whether to report progress of data download (if queried) in the console or not.
TimeOut	Numeric. The timeout for each download in seconds. Default 36000 seconds (10 hours).
SingularDL	Logical. Whether to force download of data in one call to CDS or automatically break download requests into individual monthly downloads. Default is FALSE.

Value

A list object containing the downscaled data as well as the standard error for downscaling as well as the call to the krigR function, and two NETCDF (.nc) file in the specified directory which are the two data contents of the aforementioned list. A temporary directory is populated with individual NETCDF (.nc) files throughout the runtime of krigR which is deleted upon completion if Keep_Temporary = TRUE and all layers in the Data raster object were kriged successfully.

Examples

## Not run: 
## THREE-STEP PROCESS (By Itself)
# Downloading ERA5-Land air temperature reanalysis data in 12-hour intervals for 02/01/1995 - 04/01/1995 (DD/MM/YYYY). API User and Key in this example are non-functional. Substitute with your user number and key to run this example.
Extent <- extent(c(11.8, 15.1, 50.1, 51.7)) # roughly the extent of Saxony
API_User <- "..."
API_Key <- "..."
State_Raw <- download_ERA(
  Variable = "2m_temperature",
  DataSet = "era5-land",
  DateStart = "1995-01-02",
  DateStop = "1995-01-04",
  TResolution = "hour",
  TStep = 12,
  Extent = Extent,
  API_User = API_User,
  API_Key = API_Key
)
State_Raw # a raster brick with 6 layers at resolution of ~0.1°
# Downloading GMTED2010-data at resolution and extent obtained by a call to download_ERA and a target resolution of .02.
Covs_ls <- download_DEM(
  Train_ras = State_Raw,
  Target_res = .02,
  Keep_Temporary = TRUE
)
Covs_ls # a list with two elements: (1) GMTED 2010 data at training resolution, and (2) GMTED 2010 data aggregated as close as possible to a resolution of 0.02
# Kriging the data sets prepared with the previous functions.
State_Krig <- krigR(
  Data = State_Raw, # data we want to krig as a raster object
  Covariates_coarse = Covs_ls[[1]], # training covariate as a raster object
  Covariates_fine = Covs_ls[[2]], # target covariate as a raster object
)

## PIPELINE (From Scratch)
#' # Downloading ERA5-Land air temperature reanalysis data in 12-hour intervals for 02/01/1995 - 04/01/1995 (DD/MM/YYYY), downloading and preparing GMTED 2010 covariate data, and kriging. API User and Key in this example are non-functional. Substitute with your user number and key to run this example. This example produces the same output as the example above.
Extent <- extent(c(11.8, 15.1, 50.1, 51.7)) # roughly the extent of Saxony
API_User <- "..."
API_Key <- "..."
Pipe_Krig <- krigR(
  Variable = "2m_temperature",
  Type = "reanalysis",
  DataSet = "era5-land",
  DateStart = "1995-01-02",
  DateStop = "1995-01-04",
  TResolution = "hour", #
  TStep = 12,
  Extent = Extent,
  API_User = API_User,
  API_Key = API_Key,
  Target_res = .02,
)

## End(Not run)

ErikKusch/KrigR documentation built on Feb. 17, 2025, 2:09 p.m.