Skip to contents

Basic usage and examples

Source: vignettes/marteloscope.Rmd
marteloscope.Rmd

This vignette illustrates the workflow to use marteloscope package and animate a marteloscope workshop. The package link forest inventory with Capsis model Samsara 2 Courbaud et al. (2015), allowing to produce field reports with simulations for scenarii of different management actions.

Installation and creation of workshop directory

A workshop is stored in a single directory where inventory files and simulations will be stored.

You can create a workshop by using RStudio :

Marteloscope project

Marteloscope project

Or calling the function that is called below the GUI :

library(marteloscope)
marteloscope:::new_marteloscope("reports", 
                 caps_exe = "",
                 site = "Col_de_porte",
                 date = "YYYY.MM.DD",
                 anim = "Benoit Courbaud",
                 contact = "benoit.courbaud@inrae.fr",
                 lang = "en"
)

Directories : - data : place to store xlsx files with inventories, and later on simulations outputs. - markings : marking files to use on the field, and once filled used to run simulations on. - reports : directory where to find the final outputs of this package. - scripts : R scripts to run the different steps, to help you run all simulations.

File names are dependent on your site name and date. You can name your project as you want. Because everything is stored in one place, you can transfer the directory to anyone wanting to replicate the simulations, as long as they have installed the package and Capsis.

Preparation of the workshop for the animator : scripts/01_start.R

Once the project has been created, the marteloscope animator can follow the progress of the various scripts.

The first script is used to set up all the inventory files describing the plot. This requires few changes to the scripts, and all that is needed is to execute the commands in the right order (“Run” button in RStudio or ctrl+enter on the line of interest). Lines beginning with a # are comments, to document the use of the R code next to them.

The first command is used to specify the general options, i.e. metadata about the site, the leader, etc.

The new_inventory() command will create an excel type file for recording the plot inventory. The open = TRUE option will automatically open this file so that the host can complete it. A complete example is provided in the package for the Prelenfrey site. This inventory file can be edited several times.

The build_samsa2_files() command will read this inventory and translate it into configuration files for the samsara2 model within Capsis. It is therefore important to run it again if the inventory (xlsx file) is edited. This command will also check that the data entered is correctly formatted, and can therefore return various errors to guide the animator in addition to the “Notice” sheet of the inventory.

The last command simply opens the following script in RStudio, which is otherwise in the “scripts” folder.

Testing simulations : scripts/02_test.R

This second script is intended for the site moderator, so that he can test that the simulations are working in preparation for the workshop.

During the workshop, each group must return a marking file with the same list of trees as the site. There are two types of file that can be read by the {marteloscope} package:

  • Iplus output files, which are csv files saved from the application. Their creation will not be detailed in this document, but they can still be used by this package.

  • .xlsx files in the format defined by this package. They are located in the “marking” folder. The find_marking() function is available to find these files. By default, an empty marking is created with a file named “Site_date_Marking_X.xlsx”, where “X” is the group name. Another function which makes it easier to test the simulations is random_marking(), which will provide a random cut of 30% of the trees (the group name here is “Random” by default).

Once these files have been filled in and are present in the “marking” folder, the write_samsara_cmd() function will create the last configuration file to set the parameters for the simulations. It is important to specify which markings are to be taken into account (by listing the group names).

It is important to test that the simulations are working, as this also allows the plot periphery and recruits to be pre-calculated. These pre-calculations will speed up the subsequent simulations.

Finally, the run_samsara() function will run the simulations. This may take a few minutes, depending on the number of groups and the size of the plot.

Once the simulations have been completed, the martelo_report() function will compile the results and provide a pdf report containing all the graphs for a group given as an argument. This report contains several themes, and it is possible to select these themes by specifying which ones to remove (e.g.: carbon = FALSE in argument will remove the page concerning carbon storage). Reports are saved in the ‘reports’ folder, under a pdf format.

On the day of the workshop, only the latter functions will be used, with a longer list of groups.

Courbaud, B., V. Lafond, G. Lagarrigues, G. Vieilledent, T. Cordonnier, F. Jabot, and F. de Coligny. 2015. “Applying Ecological Model Evaludation: Lessons Learned with the Forest Dynamics Model Samsara2.” Ecological Modelling 314: 1–14. https://doi.org/https://doi.org/10.1016/j.ecolmodel.2015.06.039.