Travaux Pratiques `rcontroll`

Une interface R pour le simulateur de dynamique forestière basé sur les individus TROLL

Sylvain Schmitt

CIRAD

Oct 28, 2025

Introduction

Nous allons aujourd’hui explorer l’utilisation de simulateurs forestiers en écologie, notamment à travers un modèle basé sur les agents :

modèle permettant de simuler les actions et les interactions d’agents autonomes afin de comprendre le comportement d’un système et les facteurs qui déterminent ses résultats.

Le jeu de la vie (J. Conway, 1970)

Chaque cellule ne peut se trouver que dans deux états : allumée (vivante) ou éteinte (morte)
Une cellule allumée le reste uniquement si 2 ou 3 de ses 8 voisines sont allumées
Une cellule éteinte s’allume uniquement si 3 de ses 8 voisines sont allumées

Boids (C. W. Reynolds, 1986)

La cohésion : les boids se rapprochent les uns des autres
La séparation : deux boids ne peuvent pas se trouver au même endroit au même moment
L’alignement : les boids suivent leurs voisins

Levi et al. (2018)

Tropical forests can maintain hyperdiversity because of enemies

Levi et al. (2018)

Tropical forests can maintain hyperdiversity because of enemies par Levi et al. (2018)

TROLL

An Individual-BasedForest Model to Jointly Simulate Carbon and Tree Diversity in Amazonia par Maréchaux and Chave (2017)

Qu’est-ce que c’est ?

TROLL modélise chaque arbre individuellement dans un environnement spatialisé. Le modèle TROLL peut donc être défini comme un modèle de croissance forestière individuel, centré et spatialement explicite. Il simule le cycle de vie des arbres, depuis le recrutement à partir d’un diamètre à hauteur de poitrine (dbh) de 1 cm, jusqu’à la mort. Les arbres poussent dans un environnement lumineux dont les valeurs sont calculées dans des voxels de \(1 m^3\).

Représentation

Fonctionnement

Chaque arbre est défini par son âge, son diamètre à hauteur de poitrine (DBH), sa hauteur (H), le rayon de son houppier (CR), la profondeur de son houppier (CD) et sa surface foliaire (LA). La géométrie de l’arbre est calculée à l’aide d’équations allométriques et la surface foliaire varie dynamiquement au sein de chaque couronne en fonction de l’allocation de carbone. Un arbre peut occuper au maximum un pixel de 1 m sur 1 m. Chaque arbre appartient à une espèce héritée de son arbre parent. Pour chaque espèce, un certain nombre de paramètres sont connus : les valeurs des traits de cette espèce, qui ont été recueillies sur le terrain. L’assimilation du carbone est calculée sur une période de 30 minutes. L’allocation est ensuite calculée pour simuler la croissance des arbres. L’environnement est mis à jour chaque mois. Les juvéniles (arbres dont le diamètre à hauteur de poitrine est inférieur à 1 cm) ne sont pas simulés explicitement, mais comme un groupe. En outre, les processus souterrains, les plantes herbacées, les épiphytes et les lianes ne sont pas pris en compte dans TROLL.

Environnement R

Pendant ce TP, nous utiliserons le modèle TROLL (Maréchaux and Chave 2017) avec le package rcontroll (Schmitt et al. 2023). Nous utiliserons également les packages dplyr, tidyr et ggplot2 pour les manipulations de tables et la création de graphiques. Téléchargez-les (pré-requis !) :

install.packages("dplyr", "tidyr", "ggplot2", "rcontroll")

Chargez les avec :

library(dplyr)
library(tidyr)
library(ggplot2)
library(rcontroll)

Données

Espèces

Pour fonctionner, le modèle TROLL utilise un certain nombre de données par espèce, dont une liste de traits fonctionnels. Vous pouvez charger les valeurs de ces traits pour un ensemble d’espèces de Guyane française et explorer ces données.

data("TROLLv3_species")

Question 1 : Combien de traits sont recensés dans ce tableau, et pour combien d’espèce ?

Question 2 : Sélectionnez une espèce d’arbre de Guyane française pour ce TP. Quelles sont ses valeurs de traits et que comprenez-vous de ses caractéristiques ?

Espèces

Question 1 : Combien de traits sont recensés dans ce tableau, et pour combien d’espèce ?

dim(TROLLv3_species)

[1] 45 12

Espèces

Question 2 : Sélectionnez une espèce d’arbre de Guyane française pour ce TP. Quelles sont ses valeurs de traits et que comprenez-vous de ses caractéristiques ?

head(TROLLv3_species)

# A tibble: 6 × 12
  s_name            s_LMA s_Nmass s_Pmass s_wsg s_dbhmax s_hmax  s_ah s_seedmass
  <chr>             <dbl>   <dbl>   <dbl> <dbl>    <dbl>  <dbl> <dbl>      <dbl>
