RunModel_CemaNeigeGR4J.Rd 10.7 KB
Newer Older
Delaigue Olivier's avatar
Delaigue Olivier committed
1
\encoding{UTF-8}
2
3


Delaigue Olivier's avatar
Delaigue Olivier committed
4
5
\name{RunModel_CemaNeigeGR4J}
\alias{RunModel_CemaNeigeGR4J}
6
7


Delaigue Olivier's avatar
Delaigue Olivier committed
8
\title{Run with the CemaNeigeGR4J hydrological model}
9
10


Delaigue Olivier's avatar
Delaigue Olivier committed
11
\usage{
12
RunModel_CemaNeigeGR4J(InputsModel, RunOptions, Param, IsHyst = FALSE)
Delaigue Olivier's avatar
Delaigue Olivier committed
13
}
14
15


Delaigue Olivier's avatar
Delaigue Olivier committed
16
17
18
19
20
\arguments{
\item{InputsModel}{[object of class \emph{InputsModel}] see \code{\link{CreateInputsModel}} for details}

\item{RunOptions}{[object of class \emph{RunOptions}] see \code{\link{CreateRunOptions}} for details}

21
\item{Param}{[numeric] vector of 6 (or 8 parameters if \code{IsHyst = TRUE})
Delaigue Olivier's avatar
Delaigue Olivier committed
22
\tabular{ll}{                                                                      
23
24
25
26
27
28
29
30
GR4J X1      \tab production store capacity [mm]                                          \cr
GR4J X2      \tab intercatchment exchange coefficient [mm/d]                              \cr
GR4J X3      \tab routing store capacity [mm]                                             \cr
GR4J X4      \tab unit hydrograph time constant [d]                                       \cr
CemaNeige X1 \tab weighting coefficient for snow pack thermal state [-]                   \cr
CemaNeige X2 \tab degree-day melt coefficient [mm/°C/d]                                   \cr
CemaNeige X3 \tab (optional) accumulation threshold [mm] (needed if \code{IsHyst = TRUE}) \cr
CemaNeige X4 \tab (optional) percentage (between 0 and 1) of annual snowfall defining the melt threshold [-] (needed if \code{IsHyst = TRUE}) \cr
Delaigue Olivier's avatar
Delaigue Olivier committed
31
}}
32
33

\item{IsHyst}{}
Delaigue Olivier's avatar
Delaigue Olivier committed
34
}
35
36


Delaigue Olivier's avatar
Delaigue Olivier committed
37
\value{
Delaigue Olivier's avatar
Delaigue Olivier committed
38
39
[list] list containing the function outputs organised as follows:                                         
         \tabular{ll}{                                                                                         
Delaigue Olivier's avatar
Delaigue Olivier committed
40
41
42
         \emph{$DatesR  }          \tab [POSIXlt] series of dates                                                     \cr
         \emph{$PotEvap }          \tab [numeric] series of input potential evapotranspiration [mm/d]                 \cr
         \emph{$Precip  }          \tab [numeric] series of input total precipitation [mm/d]                          \cr
43
         \emph{$Prod    }          \tab [numeric] series of production store level [mm]                        \cr
44
         \emph{$Pn      }          \tab [numeric] series of net rainfall [mm/d]                         			  \cr
45
         \emph{$Ps      }          \tab [numeric] series of the part of Pn filling the production store [mm/d]        \cr
Delaigue Olivier's avatar
Delaigue Olivier committed
46
47
         \emph{$AE      }          \tab [numeric] series of actual evapotranspiration [mm/d]                          \cr
         \emph{$Perc    }          \tab [numeric] series of percolation (PERC) [mm/d]                                 \cr
48
         \emph{$PR      }          \tab [numeric] series of PR=Pn-Ps+Perc [mm/d]                                      \cr
49
50
51
         \emph{$Q9      }          \tab [numeric] series of UH1 outflow (Q9) [mm/d]                                   \cr
         \emph{$Q1      }          \tab [numeric] series of UH2 outflow (Q1) [mm/d]                                   \cr
         \emph{$Rout    }          \tab [numeric] series of routing store level [mm]                           \cr
Delaigue Olivier's avatar
Delaigue Olivier committed
52
         \emph{$Exch    }          \tab [numeric] series of potential semi-exchange between catchments [mm/d]         \cr
53
54
         \emph{$AExch1  }          \tab [numeric] series of actual exchange between catchments for branch 1 [mm/d]    \cr
         \emph{$AExch2  }          \tab [numeric] series of actual exchange between catchments for branch 2 [mm/d]    \cr
Delaigue Olivier's avatar
Delaigue Olivier committed
55
56
         \emph{$AExch   }          \tab [numeric] series of actual exchange between catchments (1+2) [mm/d]           \cr
         \emph{$QR      }          \tab [numeric] series of routing store outflow (QR) [mm/d]                         \cr
57
         \emph{$QD      }          \tab [numeric] series of direct flow from UH2 after exchange (QD) [mm/d]           \cr
58
         \emph{$Qsim    }          \tab [numeric] series of simulated discharge [mm/d]                                               \cr
Delaigue Olivier's avatar
Delaigue Olivier committed
59
60
61
62
         \emph{$CemaNeigeLayers}   \tab [list] list of CemaNeige outputs (1 list per layer)                          \cr
         \emph{$CemaNeigeLayers[[iLayer]]$Pliq         }   \tab [numeric] series of liquid precip. [mm/d]                          \cr
         \emph{$CemaNeigeLayers[[iLayer]]$Psol         }   \tab [numeric] series of solid precip. [mm/d]                           \cr
         \emph{$CemaNeigeLayers[[iLayer]]$SnowPack     }   \tab [numeric] series of snow pack [mm]                                 \cr
63
         \emph{$CemaNeigeLayers[[iLayer]]$ThermalState }   \tab [numeric] series of snow pack thermal state [°C]                 \cr
Delaigue Olivier's avatar
Delaigue Olivier committed
64
65
66
67
         \emph{$CemaNeigeLayers[[iLayer]]$Gratio       }   \tab [numeric] series of Gratio [0-1]                                   \cr
         \emph{$CemaNeigeLayers[[iLayer]]$PotMelt      }   \tab [numeric] series of potential snow melt [mm/d]                     \cr
         \emph{$CemaNeigeLayers[[iLayer]]$Melt         }   \tab [numeric] series of actual snow melt [mm/d]                        \cr
         \emph{$CemaNeigeLayers[[iLayer]]$PliqAndMelt  }   \tab [numeric] series of liquid precip. + actual snow melt [mm/d]       \cr
68
         \emph{$CemaNeigeLayers[[iLayer]]$Temp         }   \tab [numeric] series of air temperature [°C] \cr     
69
70
         \emph{$CemaNeigeLayers[[iLayer]]$Gthreshold   }   \tab [numeric] series of melt threshold [mm] \cr
         \emph{$CemaNeigeLayers[[iLayer]]$Glocalmax    }   \tab [numeric] series of local melt threshold for hysteresis [mm] \cr
71
         \emph{$StateEnd}                                  \tab [numeric] states at the end of the run: \cr\tab store & unit hydrographs levels [mm], CemaNeige states [mm & °C], \cr\tab see \code{\link{CreateIniStates}} for more details \cr
Delaigue Olivier's avatar
Delaigue Olivier committed
72
         }                                                                                                     
Delaigue Olivier's avatar
Delaigue Olivier committed
73
74
         (refer to the provided references or to the package source code for further details on these model outputs)
}
75
76


