Skip to contents

The Marteloscope R package Quick User guide

Simulating the evolution of a marteloscope following a marking and over a period of several decades with thinning

Source: vignettes/marteloscope.Rmd
marteloscope.Rmd

Principle

The Marteloscope package is a tool making possible to simulate the evolution of a marteloscope over several decades, a first thinning corresponding to the marking made on the field and later thinning reproducing a strategy deduced from the field marking.

The package uses the model Samsara2 (Lafond et al. (2017), Benoit Courbaud et al. (2016), B. Courbaud et al. (2015)), which is a module of the software CAPSIS. It proposes a specific interface for marteloscopes that facilitates the preparation of all the files describing the marteloscope initial conditions, the loading of field marking information during a marking exercise, the simulation processing, and the production of a standardized output report.

The package is designed to be run by the marteloscope instructor on a computer. During a marteloscope exercise, each marking group enters his marking data on a tablet (we propose an Excel file by default. The EFI I+Trainer can be used also for this step). The marteloscope instructor collects all the marking files and runs the simulations for all the groups on his computer. The package produces a personalized simulation report for each group.

Here are the steps you have to follow: - Install the marteloscope package on the marteloscope trainer’s computer: - Test the Marteloscope package making a virtual workshop on the marteloscope of Prelenfrey - Set up your marteloscope on the field - Prepare a marteloscope workshop on your computer and your tablets - Test the simulator on a random marking - Carry out the marking on the field - Simulate the results of a marteloscope exercise

Software installation

Installing Java

Java is usually already installed in most computers. However, for Capsis, you need a version 1.8.xxx of Java. To check the version of Java on your computer, - Open a MS-DOS command prompt (on Windows) - type : java –version

If you don’t have a Java 1.8.xxx on your computer, download a “Java SE Runtime Environnement 8” on your machine, https://java.com/en/download/manual.jsp (for Windows choose an offline version) https://www.oracle.com/java/technologies/javase-jre8-downloads.html (subscription is mandatory on this site)

Installing Capsis

Run the Capsis installer provided to you by LESSEM

  • Double click on the installer file : capsis_Samsara2_version_setup.jar
  • Choose a name and location for your Capsis folder (for example /My documents/Capsis).
  • Caution, the path to your Capsis folder must not contain names with accents.
  • Remember this location and path, because you’ll need it later.
  • For more information, see : http://capsis.cirad.fr/capsis/documentation/installation_guide

Be careful : the Capis version must be compatible with the R package version you install.

Installing R and Rstudio

Installing Marteloscope R package

Open R studio or close any project and paste one of the following commands in the console:

If you are a marteloscope instructor

You should install the last stabilized version of the package, copying and pasting the command line:

if (!require("remotes", quietly = TRUE)) {install.packages("remotes")}
remotes::install_url('https://forge.inrae.fr/lessem/marteloscope/-/archive/main/marteloscope-main.zip')

Restart R either in closing and reopening RStudio or by copying and pasting the command .rs.restartR()

If you are a researcher

You can install the current development version with the command line:

if (!require("remotes", quietly = TRUE)) {install.packages("remotes")}
remotes::install_url('https://forge.inrae.fr/lessem/marteloscope/-/archive/dev/marteloscope-dev.zip')

Restart R either in closing and reopening RStudio or by copying and pasting the command .rs.restartR()

The documentation of the package Marteloscope is available here: https://marteloscope-lessem-d3ee0b35d60b232cf2359e16b807e838c535e5a39f3.pages.mia.inra.fr/index.html

Using the Marteloscope package

You have to prepare in advance a marteloscope exercise by following the 3 steps in sequence:

  1. Testing the Marteloscope package making a virtual workshop on the marteloscope of Prelenfrey
  2. Testing the package on your own marteloscope with a random marking
  3. Using the package during a marking exercise

Testing the package on a virtual workshop on the marteloscope of Prelenfrey

Create a directory and an R project to simulate a marteloscope workshop on the marteloscope of your choice

  • Open RStudio
    `File/New project` (in the upper left menu bar)

    File/New project (in the upper left menu bar)

    `New directory`

    New directory

    `Marteloscope workshop`

    Marteloscope workshop

    Creation menu

    Creation menu

    • Directory name : we suggest that you create a directory named with the marteloscope and the date of your exercise: ex Prelenfrey_2024.11.19. You can create right away a succession of directories to organize your marteloscopes and future workshops. (ex : Marteloscope_Workshops/Prelenfrey/Prelenfrey_2024.11.19)
    • Subdirectory of : indicate the folder in which you want to store the directory of your exercise : ex Marteloscope_Workshops/Prelenfrey
    • Repeat the Marteloscope name and Workshop Date : ex Prelenfrey and 2024.11.19
    • Capsis path : Click on Browse and develop the pathway up to your Capsis folder and select the file capsis.sh
      Marteloscope project

      Marteloscope project

    • Create project
  • The dialogue box creates a folder for your exercise (ex: Prelenfrey_2024.11.19) In this folder, you find
    • The R project for the exercise (ex: Prelenfrey_2024.11.19.Rproj)
    • Subfolders : scripts, data, martelages, reports
  • RStudio opens your project (ex: Prelenfrey_2024.11.19.Rproj).

