autoplot_forecast_map: Wrapper function for plotting maps of seasonal forecasts

In Climandes/ClimIndVis: Calculation, verification and visualisation of climate indices

Description

Generates maps showing the forecast probability of the dominant forecast category for a seasonal forecasts of indices. Additionally a skill criterion can be applied which omits showing the forecasts with a skill lower than a user defined minimum skill.
The function works with gridded and/or station data and first calculates the chosen index (using calc_index) for hindcasts and forecasts and then divides the forecast into categories (e.g. terciles) based on the climatology of the hindcasts. If the skill criterion is applied, indices are additionally calculated for observational data which is then used for verification (using verify_index). The output of the function is one plot per temporal aggregation which can directly be saved to a user specified directory.
To see some example outputs of this function, look at the vignette "autoplot-functions" accessible through the package help main page or by typing
vignette("autoplot-functions",package="ClimIndVis") into the console.

Usage

autoplot_forecast_map(
  fc_grid,
  hc_grid,
  hc_ref_grid = NULL,
  obs_grid = NULL,
  fc_p,
  hc_p,
  hc_ref_p = NULL,
  obs_p = NULL,
  index,
  index_args = list(),
  selyears = NULL,
  veri_metric,
  veri_args = list(),
  skillmin = NULL,
  col = "default",
  noskill_col = "darkgrey",
  nocat_col = "grey",
  prob,
  ncat = 3,
  cat_names = paste0("cat", 1:ncat),
  plot_title = TRUE,
  plot_args = list(),
  plot_climatology = FALSE,
  output = NULL,
  plotdir,
  plotname = "",
  title = ""
)

Arguments

fc_grid	Gridded forecasts. Climindvis-object with type = "fc_grid" generated by make_object.
hc_grid	Gridded hindcasts. Climindvis-object with type = "hc_grid" generated by make_object.
hc_ref_grid	Optional. Reference gridded hindcasts for calculation of skill scores. If not provided (NULL), climatology is taken as reference. Default = NULL.
obs_grid	Gridded observation data. Climindvis-object with type = "grid" generated by make_object. For autoplot_forecast_map and autoplot_forecast_point only needed if skill criterion is applied.
fc_p	Forecasts at stations. Climindvis-object with type = "fc_p" generated by make_object.
hc_p	Hindcasts at stations. Climindvis-object with type = "hc_p" generated by make_object.
hc_ref_p	Optional. Reference hindcasts at stations for calculation of skill scores. If not provided (NULL), climatology is taken as reference. Default = NULL.
obs_p	Station observations. Climindvis-object with type = "p" generated by make_object. For autoplot_forecast_map and autoplot_forecast_point only needed if skill criterion is applied.
index	Name of index to be calculated., e.g. index = "dd" or index = "tnn". For list of indices see indices_list
index_args	List of arguments for index. See indices_list.
selyears	Integer array of years to be selected from data. For indices with quantiles, years as defined in index_args are used for quantile calculation, but only selected years are plotted. For functions using seasonal forecast data, selyears is only applied to hindcasts.
veri_metric	Skill metric to calculate, see verify_index.
veri_args	Optional list of additional arguments for verification, see veri_args
skillmin	Minimum skill limit for which forecasts are shown. Default=NULL (no skill criterion applied).
col	Color scale for plotting. Array of same length as ncat/(prob-1) with entries being valid arguments to col2rgb. If not provided, package default colors for index are used.
noskill_col	Color for marking grid point/stations without skill (only if skillmin!=NULL). Default="darkgrey"
nocat_col	Color for marking grid point/stations with no dominant category . Default="grey"
prob	Probability thresholds for converting continuous forecasts to category forecasts. If not provided then ncat equidistant categories are calulated: (1:(ncat-1))/ncat).
ncat	Number of forecast categories. Default = 3.
cat_names	Names of forecast categorys to be used for plot. Default = paste0("cat",1:ncat)
plot_title	Logical. Add plot title to graphic. Default = TRUE.
plot_args	Optional. List of arguments passed to plotting function, see plot_args_map.
plot_climatology	Logical. Should climatology of index be plottet as time series? If TRUE, time series with shading indicating corresponding climatological values for forecast categories are plottet. Default = FALSE.
output	Format of image to be plotted ("png", "jpeg", "tiff", "pdf","dev.new"). Default = NULL, output to null device (getOption("device") will show you the null device. If you are not using RStudio, NULL and dev.new will give the same output).
plotdir	Character string of path of directory for saving plots. Ignored if output is NULL or "dev.new".
plotname	Optional. Character string. First part of plot name followed by character string containing index name/aggregation/time period/... depending on the autoplot function. Default = "".
title	Optional. Character string. If provided added above the plot in addition to default information from the respective function (e.g. index name/aggregation/time period/...). Default = "", no additional title is written.