Delaigue Olivier's avatar
Delaigue Olivier committed
77
\description{
78
Function which performs a single run for the CemaNeige-GR4J daily lumped model over the test period.
Delaigue Olivier's avatar
Delaigue Olivier committed
79
}
80
81


Delaigue Olivier's avatar
Delaigue Olivier committed
82
\details{
83
84
85
If \code{IsHyst = FALSE}, the original CemaNeige version from Valéry et al. (2014) is used.  \cr
If \code{IsHyst = TRUE}, the CemaNeige version from Riboust et al. (2019) is used. Compared to the original version, this version of CemaNeige needs two more parameters and it includes a representation of the hysteretic relationship between the Snow Cover Area (SCA) and the Snow Water Equivalent (SWE) in the catchment. The hysteresis included in airGR is the Modified Linear hysteresis (LH*); it is represented on panel b) of Fig. 3 in Riboust et al. (2019). Riboust et al. (2019) advise to use the LH* version of CemaNeige with parameters calibrated using an objective function combining 75 \% of KGE calculated on discharge simulated from a rainfall-runoff model compared to observed discharge and 5 \% of KGE calculated on SCA on 5 CemaNeige elevation bands compared to satellite (e.g. MODIS) SCA (see Eq. (18), Table 3 and Fig. 6). Riboust et al. (2019)'s tests were realized with GR4J as the chosen rainfall-runoff model. \cr \cr
For further details on the model, see the references section. \cr
Delaigue Olivier's avatar
Delaigue Olivier committed
86
87
For further details on the argument structures and initialisation options, see \code{\link{CreateRunOptions}}.
}
88
89


