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

\item{pred_rea}{List of matrix training period 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)
- sea level pressure (slp) 
- specific humidity at 700 hPa (q700) 
For maximum and minimum temperature:
- u component of wind at 500 hPa (u500) 
- v component of wind at 500 hPa (v500)
- temperature at 500 hPa (t500) 
- temperature at 700 hPa (t500) 
- temperature at 850 hPa (t850)
- sea level pressure (slp) 
- specific humidity at 700 hPa (q700) 
- 2 meters temperature (tm2m) 
All matrix must have 'nd' x 'ngp + 1' dimensions (nd = number of training days, 
ngp = number of synoptic gridpoints). Ascii files have 'ngp + 1' columns because 
first column must include the date in format %Y%m%d (e.g. 19810101).
Note: If you have already charged the reanalysis predictors in your R session, you just
need to create the pred_rea object as a list that includes proper variables 
(see example 1 below).}

\item{pred_mod}{List of matrix downscaled period seasonal forecast data. The list 
has to contain model atmospheric variables (instantaneous 12h data) that must 
be indentify by parenthesis name.
For precipitation:
- u component of wind at 500 hPa (u500_mod) 
- v component of wind at 500 hPa (v500_mod)
- temperature at 500 hPa (t500_mod) 
- temperature at 850 hPa (t850_mod)
- sea level pressure (extended domain) (slp_ext_mod) 
- specific humidity at 700 hPa (q700_mod) 
For temperature:
- u component of wind at 500 hPa (u500_mod) 
- v component of wind at 500 hPa (v500_mod)
- temperature at 500 hPa (t500_mod) 
- temperature at 700 hPa (t500_mod) 
- temperature at 850 hPa (t850_mod)
- sea level pressure (extended domain) (slp_ext_mod) 
- specific humidity at 700 hPa (q700_mod) 
- 2 meters temperature (tm2m_mod) 
Seasonal forecast variables must have the same resolution and synoptic/extended 
domain as reanalysis variables.
All matrix must have 'nm' x 'ngp + 1' dimensions (nm = number of downscaling 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. The same as for the training function.}

\item{lat}{Vector of the synoptic latitude. The vector must go from north to south.
The same as for the training function.}

\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º). The same as for 
the training function.}

\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-20181231). The same as for the training function.}

\item{ddates}{Downscaling period dates in format %Y%m%d(start)-%Y%m%d(end) (e.g. 20191001-20200331).}

\item{restrain}{List of matrix and parameters obtained from training_analogs. 
For precipitation, 'restrain' object must contains um, vm, nger, gu92, gv92, 
gu52, gv52, neni, vdmin, vref, ccm, lab_pred and cor_pred variables. 
For temperature, 'restrain' object must contains um, vm, insol, neni, vdmin y vref.
See 'AnalogsPred_train.R' for more information.}
}
\value{
downscaling_analogs returns seasonal forecast precipitation (mm) or
maximum and minimum temperature in a 5km x 5km regular grid over peninsular 
Spain and Balearic Islands. The object is a matrix with 'nm' x 'nptos' dimensions.
}
\description{
This function downscales low resolution precipitation data (e.g. from 
Seasonal Forecast Models) through the association with an observational high 
resolution (HR) dataset (AEMET 5 km gridded data of daily precipitation (Peral et al., 2017))
and a collection of predictors and past synoptic situations similar to estimated day. 
The method uses three domains: 
- peninsular Spain and Balearic Islands domain (5 km resolution): HR precipitation 
  and the downscaling result domain. 
- synoptic domain (low resolution, e.g. 1.5º x 1.5º): it should be centered over Iberian Peninsula 
  and cover enough extension to detect as much synoptic situations as possible.  
- extended domain (low resolution, e.g. 1.5º x 1.5): it is an extension of the 
  synoptic domain to west and nothward. See 'nw_ext' parameter below.
}
\examples{
# Example 1 (precipitation): reading both 'pred_rea' and 'pred_mod' lists from ascii files 
#(training period = 200 days).  
#(downscaling period =  70 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)
slp <- matrix(scan("slp.txt"), nrow=200, ncol=541, byrow=TRUE)
q700 <- matrix(scan("q700.txt"), nrow=200, ncol=541, byrow=TRUE)
pred_rea <- list ("u500" = u500,
              "v500" = v500,
              "t500" = t500,
              "t850" = t850,
              "slp" = slp,
              "q700" = q700)
u500_mod <- matrix(scan("u500_mod.txt"), nrow=70, ncol=541, byrow=TRUE)
v500_mod <- matrix(scan("v500_mod.txt"), nrow=70, ncol=541, byrow=TRUE)
t500_mod <- matrix(scan("t500_mod.txt"), nrow=70, ncol=541, byrow=TRUE)
t850_mod <- matrix(scan("t850_mod.txt"), nrow=70, ncol=541, byrow=TRUE)
slp_ext_mod <- matrix(scan("slp_ext_mod.txt"), nrow=70, ncol=926, byrow=TRUE)
q700_mod <- matrix(scan("q700_mod.txt"), nrow=70, ncol=541, byrow=TRUE)
pred_mod <- list ("u500_mod" = u500_mod,
              "v500_mod" = v500_mod,
              "t500_mod" = t500_mod,
              "t850_mod" = t850_mod,
              "slp_ext_mod" = slp_ext_mod,
              "q700_mod" = q700_mod)
HR_path <- "/home/localhrpath/" 
tdates <- "19810101-19810719"
ddates <- "20191001-20191209"
resdowns <- downscaling_analogs(prec,pred_rea, pred_mod, lon, lat, nw_ext, HR_path, tdates, ddates,
                                restrain)
str(resdowns)
num [1:70, 1:20945] 11.567 11.14 26.602 0.042 11.532 ...

}
\author{
Marta Dom\'inguez Alonso - AEMET, \email{mdomingueza@aemet.es}
}
