localScaling: Grid local scaling

In SantanderMetGroup/transformeR: A climate4R package for general climate data manipulation and transformation

Grid local scaling

Description

Scale a grid (or compute anomalies)

Usage

localScaling(
  grid,
  base = NULL,
  ref = NULL,
  clim.fun = list(FUN = "mean", na.rm = TRUE),
  by.member = TRUE,
  time.frame = c("none", "monthly", "daily"),
  spatial.frame = c("gridbox", "field"),
  type = "additive",
  parallel = FALSE,
  max.ncores = 16,
  ncores = NULL,
  scale = FALSE
)

Arguments

grid	Input grid to be rescaled
base	Reference baseline whose climatology will be subtracted to the input grid. If NULL (the default), the climatology is directly computed from the input grid via climatology, either member-by-member or using the ensemble mean climatology, as specified by the by.member flag. Note that base must NOT be a climatology (the base climatology is internally calculated via the argument clim.fun).
ref	Reference grid. After subtracting to grid its climatology (as defined by grid.clim), the mean climatology of this additional grid is added. Default to NULL, so no reference grid is used.
clim.fun	Function to compute the climatology. Default to mean. See climatology for details on function definition.
by.member	Logical. In case of multimember grids, should the climatology be computed sepparately for each member (by.member=TRUE), or a single climatology calculated from the ensemble mean (by.member=FALSE)?. Default to TRUE. Argument passed to climatology.
time.frame	Character indicating the time frame to perform the scaling. Possible values are "none", which considers the climatological mean of the whole period given in base and/or ref, "monthly", that performs the calculation on a monthly basis and "daily", for a julian day-based approach. See details.
spatial.frame	Character string indicating whether to perform the local scaling considering the climatolopgical value at the field scale ("field") or per gridbox ("gridbox", the default).
type	Character string. Either "additive" or "ratio", depending on wheter the correction factor is added (e.g. temperature...) or applied as a ratio (e.g. precipitation, wind speed...). See details
parallel	Logical. Should parallel execution be used?
max.ncores	Integer. Upper bound for user-defined number of cores.
ncores	Integer number of cores used in parallel computation. Self-selected number of cores is used when ncpus = NULL (the default), or when maxcores exceeds the default ncores value.
scale	Logical. If TRUE data is standarized. Default is FALSE.

Details

In the type = "additive" set up the reference grid (ref) is used to correct the input grid, as follows:

grid'_{t} = grid - base_{clim} + ref_{clim}

In the case of type = "ratio":

grid'_{t} = (grid / base_{clim}) * ref_{clim}

, where grid'_t is each time slice t of the input grid, and base_clim corresponds to the baseline climatology (by default the grid climatology), thus yielding an anomaly w.r.t. the base, and ref_clim is a reference climatological value added to the previously calculated anomaly. The "additive" version is preferably applied to unbounded variables (e.g. temperature) and the "ratio" to variables with a lower bound (e.g. precipitation, because it also preserves the frequency).

Depending on the value of the argument time.frame, the baseline and reference climatologies are calculated for the whole season (time.frame = "none"), month by month time.frame = "monthly" or by day-of-the-year (julian days) (time.frame = "daily"). Thus, if both base and ref are set to NULL, the output grid corresponds to the anomaly field of the input grid w.r.t. its own mean. The way base_clim and ref_clim_grid are computed in case of multimember grids is controlled by the argument by.member. By default the climatological mean is used, but this can be changed by the user through the argument clim.fun, that is passed to climatology.

The ref usually corresponds to the control (historical, 20C3M...) run of the GCM in the training period in climate change applications, or the hindcast data for the training period in s2d applications. Note that by default ref = NULL.

Value

A locally scaled grid

Author(s)

J. Bedia

Examples

require(climate4R.datasets)
## ANOMALIES
data("NCEP_Iberia_psl")
# Define average aggregation function
f = list(FUN = "mean", na.rm = TRUE)
psl <- aggregateGrid(NCEP_Iberia_psl, aggr.y = f) # get interannual DJF series

## When 'base' and 'ref' are not supplied,
## the input grid climatology (by default the mean) is subtracted, thus yielding anomalies:
psl.anom <- localScaling(psl)
# spatial aggregation of the output (for plotting the time series)
psl.anom.iberia <- aggregateGrid(psl.anom, aggr.lat = f, aggr.lon = f)
plot(getYearsAsINDEX(psl.anom.iberia), psl.anom.iberia$Data, ty = 'b',
     ylab = "MSLP anomalies (Pa)", xlab = "year",
     main = "NCEP Reanalysis - Mean SLP anomalies (DJF)")
