R/plot_documentation.R

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

#' plot_args
#'
#' optional arguments to be passed to plotting function.
#'
#' @name plot_args_map
#' @param xlims,ylims x and y limits of the plot. If not specified calculated from input data.
#' @param zlims Limits of plot data. If not specified calculated from input data.
#' @param mask Array of same dimension as gridded data (only if input data contains gridded data) containing 1 (mask) and NA (no mask). As default, values where all time steps of variable are NAs are masked.
#' @param mask_col Color for data mask (only if input data contains gridded data).  Must be a valid argument to \code{\link[grDevices]{col2rgb}}. If not specified by the user in \code{\link{make_object}} the mask contains all grid points where all values of the time series are missing values. Default = "lightgrey".
#' @param NA_col Color for values where index is NA (for grid and points). Must be a valid argument to \code{\link[grDevices]{col2rgb}}. Default = "white".
#' @param p_pch: pch of the points (see par). Values between 21:25 are implemented. Default is 21.
#' @param p_cex: cex of points (number or array). Deefault is 2.
#' @param g_breaks/p_breaks User defined breaks for plotting. If gridded data is plotted, g_breaks will be used for both grid and point data. If only point data is provided, p_breaks needs to be specified.
#' @param g_nlev/p_nlev Number of levels for calculating breaks. If gridded data is plotted, g_nlev will be used for both grid and point data. If only point data is provided, p_nlev needs to be specified. If breaks are provided, nlev is ignored.
#' @param ratio Ratio of lat/lon in plotting region. Default = diff(ylims)/diff(xlims).
#' @param pwidth Width of plotting region of output (as input for jpeg, png, ...). Height is calculated in functions based on plot layout.
#' @param lwidth Width of legend. Default = 1.
#' @param plwidth Width of legend for points (not in all plot types). Default = 1.
#' @param text_sec Numeric. Factor by which cex of text is multiplied (for title and axes).
#'@param text_cex Value with which  default cex of text (e.g. axes,title) is multiplied (important when changing dimensions of plots). Default=1
#' @param graphic_device Arguments for graphics devices (in addition to \emph{filename}, \emph{width} and \emph{height} ), depending on the output chosen see \code{\link[grDevices]{png}} or \code{\link[grDevices]{pdf}}. Ignored if  \emph{output} is NULL or "dev.new".
#' @param topo A list containing three elements. 1) a matrix with altitude values, 2) the longitudes of 1) and 3) tha latitudes of 1). Note, that longitudes and latitudes need to correspond to the coordinates of the climate data.

#' @keywords internal
NULL

#'veri docu
#'@name veri_doc
#'@param ncat Number of equidistant categories to divide forecast into (if probs is specified not used). Default=3 (=tercile forecasts).
#'@param prob Probability thresholds for converting continuous forecasts to category forecasts. If not provided then ncat equidistant categories are calulated: (1:(ncat-1))/ncat).
#'@param cat_names Names of forecast categorys to be used for plot. Default = paste0("cat",1:ncat)
#'@param skillmin Minimum skill limit for which forecasts are shown. Default=NULL (no skill criterion applied).
#'@param veri_metric Skill metric to calculate, see \code{\link{verify_index}}.
#'@keywords internal
NULL


#'veri_args
#'
#'optional arguments for verification function
#'@name veri_args
#'@param nmin Number of forecasts that are not-missing for forecast to be evaluated, otherwise NA is returned see \code{\link{easyVerification}{veriApply}}. Default=20.
#'@param na_rm 	Logical, should incomplete forecasts-observation pairs be used? see \code{\link{easyVerification}{veriApply}}. Default=TRUE
#'@param ncat Number of equidistant categories for converting continous forecast into category forecasts (only for category skill scores). Default=3
#'@param prob Optional parameters passed to \code{\link{easyVerification}{veriApply}} for user defined probability thresholds for converting continuous forecasts to category forecasts(only for category skill scores). Default=NULL (in this case prob is set to (1:(ncat-1))/ncat).
NULL

