---
title: "Using the devRate package to simulate the phenology of *Helicoverpa armigera*"
author: "François Rebaudo ; IRD UMR EGCE"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{sec02}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

This vignette exemplifies the use of the devRate package to simulate 
*Helicoverpa armigera* phenology using thermal performance curves available 
in the literature.

```{r, "r001"}
require("devRate")
```

## 1. Models published in the literature

Numerous models have been developed to simulate the phenology of 
*Helicoverpar armigera*. Most are based on the characterization of development 
as a function of temperature. Insects are reared at various constant 
temperatures under laboratory conditions, then a model is fitted to the data 
to obtain a thermal performance curve. The various publications for which 
models were retrievable are listed in Table 1.

__Table 1.__ Models for *Helicoverpa armigera*

| Ref                                    | DOI                              | Function name in devRate|
|----------------------------------------|----------------------------------|-------------------------|
| Bartekova and Praslicka, 2006          |10.17221/2768-PPS                 |ha_bartekova2006         |
| Jallow and Matsumura, 2001             |10.1303/aez.2001.427              |ha_jallow2001            |
| Mironidis and Savopoulou-Soultani, 2008|10.1093/ee/37.1.16                |ha_mironidis2008_ls      |
| Mironidis and Savopoulou-Soultani, 2008|10.1093/ee/37.1.16                |ha_mironidis2008_nls     |
| Foley, 1981                            |10.1111/j.1440-6055.1981.tb00993.x|ha_foley1981             |
| Kay, 1981                              |10.1111/j.1440-6055.1981.tb01020.x|ha_kay1981_ls            |
| Kay, 1981                              |10.1111/j.1440-6055.1981.tb01020.x|ha_kay1981_nls           |
| Noor-ul-Ane et al., 2018               |10.1017/S0007485317000724         |ha_noorulane2018_ls      |
| Noor-ul-Ane et al., 2018               |10.1017/S0007485317000724         |ha_noorulane2018_nls     |
| Qureshi et al., 1999                   |10.1303/aez.34.327                |ha_qureshi1999_ls        |
| Ahmad 2024                             |10.21203/rs.3.rs-4845823/v1       |ha_ahmad2024_ls          |

Each model is implemented in this package as a function that returns a list 
object. Each list is composed of two elements: the first contains the 
mathematical equation used and the second a list of the parameters of the 
mathematical equation for each life stage of the insect. The life stages 
available, the models, and the number of temperatures used for fitting are 
shown in Table 2.

__Table 2.__ Model specifications for *Helicoverpa armigera*

| Name                | Type      |Temperature (Celsius)                                        | Life stages            |
|---------------------|-----------|-------------------------------------------------------------|------------------------|
| ha_bartekova2006    |Campbell   |20, 25, 30 (3)                                               | eggs, larvae, pupae (3)|
| ha_jallow2001       |Campbell   |10, 13.3, 16.4, 20, 22.5, 25, 27.9, 30.5, 32.5 (9)           | eggs, larvae, pupae (3)|
| ha_mironidis2008_ls |Campbell   |10, 12.5, 15, 17.5, 20, 25, 27.5, 30, 32.5, 35, 37.5, 40 (12)| eggs, larvae, pupae (3)|
| ha_mironidis2008_nls|Lactin-2   |10, 12.5, 15, 17.5, 20, 25, 27.5, 30, 32.5, 35, 37.5, 40 (12)| eggs, larvae, pupae (3)|
| ha_foley1981        |Campbell   |20, 24, 28, 32 (4)                      | post-diapausing and non-diapausing pupae (2)|
| ha_kay1981_ls       |Campbell   |8, 10, 13.3, 17.8, 20.8, 24.4, 27.2, 31.4, 35, 39.4 (10)     | eggs (1)               |
| ha_kay1981_nls      |Davidson   |8, 10, 13.3, 17.8, 20.8, 24.4, 27.2, 31.4, 35, 39.4 (10)     | eggs (1)               |
| ha_noorulane2018_ls |Campbell   |10, 15, 17.5, 20, 25, 27.5, 30, 35, 37.5, 40 (10)            | eggs, larvae, pupae (3)|
| ha_noorulane2018_nls|Briere-2   |10, 15, 17.5, 20, 25, 27.5, 30, 35, 37.5, 40 (10)            | overall (1)            |
| ha_qureshi1999_ls   |Campbell   |15, 20, 25, 30 (4)                                           | eggs, larvae, pupae (3)|
| ha_ahmad2024_ls     |Campbell   |14, 16, 18, 20, 22, 25, 27, 30, 32, 35, 36 (11)              | eggs, l1:6, prepupae, pupae (9)|

## 2. Simulating phenology

Based on the relationship between development and temperature, and on a 
temperature time series, it is then possible to run simulations of the pest's 
phenology.

### 2.1. Temperature time series

Any temperature time series can be used to simulate pest phenology. In the 
following simulations, the time step is expressed in days. If the temperature 
time series has a time step of 1h, a time step of 1/24 should be 
specified. In this example, we'll simulate a theoretical temperature time 
series using a random generation for the normal distribution with mean equal 
to 25 and standard deviation equal to 2 (90 days with one temperature data 
every 6 hours ; 90x4 temperature values).

```{r, "r002", fig.width=7, fig.height=4}
temp <- stats::rnorm(n = 90*4, mean = 25, sd = 2)
par(mar = c(4, 4, 0, 0))
plot(
  x = temp, type = "o", 
  xlab = "Time (6 hours time step)", ylab = "Temperature",
  ylim = c(15, 35)
)
```

### 2.2. Model selection and computation

Now we can run simulations, selecting our temperature time series and the 
models of our choice.

#### 2.2.1. Simulation using a single model

