\name{REOF}
\alias{REOF}
\title{
Area-Weighted Rotated Empirical Orthogonal Function Analysis Using SVD and Varimax rotation.
}
\description{
Performs an area-weighted EOF analysis using SVD, and then performs a Varimax rotation using a 
truncated space with only the first ntrunc EOFs. The EOF is based on a covariance matrix. 
}
\usage{
REOF(ano, lon, lat, ntrunc)
}
\arguments{
  \item{ano}{
Array of anomalies with dimensions (number of timesteps, number of latitudes,
number of longitudes).
  }
  \item{lon}{
Vector of longitudes of \code{ano}.
  }
  \item{lat}{
Vector of latitudes of \code{ano}.
  }
  \item{ntrunc}{
Number of modes to retain before performing varimax rotation.
  }
}
\value{
  \item{REOFs}{
An array of rotated EOF patterns normalized to 1 (unitless) and then divided by the area weights, 
with dimensions (number of modes, number of latitudes, number of longitues). Multiplying 
\code{REOFs} by \code{RPCs} gives the original reconstructed (filtered) field.
  }
  \item{RPCs}{
An array of rotated pincipal components with the units of the original field to the 
power of 2, with dimensions (number of time steps, number of modes). \code{RPCs} 
contains already the percentage of explained variance so, to reconstruct the 
original field it's only needed to multiply \code{REOFs} by \code{RPCs}. 
  }
  \item{var}{
Percentage (%) of variance fraction of total variance explained by each mode
(number of modes).
  }
  \item{wght}{
Weights with dimensions (number of latitudes, number of longitudes).
  }
}
\examples{
#----------------------------    
## A test for REOF function:
#----------------------------    
## if n.trunc=min(ntime,nlat*nlon), then eofs$RPCs %*% eofs$REOFs should yield the original anomalies
# reofs <- REOF(ano=anom, lon=lon,lat = lat, ntrunc = 35)
# dim(reofs$REOFs) <- c(ntrunc,nlat*nlon)
# anom2 <- reofs$RPCs %*% reofs$REOFs
# max(abs(as.vector(anom)-as.vector(anom2)))
#----------------------------    
# See examples on Load() to understand the first lines in this example
  \dontrun{
data_path <- system.file('sample_data', package = 's2dverification')
expA <- list(name = 'experiment', path = file.path(data_path, 
             'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly',
             '$VAR_NAME$_$START_DATE$.nc'))
obsX <- list(name = 'observation', path = file.path(data_path, 
             '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$',
             '$VAR_NAME$_$YEAR$$MONTH$.nc'))

# Now we are ready to use Load().
startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101')
sampleData <- Load('tos', list(expA), list(obsX), startDates,
                   leadtimemin = 1, leadtimemax = 4, output = 'lonlat',
                   latmin = 27, latmax = 48, lonmin = -12, lonmax = 40)
  }
  \dontshow{
startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101')
sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'),
                                                c('observation'), startDates,
                                                leadtimemin = 1,
                                                leadtimemax = 4,
                                                output = 'lonlat',
                                                latmin = 27, latmax = 48,
                                                lonmin = -12, lonmax = 40)
  }
# This example computes the REOFs along forecast horizons and plots the one that 
# explains the greatest amount of variability. The example data is very low 
# resolution so it does not make a lot of sense.
ano <- Ano_CrossValid(sampleData$mod, sampleData$obs)
reof <- REOF(Mean1Dim(ano$ano_exp, 2)[1, , 1, , ], sampleData$lon, sampleData$lat,10)
PlotEquiMap(reof$REOFs[1, , ], sampleData$lon, sampleData$lat)
}
\author{
History:\cr
0.1  -  2016-105 (Ll. Lledó and N. Cortesi, \email{llledo at bsc.es})  -  Original\cr
code.
1.0  -  2016-05  (N. Manubens, \email{nicolau.manubens at bsc.es})  -  Formatting to R CRAN
}
\seealso{ProjectField, NAO, PlotBoxWhisker}
\keyword{datagen}
