CST_RainFARM {CSTools}

RainFARM stochastic precipitation downscaling of a CSTools object

Description

This function implements the RainFARM stochastic precipitation downscaling method and accepts a CSTools object (an object of the class 's2dv_cube' as provided by 'CST_Load') as input. Adapted for climate downscaling and including orographic correction as described in Terzago et al. 2018.

Usage

CST_RainFARM(
  data,
  weights = 1,
  slope = 0,
  nf,
  kmin = 1,
  nens = 1,
  fglob = FALSE,
  fsmooth = TRUE,
  nprocs = 1,
  time_dim = NULL,
  verbose = FALSE,
  drop_realization_dim = FALSE
)

Arguments

data

An object of the class 's2dv_cube' as returned by 'CST_Load', containing the spatial precipitation fields to downscale. The data object is expected to have an element named $data with at least two spatial dimensions named "lon" and "lat" and one or more dimensions over which to compute average spectral slopes (unless specified with parameter slope), which can be specified by parameter time_dim. The number of longitudes and latitudes in the input data is expected to be even and the same. If not the function will perform a subsetting to ensure this condition.

weights

Matrix with climatological weights which can be obtained using the CST_RFWeights function. If weights = 1. (default) no weights are used. The names of these dimensions must be at least 'lon' and 'lat'.

slope

Prescribed spectral slope. The default is slope = 0. meaning that the slope is determined automatically over the dimensions specified by time_dim. A 1D array with named dimension can be provided (see details and examples).

nf

Refinement factor for downscaling (the output resolution is increased by this factor).

kmin

First wavenumber for spectral slope (default: kmin = 1).

nens

Number of ensemble members to produce (default: nens = 1).

fglob

Logical to conserve global precipitation over the domain (default: FALSE).

fsmooth

Logical to conserve precipitation with a smoothing kernel (default: TRUE).

nprocs

The number of parallel processes to spawn for the use for parallel computation in multiple cores. (default: 1)

time_dim

String or character array with name(s) of dimension(s) (e.g. "ftime", "sdate", "member" ...) over which to compute spectral slopes. If a character array of dimension names is provided, the spectral slopes will be computed as an average over all elements belonging to those dimensions. If omitted one of c("ftime", "sdate", "time") is searched and the first one with more than one element is chosen.

verbose

Logical for verbose output (default: FALSE).

drop_realization_dim

Logical to remove the "realization" stochastic ensemble dimension, needed for saving data through function CST_SaveData (default: FALSE) with the following behaviour if set to TRUE:

1. if nens == 1: the dimension is dropped;

2. if nens > 1 and a "member" dimension exists: the "realization" and "member" dimensions are compacted (multiplied) and the resulting dimension is named "member";

3. if nens > 1 and a "member" dimension does not exist: the "realization" dimension is renamed to "member".

Details

Wether parameter 'slope' and 'weights' presents seasonality dependency, a dimension name should match between these parameters and the input data in parameter 'data'. See example 2 below where weights and slope vary with 'sdate' dimension.

Value

CST_RainFARM() returns a downscaled CSTools object (i.e., of the class 's2dv_cube'). If nens > 1 an additional dimension named "realization" is added to the $data array after the "member" dimension (unless drop_realization_dim = TRUE is specified). The ordering of the remaining dimensions in the $data element of the input object is maintained.

Author(s)

Jost von Hardenberg - ISAC-CNR, [e-mail]

References

Terzago, S. et al. (2018). NHESS 18(11), 2825-2840. doi: 10.5194/nhess-18-2825-2018; D'Onofrio et al. (2014), J of Hydrometeorology 15, 830-843; Rebora et. al. (2006), JHM 7, 724.

Examples

# Example 1: using CST_RainFARM for a CSTools object
nf <- 8   # Choose a downscaling by factor 8
exp <- 1 : (2 * 3 * 4 * 8 * 8)
dim(exp) <- c(dataset = 1, member = 2, sdate = 3, ftime = 4, lat = 8, lon = 8)
lon <- seq(10, 13.5, 0.5)
lat <- seq(40, 43.5, 0.5)
coords <- list(lon = lon, lat = lat)
data <- list(data = exp, coords = coords)
class(data) <- 's2dv_cube'
# Create a test array of weights
ww <- array(1., dim = c(lon = 8 * nf, lat = 8 * nf))
res <- CST_RainFARM(data, nf = nf, weights = ww, nens = 3, time_dim = 'ftime')