sidfex.evaluate: Evaluate SIDFEx Forecasts Against Observations

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

Evaluate SIDFEx Forecasts Against Observations

Description

Compute various types of errors of SIDFEx forecasts relative to observations and, if applicable, ensemble spread.

Usage

sidfex.evaluate(obs = NULL, fcst, do.speedangle = TRUE, ens.stats.na.rm = TRUE, do.multifcst.stats = TRUE, multifcst.stats.na.rm = TRUE, data.path = NULL, verbose = TRUE)

Arguments

obs	a list with SIDFEx observations as returned by sidfex.read.obs, or NULL (default). If NULL, sidfex.read.obs is used to read the required observations.
fcst	a list with SIDFEx forecasts as returned by sidfex.read.fcst (or a single element from the res.list element of such a list).
do.speedangle	a logical value specifying whether relative speed and angle errors shall be computed in addition to great-circle distance and lon-lat errors.
ens.stats.na.rm	a logical value specifying whether to remove NAs before statistics are computed across ensemble members.
do.multifcst.stats	a logical value specifying whether statistics across all elements of fcst$res.list shall be computed (if length(fcst$res.list)>1 and fcst is not a single element of such a list). Will result in an error if the forecast elements do not have identical time axes in terms of forecast lead time. This can be achieved by applying sidfex.remaptime.fcst with the argument newtime.DaysLeadTime first and providing the result as argument 'fcst' to sidfex.evaluate (this function).
multifcst.stats.na.rm	a logical value specifying whether to remove NAs before statistics are computed across forecast elements.
data.path	NULL or a character specifying the directory of the observational data. If NULL, it is attempted to source a file named .SIDFEx in the home directory where a character variable data.path.obs needs to be defined (used only if obs=NULL).
verbose	a logical value specifying whether to produce warnings in sidfex.remaptime.fcst and sidfex.remaptime.obs2fcst, in particular when new time axes reach outside original time axes. Default is TRUE.

Value

If fcst is a list with SIDFEx forecasts as returned by sidfex.read.fcst, the return value is a list with elements ens.merge (inherited from fcst), evaluate.arguments (to document the logical values specified for do.speedangle and do.multifcst.stats), res.list, and optionally multifcst.stats if do.multifcst.stats=TRUE and length(fcst$res.list)>1. The element res.list holds one element for each corresponding element in fcst$res.list, with various types of forecast errors listed below. If fcst is a single forecast element, only a single list with the types of forecast errors is returned.

Forecast errors are computed for all Nts timesteps in fcst and, if the respective element of fcst is an ensemble, for all Nens ensemble members individually. If provided, multifcst.stats has four elements per element of res.list (except results for individual members) with the mean, st.dev (standard deviation), st.err (standard error), and median across the elements of res.list.

The errors provided are listed in the following. Those with 'individual' or 'spread' in their names are provided only for forecast elements composed of an ensemble.

ens.mean.gc.dist	a numeric vector of length Nts with the great-circle distance of the ensemble-mean position from the observed position
ens.mean.lat.err	a numeric vector of length Nts with the latitudinal error of the ensemble-mean position relative to the observed position
ens.mean.lon.err	a numeric vector of length Nts with the longitudinal error of the ensemble-mean position relative to the observed position
ens.individual.gc.dist	an Nts x Nens matrix with the great-circle distance of the individual ensemble-member positions from the observed position
ens.individual.lat.err	an Nts x Nens matrix with the latitudinal error of the individual ensemble-member positions from the observed position
ens.individual.lon.err	an Nts x Nens matrix with the longitudinal error of the individual ensemble-member positions from the observed position
ens.individual.gc.dist.mean	a numeric vector of length Nts with the mean great-circle distance of ensemble-member positions from the observed position, averaged over all ensemble members
ens.individual.lat.err.mean	a numeric vector of length Nts with the mean latitudinal error of ensemble-member positions from the observed position, averaged over all ensemble members
ens.individual.lat.err.meanabs	a numeric vector of length Nts with the mean absolute latitudinal error of ensemble-member positions from the observed position, averaged over all ensemble members
ens.individual.lon.err.mean	a numeric vector of length Nts with the mean longitudinal error of ensemble-member positions from the observed position, averaged over all ensemble members
ens.individual.lon.err.meanabs	a numeric vector of length Nts with the mean absolute longitudinal error of ensemble-member positions from the observed position, averaged over all ensemble members
ens.spread.gc.dist	a numeric vector of length Nts with the mean great-circle distance of ensemble-member positions from the ensemble-mean position, averaged over all ensemble members
ens.spread.lat	a numeric vector of length Nts with the mean latitudinal distance of ensemble-member positions from the ensemble-mean position, averaged over all ensemble members
ens.spread.lon	a numeric vector of length Nts with the mean longitudinal distance of ensemble-member positions from the ensemble-mean position, averaged over all ensemble members

If do.speedangle, additionally the following types are included:

ens.mean.relspeed	a numeric vector of length Nts with the relative integrated speed of the drift since the initial time/location (distance from the initial location) of the ensemble-mean position relative to the observed speed of the drift since the initial time/location
ens.mean.angle	a numeric vector of length Nts with the angle between the drift since the initial time/location of the ensemble-mean position relative to the observed drift since the initial time/location
ens.individual.relspeed	an Nts x Nens matrix with relative speed errors for each ensemble member (compare ens.mean.relspeed)
ens.individual.angle	an Nts x Nens matrix with angle errors for each ensemble member (compare ens.mean.angle)
ens.individual.relspeed.mean	a numeric vector of length Nts with the mean relative drift speed error, averaged over all ensemble members
ens.individual.angle.mean	a numeric vector of length Nts with the mean angle error, averaged over all ensemble members
ens.individual.angle.meanabs	a numeric vector of length Nts with the mean absolute angle error, averaged over all ensemble members

Note

Based on several spheRlab and SIDFEx functions.

To recompute multi-forecast statistics for a subset of the forecasts already evaluated with sidfex.evaluate (this function), use sidfex.evaluate.subset afterwards.

Author(s)

Helge Goessling

See Also

sidfex.read.fcst, sidfex.read.obs, sidfex.evaluate.subset

Examples

# Load the forecast data index
index = sidfex.load.index()

# Select a subset containing one specific forecast ensemble
subind = sidfex.fcst.search.extractFromTable(gid = "ecmwf001" , tid = "300234063991680", iy = 2019, idoy = c(1,65))

# Read the forecasts
fcst = sidfex.read.fcst(subind)

# Remap these seasonal-range forecasts to the first ten days only
fcst.remapped = sidfex.remaptime.fcst(fcst,newtime.DaysLeadTime=0:10)

# Compute forecast errors
errs = sidfex.evaluate(fcst = fcst.remapped)

# Show structure of errs
str(errs)

# Recompute multi-forecast statistics for small subset of forecasts
errs.sub = sidfex.evaluate.subset(eval.res = errs, keep = c(1,3))

# Show structure of errs.sub
str(errs.sub)

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