1 Abarema_jupunba   110.   0.0232 5.7 e-4 0.576     0.66   50.9 0.308          1
2 Bocoa_prouacensis  95.6  0.0255 5.05e-4 0.798     0.4    47.9 0.251          1
3 Brosimum_rubesce…  85.8  0.0188 6.88e-4 0.619     0.52   50.9 0.308          1
4 Carapa_procera    130.   0.0177 6.36e-4 0.55      0.49   41.4 0.187          1
5 Caryocar_glabrum   84.2  0.0217 8.13e-4 0.612     1.15   48.6 0.275          1
6 Cecropia_obtusa    69.5  0.0276 1.38e-3 0.388     0.35   50.9 0.308          1
# ℹ 3 more variables: s_regionalfreq <dbl>, s_tlp <dbl>, s_drymass <dbl>

Climat

Les équations qui décrivent les processus de la dynamique forestière dans le modèle TROLL font intervenir des variables climatiques, ces données sont réunies dans un tableau que vous pouvez charger et explorer :

data("TROLLv3_climatedaytime12")

Question 3 : Quelles sont les variables climatiques qui sont utilisées pour modéliser la dynamique forestière dans TROLL?

Question 4 : Quelles sont les valeurs moyennes de ces variables en Guyane française? Ces valeurs sont-elles cohérentes avec ce que vous savez des conditions d’existence des forêts tropicales?

Climat

Question 3 : Quelles sont les variables climatiques qui sont utilisées pour modéliser la dynamique forestière dans TROLL?

head(TROLLv3_climatedaytime12)

# A tibble: 6 × 12
  Temperature DaytimeMeanTemperature NightTemperature Rainfall WindSpeed
        <dbl>                  <dbl>            <dbl>    <dbl>     <dbl>
1        24.3                   26.4             23.0     9.46     0.904
2        24.3                   26.2             23.0     9.52     0.941
3        24.1                   26.4             23.0     9.58     0.876
4        24.6                   26.8             23.0    10.5      0.908
5        24.6                   26.7             23.4    16.0      0.756
6        24.6                   26.5             23.0     8.05     0.828
# ℹ 7 more variables: DaytimeMeanIrradiance <dbl>, MeanIrradiance <dbl>,
#   SaturatedVapourPressure <dbl>, VapourPressure <dbl>,
#   VaporPressureDeficit <dbl>, DayTimeVapourPressureDeficitVPDbasic <dbl>,
#   DaytimeMeanVapourPressureDeficit <dbl>

Climat

summary(TROLLv3_climatedaytime12)

  Temperature    DaytimeMeanTemperature NightTemperature    Rainfall     
 Min.   :24.09   Min.   :26.21          Min.   :22.97    Min.   : 0.586  
 1st Qu.:24.50   1st Qu.:26.49          1st Qu.:22.99    1st Qu.: 3.507  
 Median :24.73   Median :26.76          Median :23.17    Median : 7.669  
 Mean   :25.04   Mean   :27.32          Mean   :23.31    Mean   : 7.026  
 3rd Qu.:25.46   3rd Qu.:28.27          3rd Qu.:23.45    3rd Qu.: 9.537  
 Max.   :26.72   Max.   :29.39          Max.   :24.11    Max.   :15.997  
   WindSpeed      DaytimeMeanIrradiance MeanIrradiance  SaturatedVapourPressure
 Min.   :0.7560   Min.   :293.2         Min.   :130.1   Min.   :2.988          
 1st Qu.:0.8600   1st Qu.:313.5         1st Qu.:149.6   1st Qu.:3.095          
 Median :0.9060   Median :329.4         Median :159.6   Median :3.152          
 Mean   :0.9167   Mean   :360.5         Mean   :169.7   Mean   :3.213          
 3rd Qu.:0.9772   3rd Qu.:415.3         3rd Qu.:186.3   3rd Qu.:3.306          
 Max.   :1.0780   Max.   :461.2         Max.   :225.9   Max.   :3.578          
 VapourPressure  VaporPressureDeficit DayTimeVapourPressureDeficitVPDbasic
 Min.   :2.792   Min.   :0.1520       Min.   :0.2600                      
 1st Qu.:2.840   1st Qu.:0.2052       1st Qu.:0.3767                      
 Median :2.864   Median :0.2780       Median :0.4880                      
 Mean   :2.864   Mean   :0.3510       Mean   :0.6038                      
 3rd Qu.:2.898   3rd Qu.:0.4370       3rd Qu.:0.7595                      
 Max.   :2.947   Max.   :0.7620       Max.   :1.2680                      
 DaytimeMeanVapourPressureDeficit
 Min.   :0.4980                  
 1st Qu.:0.5567                  
 Median :0.6290                  
 Mean   :0.7973                  
 3rd Qu.:1.0593                  
 Max.   :1.4250