Run the script 01_start.R

This script prepares the files describing your marteloscope initial conditions. You have to run it before each exercise.

On the bottom right window, double click on the file scripts/01_start.R

To run a RStudio script, click on each line of code and type Ctrl Enter , it will run the code section by section.

  • marteloscope::marteloscope_options() checks that the indications for your workshop are correct.
  • marteloscope::new_inventory() copies the Excel file of field data in the subdirectory data of your exercise and checks its name :
    • The option site = Prelenfrey will copy the example file of Prelenfrey stored in the package. This is what we suggest to do to test the package the first time. In our example, this file will be named: Marteloscopes_Workshops/Prelenfrey/Prelenfrey_2024.11.19/data/Data_Marteloscope_Prelenfrey.xlsx
    • If the option open = TRUE, then the Excel file is open and you can check the Prelenfrey data file. You have to close the Excel file before continuing running the R code.
  • marteloscope::build_samsa2_files()
    • Creates the files of initial conditions used by the simulator samsara2 and store them in the subdirectory data
    • Creates in the folder markings the file markings/Prelenfrey_2024.11.19_Marking_X.xlsx which can be used on the field to enter marking data for the marking group X.
  • marteloscope::prepare_samsara() makes a preliminary simulation to complement the data of your marteloscope
    • the option create_periphery = TRUE is necessary if your marteloscope is not rectangular. It includes your marteloscope in a rectangular plot complemented with virtual trees. Light interception is calculated considering that this rectangular plot is duplicated infinitely in all directions (torus method).
    • The option create_saplings = TRUE is necessary if you have not measured regeneration on the field. It creates a virtual regeneration in balance with the adult stand. Simulations of continuous cover management are more realistic with this initial virtual regeneration than with no initial regeneration at al. than when no regeneration at all.
  • navigateToFile(« script 02_test.R ») opens the script used for the next step

Run the script 02_test.R

This script runs marteloscope marking exercise with a random marking in order to test the whole process.

  • marteloscope::random_marking() creates a virtual marking where trees have been selected randomly. It makes a marking file similar to a field marking file. In our example: markings/ Prelenfrey_2024.11.19_Marking_Random.xlsx
  • write_samsara_cmd() creates the file data Prelenfrey_CommandFile.txt. This command file plans all the simulation steps for Samsara. You have the option to change the thinning_time and evolution_time settings if you want to test different scenarios.
  • run_samsara() runs the simulations for the the random marking and stores result files in the folder data. It takes approximately 1 minutes for a 20 year evolution simulation.
  • martelo_report() writes a PDF report for your simulation and stores it in the reports folder. In our example: reports/Prelenfrey_2024.11.19_Random_Report.pdf. You can read it as any pdf file.

The scripts 03_workshop.R is for a real marking exercise, not needed if you just want to test the package on a virtual marteloscope with a random marking.

Testing the package on your own marteloscope

Set up your marteloscope on the field

  • Specific data are required to run simulations. See the list of these data and the format to follow on the Excel file template Data_Marteloscope_template_en.xlsx or the example Data_Marteloscope_Prelenfrey.xlsx.
  • Be careful to respect exactly the required format otherwise the simulation package will not work.
  • Tree coordinates X, Y (and Z if relevant) are necessary to calculate light interception by trees taking slope and aspect into account. If necessary, you can use the additional R code martelo-main.zip by Jean-Matthieu Monnet to convert angles and distances measured on the field between reference poles and trees into X,Y,(Z) coordinates.

Create a directory and an R project to simulate a marteloscope workshop on the marteloscope of your choice - Before each exercise

A new R project must be created before each exercise. Follow the same instructions as in part 3.1.1. changing Prelenfrey and 2024.11.19 by your own marteloscope name and exercise date.

Run the script 01_start.R - Before each exercise

Before the exercise, run 01_start.R to prepares the files describing your marteloscope initial conditions.

  • marteloscope::new_inventory() copies the Excel file of field data in the subdirectory data of your exercise and checks its name :
    • The option site = new will copy the data file template in the folder data with the name of your marteloscope and date of your exercise. If the option open = TRUE, then the Excel file is opened directly. You can fill it with your own data. You have to close the Excel file before continuing running the R code.
    • The option site = copy, opens a popup window to copy a data file you have already prepared and stored anywhere on your computer. If the popup window does not open directly it may appear on the bottom bar of your screen. Be careful that the format of the file is correct.
  • If the following code doesn’t work, first check for errors in your data file.

Run the script 02_test.R to test a random marking

To run a simulation with a random marking, follow the instructions in Run the script 01_start.R

