% 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 downscaling method based on analogs: 
synoptic situations and significant predictors.}
\usage{
downscaling_analogs(
  pred_rea,
  pred_mod,
  lon,
  lat,
  nw_ext,
  HR_path,
  tdates,
  ddates,
  restrain
)
}
\arguments{
\item{pred_rea}{List of matrix training period reanalysis data. It contains a fields selection 
of 'pred' training parameter (see 'AnalogsPred_train.R' for more information). The list 
has to contain reanalysis atmospheric variables (instantaneous 12h data) that must be 
indentify by parenthesis name:
- 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) 
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:
- 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) 
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). 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   
maestro file (maestro_red_hr_SPAIN.txt) has gridpoint (nptos), longitude (lon), latitude (lat) and 
altitude (alt) in columns (vector structure).
Data file (pcp_red_SPAIN_1951-201903.txt) includes 5km resolution spanish daily precipitation from 
january 1951 to march 2019. See README file for more information.
IMPORTANT!: The HR observational period must be the same as for the 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 as a result of 
characterize the past synoptic situations and calculate the significant predictors needed to  
downscale seasonal forecast precipitation. 
'restrain' object must contains um, vm, nger, gu92, gv92, gu52, gv52, neni, vdmin, vref, ccm,
lab_pred and cor_pred variables. See 'AnalogsPred_train.R' for more information.}
}
\value{
downscaling_analogs returns seasonal forecast precipitation (mm) in a 5km x 5km regular grid
}
\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: 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(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}
}
