sidfex.plot.speedangle.on.template: Plot Speed-vs-Angle data on existing template

In helgegoessling/SIDFEx: Tools for the Sea Ice Drift Forecast Experiment (SIDFEx)

Plot Speed-vs-Angle data on existing template

Description

Does mainly the same thing as sidfex.plot.speedangle but uses an input file for the background axis and labels.

Usage

sidfex.plot.speedangle.on.template(index=NULL,read.fcst.res=NULL,read.obs.res=NULL,remap.res=NULL,
                                   col.by="DaysLeadTime",colbar=sl.colbar.redgreyblue_256,
                                   colbar.breaks=NULL,colbar.breaks.log=FALSE,points.type="p",out.device="pdf", in.device="png",
                                   file=paste0("~/sidfex.plot.speedangle.",out.device),width=NULL,outer.plot=F
                                   templatefile = NULL,...) 

Arguments

index	a data frame specifying the SIDFEx forecasts to be read/analysed/plotted, or NULL (default). In the latter case, read.fcst.res must be provided and a corresponding index is derived from that.
read.fcst.res	a list with SIDFEx forecasts as returned by sidfex.read.fcst, or NULL (default). In the latter case, sidfex.read.fcst is used to read the required forecasts based on index.
read.obs.res	a list with SIDFEx observations as returned by sidfex.read.obs, or NULL (default). In the latter case, sidfex.read.obs is used to read the required observations (based on index or read.fcst.res). Providing this argument can save time. Ignored if remap.res is provided, which saves even more time.
remap.res	a list with remapped SIDFEx observations as returned by sidfex.remaptime.obs2fcst, or NULL (default). In the latter case, sidfex.remaptime.obs2fcst is used to remap observations temporally to times at which the forecasts are valid. Providing this argument can save time.
col.by	a character specifiying by what property data points shall be coloured. Can be either any column of index (except File): File, GroupID, MethodID, TargetID, InitYear, InitDayOfYear, EnsMemNum, SubmitYear, SubmitDayOfYear, ProcessedYear, ProcessedDayOfYear, Delay, nTimeSteps, FirstTimeStepYear, FirstTimeStepDayOfYear, LastTimeStepYear, LastTimeStepDayOfYear, and FcstTime. Or, it can be a column of the forecast data table: Year, DayOfYear, Lat, Lon, and DaysLeadTime. Some of these are interpreted in a categorical way (e.g., GroupID, EnsMemNum, and Year), and some as continuous numerical values (e.g., Delay, Lat, and DaysLeadTime, which is the default).
colbar	a spheRlab colourbar as returned by sl.colbar). If col.by is categorical, colbar must contain at least as many colours as there are categories; if colbar has more colours, the colourbar is thinned out.
colbar.breaks	an optional numeric vector specifying the breaks between colours. Ignored if col.by is categorical.
colbar.breaks.log	a logical value indicating whether breaks for the colourbar shall be placed in logarithmic steps. Default is breaks.log=FALSE. Ignored if col.by is categorical or if breaks is provided.
points.type	a character specifying whether only points ('p'), only lines ('l'), or both ('b') shall be plotted.
in.device	a character specifying the graphics device of the template (templatefile), or NULL for the default device. Default is device='png'.
out.device	a character specifying which graphics device to use, or NULL for the default device. Default is device='pdf'.
file	a character specifying the output file (if device!=NULL). Default is file=paste0("~/sidfex.plot.speedangle.",out.device).
width	a scalar specifying the width of the resulting output figure. The height will be equal. If NULL (default), a (hopefully) useful value depending on device is used.
outer.plot	a boolean (default FALSE) specifying whether there is already a new plot created (e.g. calling par)() and plot()) outside this function or not. If TRUE, the calls of par() and plot() inside the function will be suppressed, which basically avoids plotting unnecessary axes and keeps the aspect ratio correctly. The default should be sufficient for almost all cases.
templatefile	the image on which the data will be plotted. For best results use a png-file created by sidfex.plot.speedangle.template.
...	Further graphical parameters to be forwarded to points (see documentation of points for details).

Value

A list with the elements col.by, colbar, categorical, breaks, and labels, which can be used to plot the corresponding colourbar with sl.plot.colbar.

Note

So far (and very certainly it will stay like this) only 'png' and 'jpeg' are intended and implemented as template types (in.device). We recommend the usage of 'png', as 'jpeg' could lead to data points covering the labels, which can be solved by using transparend templates - a feature, that 'png' easily can provide. Aside from this limitation, the output files can be any supported graphics device.

As this function is almost identical with sidfex.plot.speedangle now, the authors will soon discuss the necessity of keeping both.

Author(s)

Simon Reifenberg, Helge Goessling

See Also

sidfex.plot.speedangle.template, sidfex.plot.speedangle

Examples

# load whole SIDFEx forecast index
index = sidfex.load.index()
 
# extract subindex with all forecasts that match some filters
subindex = index[ index$TargetID == "300234063991680" &
                   index$GroupID 
                   index$InitYear == 2018 &
                   index$InitDayOfYear > 210 &
                   index$InitDayOfYear < 215, ]
                   
# create the template
fn_template = "~/speedangle.template.png"
sidfex.plot.speedangle.template(device = "png", file = fn_template, width = 700)

# generate a speed-angle-plot for all forecast data corresponding to the subindex, with colours according to the GroupID
cb = sidfex.plot.speedangle.on.template(subindex,col.by="GroupID",points.type="p",colbar=sl.colbar(cols = c("violet","blue","green","yellow","orange","red"),N=256),
                                   out.device="png",file="~/speedangle_example_plot2template.png", 
                                   templatefile = fn_template, width = 800)

helgegoessling/SIDFEx documentation built on March 15, 2024, 2:26 p.m.