grid()
abline(h = 0, lty = 2, col = "blue")
# In the particular case of multimember grids, the anomalies are computed for each member
# by subtracting either their own mean (by.member = TRUE) or the
# multimember mean climatology (by.member = FALSE)
data("CFS_Iberia_tas")
a <- localScaling(CFS_Iberia_tas, by.member = FALSE)
aa <- aggregateGrid(a, aggr.lat = f, aggr.lon = f, aggr.m = f, aggr.y = f)
# Example, member 4 time series
plot(as.Date(getRefDates(aa)), aa$Data[4,], ty = "o", xlab = "Date",
     ylab = "Tmean anomaly (degC)", main = "Tmean DJF anomalies, Member 4")
abline(h = 0, lty = 2, col = "blue")
grid()
b <- localScaling(CFS_Iberia_tas, by.member = TRUE) # almost identical in this case
bb <- aggregateGrid(b, aggr.lat = f, aggr.lon = f, aggr.m = f, aggr.y = f)
lines(as.Date(getRefDates(aa)), bb$Data[4,], col = "red", ty = "l")
legend("bottomright", c("by.member = FALSE", "by.member = TRUE"), lty = 1, col = c(1,2))

# In this example, the anomalies are calculated using a different period specifying a "base".
# Note that "base" could also be a grid of a different dataset, for instance a
# reanalysisdata(EOBS_Iberia_tas)
data("EOBS_Iberia_tas")
grid <- subsetGrid(EOBS_Iberia_tas, years = 1999:2000)
base <- subsetGrid(EOBS_Iberia_tas, years = 1998)
lc <- localScaling(grid = grid, base = base)
plot(lc$Data[,,15,15], ty = 'l', ylim = c(-10,10),
     xlab = "time", ylab = "Anomaly (degC)",
     main = "Anomalies w.r.t. 1998")
abline(h = 0, lty = 2, col = "grey30")
str(lc)
# The anomalies are calculated on a monthly basis using the 'time.frame' argument:
lc.m <- localScaling(grid = grid, base = base, time.frame = "monthly")
lines(lc.m$Data[,15,15], col = "red")
lc.d <- localScaling(grid = grid, base = base, time.frame = "daily")
lines(lc.d$Data[,15,15], col = "blue")
legend("topleft", c("none", "monthly","daily"), title = "'time.frame'",
       lty = 1, col = c(1,2,4), bty = "n")

# An example in which the reference climatology is added to the anomalies:
# (not quite meaningful, though)
grid <- subsetGrid(EOBS_Iberia_tas, years = 1999)
base <- subsetGrid(EOBS_Iberia_tas, years = 1998)
ref <- subsetGrid(EOBS_Iberia_tas, years = 2000)
lc.ref <- localScaling(grid = grid, base = base, ref = ref)
lc.ref.m <- localScaling(grid = grid, base = base, ref = ref, time.frame = "monthly")
plot(grid$Data[,15,15], ty = "l", ylim = c(-7.5,10))
lines(lc.ref$Data[,,15,15], col = "blue")
lines(lc.ref.m$Data[,15,15], col = "red")

# An example using the "ratio" type:
data("EOBS_Iberia_pr")
grid <- subsetGrid(EOBS_Iberia_pr, years = 1999)
base <- subsetGrid(EOBS_Iberia_pr, years = 1998)
ref <- subsetGrid(EOBS_Iberia_pr, years = 2000)
fun <- list(FUN = "sum")
# We plot the climatologies (total accumulated precip) to have a visual comparison of
# the input grid, the grid used as base and the reference
mg <- makeMultiGrid(climatology(grid, clim.fun = fun),
                    climatology(base, clim.fun = fun),
                    climatology(ref, clim.fun = fun), skip.temporal.check = TRUE)
require(visualizeR)
spatialPlot(mg, names.attr = c("input_grid", "base", "ref"))
# Note that for precipitation we use a scaling factor rather than an addition:
grid.corr <- localScaling(grid = grid, base = base, ref = ref,
                          time.frame = "monthly", type = "ratio")
mg.corr <- makeMultiGrid(climatology(grid, clim.fun = fun), climatology(grid.corr, clim.fun = fun))
spatialPlot(mg.corr, at = seq(0,350,10), names.attr = c("Raw","Scaled"))

SantanderMetGroup/transformeR documentation built on Nov. 25, 2024, 1:25 p.m.