Variation diurne

Dans le modèle TROLL, les processus d’assimilation du carbone par les plantes sont calculés sur un pas d’une demi-heure. Les données climatiques sont donc recalculées sur ce pas de temps, pour cela, vous aurez besoin de charger un troisième tableau, qui correspond aux variances des variables pour chaque pas de temps de la journée :

data("TROLLv3_daytimevar")

Paramètres

Il vous faut maintenant définir les paramètres de votre simulation :

le nombre de pas de temps par an iterperyear
le nombre de pas de temps total de la simulation nbiter
la taille de la parcelle simulée, grace aux nombres de colonnes cols et de lignes rows (les parcelles sont rectangulaires)
le nombre de graines vennant de l’extérieur seedrain (la pluie de graine correspond aux graines qui sont dispersée dans la parcelle simulée depuis l’exterieur)

Paramètres

La fonction generate_parameters permet de créer un tableau avec les différents paramètres d’une simulation :

generate_parameters(cols = 250, rows = 250, nbiter = 12 * 10) %>%
  head() %>%
  knitr::kable()

param	value	description
cols	250	/* nb of columns */
rows	250	/* nb of rows */
HEIGHT	70	/* vertical extent of simulation */
length_dcell	25	/* linear size of a dcell */
nbiter	120	/* total nb of timesteps */
iterperyear	12	/* number of iteration per year */

Question 5 : Si vous utilisez le code précédent, quelle est la durée de votre simulation?

Simulation

`troll`

Maintenant que vous avez les données nécessaires, vous pouvez réaliser une simulation. Pour réaliser une simulation, vous pouvez utiliser la fonction troll() :

sim <- troll(
  name = "test",
  global = generate_parameters(
    cols = 100, rows = 100,
    iterperyear = 12, nbiter = 12 * 100
  ),
  species = TROLLv3_species,
  climate = TROLLv3_climatedaytime12,
  daily = TROLLv3_daytimevar,
  verbose = TRUE
)

Question 6 : Comment s’appelle votre simulation? Quel est son format (dans R)?

⚠️ la fonction troll() met un certain temps à s’exécuter, rappelez-vous que le modèle calcule l’assimilation du carbone pour chaque arbre modélisé sur une période d’une demi-heure.

`troll`

Question 6 : Comment s’appelle votre simulation? Quel est son format (dans R)?

sim

Object of class : trollsim 
Name : test 
Path :  
In memory : TRUE 
Extended : TRUE 
From data : FALSE 
Lidar simulation : FALSE 
Random : FALSE 

2D discrete network: horizontal step =  1 m, one tree per 1 m^2 
Number of sites      :  100 x 100 
Number of iterations :  1200 
Duration of timestep :  30.41667 days 
Number of Species    :  45

Visualisation

`autoplot`

Vous pouvez utiliser la fonction autoplot() pour visualiser les résultats de votre simulation, pour cela vous devez choisir les arguments :

what doit valoir soit "temporal", soit "spatial", soit "distribution"
species doit être le nom de l’espèce à laquelle vous vous intéressez (entre guillemets)

rcontroll::autoplot(sim,
  what = ,
  species = ) +
  theme(legend.position = "bottom")

Question 7 : Quels sont les indicateurs (ou variables) auxquels vous pouvez avoir accès avec la fonction autoplot()?

Vous pouvez constater que la simulation a été réalisée à partir d’un sol nu (sans arbre).

Question 8 Augmentez le nombre d’années de simulation et effectuez une simulation de 100 ans. Quelle est la surface terrière de cette espèce en début de simulation et en fin de simulation? Comparez vos résultats avec ceux de vos camarades sur les autres espèces.

`autoplot`

Question 7 : Quels sont les indicateurs auxquels vous pouvez avoir accès avec la fonction autoplot()?

?rcontroll::`autoplot,trollsim-method`

`autoplot`

Question 8 : Augmentez le nombre d’années de simulation et effectuez une simulation de 100 ans. Quelle est la surface terrière de cette espèce en début de simulation et en fin de simulation? Comparez vos résultats avec ceux de vos camarades sur les autres espèces.

rcontroll::autoplot(sim,
  what = "temporal",
  species = "Eperua_grandiflora") +
  theme(legend.position = "bottom")

Multiples simulations

Pluie de graine

Pour comparer différentes simulations, il est possible de faire des simulations multiples, dont les jeux de paramètres peuvent être différents. Ici, nous allons réaliser des simulations en changeant la valeur de la pluie de graine.

Question 9 : En changeant la pluie de graine, quel(s) processus de la dynamique forestières est/seront impacté(s) et pourquoi ?