Delaigue Olivier's avatar
Delaigue Olivier committed
90
\examples{
91
library(airGR)
unknown's avatar
unknown committed
92
93

## loading catchment data
Delaigue Olivier's avatar
Delaigue Olivier committed
94
95
96
data(L0123002)

## preparation of the InputsModel object
97
98
InputsModel <- CreateInputsModel(FUN_MOD = RunModel_CemaNeigeGR4J, DatesR = BasinObs$DatesR, 
                                 Precip = BasinObs$P, PotEvap = BasinObs$E, TempMean = BasinObs$T, 
99
                                 ZInputs = median(BasinInfo$HypsoData),
100
                                 HypsoData = BasinInfo$HypsoData, NLayers = 5)
Delaigue Olivier's avatar
Delaigue Olivier committed
101
102

## run period selection
103
104
Ind_Run <- seq(which(format(BasinObs$DatesR, format = "\%d/\%m/\%Y")=="01/01/1990"), 
               which(format(BasinObs$DatesR, format = "\%d/\%m/\%Y")=="31/12/1999"))
Delaigue Olivier's avatar
Delaigue Olivier committed
105
106

## preparation of the RunOptions object
107
108
RunOptions <- CreateRunOptions(FUN_MOD = RunModel_CemaNeigeGR4J, InputsModel = InputsModel, 
                               IndPeriod_Run = Ind_Run)
Delaigue Olivier's avatar
Delaigue Olivier committed
109
110

## simulation
111
112
113
Param <- c(408.774, 2.646, 131.264, 1.174, 0.962, 2.249)
OutputsModel <- RunModel_CemaNeigeGR4J(InputsModel = InputsModel,
                                       RunOptions = RunOptions, Param = Param)
Delaigue Olivier's avatar
Delaigue Olivier committed
114
115

## results preview
116
plot(OutputsModel, Qobs = BasinObs$Qmm[Ind_Run])
Delaigue Olivier's avatar
Delaigue Olivier committed
117
118

## efficiency criterion: Nash-Sutcliffe Efficiency
119
InputsCrit  <- CreateInputsCrit(FUN_CRIT = ErrorCrit_NSE, InputsModel = InputsModel, 
120
                                RunOptions = RunOptions, obs = BasinObs$Qmm[Ind_Run], varObs = "Q")
121
OutputsCrit <- ErrorCrit_NSE(InputsCrit = InputsCrit, OutputsModel = OutputsModel)
Delaigue Olivier's avatar
Delaigue Olivier committed
122
}
123
124


125
126
127
128
129
130
131
132
133
134
135
136
137
138
## simulation with the Linear Hysteresis
Param <- c(408.774, 2.646, 131.264, 1.174, 0.962, 2.249, 100, 0.4)
OutputsModel <- RunModel_CemaNeigeGR4J(InputsModel = InputsModel,
                                       RunOptions = RunOptions, Param = Param, IsHyst = TRUE)

## results preview
plot(OutputsModel, Qobs = BasinObs$Qmm[Ind_Run])

## efficiency criterion: Nash-Sutcliffe Efficiency
InputsCrit  <- CreateInputsCrit(FUN_CRIT = ErrorCrit_NSE, InputsModel = InputsModel, 
                                RunOptions = RunOptions, obs = BasinObs$Qmm[Ind_Run], varObs = "Q")
OutputsCrit <- ErrorCrit_NSE(InputsCrit = InputsCrit, OutputsModel = OutputsModel)


Delaigue Olivier's avatar
Delaigue Olivier committed
139
\author{
140
Laurent Coron, Audrey Valéry, Claude Michel, Charles Perrin, Vazken Andréassian, Olivier Delaigue
Delaigue Olivier's avatar
Delaigue Olivier committed
141
}
142
143


Delaigue Olivier's avatar
Delaigue Olivier committed
144
\references{
Delaigue Olivier's avatar
Delaigue Olivier committed
145
146
Perrin, C., C. Michel and V. Andréassian (2003), 
      Improvement of a parsimonious model for streamflow simulation, 
Delaigue Olivier's avatar
Delaigue Olivier committed
147
      Journal of Hydrology, 279(1-4), 275-289, doi:10.1016/S0022-1694(03)00225-7. \cr
148
149
150
151
Riboust, P., G. Thirel, N. Le Moine and P. Ribstein (2019), 
      Revisiting a simple degree-day model for integrating satellite data: implementation of SWE-SCA hystereses.
      Journal of Hydrology and Hydromechanics, doi:10.2478/johh-2018-0004, 67, 1, 70–81. \cr
Valéry, A., V. Andréassian and C. Perrin (2014), 
Delaigue Olivier's avatar
Delaigue Olivier committed
152
      "As simple as possible but not simpler": what is useful in a temperature-based snow-accounting routine? 
Delaigue Olivier's avatar
Delaigue Olivier committed
153
      Part 1 - Comparison of six snow accounting routines on 380 catchments, Journal of Hydrology, doi:10.1016/j.jhydrol.2014.04.059. \cr
154
Valéry, A., V. Andréassian and C. Perrin (2014), 
Delaigue Olivier's avatar
Delaigue Olivier committed
155
      "As simple as possible but not simpler": What is useful in a temperature-based snow-accounting routine? 
Delaigue Olivier's avatar
Delaigue Olivier committed
156
157
      Part 2 - Sensitivity analysis of the Cemaneige snow accounting routine on 380 catchments, Journal of Hydrology, doi:10.1016/j.jhydrol.2014.04.058.
}
158
159


Delaigue Olivier's avatar
Delaigue Olivier committed
160
\seealso{
161
\code{\link{RunModel_CemaNeige}}, \link{RunModel_CemaNeigeGR5J}}, \code{\link{RunModel_CemaNeigeGR6J}}, \code{\link{RunModel_GR4J}},
162
         \code{\link{CreateInputsModel}}, \code{\link{CreateRunOptions}}, \code{\link{CreateIniStates}}.
Delaigue Olivier's avatar
Delaigue Olivier committed
163
164
}