docs(vignette): adding caramel for multiobjective optimization

vignettes/V02.1_param_optim.Rmd

 ---
 title: "Plugging in new calibration algorithms in airGR"
-author: "François Bourgin"
 output: rmarkdown::html_vignette
 vignette: >
   %\VignetteEngine{knitr::rmarkdown}
@@ -15,6 +14,9 @@ library(airGR)
 library(DEoptim)
 library(hydroPSO) # Needs R version >= 3.6 or latticeExtra <= 0.6-28 on R 3.5
 library(Rmalschains)
+library(caRamel)
+library(ggplot2)
+library(GGally)
 # source("airGR.R")
 set.seed(321)
 load(system.file("vignettesData/vignetteParamOptim.rda", package = "airGR"))
@@ -172,4 +174,95 @@ resGLOB
 <!-- This is an expected result because the response surface for quadratic performance criteria of the **GR4J** model is generally sufficiently well defined in the transformed parameter space to allow using a local optimization strategy instead of a more time consuming global optimization strategy. -->
 
 
+# Multiobjective optimization
+
+Multiobjective optimization is used to explore possible trade-offs between different performances criteria.
+Here we use the following R implementation of an efficient strategy:
+* [caRamel: Automatic Calibration by Evolutionary Multi Objective Algorithm](https://cran.r-project.org/package=caRamel)
+
+Motivated by using the rainfall-runoff model for low flow simulation, we explore the trade-offs between the KGE values obtained without any data transformation and with the inverse transformation.
+
+First, the OptimGR4J function previously used is modified to return two values.
+
+```{r, warning=FALSE, results='hide', eval=FALSE}
+InputsCrit_inv <- InputsCrit
+InputsCrit_inv$transfo <- "inv"
+  
+MOptimGR4J <- function(i) {
+  
+  if (algo == "caRamel") ParamOptim = x[i, ]
+  
+  ## Transformation of the parameter set to real space
+  RawParamOptim <- airGR::TransfoParam_GR4J(ParamIn = ParamOptim,
+                                            Direction = "TR")
+  ## Simulation given a parameter set
+  OutputsModel <- airGR::RunModel_GR4J(InputsModel = InputsModel,
+                                       RunOptions = RunOptions,
+                                       Param = RawParamOptim)
+  ## Computation of the value of the performance criteria
+  OutputsCrit1 <- airGR::ErrorCrit_KGE(InputsCrit = InputsCrit,
+                                       OutputsModel = OutputsModel,
+                                       verbose = FALSE)
+  ## Computation of the value of the performance criteria
+  OutputsCrit2 <- airGR::ErrorCrit_KGE(InputsCrit = InputsCrit_inv,
+                                       OutputsModel = OutputsModel,
+                                       verbose = FALSE)
+  return(c(OutputsCrit1$CritValue, OutputsCrit2$CritValue))
+}
+```
+
+## caRamel
+caRamel is a multiobjective evolutionary algorithm combining the MEAS algorithm and the NGSA-II algorithm.
+
+```{r, warning=FALSE, results='hide', eval=FALSE}
+algo <- "caRamel"
+optMO <- caRamel::caRamel(nobj = 2,
+                          nvar = 4,
+                          minmax = rep(TRUE, 2),
+                          bounds = matrix(c(lowerGR4J, upperGR4J), ncol = 2),
+                          func = MOptimGR4J,
+                          popsize = 100,
+                          archsize = 100,
+                          maxrun = 15000,
+                          prec = rep(1.e-3,2),
+                          carallel = FALSE,
+                          graph = FALSE)
+```
+
+The algorithm returns parameter sets that describe the pareto front, illustrating the trade-off between overall good performance and good performance for low flow.
+
+```{r, fig.width=6, fig.height=6, warning=FALSE}
+ggplot() + 
+  geom_point(aes(optMO$objectives[, 1], optMO$objectives[, 2])) +
+  coord_equal(xlim = c(0.4,0.9), ylim= c(0.4, 0.9)) + 
+  xlab("KGE") + ylab("KGE_inv") +
+  theme_bw()
+```
+
+The pameter sets can be viewed in the parameter space, illustrating different populations.
+
+```{r fig.height=6, fig.width=6, message=FALSE, warning=FALSE}
+param_optMO = apply(optMO$parameters, 1, FUN = function(x) {
+  airGR::TransfoParam_GR4J(x, Direction = "TR")})
+ggpairs(data.frame(t(param_optMO)), diag = NULL) + theme_bw()
+```
+
+```{r fig.height=6, fig.width=12, message=FALSE, warning=FALSE}
+RunOptions$Outputs_Sim = "Qsim"
+run_optMO = apply(optMO$parameters, 1, FUN = function(x) {
+  airGR::RunModel_GR4J(InputsModel = InputsModel,
+                       RunOptions = RunOptions,
+                       x)}$Qsim)
+run_optMO = data.frame(run_optMO)
+
+ggplot() +
+  geom_line(aes(x=as.POSIXct(InputsModel$DatesR[Ind_Run]), y=run_optMO$X1)) +
+  geom_line(aes(x=as.POSIXct(InputsModel$DatesR[Ind_Run]), y=run_optMO$X54), colour="darkred") +
+  scale_x_datetime(limits = c(as.POSIXct("1998-01-01"), NA)) +
+  ylab("Discharge [mm/d]") + xlab("Date") +
+  scale_y_sqrt() +
+  theme_classic()
+```
+
+
 

vignettes/V02.2_param_mcmc.Rmd

 ---
 title: "Parameter estimation within a Bayesian MCMC framework"
-author: "François Bourgin"
 output: rmarkdown::html_vignette
 vignette: >
   %\VignetteEngine{knitr::rmarkdown}

[Delaigue Olivier]

@francois.bourgin, I would prefer that your name appears in the vignettes you have written. I think it's normal to notify your contribution, and it's a way to thank you for it. I think it's also good idea for the tracking history. But if you do not agree, I will respect your wishes. Tell me what you think about.

David's name is on the SD vignette. And I think I'll add the missing names of the writers of the other vignettes.

[François Bourgin]

I see it as a small contribution to a team effort and I think it is better if the vignettes are endorsed by the authors of the package and do not appear as some personal contribution. But I don't really care, it's up to you.

[Dorchies David]

I agree with @francois.bourgin.

I didn't think that we could be possible to have several authors on a vignette. But yes, we can : https://bookdown.org/yihui/rmarkdown-cookbook/multiple-authors.html

[Delaigue Olivier]

In fact, Laurent noted the contributors of each functions in the help pages and we continue to do this. I think we can do it for each vignette as well. For the "param_optim" vignette we can note both François and @guillaume.thirel.

[Delaigue Olivier]

By the way François, your name has been in the list of package contributors for a long time (in the DESCRPTION file.)

[François Bourgin]

Ok, great. If I may, I would suggest to also consider the more substancial contributions of Andrea and Philippe.