% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/AnalogsPred_train.R
\name{training_analogs}
\alias{training_analogs}
\title{AEMET Training   
Training method (pre-downscaling) based on analogs: 
synoptic situations and significant predictors.}
\usage{
training_analogs(var, pred, lon, lat, nw_ext, HR_path, tdates)
}
\arguments{
\item{var}{Variable name to downscale. There are two options: 'prec' for
precipitation and 'temp' for maximum and minimum temperature.}

\item{pred}{List of matrix reanalysis data. The list has to contain reanalysis atmospheric variables
(instantaneous 12h data) that must be indentify by parenthesis name.
For precipitation:
- u component of wind at 500 hPa (u500) 
- v component of wind at 500 hPa (v500)
- temperature at 500 hPa (t500) 
- temperature at 850 hPa (t850)
- temperature at 1000 hPa (t1000)
- geopotential at 500 hPa (z500) 
- geopotential at 1000 hPa (z1000) 
- sea level pressure (slp) 
- sea level pressure (extended domain) (slp_ext) 
- specific humidity at 700 hPa (q700) 
For maximum and minimum temperature:
- temperature at 1000 hPa (t1000)
- sea level pressure (slp) 
- sea level pressure (extended domain) (slp_ext) 
All matrix must have 'nd' x 'ngp + 1' dimensions (nd = number of training days, ngp = number of 
synoptic/extended gridpoints). 
Ascii files have 'ngp + 1' columns because first column must include the date in format %Y%m%d (e.g. 19810101)
Consider that 'ngp' of extended domain > 'ngp' of synoptic domain.}

\item{lon}{Vector of the synoptic longitude (from (-180º) to 180º), 
The vector must go from west to east.}

\item{lat}{Vector of the synoptic latitude. The vector must go from north to south.}

\item{nw_ext}{Number of extra degrees adding to north and west synoptic domain
to obtain the extended one. This parameter should be multiple of synoptic grid 
resolution (e.g. nw_ext = 10.5 to ERA Interim 1.5º x 1.5º).}

\item{HR_path}{Local path of HR observational files (maestro and pcp/tmx-tmn). 
For precipitation can be downloaded from http://www.aemet.es/documentos/es/serviciosclimaticos/cambio_climat/datos_diarios/dato_observacional/rejilla_5km/v2/Serie_AEMET_v2_pcp_1951a201903_txt.tar.gz   
For maximum and minimum temperature can be downloaded from XX.
Maestro file (maestro_red_hr_SPAIN.txt) has gridpoint (nptos), longitude (lon), latitude (lat) and 
altitude (alt) in columns (vector structure).
Data file (pcp/tmx/tmn_red_SPAIN_1951-201903.txt) includes 5km resolution spanish daily data 
(precipitation or maximum and minimum temperature from january 1951 to march 2019. See README 
file for more information.
IMPORTANT!: HR observational period must be the same as for reanalysis variables.
It is assumed that the training period is smaller than the HR original one (1951-2019), so it is 
needed to make a new ascii file with the new period and the same structure as original, 
specifying the training dates in the name (e.g. 'pcp_red_SPAIN_19810101-19961231.txt' for 
'19810101-19961231' period). See 'tdates' parameter below.}

\item{tdates}{Training period dates in format %Y%m%d(start)-%Y%m%d(end) (e.g. 19810101-19961231).}
}
\value{
training_analogs() returns a parameters list (e.g. restrain) as a result of 
characterize the past synoptic situations and the significant predictors needed to  
downscale seasonal forecast variables. 
For precipitation the output includes:
um: u component of geostrophic wind in all period (numeric matrix with [nd,ngp] dimensions) 
vm: v component of geostrophic wind in all period (numeric matrix with [nd,ngp] dimensions) 
nger: number of synoptic situations (integer parameter)  
gu92: u component of geostrophic wind for each synoptic situation (numeric matrix with 
      [nger,ngp] dimensions)
gv92: v component of geostrophic wind for each synoptic situation (numeric matrix with
      [nger,ngp] dimensions)
gu52: u component of wind at 500 hPa for each synotic situation (numeric matrix with
      [nger,ngp] dimensions)
gv52: v component of wind at 500 hPa for each synotic situation (numeric matrix with
      [nger,ngp] dimensions)
neni: number of reference centers where predictors are calculated (integer parameter)
vdmin: minimum distances between each HR gridpoint and the four nearest synoptic 
       gridpoints (numeric matrix with [nptos,4] dimensions) (nptos = number of HR gridpoints)
vref: four nearest synoptic gridpoints to each HR gridpoint (integer matrix with 
      [nptos,4] dimensions) 
ccm: multiple correlation coeficients (numeric matrix with [nger,nptos] dimensions)
indices (2 elements corresponding to last dimension): 
        - lab_pred: numeric labels of selected predictors (integer matrix 
                    with [nger,nptos,npx,1] dimensions) 
        - cor_pred: partial correlation of selected predictors (numeric matrix with 
                    [nger,nptos,npx,2] dimensions) 
For maximum and minimum temperature the output includes:
um: u component of geostrophic wind in all training period (numeric matrix with [nd,ngp] dimensions) 
vm: v component of geostrophic wind in all training period (numeric matrix with [nd,ngp] dimensions) 
insol: insolation in all training period (numeric vector with [nd] dimension)
neni: number of reference centers where predictors are calculated (integer parameter)
vdmin: minimum distances between each HR gridpoint and the four nearest synoptic 
       gridpoints (numeric matrix with [nptos,4] dimensions) (nptos = number of HR gridpoints)
vref: four nearest synoptic gridpoints to each HR gridpoint (integer matrix with 
      [nptos,4] dimensions) 

The output can directly use as argument to 'downscaling_analogs' function 
(e.g. resdowns <- downscaling_analogs(...,restrain))
}
\description{
This function caracterizes the synoptic situations in a past period based on 
low resolution reanalysis data (e.g, ERAInterim 1.5km x 1.5km) and an observational high 
resolution (HR) dataset (AEMET 5 km gridded daily precipitation and maximum and 
minimum temperature) (Peral et al., 2017)). 
The method uses three domains: 
- peninsular Spain and Balearic Islands domain (5 km resolution): HR domain
- synoptic domain (low resolution): it should be centered over Iberian Peninsula and 
  cover enough extension to detect as much synoptic situations as possible.  
- extended domain (low resolution): it is an extension of the synoptic 
  domain to west and nothward. See 'nw_ext' parameter below.
}
\examples{
# Example 1 (precipitation): 'pred' list from ascii reanalysis files (training period = 200 days).  
lon <- seq(from = -28.5, to = 15, by = 1.5)
lat <- seq(from = 55.5, to = 30, by = -1.5)  
nw_ext <- 10.5
u500 <- matrix(scan("u500.txt"), nrow=200, ncol=541, byrow=TRUE)
v500 <- matrix(scan("v500.txt"), nrow=200, ncol=541, byrow=TRUE)
t500 <- matrix(scan("t500.txt"), nrow=200, ncol=541, byrow=TRUE)
t850 <- matrix(scan("t850.txt"), nrow=200, ncol=541, byrow=TRUE)
t1000 <- matrix(scan("t1000.txt"), nrow=200, ncol=541, byrow=TRUE)
z500 <- matrix(scan("z500.txt"), nrow=200, ncol=541, byrow=TRUE)
z1000 <- matrix(scan("z1000.txt"), nrow=200, ncol=541, byrow=TRUE)
slp <- matrix(scan("slp.txt"), nrow=200, ncol=541, byrow=TRUE)
slp_ext <- matrix(scan("slp_ext.txt"), nrow=200, ncol=926, byrow=TRUE)
q700 <- matrix(scan("q700.txt"), nrow=200, ncol=541, byrow=TRUE)
pred <- list ("u500" = u500,
              "v500" = v500,
              "t500" = t500,
              "t850" = t850,
              "t1000" = t1000,
              "z500" = z500,
              "z1000" = z1000,
              "slp" = slp,
              "slp_ext" = slp_ext,
              "q700" = q700)
HR_path <- "/home/localhrpath/" 
tdates <- "19810101-19810719"
restrain <- training_analogs(prec, pred, lon, lat, nw_ext, HR_path, tdates)
str(restrain)
List of 12
 $ um     : num [1:200, 1:540] 24.26 22.17 -11.29 11.46 9.76 ...
 $ vm     : num [1:200, 1:540] 14.572 0.435 -0.433 0 10.768 ...
 $ nger   : int 94
 $ gu92   : num [1:94, 1:540] 20.21 5.19 10.6 6.47 12.04 ...
 $ gv92   : num [1:94, 1:540] 6.155 4.459 15.211 -0.132 6.413 ...
 $ gu52   : num [1:94, 1:540] 41.9 25.9 25.9 20.9 16.1 ...
 $ gv52   : num [1:94, 1:540] 16.27 11.5 19.96 12.04 8.41 ...
 $ neni   : int 74
 $ vdmin  : num [1:20945, 1:4] 77 56.6 62.1 33.8 39.3 ...
 $ vref   : int [1:20945, 1:4] 408 406 406 406 406 406 406 406 406 406 ...
 $ ccm    : num [1:94, 1:20945] 0.452 0.452 0.452 0.452 0.452 ...
 $ indices: num [1:94, 1:20945, 1:11, 1:2] 1 1 1 1 1 1 1 1 1 1 ...
  ..- attr(*, "dimnames")=List of 4
  .. ..$ : NULL
  .. ..$ : NULL
  .. ..$ : NULL
  .. ..$ : chr [1:2] "lab_pred" "cor_pred"
}
\author{
Marta Dom\'inguez Alonso - AEMET, \email{mdomingueza@aemet.es}
}