Question 10 : Comment se disperse l’espèce étudiée par votre binôme ?

Paramètres multiples

Vous pouvez utiliser à nouveaux la fonction generate_parameters(), mais cette fois en précisans qu’il y aura deux simulations, auxquelles on donnera les noms seed50000 et seed500. Ensuite, vous pouvez changer le paramètre de la pluie de graine de la simulation seed500 pour que ce paramètre soit égale à 500 :

stack_parameters <- generate_parameters( cols = 100, rows = 100, iterperyear = 12, nbiter = 12 * 50 ) %>% 
  mutate(simulation = list(c("seed50000", "seed500"))) %>% 
  unnest(simulation)
stack_parameters[62, 2] <- 500

`stack`

La fonction stack() permet des faire des simulations multiples, vous pouvez l’utiliser en précisant les paramètres des simulations avec l’argument global. Ici l’argument verbose prend la valeur FALSE pour éviter d’avoir les messages de TROLL, vous ne verrez donc qu’une barre de chargement pendant les simulations. Les autres arguments de la fonction stack() permettent entre autre de préciser le nombre de coeur utilisés (cores), et les itérations dont les résultats seront stockés (thin).

sim_stack <- stack(
  name = "teststack",
  simulations = c("seed50000", "seed500"),
  global = stack_parameters,
  species = TROLLv3_species,
  climate = TROLLv3_climatedaytime12,
  daily = TROLLv3_daytimevar,
  verbose = FALSE,
  cores = 2,
  thin = (1:10)*10
)


  |                                                                            
  |                                                                      |   0%
  |                                                                            
  |======================================================================| 100%

Visualisation multiples

Vous pouvez ensuite utiliser la fonction autoplot() comme vous l’avez fait avec une simulation simple :

rcontroll::autoplot(sim_stack,
  what = "temporal",
  variables = c("ba", "agb")
)

Question 12 : Comment se comporte votre espèce? par rapport aux autres? Etait-ce attendu? A votre avis, quel(s) processus est/sont être responsable(s) de ce que vous observez?

Questions bonus exploratoire

A partir de simulations réalisées avec le modèle TROLL, à quelle question en écologie des forêts pouvez-vous répondre ?

Bonus

Visualisation dynamique

Code

data("TROLLv3_output")

gifs <- autogif(
  name = "dynamic",
  variables = "height_ct",
  global = update_parameters(TROLLv3_output,
    nbiter = 12 * 100,
    extent_visual = 100
  ),
  species = TROLLv3_output@inputs$species,
  climate = TROLLv3_output@inputs$climate,
  daily = TROLLv3_output@inputs$daily,
  forest = get_forest(TROLLv3_output),
  verbose = FALSE
)
gifs$height_ct

Result

Conclusion

Félicitations 👏 , vous êtes désormais des pros de rcontroll !

Plus sérieusement, je serais ravis de répondre à toutes vos questions. N’hésitez pas à consulter GitHub si vous avez besoin d’aide plus tard.

Références

Levi, Taal, Michael Barfield, Shane Barrantes, Christopher Sullivan, Robert D. Holt, and John Terborgh. 2018. “Tropical Forests Can Maintain Hyperdiversity Because of Enemies.” Proceedings of the National Academy of Sciences 116 (2): 581–86. https://doi.org/10.1073/pnas.1813211116.

Maréchaux, Isabelle, and Jérôme Chave. 2017. “An Individual-Based Forest Model to Jointly Simulate Carbon and Tree Diversity in Amazonia: Description and Applications.” Ecological Monographs 87: 632–64. https://doi.org/10.1002/ecm.1271.

Schmitt, Sylvain, Guillaume Salzet, Fabian Jörg Fischer, Isabelle Maréchaux, and Jerome Chave. 2023. “Rcontroll: An r Interface for the Individual-Based Forest Dynamics Simulator TROLL.” Methods in Ecology and Evolution 14 (11): 2749–57. https://doi.org/10.1111/2041-210X.14215.

Travaux Pratiques rcontroll

Introduction

Le jeu de la vie (J. Conway, 1970)

Boids (C. W. Reynolds, 1986)

Levi et al. (2018)

Levi et al. (2018)

TROLL

Qu’est-ce que c’est ?

Représentation

Représentation

Fonctionnement

Environnement R

Données

Espèces

Espèces

Espèces

Climat

Climat

Climat

Variation diurne

Paramètres

Paramètres

Simulation

troll

troll

Visualisation

autoplot

autoplot

autoplot

Multiples simulations

Pluie de graine

Paramètres multiples

stack

Visualisation multiples

Questions bonus exploratoire

Bonus

Code

Result

Conclusion

Références

Travaux Pratiques `rcontroll`

`troll`

`troll`

`autoplot`

`autoplot`

`autoplot`

`stack`