RainFARM {CSTools}R Documentation

RainFARM stochastic precipitation downscaling (reduced version)


This function implements the RainFARM stochastic precipitation downscaling method and accepts in input an array with named dims ("lon", "lat") and one or more dimension (such as "ftime", "sdate" or "time") over which to average automatically determined spectral slopes. Adapted for climate downscaling and including orographic correction. References: Terzago, S. et al. (2018). NHESS 18(11), 2825-2840. http://doi.org/10.5194/nhess-18-2825-2018, D'Onofrio et al. (2014), J of Hydrometeorology 15, 830-843; Rebora et. al. (2006), JHM 7, 724.


  weights = 1,
  nens = 1,
  slope = 0,
  kmin = 1,
  fglob = FALSE,
  fsmooth = TRUE,
  nprocs = 1,
  time_dim = NULL,
  lon_dim = "lon",
  lat_dim = "lat",
  drop_realization_dim = FALSE,
  verbose = FALSE



Precipitation array to downscale. The input array is expected to have at least two dimensions named "lon" and "lat" by default (these default names can be changed with the lon_dim and lat_dim parameters) and one or more dimensions over which to average these slopes, 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.


Vector or array of longitudes.


Vector or array of latitudes.


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


multi-dimensional array 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'.


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


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)


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


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


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


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


String or character array with name(s) of time dimension(s) (e.g. "ftime", "sdate", "time" ...) over which to compute spectral slopes. If a character array of dimension names is provided, the spectral slopes will be computed 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.


Name of lon dimension ("lon" by default).


Name of lat dimension ("lat" by default).


Logical to remove the "realization" stochastic ensemble dimension (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".


logical for verbose output (default: FALSE).


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.


RainFARM() returns a list containing the fine-scale longitudes, latitudes and the sequence of nens downscaled fields. If nens>1 an additional dimension named "realization" is added to the output array after the "member" dimension (if it exists and unless drop_realization_dim=TRUE is specified). The ordering of the remaining dimensions in the exp element of the input object is maintained.


Jost von Hardenberg - ISAC-CNR, j.vonhardenberg@isac.cnr.it


# Example for the 'reduced' RainFARM function 
nf <- 8   # Choose a downscaling by factor 8
nens <- 3 # Number of ensemble members
# create a test array with dimension 8x8 and 20 timesteps
# or provide your own read from a netcdf file
pr <- rnorm(8 * 8 * 20)
dim(pr) <- c(lon = 8, lat = 8, ftime = 20)
lon_mat <- seq(10, 13.5, 0.5) # could also be a 2d matrix
lat_mat <- seq(40, 43.5, 0.5)
# Create a test array of weights
ww <- array(1., dim = c(lon = 8 * nf, lat = 8 * nf))
# or create proper weights using an external fine-scale climatology file
#     Specify a weightsfn filename if you wish to save the weights
## Not run: 
ww <- CST_RFWeights("./worldclim.nc", nf, lon = lon_mat, lat = lat_mat, 
                    fsmooth = TRUE)

## End(Not run)
# downscale using weights (ww=1. means do not use weights)
res <- RainFARM(pr, lon_mat, lat_mat, nf, 
                fsmooth = TRUE, fglob = FALSE, 
                weights = ww, nens = 2, verbose = TRUE)
#List of 3
# $ data: num [1:3, 1:20, 1:64, 1:64] 0.186 0.212 0.138 3.748 0.679 ...
# $ lon : num [1:64] 9.78 9.84 9.91 9.97 10.03 ...
# $ lat : num [1:64] 39.8 39.8 39.9 40 40 ...
#  lon         lat       ftime realization 
#   64          64          20           2 
# Example 2:
slo <- array(c(0.1, 0.5, 0.7), c(sdate= 3))
wei <- array(rnorm(8*8*3), c(lon = 8, lat = 8, sdate = 3))
res <- RainFARM(lonlat_prec$data, lon = lonlat_prec$lon,
                lat = lonlat_prec$lat, weights = wei, slope = slo, nf = 2)

[Package CSTools version 4.0.1 Index]