Prepare the field tablets - Before going to the field

  • To enter on the field the marking made by a marking group, you have to prepare on each tablet either the simple Excel file provided by in the package or the I+Trainer software. It is a good precaution to prepare the Excel file in any case.
  • To transfer files, you can use the cable of your tablet charger. Authorize the transfer. The tablet becomes an extension of your computer. Use the windows explorer on your computer to create folders and copy files on the tablet.

Case 1: You intend to use the simple Excel file provided with the package

  • Download Excel or an equivalent software on your tablet
  • Create a folder for your marteloscope exercise on the tablet. For example: Stockage interne/Documents/Marteloscopes/YourMarteloscopeName/YourMarteloscopeName_YourDate /
  • Transfer from your computer to the tablet the Excel marking file that has been prepared on your computer when running the project script_01.R. For example: YourMarteloscopeName_YourDate_Marking_X.xlsx. Change the name of the file with the correct tablet name or marking group name (ex: YourMarteloscopeName_YourDate_Marking_A.xlsx for group A)
  • Transfer also on the tablet the map of the marteloscope : it will be helpful to navigate on the field.

Case 2: You intend to use the I+Trainer software

  • Download the I+Trainer, register your marteloscope in the European Forest Institute database and download your marteloscope on the I+Trainer from their database.

On the tablet, enter the marking data on the marking file – On the field

Case 1: A marking group uses the simple Excel file provided with the package

  • The marking group opens the Excel file. A table presents all the trees of the marteloscope with their species and diameter. By default, the Action column has been filled with the keyword Wait which mean that you don’t do anything on this tree. If you click on the box, you can choose among the actions: Cut, Wait, Promote or Retain. You can select a reason for your choice in the column Reason.
  • Transfer the marking file on the marteloscope instructor’s computer in the markings folder for simulation. Check that the name of the file is correct. it should follow the rule: YourMarteloscopeName_YourDate_Marking_YourGroup.xlsx.

Case 2: You use the field the I+Trainer software

  • The marking group enter marked trees on the I+trainer as usual. At the end of the exercise, go to Menu, Exercise results. Use the green arrow to visualize the I+Trainer results. When you arrive on the box Finish the exercise choose save results on the device. Enter a name for your marking file. Two files are saved on the folder sdcard/iplus/ : a pdf file and a csv file. The .csv file will be used by the simulation package. The I+ trainer adds extensions to the names, so you will have to modify the names for Samsara.
  • Transfer the marking file on the marteloscope instructor’s computer in the markings folder for simulation. Check that the name of the file is correct. it should follow the rule: YourMarteloscopeName_YourDate_Marking_YourGroup.csv.

Run the script 03_workshop.R - After the marking

This script runs marteloscope marking exercise in order to test the whole process.

  • find_marking() reads the making file template. You can check that it identifies all of your marking files. If the option open = TRUE, the Excel sheet is opened to be checked. You have to close the Excel sheet before going on.

  • write_samsara_cmd() (as in section Run the script 02_test.R) creates the file data YourMarteloscopeName_Martelo_CommandFile.txt. This command file plans all the simulation steps for Samsara. You can change the option foresters = c("Random","X") with the name of your different foresters from your different marking files (ex: foresters = c("A","B","C") ). You can change the thinning_time and evolution_time settings if you want a different scenario.

  • run_samsara() runs the simulations for the marking groups you have chosen in the creation of the CommandFile and stores result files in the folder data.

  • martelo_report() writes a PDF report for the marking group and stores it in the reports folder. The option Forester = c("X") can be changed to the name of the forester you want. This function has to be run as many times as needed with your different foresters.

This part of running the simulation can usually be done during lunch to save time.

Visualize the results

Visualize the pdf simulation report of each group and transfer it back to the group’s tablet. To share and discuss the results, if you can gather in a room, the best is to project simulation reports using a video-projector. Alternatively, you can print the reports using a portable printer or simply transfer them back to the tablets. After the exercise, you can transfer the reports of all groups to all the participants by email.

References

Courbaud, Benoit, Thierry Sardin, François De Coligny, Thomas Cordonnier, Christine Deleuze, Didier François, Catherine Riond, Valentine Lafond, and Guillaume Lagarrigues. 2016. “Utilisation Du Modèle Individu-Centré Samsara2 Pour Analyser Les Sylvicultures En Peuplement Irrégulier.” Rendez-Vous Techniques de l’ONF 53: 11–23. https://capsis.cirad.fr/capsis/_media/help_en/courbaudb_al.-rdvtech2016.pdf.
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.
Lafond, Valentine, Thomas Cordonnier, Zhun Mao, and Benoit Courbaud. 2017. “Trade-Offs and Synergies Between Ecosystem Services in Uneven-Aged Mountain Forests: Evidences Using Pareto Fronts.” European Journal of Forest Research 136 (5): 997–1012. https://doi.org/10.1007/s10342-016-1022-3.