% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/eva.R
\name{eva}
\alias{eva}
\title{Model statistical evaluation}
\usage{
eva(
  mo,
  ob,
  rname = site,
  table = NULL,
  site = "ALL",
  wd = FALSE,
  fair = NULL,
  cutoff = NA,
  cutoff_NME = NA,
  no_tz = FALSE,
  nobs = 8,
  eval_function = stat,
  select_time,
  time = "date",
  remove_ch = FALSE,
  clean = TRUE,
  verbose = TRUE,
  ...
)
}
\arguments{
\item{mo}{data.frame with model data}

\item{ob}{data.frame with observation data}

\item{rname}{row name of the output (default is site argument)}

\item{table}{data.frame to append the results}

\item{site}{name of the station or "ALL" (default) or "complete", see notes}

\item{wd}{default is FALSE, see notes}

\item{fair}{model data.frame (or list of names) to perform a fair comparison, see notes}

\item{cutoff}{minimum (optionally the maximum) valid value for observation}

\item{cutoff_NME}{minimum (optionally the maximum) valid value for observation for NME}

\item{no_tz}{ignore tz from input (force GMT)}

\item{nobs}{minimum number of valid observations, default is 8}

\item{eval_function}{evaluation function (default is stat)}

\item{select_time}{select the observation (ob) using time from model (mo) data.frame}

\item{time}{name of the time column (containing time in POSIXct)}

\item{remove_ch}{remove special characters on column names}

\item{clean}{remove rows when number of observations < nobs, for site="complete"}

\item{verbose}{display additional information}

\item{...}{arguments to be passing to stats and plot}
}
\value{
data.frame with statistical metric
}
\description{
Statistical (or categorical) evaluation from 2 data.frames. The input data.frames (model and observation)
must contain a time column (containing POSIXlt). The function perform pre-conditioning of the data,
data pairing (using the time column) of the observations and model and calculate the metrics for statistical or
categorical evaluation.
}
\note{
Fair argument can be a data.frame or a character string to be used for the analysis, alternatively the function %IN% can be used instead, for example model_d01 %IN% model_d02.

If wd = TRUE, used for wind direction, a rotation of 360 (or -360) is applied to minimize the wind direction difference.

If site == 'ALL' (default) all the columns from observations are combined in one column
(same for observation) and all the columns are evaluated together.

If site == 'complete' a internal loop, calls recursively eva() to evaluate all sites in the first argument (model) and using all sites (see "ALL").

Special thanks to Kiarash and Libo to help to test the wind direction option.
}
\examples{
model <- readRDS(paste0(system.file("extdata",package="eva3dm"),
                        "/model.Rds"))
obs   <- readRDS(paste0(system.file("extdata",package="eva3dm"),
                        "/obs.Rds"))

# if there is no observed data
# the function return an empty row
table <- eva(mo = model, ob = obs, site = "VVIbes")
print(table)

# if the site are not in the input data frame a message is displayed
# and the function return an empty row
table <- eva(mo = model, ob = obs, site = "Ibirapuera")
print(table)

# calculating statistical with a few observed values
table <- eva(mo = model, ob = obs, site = "Americana")
print(table)

# calculating categorical (using 2 for threshold) with a few observed values
table <- eva(mo = model, ob = obs, site = "Americana",
             eval_function = cate, threshold = 2)
print(table)

# calculating categorical (using 10 for threshold) with a few observed values
table <- eva(mo = model, ob = obs, site = "Americana",
             eval_function = cate, threshold = 10)
print(table)

# customizing the evaluation function: inclusion of p.value from stats::cor.test()
stat_p <- function(x, y, ...){
  table         <- eva3dm::stat(x, y, ...)
  cor.result    <- stats::cor.test(x, y, ... )
  table$p.value <- cor.result$p.value
  table         <- table[,c(1:4,12,5:11)]
  return(table)
}

table <- eva(mo = model, ob = obs, site = "Americana",eval_function = stat_p)
print(table)

}
\seealso{
\code{\link{stat}} for additional information about the statistical metrics and \code{\link{cate}} for categorical metrics, and check the example with the custom evaluation function (inclusion of p.value from stats::cor.test()).
}