#'plot docu
#'@param obs Observations. "climindvis" object of type p/grid as output from \code{\link{make_object}} by using daily observational or Re-analysis data.
#'@param hc Hindcasts. "climindvis_index" object  of type hc_p/hc_grid as output from \code{\link{make_object}} using an ensemble of  daily seasonal hindcasts.
#'@param fc Forecasts. "climindvis_index" object  of type fc_p/fc_grid as output from \code{\link{make_object}} using an ensemble daily seasonal forecasts.
#'@param dat_p Climindvis-object with type = "p" generated by \code{\link{make_object}}.
#'@param dat_grid Climindvis-object with type = "grid" generated by \code{\link{make_object}}.
#'@param hc_p Hindcasts at stations. Climindvis-object with type = "hc_p" generated by \code{\link{make_object}}.
#'@param hc_grid Gridded hindcasts. Climindvis-object with type = "hc_grid" generated by \code{\link{make_object}}.
#'@param hc_ref_p Optional. Reference hindcasts at stations for calculation of skill scores. If not provided (NULL), climatology is taken as reference. Default = NULL.
#'@param hc_ref_grid Optional. Reference gridded hindcasts for calculation of skill scores. If not provided (NULL), climatology is taken as reference. Default = NULL.
#'@param fc_p Forecasts at stations. Climindvis-object with type = "fc_p" generated by \code{\link{make_object}}.
#'@param fc_grid Gridded forecasts. Climindvis-object with type = "fc_grid" generated by \code{\link{make_object}}.
#'@param obs_p Station observations. Climindvis-object with type = "p" generated by \code{\link{make_object}}. For autoplot_forecast_map and autoplot_forecast_point only needed if skill criterion is applied.
#'@param obs_grid Gridded observation data. Climindvis-object with type = "grid" generated by \code{\link{make_object}}. For autoplot_forecast_map and autoplot_forecast_point only needed if skill criterion is applied.
#'@param datlist_p Single object or list of climindvis-objects with type = "p"/"hc_p" generated by \code{\link{make_object}}.
#'@param index Name of index to be calculated., e.g. index = "dd" or index = "tnn". For list of indices see \code{\link{indices_list}}
#'@param index_args List of arguments for index. See \code{\link{indices_list}}.
#'@param indices Character array of indices to be calculated.
#'@param indices_args List containing a list of index arguments for each index. See \code{\link{calc_index}}.
#'@param 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.
#'@param selpoints Array to select subset of points to plot. There are two options:
#'    \itemize{
#'   \item Character array of station names (works only if names are defined in climindvis_index objects ...$data_info$pnames and if they are the same for all objects in climindvis_index_list)
#'   \item Integer array of station indices (works only if  coordinates of all objects in climindvis_index_list are the same)
#'   }
#'@param trendplots Logical. Plot trend line and 95\% confidence interval for index. Default = FALSE.
#'@param NAmaxClim Integer [0,100]. Maximum percentage of years with missing values for calculation of climatology. If exceeded value for respective grid point/station is set to NA. Default = 20 ( = 20"\%").
#'@param NAmaxTrend Integer [0,100]. Maximum percentage of years with missing values for calculation of trend. If exceeded value for respective grid point/station is set to NA. Default = 20 ( = 20"\%").
#'@param text_noskill Character string. Text to show if forecast skill is lower than noskill. Default = "no skill".
#'@param text_novar Character string. Text if climatology shows no or little variation and plotting of forecast does not make sense. Default = "no or little variation in climatology".
#'@param text_nocat Character string. Text if forecast shows no dominant forecast category (=probabilities of two or more cateogries are equal). Default = "no dominant category".
#'@param veri_metrics Character array of skill metrics to calculate. For metrics see \code{\link{verify_index}}.
#'@param veri_args Optional list of additional arguments for verification, see \code{\link{veri_args}}
#'@param ncat Number of forecast categories. Default = 3.
#'@param 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.
#'@param tacholabs Labels for categories of the tacho plot.
#'@param 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).
#'@param plotdir Character string of path of directory for saving plots. Ignored if  \emph{output} is NULL or "dev.new".
#'@param plot_title Logical. Add plot title to graphic. Default = TRUE.
#'@param 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 = "".
#' @param graphic_device Optional arguments for graphics devices (in addition to \emph{filename}, \emph{width} and \emph{height} ), depending on the output chosen see \code{\link[grDevices]{png}} or \code{\link[grDevices]{pdf}}. Ignored if  \emph{output} is NULL or "dev.new".
#'@param 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.
#'@param plot_args Optional. List of arguments passed to plotting function, see \code{\link{plot_args_map}}.
#'@name plot_doc
#'@keywords internal
NULL