Output

This function returns one plot per temporal aggregation for which data is available, e.g. if index_args$aggt="monthly", for all months which are covered by the forecast.

If output is not NULL or "dev.new" the graphics are directly saved in the user specified directory (plotdir) with the following filename structure:

plotname // "forecast_" // indexname // (skill_criterion) // aggregation // forecast_year // forecast_month // hindcast_years // output
e.g.
plotname_forecast_dry_days_MAM_2018_fcmon01_hc1981-2010.png
plotname_forecast_dry_days_EnsRocss>=0.3_MAM_2018_fcmon01_hc1981-2010.png

Details

This function visualizes the probability of the dominant forecast category where the color shows the category (e.g. for a tercile forecast of dry days; a:below-normal, b:normal, c:above-normal one color for each category) and the inverse transparency the probability value of the forecast for this category (e.g. for a forecast a:0%,b:0%,c:100% ).transparency=0%).

Gridpoints/stations colored in the color nocat_col either don't show a dominant forecast category or the index value is NA. The latter can occur e.g. for the start of the rainy season if the index criteria are not met within the specified time period or if the skill criterion is applied and the verifying observations are NA. If the probabilities of two or more categories are equal (e.g. a:35,b:35,c:30) no dominant category can be determined. This also applies when calculating a category forecast does not make sense , e.g. in areas where the number of frost days is always zero or maybe only in one or two years slightly above zero and the category boundaries derived from the hindcasts are all equal.

If the skill criterion is applied, grid points/stations with a lower skill than defined in skillmin are colored in noskill_col. If skill is calculated, values where the verifying observations are NA will also be shown as NA. Note that when using the category functions, only probability thresholds can be used to calculate forecast categories. If verify_metric is EnsRoca or EnsRocss, the skill value of the dominant forecast category is taken.

See Also

Other autoplot_functions: autoplot_anomaly_map(), autoplot_anomaly_ts(), autoplot_climatology_map(), autoplot_forecast_spi(), autoplot_forecast_stations(), autoplot_overview_stations(), autoplot_trend_map(), autoplot_ts_stations(), autoplot_verification_map()

Examples

## Load example climindvis objects:

data("object_hc_grid", "object_fc_grid", "object_hc_st", "object_fc_st", "object_st", "object_grid")


## If you use the default values, the only inputs needed are the climindvis objects,
## the index and the index_args, e.g. for a tercile dry day forecast
## for MAM without skill information:

autoplot_forecast_map(
     fc_grid = object_fc_grid, hc_grid = object_hc_grid,
     fc_p = object_fc_st, hc_p = object_hc_st,
     index = "dd", index_args = list(aggt = "seasonal", selagg = "MAM"))


## If you additionally want to cut out all stations with a EnsRocss < 0.3 you have to add:
## veri_metric = "EnsRocss" , skill_min = 0.2.

autoplot_forecast_map(
      fc_grid = object_fc_grid, hc_grid = object_hc_grid, obs_grid = object_grid,
      fc_p = object_fc_st, hc_p = object_hc_st, obs_p = object_st,
      veri_metric = "EnsRocss", skillmin = 0.3,
      index = "dd", index_args = list(aggt = "seasonal", selagg = "MAM"))

Climandes/ClimIndVis documentation built on Oct. 24, 2021, 10:52 a.m.