DataAltiExtrapolation_HBAN.R

#*****************************************************************************************************************
#' Function which extrapolates the precipitation and air temperature series for different elevation layers (method from Valery, 2010).
#'
#' Elevation layers of equal surface are created the 101 elevation quantiles (\emph{HypsoData}) 
#' and the number requested elevation layers (\emph{NLayers}). \cr
#' Forcing data (precipitation and air temperature) are extrapolated using gradients from Valery (2010).
#' (e.g. gradP=0.0004 [m-1] for France and gradT=0.434 [degreC/100m] for January, 1st). \cr
#' This function is used by the \emph{CreateInputsModel} function. \cr
#*****************************************************************************************************************
#' @title   Altitudinal extrapolation of precipitation and temperature series
#' @author  Laurent Coron, Pierre Brigode (June 2014)
#' @references
#'   Turcotte, R., L.-G. Fortin, V. Fortin, J.-P. Fortin and J.-P. Villeneuve (2007), 
#'       Operational analysis of the spatial distribution and the temporal evolution of the snowpack water equivalent 
#'       in southern Quebec, Canada, Nordic Hydrology, 38(3), 211, doi:10.2166/nh.2007.009. \cr
#'   Valéry, A. (2010), Modélisation précipitations-débit sous influence nivale ? : Elaboration d'un module neige 
#'       et évaluation sur 380 bassins versants, PhD thesis (in french), AgroParisTech, Paris, France. \cr
#'   USACE (1956), Snow Hydrology, pp. 437, U.S. Army Coprs of Engineers (USACE) North Pacific Division, Portland, Oregon, USA.
#' @seealso \code{\link{CreateInputsModel}}, \code{\link{RunModel_CemaNeigeGR4J}}
#' @encoding UTF-8
#' @export
#_FunctionInputs__________________________________________________________________________________________________
#' @param  DatesR      [POSIXlt] vector of dates
#' @param  Precip      [numeric] time series of daily total precipitation (catchment average) [mm]
#' @param  TempMean    [numeric] time series of daily mean air temperature [degC]
#' @param  TempMin     (optional) [numeric] time series of daily min air temperature [degC]
#' @param  TempMax     (optional) [numeric] time series of daily max air temperature [degC]
#' @param  ZInputs     [numeric] real giving the mean elevation of the Precip and Temp series (before extrapolation) [m]
#' @param  HypsoData   [numeric] vector of 101 reals: min, q01 to q99 and max of catchment elevation distribution [m]
#' @param  NLayers     [numeric] integer giving the number of elevation layers requested [-]
#' @param  quiet       (optional) [boolean] boolean indicating if the function is run in quiet mode or not, default=FALSE
#_FunctionOutputs_________________________________________________________________________________________________
#' @return  list containing the extrapolated series of precip. and air temp. on each elevation layer
#'          \tabular{ll}{                                                                                                      
#'            \emph{$LayerPrecip         }  \tab  [list] list of time series of daily precipitation (layer average) [mm]           \cr
#'            \emph{$LayerTempMean       }  \tab  [list] list of time series of daily mean air temperature (layer average) [degC]  \cr
#'            \emph{$LayerTempMin        }  \tab  [list] list of time series of daily min air temperature (layer average) [degC]   \cr
#'            \emph{$LayerTempMax        }  \tab  [list] list of time series of daily max air temperature (layer average) [degC]   \cr
#'            \emph{$LayerFracSolidPrecip}  \tab  [list] list of time series of daily solid precip. fract. (layer average) [-]     \cr
#'            \emph{$ZLayers             }  \tab  [numeric] vector of median elevation for each layer                              \cr
#'          }                                                                                                                  
#*****************************************************************************************************************
DataAltiExtrapolation_HBAN <- function(DatesR,Precip,TempMean,TempMin=NULL,TempMax=NULL,ZInputs,HypsoData,NLayers,quiet=FALSE){


    ##Altitudinal_gradient_functions_______________________________________________________________
      ##unique_gradient_for_precipitation
      GradP_Valery2010 <- function(){ 
        return(0.00041); ### value from Val? PhD thesis page 126
      }
      ##daily_gradients_for_mean_min_and_max_air_temperature
      GradT_Valery2010 <- function(){ 
        RESULT <- matrix(c(
               1,  1, 0.434, 0.366, 0.498,
               2,  1, 0.434, 0.366, 0.500,
               3,  1, 0.435, 0.367, 0.501,
               4,  1, 0.436, 0.367, 0.503,
               5,  1, 0.437, 0.367, 0.504,
               6,  1, 0.439, 0.367, 0.506,
               7,  1, 0.440, 0.367, 0.508,
               8,  1, 0.441, 0.368, 0.510,
               9,  1, 0.442, 0.368, 0.512,
              10,  1, 0.444, 0.368, 0.514,
              11,  1, 0.445, 0.368, 0.517,
              12,  1, 0.446, 0.368, 0.519,
              13,  1, 0.448, 0.369, 0.522,
              14,  1, 0.450, 0.369, 0.525,
              15,  1, 0.451, 0.369, 0.527,
              16,  1, 0.453, 0.370, 0.530,
              17,  1, 0.455, 0.370, 0.533,