modStats.Rd
Function to calculate common numerical model evaluation statistics with flexible conditioning
modStats(mydata, mod = "mod", obs = "obs", statistic = c("n", "FAC2", "MB", "MGE", "NMB", "NMGE", "RMSE", "r", "COE", "IOA"), type = "default", rank.name = NULL, ...)
mydata  A data frame. 

mod  Name of a variable in 
obs  Name of a variable in 
statistic  The statistic to be calculated. See details below for a description of each. 
type 
It is also possible to choose More than one type can be considered e.g. 
rank.name  Simple model ranking can be carried out if

...  Other aruments to be passed to 
Returns a data frame with model evaluation statistics.
This function is under development and currently provides some common model evaluation statistics. These include (to be mathematically defined later):
\(n\), the number of complete pairs of data.
\(FAC2\), fraction of predictions within a factor of two.
\(MB\), the mean bias.
\(MGE\), the mean gross error.
\(NMB\), the normalised mean bias.
\(NMGE\), the normalised mean gross error.
\(RMSE\), the root mean squared error.
\(r\), the Pearson correlation coefficient. Note, can also
supply and aurument method
e.g. method = "spearman"
\(COE\), the Coefficient of Efficiency based on Legates and McCabe (1999, 2012). There have been many suggestions for measuring model performance over the years, but the COE is a simple formulation which is easy to interpret.
A perfect model has a COE = 1. As noted by Legates and McCabe although the COE has no lower bound, a value of COE = 0.0 has a fundamental meaning. It implies that the model is no more able to predict the observed values than does the observed mean. Therefore, since the model can explain no more of the variation in the observed values than can the observed mean, such a model can have no predictive advantage.
For negative values of COE, the model is less effective than the observed mean in predicting the variation in the observations.
\(IOA\), the Index of Agreement based on Willmott et al. (2011), which spans between 1 and +1 with values approaching +1 representing better model performance.
An IOA of 0.5, for example, indicates that the sum of the errormagnitudes is one half of the sum of the observeddeviation magnitudes. When IOA = 0.0, it signifies that the sum of the magnitudes of the errors and the sum of the observeddeviation magnitudes are equivalent. When IOA = 0.5, it indicates that the sum of the errormagnitudes is twice the sum of the perfect modeldeviation and observeddeviation magnitudes. Values of IOA near 1.0 can mean that the modelestimated deviations about O are poor estimates of the observed deviations; but, they also can mean that there simply is little observed variability  so some caution is needed when the IOA approaches 1.
All statistics are based on complete pairs of mod
and obs
.
Conditioning is possible through setting type
, which can be
a vector e.g. type = c("weekday", "season")
.
Details of the formulas are given in the openair manual.
Legates DR, McCabe GJ. (1999). Evaluating the use of goodnessoffit measures in hydrologic and hydroclimatic model validation. Water Resources Research 35(1): 233241.
Legates DR, McCabe GJ. (2012). A refined index of model performance: a rejoinder, International Journal of Climatology.
Willmott, C.J., Robeson, S.M., Matsuura, K., 2011. A refined index of model performance. International Journal of Climatology.
## the example below is somewhat artificial  assuming the observed ## values are given by NOx and the predicted values by NO2. modStats(mydata, mod = "no2", obs = "nox")#> default n FAC2 MB MGE NMB NMGE RMSE #> 1 all data 63095 0.1703868 129.6739 129.7277 0.7252306 0.725532 166.6203 #> r COE IOA #> 1 0.7874487 0.3374671 0.3312664## evaluation stats by season modStats(mydata, mod = "no2", obs = "nox", type = "season")#> season n FAC2 MB MGE NMB NMGE #> 2 spring (MAM) 17343 0.25763083 107.5466 107.5466 0.6846951 0.6846951 #> 3 summer (JJA) 14658 0.17140113 116.2004 116.2004 0.7053470 0.7053470 #> 1 autumn (SON) 14775 0.09825963 154.1534 154.1534 0.7526324 0.7526324 #> 4 winter (DJF) 16319 0.14201438 143.1283 143.3366 0.7494609 0.7505519 #> RMSE r COE IOA #> 2 139.9177 0.8196724 0.2497589 0.3751205 #> 3 144.7206 0.7568891 0.4197370 0.2901315 #> 1 191.9351 0.7881365 0.4370783 0.2814608 #> 4 185.3849 0.8260512 0.3207156 0.3396422