climagram: Implementation of the so-called "climagrams" for seasonal...

View source: R/climagram.R

climagramR Documentation

Implementation of the so-called "climagrams" for seasonal forecasts

Description

A "climagram" is a box plot for visualization of a seasonal forecast with added EQC information from the hindcast (and possibly the verifying observations).

Usage

climagram(
  hindcast,
  forecast = NULL,
  obs = NULL,
  year.target = NULL,
  use.anomalies = TRUE,
  violin = TRUE,
  add.points = FALSE,
  detrend = FALSE,
  add.legend = TRUE,
  clim.time.frame = "monthly",
  add.eqc.info = TRUE,
  tercile.member.counts = FALSE
)

Arguments

hindcast

A climate4R multi-member grid with the hindcast for verification.

forecast

A climate4R multi-member grid with the forecast. Default is NULL. See details.

obs

A climate4R grid with the reference observations. They should match the hindcast period. Default is NULL.

year.target

Year within the hindcast period considered as forecast. Default is NULL. See Details

use.anomalies

Should anomalies or the original variable magnitudes be used for data representation? Default to TRUE (i.e., anomalies). See Details.

violin

Logical flag indicating whether a violin plot should be added to the graph instead of an ordinary boxplot. Default is TRUE.

add.points

Logical flag indicating whether crosses indicating the individual forecast members should be added to the graph. Default to FALSE.

detrend

Logical indicating if the data should be (linearly) detrended. Default is FALSE.

add.legend

Should legend be added to the plot. Default to TRUE

clim.time.frame

Default to "monthly". Temporal frame used as reference for the calculation of the climatological normal. See Details.

add.eqc.info

Should EQC (Evaluation and Quality Control) information be added onto the plot?. Ignored if no obs is passed. See Details

tercile.member.counts

Logical flag indicating whether the number of forecast members in each tercile category should be indicated in the plot. Default to FALSE.

Details

Forecast data

The product is conceived to display forecast information in an operative framework. However, for testing purposes, a target year from the hindcast can be extracted via the year.target argument and treated as the forecast year (see last example). Note that all the hindcast statistics (including the optional detrending) will be computed after extracting the target year from the hindcast (and the observations).

Spatial averaging

For spatial domains encompassing multiple points/grid points, the spatial average is first computed to obtain a unique series for the whole domain via aggregateGrid (latitude cosine weighting is used).

Forecast/Hindcast representation

In order to represent the forecast and hindcast information, “violins” are used as default, although boxplots (see boxplot) can be obtained by setting argument violin to FALSE. For further details on violin construction see the documentation of the function vioplot.

Using anomalies

By default, anomalies are displayed. In this case, the forecast anomalies will be calculated considering the hindcast climatology (see next section for details).

Climatological reference period

The hindcast climatology is calculated by considering the annual multimember averages (i.e., the univariate annual time series of ensemble means).

By default, the climatology is computed on a monthly basis. For instance, assuming a forecast for DJF is given, the DJF anomaly will be computed by subtracting to the January forecast the January climatology, to February the February climatology and so on. If clim.time.frame is set to "monthly", the climatology is computed using the seasonal climatology , so the anomalies for January will be computed using the DJF climatology, and the same for the remaining months. See argument "time.frame" of scaleGrid, to which the clim.time.frame argument is passed, for more details.

EQC Information

EQC (Evaluation and Quality Control) information can be optionally added to the plot. This is the default behaviour when obs is supplied. Here the CRPS (bias-sensitive) measure is considered.

Value

Plots a climagram. Some degree of transparency is given to the forecast boxes/violins to avoid a potential masking of underlying information.

Note

All inputs for this function must be at a monthly temporal resolution.

The computation of climatological quantiles requires a representative period to obtain meaningful results.

Author(s)

J. Bedia

See Also

Type utils::RShowDoc("climagram_vignette", package = "visualizeR") for further worked examples on climagram options.

Other visualization functions: bubblePlot(), cascadePlot(), reliabilityCategories(), spreadPlot(), tercileBarplot(), tercilePlot()

Examples

## Not run: 
my_load <- function(file.url, verbose = TRUE) {
    tmpfile <- tempfile()
    download.file(url = file.url, destfile = tmpfile)
    readRDS(tmpfile)
}
hindcast <- my_load("http://meteo.unican.es/work/visualizeR/data/tas.cfs.enso34.rds")
forecast <- my_load("http://meteo.unican.es/work/visualizeR/data/tas.cfs.2016.enso34.rds")
# A seasonal forecast product, without reference obs information
climagram(hindcast = hindcast, forecast = forecast, violin = TRUE, obs = NULL)
# Violins can be replaced by ordinary boxplots:
climagram(hindcast = hindcast, forecast = forecast, violin = FALSE, obs = NULL)
# Instead of anomalies, raw values can be used: 
climagram(hindcast = hindcast, forecast = forecast, use.anomalies = FALSE)
# Observation quartiles are depicted by the backgroud shadows (median indicated by the dotted line):
# CRPS is added by default when observations are included:
obs <- my_load("http://meteo.unican.es/work/visualizeR/data/tas.ncep.enso34.rds")
climagram(hindcast = hindcast, forecast = forecast, obs = obs)
# An arbitrary year can be extracted from the hindcast to be used as forecast
climagram(hindcast = hindcast, year.target = 2001, obs = obs)
# Adding tercile counts:
climagram(hindcast = hindcast, year.target = 2001, obs = obs, tercile.member.count = TRUE)

## End(Not run)

SantanderMetGroup/visualizeR documentation built on Oct. 28, 2023, 6:11 a.m.