```{r, "r003", fig.width=7, fig.height=4}
set.seed(1234)

# Using Bartekova and Praslicka, 2006 model
my_model <- ha_bartekova2006()

# This model was designed for eggs, larvae and pupae, using simple linear
# regression models (following Campbell 1974).
forecastX <- devRateIBMparam(
  tempTS = temp, # the temperature time series described above
  timeStepTS = 1/4, # we  have 4 temperature values per day (every 6 hours)
  eq = list("campbell_74", "campbell_74", "campbell_74"), # the model eq for
    # the three life stages
  myParam = list(
    my_model[["model"]]$pupa, # starting with pupae
    my_model[["model"]]$egg,  # then adults and eggs
    my_model[["model"]]$larva # then larvae and the cycle goes on
  ),
  adultLifeStage = 1, # adult life stage after the first model step (pupae 
    # to adults)
  timeLayEggs = 10, # adults longevity fixed to 10 days
  numInd = 10, # 10 individuals for the simulation
  stocha = 0.05 # a bit of intra-population variability
)
```

The result of the simulation is a list object, with the first element being 
the predictions of the various stages for all individuals (phenology). The 
data correspond to the number of time steps expressed in the time series 
value (6h time step here). The second element corresponds to the model 
parameters used, and the third element to the temperature series used. We can
plot the simualtion result using the first element.

```{r, "r004", fig.width=7, fig.height=4}
sim01 <- forecastX[[1]]
hist(
  -999, # empty histogram
  xlim = c(0, max(sim01)), ylim = c(0, nrow(sim01)), 
  xlab = "Time", ylab = "Number of individuals", axes = FALSE, main = ""
)
axis(1)
axis(2, las = 1)
cycleLabels <- rep(c("adults", "larvae", "pupae"), 10)
trash <- lapply(1:ncol(sim01), function(i){
  hist(sim01[,i], add = TRUE)
  text(
    x = mean(sim01[,i]), 
    y = max(table(sim01[,i])), 
    labels = colnames(sim01)[i],
    pos = 2
  )
  text(
    x = mean(sim01[,i]), 
    y = max(table(sim01[,i]))+1, 
    labels = cycleLabels[i],
    pos = 2
  )
  
})
```

#### 2.2.2. Simulation using different models

```{r, "r005", fig.width=7, fig.height=4}
set.seed(1234)

my_model01 <- ha_bartekova2006(plotfig = FALSE)
my_model02 <- ha_mironidis2008_nls(plotfig = FALSE)
my_model03 <- ha_foley1981(plotfig = FALSE)

forecastX <- devRateIBMparam(
  tempTS = temp, # the temperature time series described above
  timeStepTS = 1/4, # we  have 4 temperature values per day (every 6 hours)
  eq = rep(list(
    "campbell_74", "campbell_74", "lactin2_95"
  ), 3), # the model eq for
    # the three life stages
  myParam = list(
    my_model03[["model"]]$diapausingpupae, # starting with diapausing pupae (Foley 1981)
    my_model01[["model"]]$egg,  # then adults and eggs (Bartekova 2006)
    my_model02[["model"]]$larva, # then larvae (Mironidis 2008)
    my_model03[["model"]]$nondiapausingpupae, # pupae G2 (Foley 1981)
    my_model01[["model"]]$egg,
    my_model02[["model"]]$larva,
    my_model03[["model"]]$nondiapausingpupae,
    my_model01[["model"]]$egg,
    my_model02[["model"]]$larva
  ),
  adultLifeStage = 1, # adult life stage after the first model step (pupae 
    # to adults)
  timeLayEggs = 10, # adults longevity fixed to 10 days
  numInd = 10, # 10 individuals for the simulation
  stocha = 0.05 # a bit of intra-population variability
)
```

```{r, "r006", fig.width=7, fig.height=4}
sim02 <- forecastX[[1]]
hist(
  -999, # empty histogram
  xlim = c(0, max(sim02)), ylim = c(0, nrow(sim02)), 
  xlab = "Time", ylab = "Number of individuals", axes = FALSE, main = ""
)
axis(1)
axis(2, las = 1)
cycleLabels <- rep(c("adults", "larvae", "pupae"), 10)
trash <- lapply(1:ncol(sim02), function(i){
  hist(sim02[,i], add = TRUE)
  text(
    x = mean(sim02[,i]), 
    y = max(table(sim02[,i])), 
    labels = colnames(sim02)[i],
    pos = 2
  )
  text(
    x = mean(sim02[,i]), 
    y = max(table(sim02[,i]))+1, 
    labels = cycleLabels[i],
    pos = 2
  )
  
})
```

### 2.3. Simulation results and comparison

```{r, "r007", fig.width=7, fig.height=4}
# results of simulations using model 1
apply(sim01, MARGIN = 2, FUN = summary)

# results of simulations using model 2
apply(sim02, MARGIN = 2, FUN = summary)
```

A more detailed comparison would not be meaningful here because the time 
series is theoretical and the choice of models used is arbitrary. 
Nevertheless, these simulations highlight notable differences in phenology 
for *H. armigera*. A comparison could be made based on meteorological data 
from sites where insect trapping is carried out, in order to compare simulated 
data with observed data and choose the most appropriate model from among the 
many possible combinations.

## Legal information

This work is part of the ACOMPLI project. The ACOMPLI project is part of the 
Strategic Action Plan for the anticipation of the potential European 
withdrawal of active substances and the development of alternative crop 
protection techniques (PARSADA). It is financed by ecological planning funds. 
The French Ministry of Agriculture cannot be held responsible for the content 
of this package.





<!-- # library("devtools") -->
<!-- # devtools::document() -->
<!-- # devtools::check() -->
<!-- # devtools::check_win_devel() -->
<!-- # devtools::build() -->
